A Python SDK for the ZMap network scanner that provides an easy-to-use interface for network scanning operations with REST API support.
- Simple API - Intuitive Python interface for ZMap network scanner
- Flexible Configuration - Comprehensive scan configuration options
- Blocklist/Allowlist Support - Easily manage blocklists and allowlists
- Output Control - Customize output formats and fields
- Result Parsing - Built-in parsers for CSV and JSON output formats
- REST API - FastAPI-based HTTP API for remote scanning operations
- Input Validation - Robust validation for IP addresses, subnets, and ports
- Type Hints - Full type annotation support for better IDE integration
- Well Tested - Comprehensive test suite included
See SETUP.md for detailed installation instructions.
from pyzmap import ZMap
# Initialize the PyZmap
zmap = ZMap() # Uses 'zmap' from PATH by default
# Run a basic scan on port 80
results = zmap.scan(
target_port=80,
subnets=["192.168.1.0/24"], # Scan your local network
bandwidth="1M" # Limit bandwidth to 1 Mbps
)
# Print the results
print(f"Found {len(results)} open ports")
for ip in results:
print(f"Open port at: {ip}")
# Create a blocklist
zmap.create_blocklist_file(["192.168.0.0/16", "10.0.0.0/8"], "private_ranges.txt")
# Generate a standard blocklist
zmap.generate_standard_blocklist("standard_blocklist.txt")The PyZmap consists of several core components:
- ZMap: The main class that provides the interface to ZMap
- ZMapScanConfig: Handles scan configuration parameters
- ZMapInput: Manages input sources (subnets, allowlists, blocklists)
- ZMapOutput: Controls output formatting and destinations
- ZMapRunner: Executes ZMap commands and captures results
- ZMapParser: Parses ZMap output into structured data
See USAGE.md for detailed setup and usage instructions.
See API_REFERENCE.md for detailed API documentation.
Check out the examples/ directory for practical examples:
basic-scan.py- Simple port scanning example showing essential PyZmap usageadvanced-scan.py- Advanced scanning example with custom configurations and output processing
- Python: 3.10 or higher
- ZMap: Latest version recommended (tested with v4.3.4)
- Operating System: Linux (primary), macOS (supported)
- Dependencies: FastAPI, uvicorn, psutil, click, httpx
For optimal performance when conducting network scans:
- CPU: Multi-core processor (4+ cores recommended)
- RAM: 4GB minimum, 8GB+ recommended for large scans
- Network: High-bandwidth connection for internet-wide scans
- Privileges: Root/sudo access may be required for raw socket operations
Contributions to PyZmap are welcome! Here's how you can contribute:
- Report Issues - Found a bug? Open an issue on GitHub with details
- Submit Pull Requests - Implement features or fix bugs
- Improve Documentation - Help improve docs or add examples
- Share Feedback - Let us know how you're using PyZmap
- Style: Follow PEP 8, use Black formatter (88 char line limit)
- Type Hints: Add type annotations to all functions
- Testing: Write unit tests for new features (pytest)
- Documentation: Update README and docstrings
- Commits: Write clear, descriptive commit messages
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes and commit (
git commit -m 'Add amazing feature') - Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request with a clear description
See FAQ.md for answers to common questions about PyZmap.
See CHANGELOG.md for a detailed list of changes and updates.
This project is inspired by the ZMap Project and aims to provide a user-friendly Python interface for network security researchers, system administrators, and developers.
- ZMap - Fast network scanner
- Issues: GitHub Issues
- Discussions: GitHub Discussions
MIT License - see LICENSE file for details
Copyright (c) 2025 Atilla
The pyzmap is provided for legitimate network research and security assessments only. Please use this tool responsibly and ethically.
Important considerations:
- Always ensure you have proper authorization before scanning any network or system.
- Comply with all applicable laws and regulations regarding network scanning in your jurisdiction.
- Be aware that network scanning may be interpreted as malicious activity by network administrators and may trigger security alerts.
- The authors and contributors of this SDK are not responsible for any misuse or damage caused by this software.
- Network scanning may cause disruption to services or systems; use appropriate bandwidth and rate limiting settings.
Before using this SDK for any network scanning operation, especially on production networks, consult with network administrators and obtain proper written permission.