---name: python-cybersecurity-tool-developmentdescription: 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