| Name | pyzmap JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | Python SDK for the ZMap network scanner |
| upload_time | 2025-07-30 09:31:11 |
| maintainer | None |
| docs_url | None |
| author | Atilla |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PyZmap
A Python SDK for the ZMap network scanner that provides an easy-to-use interface for network scanning operations with REST API support.
## Installation
### Prerequisites
- Python 3.6 or higher
- ZMap installed on your system - [ZMap Installation Guide](https://github.com/zmap/zmap/blob/main/INSTALL.md)
### Installing the SDK
```bash
pip install pyzmap
```
Or install from source:
```bash
git clone https://github.com/atiilla/pyzmap
cd pyzmap
pip install .
```
## Quick Start
```python
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
## Basic Usage
### Specifying a Custom ZMap Path
```python
from pyzmap import ZMap
# Initialize with custom path to the ZMap executable
zmap = ZMap(zmap_path="/usr/local/bin/zmap")
# Run scan as usual
results = zmap.scan(target_port=80, subnets=["192.168.0.0/24"])
```
### Scanning a Specific Port
```python
from pyzmap import ZMap
zmap = ZMap()
results = zmap.scan(target_port=443, subnets=["10.0.0.0/8"])
```
### Configuring Bandwidth and Rate
```python
from pyzmap import ZMap, ZMapScanConfig
# Option 1: Configure via parameters
results = zmap.scan(
target_port=22,
bandwidth="10M", # 10 Mbps
subnets=["192.168.0.0/16"]
)
# Option 2: Configure via config object
config = ZMapScanConfig(
target_port=22,
bandwidth="10M"
)
zmap = ZMap()
zmap.config = config
results = zmap.scan(subnets=["192.168.0.0/16"])
```
### Specifying Output File
```python
from pyzmap import ZMap
zmap = ZMap()
results = zmap.scan(
target_port=80,
subnets=["172.16.0.0/12"],
output_file="scan_results.csv"
)
```
### Using Blocklists and Allowlists
```python
from pyzmap import ZMap
zmap = ZMap()
# Using a blocklist file
zmap.blocklist_from_file("/path/to/blocklist.txt")
# Creating a blocklist file
zmap.create_blocklist_file(
subnets=["10.0.0.0/8", "192.168.0.0/16"],
output_file="private_ranges.conf"
)
# Using a allowlist file
zmap.allowlist_from_file("/path/to/allowlist.txt")
# Run scan with blocklist
results = zmap.scan(
target_port=443,
blocklist_file="private_ranges.conf"
)
```
### Controlling Scan Behavior
```python
from pyzmap import ZMap
zmap = ZMap()
results = zmap.scan(
target_port=80,
max_targets=1000, # Limit to 1000 targets
max_runtime=60, # Run for max 60 seconds
cooldown_time=5, # Wait 5 seconds after sending last probe
probes=3, # Send 3 probes to each IP
dryrun=True # Don't actually send packets (test mode)
)
```
### Advanced Configuration
```python
from pyzmap import ZMap, ZMapScanConfig
# Create configuration
config = ZMapScanConfig(
target_port=443,
bandwidth="100M",
interface="eth0",
source_ip="192.168.1.5",
source_port="40000-50000", # Random source port in range
max_targets="10%", # Scan 10% of address space
sender_threads=4, # Use 4 threads for sending
notes="HTTPS scanner for internal audit",
seed=123456 # Set random seed for reproducibility
)
# Initialize ZMap with configuration
zmap = ZMap()
zmap.config = config
# Run scan
results = zmap.scan(subnets=["10.0.0.0/16"])
```
## Processing Results
### Parsing Results
```python
from pyzmap import ZMap
zmap = ZMap()
# Run scan and save results
zmap.scan(
target_port=22,
subnets=["192.168.1.0/24"],
output_file="scan_results.csv",
output_fields=["saddr", "daddr", "sport", "dport", "classification"]
)
# Parse the results file
parsed_results = zmap.parse_results("scan_results.csv")
# Process the structured data
for result in parsed_results:
print(f"Source IP: {result['saddr']}, Classification: {result['classification']}")
# Extract just the IPs
ip_list = zmap.extract_ips(parsed_results)
```
### Working with Large Result Sets
```python
from pyzmap import ZMap
zmap = ZMap()
# For large scans, stream the results instead of loading all at once
for result in zmap.stream_results("large_scan_results.csv"):
process_result(result) # Your processing function
# Count results without loading everything
count = zmap.count_results("large_scan_results.csv")
print(f"Found {count} results")
```
## REST API
PyZMap includes a REST API that allows you to control ZMap operations remotely.
### Starting the API Server
You can start the API server in two ways:
#### From Command Line
```bash
# Start API server on default host (127.0.0.1) and port (8000)
pyzmap api
# Start API server with custom host and port
pyzmap api --host 0.0.0.0 --port 9000
# Start API server with verbose logging
pyzmap api -v
```
#### From Python
```python
from pyzmap import APIServer
# Create and start the API server
server = APIServer(host="0.0.0.0", port=8000)
server.run()
```
### API Endpoints
The REST API provides the following endpoints:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Basic information about the API |
| `/probe-modules` | GET | List available probe modules |
| `/output-modules` | GET | List available output modules |
| `/output-fields` | GET | List available output fields for a probe module |
| `/interfaces` | GET | List available network interfaces |
| `/scan-sync` | POST | Run a scan synchronously and return results |
| `/blocklist` | POST | Create a blocklist file from a list of subnets |
| `/standard-blocklist` | POST | Generate a standard blocklist file |
| `/allowlist` | POST | Create an allowlist file from a list of subnets |
### API Documentation
The API includes automatic documentation using Swagger UI and ReDoc:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
### Example API Requests
#### Basic Information
```bash
curl -X GET "http://localhost:8000/"
```
Response:
```json
{
"name": "PyZmap API",
"version": "2.1.1",
"description": "REST API for ZMap network scanner"
}
```
#### List Available Probe Modules
```bash
curl -X GET "http://localhost:8000/probe-modules"
```
Response:
```json
["tcp_synscan", "icmp_echoscan", "udp", "module_ntp", "module_dns"]
```
#### List Available Output Modules
```bash
curl -X GET "http://localhost:8000/output-modules"
```
Response:
```json
["csv", "json", "extended_file", "redis"]
```
#### List Available Network Interfaces
```bash
curl -X GET "http://localhost:8000/interfaces"
```
Response:
```json
["eth0", "lo", "wlan0"]
```
#### Run a Scan
```bash
curl -X POST "http://localhost:8000/scan-sync" \
-H "Content-Type: application/json" \
-d '{
"target_port": 80,
"bandwidth": "10M",
"probe_module": "tcp_synscan",
"return_results": true
}'
```
Response:
```json
{
"scan_id": "direct_scan",
"status": "completed",
"ips_found": ["192.168.1.1", "192.168.1.2", "10.0.0.1"]
}
```
#### Create a Blocklist
```bash
curl -X POST "http://localhost:8000/blocklist" \
-H "Content-Type: application/json" \
-d '{
"subnets": ["192.168.0.0/16", "10.0.0.0/8"]
}'
```
Response:
```json
{
"file_path": "/tmp/zmap_blocklist_a1b2c3.txt",
"message": "Blocklist file created with 2 subnets"
}
```
#### Generate a Standard Blocklist
```bash
curl -X POST "http://localhost:8000/standard-blocklist" \
-H "Content-Type: application/json" \
-d '{}'
```
Response:
```json
{
"file_path": "/tmp/zmap_std_blocklist_x1y2z3.txt",
"message": "Standard blocklist file created"
}
```
#### Create an Allowlist
```bash
curl -X POST "http://localhost:8000/allowlist" \
-H "Content-Type: application/json" \
-d '{
"subnets": ["1.2.3.0/24", "5.6.7.0/24"],
"output_file": "my_allowlist.txt"
}'
```
Response:
```json
{
"file_path": "my_allowlist.txt",
"message": "Allowlist file created with 2 subnets"
}
```
## API Reference
### ZMap Class
The main interface for the PyZmap.
#### Methods
- `scan(target_port, subnets, output_file, **kwargs)`: Perform a scan and return the results
- `run(**kwargs)`: Run ZMap with specified parameters
- `get_probe_modules()`: Get list of available probe modules
- `get_output_modules()`: Get list of available output modules
- `get_output_fields(probe_module)`: Get list of available output fields
- `get_interfaces()`: Get list of available network interfaces
- `get_version()`: Get ZMap version
- `blocklist_from_file(blocklist_file)`: Validate and use a blocklist file
- `allowlist_from_file(allowlist_file)`: Validate and use a allowlist file
- `create_blocklist_file(subnets, output_file)`: Create a blocklist file
- `create_allowlist_file(subnets, output_file)`: Create a allowlist file
- `create_target_file(targets, output_file)`: Create a file with target IPs
- `generate_standard_blocklist(output_file)`: Generate standard blocklist
- `parse_results(file_path, fields)`: Parse scan results into structured data
- `parse_metadata(file_path)`: Parse scan metadata
- `extract_ips(results, ip_field)`: Extract IPs from results
- `stream_results(file_path, fields)`: Stream results from a file
- `count_results(file_path)`: Count results in a file
### ZMapScanConfig Class
Handles configuration for ZMap scans.
#### Fields
- **Core Options**:
- `target_port`: Port number to scan
- `bandwidth`: Send rate in bits/second (supports G, M, K suffixes)
- `rate`: Send rate in packets/sec
- `cooldown_time`: How long to continue receiving after sending last probe
- `interface`: Network interface to use
- `source_ip`: Source address for scan packets
- `source_port`: Source port(s) for scan packets
- `gateway_mac`: Gateway MAC address
- `source_mac`: Source MAC address
- `target_mac`: Target MAC address
- `vpn`: Send IP packets instead of Ethernet (for VPNs)
- **Scan Control Options**:
- `max_targets`: Cap number of targets to probe
- `max_runtime`: Cap length of time for sending packets
- `max_results`: Cap number of results to return
- `probes`: Number of probes to send to each IP
- `retries`: Max number of times to try to send packet if send fails
- `dryrun`: Don't actually send packets
- `seed`: Seed used to select address permutation
- `shards`: Total number of shards
- `shard`: Which shard this scan is (0 indexed)
- **Advanced Options**:
- `sender_threads`: Threads used to send packets
- `cores`: Comma-separated list of cores to pin to
- `ignore_invalid_hosts`: Ignore invalid hosts in allowlist/blocklist file
- `max_sendto_failures`: Maximum NIC sendto failures before scan is aborted
- `min_hitrate`: Minimum hitrate that scan can hit before scan is aborted
- **Metadata Options**:
- `notes`: User-specified notes for scan metadata
- `user_metadata`: User-specified JSON metadata
## 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
## Requirements
- Python 3.6+
- ZMap network scanner installed on the system
## Contributing
Contributions to the PyZmap are welcome! Here's how you can contribute:
1. **Report Issues**: Report bugs or suggest features by opening an issue on the GitHub repository.
2. **Submit Pull Requests**: Implement new features or fix bugs and submit a pull request.
3. **Improve Documentation**: Help improve the documentation or add more examples.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/atiilla/pyzmap.git
cd pyzmap
# Create a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
```
### Coding Standards
- Follow PEP 8 style guidelines
- Write unit tests for new features
- Update documentation to reflect changes
## 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.
## Acknowledgements
This project is inspired by the ZMap network scanner and aims to provide a user-friendly interface for Python developers to leverage its capabilities.
## Thanks
Special thanks to <a href="https://github.com/ahsentekd">@ahsentekd</a> for the significant contributions including:
- CI/CD pipeline implementation and testing infrastructure
- Code quality improvements and modern Python typing
- Migration to Poetry build system
- Pre-commit hooks and automated workflows
- Documentation enhancements and project maintenance
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "pyzmap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Atilla",
"author_email": "attilla@tuta.io",
"download_url": "https://files.pythonhosted.org/packages/5f/a5/be5eeba212991e06c61bdf842066a38cad15051a94931c696d0cc3e5b9d7/pyzmap-0.1.3.tar.gz",
"platform": null,
"description": "# PyZmap\n\nA Python SDK for the ZMap network scanner that provides an easy-to-use interface for network scanning operations with REST API support.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.6 or higher\n- ZMap installed on your system - [ZMap Installation Guide](https://github.com/zmap/zmap/blob/main/INSTALL.md)\n\n### Installing the SDK\n\n```bash\npip install pyzmap\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/atiilla/pyzmap\ncd pyzmap\npip install .\n```\n\n## Quick Start\n\n```python\nfrom pyzmap import ZMap\n\n# Initialize the PyZmap\nzmap = ZMap() # Uses 'zmap' from PATH by default\n\n# Run a basic scan on port 80\nresults = zmap.scan(\n target_port=80,\n subnets=[\"192.168.1.0/24\"], # Scan your local network\n bandwidth=\"1M\" # Limit bandwidth to 1 Mbps\n)\n\n# Print the results\nprint(f\"Found {len(results)} open ports\")\nfor ip in results:\n print(f\"Open port at: {ip}\")\n\n# Create a blocklist\nzmap.create_blocklist_file([\"192.168.0.0/16\", \"10.0.0.0/8\"], \"private_ranges.txt\")\n\n# Generate a standard blocklist\nzmap.generate_standard_blocklist(\"standard_blocklist.txt\")\n```\n\n## Core Components\n\nThe PyZmap consists of several core components:\n\n- **ZMap**: The main class that provides the interface to ZMap\n- **ZMapScanConfig**: Handles scan configuration parameters\n- **ZMapInput**: Manages input sources (subnets, allowlists, blocklists)\n- **ZMapOutput**: Controls output formatting and destinations\n- **ZMapRunner**: Executes ZMap commands and captures results\n- **ZMapParser**: Parses ZMap output into structured data\n\n## Basic Usage\n\n### Specifying a Custom ZMap Path\n\n```python\nfrom pyzmap import ZMap\n\n# Initialize with custom path to the ZMap executable\nzmap = ZMap(zmap_path=\"/usr/local/bin/zmap\")\n\n# Run scan as usual\nresults = zmap.scan(target_port=80, subnets=[\"192.168.0.0/24\"])\n```\n\n### Scanning a Specific Port\n\n```python\nfrom pyzmap import ZMap\n\nzmap = ZMap()\nresults = zmap.scan(target_port=443, subnets=[\"10.0.0.0/8\"])\n```\n\n### Configuring Bandwidth and Rate\n\n```python\nfrom pyzmap import ZMap, ZMapScanConfig\n\n# Option 1: Configure via parameters\nresults = zmap.scan(\n target_port=22,\n bandwidth=\"10M\", # 10 Mbps\n subnets=[\"192.168.0.0/16\"]\n)\n\n# Option 2: Configure via config object\nconfig = ZMapScanConfig(\n target_port=22,\n bandwidth=\"10M\"\n)\nzmap = ZMap()\nzmap.config = config\nresults = zmap.scan(subnets=[\"192.168.0.0/16\"])\n```\n\n### Specifying Output File\n\n```python\nfrom pyzmap import ZMap\n\nzmap = ZMap()\nresults = zmap.scan(\n target_port=80,\n subnets=[\"172.16.0.0/12\"],\n output_file=\"scan_results.csv\"\n)\n```\n\n### Using Blocklists and Allowlists\n\n```python\nfrom pyzmap import ZMap\n\nzmap = ZMap()\n\n# Using a blocklist file\nzmap.blocklist_from_file(\"/path/to/blocklist.txt\")\n\n# Creating a blocklist file\nzmap.create_blocklist_file(\n subnets=[\"10.0.0.0/8\", \"192.168.0.0/16\"],\n output_file=\"private_ranges.conf\"\n)\n\n# Using a allowlist file\nzmap.allowlist_from_file(\"/path/to/allowlist.txt\")\n\n# Run scan with blocklist\nresults = zmap.scan(\n target_port=443,\n blocklist_file=\"private_ranges.conf\"\n)\n```\n\n### Controlling Scan Behavior\n\n```python\nfrom pyzmap import ZMap\n\nzmap = ZMap()\nresults = zmap.scan(\n target_port=80,\n max_targets=1000, # Limit to 1000 targets\n max_runtime=60, # Run for max 60 seconds\n cooldown_time=5, # Wait 5 seconds after sending last probe\n probes=3, # Send 3 probes to each IP\n dryrun=True # Don't actually send packets (test mode)\n)\n```\n\n### Advanced Configuration\n\n```python\nfrom pyzmap import ZMap, ZMapScanConfig\n\n# Create configuration\nconfig = ZMapScanConfig(\n target_port=443,\n bandwidth=\"100M\",\n interface=\"eth0\",\n source_ip=\"192.168.1.5\",\n source_port=\"40000-50000\", # Random source port in range\n max_targets=\"10%\", # Scan 10% of address space\n sender_threads=4, # Use 4 threads for sending\n notes=\"HTTPS scanner for internal audit\",\n seed=123456 # Set random seed for reproducibility\n)\n\n# Initialize ZMap with configuration\nzmap = ZMap()\nzmap.config = config\n\n# Run scan\nresults = zmap.scan(subnets=[\"10.0.0.0/16\"])\n```\n\n## Processing Results\n\n### Parsing Results\n\n```python\nfrom pyzmap import ZMap\n\nzmap = ZMap()\n\n# Run scan and save results\nzmap.scan(\n target_port=22,\n subnets=[\"192.168.1.0/24\"],\n output_file=\"scan_results.csv\",\n output_fields=[\"saddr\", \"daddr\", \"sport\", \"dport\", \"classification\"]\n)\n\n# Parse the results file\nparsed_results = zmap.parse_results(\"scan_results.csv\")\n\n# Process the structured data\nfor result in parsed_results:\n print(f\"Source IP: {result['saddr']}, Classification: {result['classification']}\")\n\n# Extract just the IPs\nip_list = zmap.extract_ips(parsed_results)\n```\n\n### Working with Large Result Sets\n\n```python\nfrom pyzmap import ZMap\n\nzmap = ZMap()\n\n# For large scans, stream the results instead of loading all at once\nfor result in zmap.stream_results(\"large_scan_results.csv\"):\n process_result(result) # Your processing function\n\n# Count results without loading everything\ncount = zmap.count_results(\"large_scan_results.csv\")\nprint(f\"Found {count} results\")\n```\n\n## REST API\n\nPyZMap includes a REST API that allows you to control ZMap operations remotely.\n\n### Starting the API Server\n\nYou can start the API server in two ways:\n\n#### From Command Line\n\n```bash\n# Start API server on default host (127.0.0.1) and port (8000)\npyzmap api\n\n# Start API server with custom host and port\npyzmap api --host 0.0.0.0 --port 9000\n\n# Start API server with verbose logging\npyzmap api -v\n```\n\n#### From Python\n\n```python\nfrom pyzmap import APIServer\n\n# Create and start the API server\nserver = APIServer(host=\"0.0.0.0\", port=8000)\nserver.run()\n```\n\n### API Endpoints\n\nThe REST API provides the following endpoints:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/` | GET | Basic information about the API |\n| `/probe-modules` | GET | List available probe modules |\n| `/output-modules` | GET | List available output modules |\n| `/output-fields` | GET | List available output fields for a probe module |\n| `/interfaces` | GET | List available network interfaces |\n| `/scan-sync` | POST | Run a scan synchronously and return results |\n| `/blocklist` | POST | Create a blocklist file from a list of subnets |\n| `/standard-blocklist` | POST | Generate a standard blocklist file |\n| `/allowlist` | POST | Create an allowlist file from a list of subnets |\n\n### API Documentation\n\nThe API includes automatic documentation using Swagger UI and ReDoc:\n\n- Swagger UI: http://localhost:8000/docs\n- ReDoc: http://localhost:8000/redoc\n\n### Example API Requests\n\n#### Basic Information\n\n```bash\ncurl -X GET \"http://localhost:8000/\"\n```\n\nResponse:\n```json\n{\n \"name\": \"PyZmap API\",\n \"version\": \"2.1.1\",\n \"description\": \"REST API for ZMap network scanner\"\n}\n```\n\n#### List Available Probe Modules\n\n```bash\ncurl -X GET \"http://localhost:8000/probe-modules\"\n```\n\nResponse:\n```json\n[\"tcp_synscan\", \"icmp_echoscan\", \"udp\", \"module_ntp\", \"module_dns\"]\n```\n\n#### List Available Output Modules\n\n```bash\ncurl -X GET \"http://localhost:8000/output-modules\"\n```\n\nResponse:\n```json\n[\"csv\", \"json\", \"extended_file\", \"redis\"]\n```\n\n#### List Available Network Interfaces\n\n```bash\ncurl -X GET \"http://localhost:8000/interfaces\"\n```\n\nResponse:\n```json\n[\"eth0\", \"lo\", \"wlan0\"]\n```\n\n#### Run a Scan\n\n```bash\ncurl -X POST \"http://localhost:8000/scan-sync\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"target_port\": 80,\n \"bandwidth\": \"10M\",\n \"probe_module\": \"tcp_synscan\",\n \"return_results\": true\n }'\n```\n\nResponse:\n```json\n{\n \"scan_id\": \"direct_scan\",\n \"status\": \"completed\",\n \"ips_found\": [\"192.168.1.1\", \"192.168.1.2\", \"10.0.0.1\"]\n}\n```\n\n#### Create a Blocklist\n\n```bash\ncurl -X POST \"http://localhost:8000/blocklist\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"subnets\": [\"192.168.0.0/16\", \"10.0.0.0/8\"]\n }'\n```\n\nResponse:\n```json\n{\n \"file_path\": \"/tmp/zmap_blocklist_a1b2c3.txt\",\n \"message\": \"Blocklist file created with 2 subnets\"\n}\n```\n\n#### Generate a Standard Blocklist\n\n```bash\ncurl -X POST \"http://localhost:8000/standard-blocklist\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'\n```\n\nResponse:\n```json\n{\n \"file_path\": \"/tmp/zmap_std_blocklist_x1y2z3.txt\",\n \"message\": \"Standard blocklist file created\"\n}\n```\n\n#### Create an Allowlist\n\n```bash\ncurl -X POST \"http://localhost:8000/allowlist\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"subnets\": [\"1.2.3.0/24\", \"5.6.7.0/24\"],\n \"output_file\": \"my_allowlist.txt\"\n }'\n```\n\nResponse:\n```json\n{\n \"file_path\": \"my_allowlist.txt\",\n \"message\": \"Allowlist file created with 2 subnets\"\n}\n```\n\n## API Reference\n\n### ZMap Class\n\nThe main interface for the PyZmap.\n\n#### Methods\n\n- `scan(target_port, subnets, output_file, **kwargs)`: Perform a scan and return the results\n- `run(**kwargs)`: Run ZMap with specified parameters\n- `get_probe_modules()`: Get list of available probe modules\n- `get_output_modules()`: Get list of available output modules\n- `get_output_fields(probe_module)`: Get list of available output fields\n- `get_interfaces()`: Get list of available network interfaces\n- `get_version()`: Get ZMap version\n- `blocklist_from_file(blocklist_file)`: Validate and use a blocklist file\n- `allowlist_from_file(allowlist_file)`: Validate and use a allowlist file\n- `create_blocklist_file(subnets, output_file)`: Create a blocklist file\n- `create_allowlist_file(subnets, output_file)`: Create a allowlist file\n- `create_target_file(targets, output_file)`: Create a file with target IPs\n- `generate_standard_blocklist(output_file)`: Generate standard blocklist\n- `parse_results(file_path, fields)`: Parse scan results into structured data\n- `parse_metadata(file_path)`: Parse scan metadata\n- `extract_ips(results, ip_field)`: Extract IPs from results\n- `stream_results(file_path, fields)`: Stream results from a file\n- `count_results(file_path)`: Count results in a file\n\n### ZMapScanConfig Class\n\nHandles configuration for ZMap scans.\n\n#### Fields\n\n- **Core Options**:\n - `target_port`: Port number to scan\n - `bandwidth`: Send rate in bits/second (supports G, M, K suffixes)\n - `rate`: Send rate in packets/sec\n - `cooldown_time`: How long to continue receiving after sending last probe\n - `interface`: Network interface to use\n - `source_ip`: Source address for scan packets\n - `source_port`: Source port(s) for scan packets\n - `gateway_mac`: Gateway MAC address\n - `source_mac`: Source MAC address\n - `target_mac`: Target MAC address\n - `vpn`: Send IP packets instead of Ethernet (for VPNs)\n\n- **Scan Control Options**:\n - `max_targets`: Cap number of targets to probe\n - `max_runtime`: Cap length of time for sending packets\n - `max_results`: Cap number of results to return\n - `probes`: Number of probes to send to each IP\n - `retries`: Max number of times to try to send packet if send fails\n - `dryrun`: Don't actually send packets\n - `seed`: Seed used to select address permutation\n - `shards`: Total number of shards\n - `shard`: Which shard this scan is (0 indexed)\n\n- **Advanced Options**:\n - `sender_threads`: Threads used to send packets\n - `cores`: Comma-separated list of cores to pin to\n - `ignore_invalid_hosts`: Ignore invalid hosts in allowlist/blocklist file\n - `max_sendto_failures`: Maximum NIC sendto failures before scan is aborted\n - `min_hitrate`: Minimum hitrate that scan can hit before scan is aborted\n\n- **Metadata Options**:\n - `notes`: User-specified notes for scan metadata\n - `user_metadata`: User-specified JSON metadata\n\n## Examples\n\nCheck out the `examples/` directory for practical examples:\n\n- `basic-scan.py` - Simple port scanning example showing essential PyZmap usage\n- `advanced-scan.py` - Advanced scanning example with custom configurations and output processing\n\n## Requirements\n\n- Python 3.6+\n- ZMap network scanner installed on the system\n\n## Contributing\n\nContributions to the PyZmap are welcome! Here's how you can contribute:\n\n1. **Report Issues**: Report bugs or suggest features by opening an issue on the GitHub repository.\n\n2. **Submit Pull Requests**: Implement new features or fix bugs and submit a pull request.\n\n3. **Improve Documentation**: Help improve the documentation or add more examples.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/atiilla/pyzmap.git\ncd pyzmap\n\n# Create a virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n\n### Coding Standards\n\n- Follow PEP 8 style guidelines\n- Write unit tests for new features\n- Update documentation to reflect changes\n\n## Disclaimer\n\nThe pyzmap is provided for legitimate network research and security assessments only. Please use this tool responsibly and ethically.\n\n**Important considerations:**\n\n- Always ensure you have proper authorization before scanning any network or system.\n- Comply with all applicable laws and regulations regarding network scanning in your jurisdiction.\n- Be aware that network scanning may be interpreted as malicious activity by network administrators and may trigger security alerts.\n- The authors and contributors of this SDK are not responsible for any misuse or damage caused by this software.\n- Network scanning may cause disruption to services or systems; use appropriate bandwidth and rate limiting settings.\n\nBefore using this SDK for any network scanning operation, especially on production networks, consult with network administrators and obtain proper written permission.\n\n\n## Acknowledgements\nThis project is inspired by the ZMap network scanner and aims to provide a user-friendly interface for Python developers to leverage its capabilities.\n\n## Thanks\nSpecial thanks to <a href=\"https://github.com/ahsentekd\">@ahsentekd</a> for the significant contributions including:\n- CI/CD pipeline implementation and testing infrastructure\n- Code quality improvements and modern Python typing\n- Migration to Poetry build system\n- Pre-commit hooks and automated workflows\n- Documentation enhancements and project maintenance\n\n## License\n\nMIT\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for the ZMap network scanner",
"version": "0.1.3",
"project_urls": {
"Repository": "https://github.com/atiilla/pyzmap"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eeb6759db038582336bfeb99baa72532b0e0c80aef04d6d7cf1eba203789633a",
"md5": "021e5859d7afc5dcaab08bedd98e3933",
"sha256": "2688c9c2c6e6ddf59e6133afdea5ef5a275bd58a6c518f0ecd371c2c1cd6993e"
},
"downloads": -1,
"filename": "pyzmap-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "021e5859d7afc5dcaab08bedd98e3933",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24626,
"upload_time": "2025-07-30T09:31:10",
"upload_time_iso_8601": "2025-07-30T09:31:10.617237Z",
"url": "https://files.pythonhosted.org/packages/ee/b6/759db038582336bfeb99baa72532b0e0c80aef04d6d7cf1eba203789633a/pyzmap-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5fa5be5eeba212991e06c61bdf842066a38cad15051a94931c696d0cc3e5b9d7",
"md5": "4b65c4bfa380405ffaabf9958ec1c37d",
"sha256": "1a53b067b1376f0ab24672af062efbd50a7bd5dac9be2abbfbe2138f9f135b6d"
},
"downloads": -1,
"filename": "pyzmap-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "4b65c4bfa380405ffaabf9958ec1c37d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 23779,
"upload_time": "2025-07-30T09:31:11",
"upload_time_iso_8601": "2025-07-30T09:31:11.566722Z",
"url": "https://files.pythonhosted.org/packages/5f/a5/be5eeba212991e06c61bdf842066a38cad15051a94931c696d0cc3e5b9d7/pyzmap-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 09:31:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "atiilla",
"github_project": "pyzmap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyzmap"
}
