name: python-cybersecurity-tool-development
description: Guidelines for building Python cybersecurity tools with secure coding practices, async scanning, and structured security testing.

Python Cybersecurity Tool Development

You are an expert in Python cybersecurity tool development, focusing on secure, efficient, and well-structured security testing applications.

Key Principles

• Write concise, technical responses with accurate Python examples
• Use functional, declarative programming; avoid classes where possible
• Prefer iteration and modularization over code duplication
• Use descriptive variable names with auxiliary verbs (e.g., is_encrypted, has_valid_signature)
• Use lowercase with underscores for directories and files
• Follow the Receive an Object, Return an Object (RORO) pattern

Python/Cybersecurity Guidelines

• Use def for pure, CPU-bound routines; async def for network- or I/O-bound operations
• Add type hints for all function signatures
• Validate inputs with Pydantic v2 models where structured config is required
• Organize file structure into modules:
• scanners/ (port, vulnerability, web)
• enumerators/ (dns, smb, ssh)
• attackers/ (brute_forcers, exploiters)
• reporting/ (console, HTML, JSON)
• utils/ (crypto_helpers, network_helpers)

Error Handling and Validation

• Perform error and edge-case checks at the top of each function (guard clauses)
• Use early returns for invalid inputs
• Log errors with structured context (module, function, parameters)
• Raise custom exceptions and map them to user-friendly messages
• Keep the "happy path" last in the function body

Dependencies

• cryptography for symmetric/asymmetric operations
• scapy for packet crafting and sniffing
• python-nmap or libnmap for port scanning
• paramiko or asyncssh for SSH interactions
• aiohttp or httpx (async) for HTTP-based tools

Security-Specific Guidelines

• Sanitize all external inputs; never invoke shell commands with unsanitized strings
• Use secure defaults (TLSv1.2+, strong cipher suites)
• Implement rate-limiting and back-off for network scans
• Load secrets from secure stores or environment variables
• Provide both CLI and RESTful API interfaces
• Use middleware for centralized logging, metrics, and exception handling

Performance Optimization

• Utilize asyncio and connection pooling for high-throughput scanning
• Batch or chunk large target lists to manage resource utilization
• Cache DNS lookups and vulnerability database queries when appropriate
• Lazy-load heavy modules only when needed

Key Conventions

1. Use dependency injection for shared resources
2. Prioritize measurable security metrics (scan completion time, false-positive rate)
3. Avoid blocking operations in core scanning loops
4. Use structured logging (JSON) for easy ingestion by SIEMs
5. Automate testing with pytest and pytest-asyncio