PyZmap

A Python SDK for the ZMap network scanner that provides an easy-to-use interface for network scanning operations with REST API support.

Features

• 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

Installation

See SETUP.md for detailed installation instructions.

Quick Start

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")

Core Components

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

USAGE

See USAGE.md for detailed setup and usage instructions.

API Reference

See API_REFERENCE.md for detailed API documentation.

Examples

Check out the examples/ directory for practical examples:

• basic-scan.py - Simple port scanning example showing essential PyZmap usage
• advanced-scan.py - Advanced scanning example with custom configurations and output processing

System Requirements

• 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

Recommended System Specifications

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

Contributing

Contributions to PyZmap are welcome! Here's how you can contribute:

Ways to Contribute

1. Report Issues - Found a bug? Open an issue on GitHub with details
2. Submit Pull Requests - Implement features or fix bugs
3. Improve Documentation - Help improve docs or add examples
4. Share Feedback - Let us know how you're using PyZmap

Coding Standards

• 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

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and commit (git commit -m 'Add amazing feature')
4. Push to your branch (git push origin feature/amazing-feature)
5. Open a Pull Request with a clear description

Frequently Asked Questions

See FAQ.md for answers to common questions about PyZmap.

Changelog

See CHANGELOG.md for a detailed list of changes and updates.

Acknowledgements

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.

Related Projects

• ZMap - Fast network scanner

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT License - see LICENSE file for details

Copyright (c) 2025 Atilla

---

Disclaimer

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.

⚠️ Legal Notice: The pyzmap is provided for legitimate network research and security assessments only. Always ensure you have proper authorization before scanning any network or system. Unauthorized network scanning may be illegal in your jurisdiction.