{"id":27959334,"url":"https://github.com/happyhackingspace/zmapsdk","last_synced_at":"2025-05-07T18:29:40.706Z","repository":{"id":287013260,"uuid":"962957707","full_name":"HappyHackingSpace/ZmapSDK","owner":"HappyHackingSpace","description":"A Python SDK for the ZMap network scanner that provides an easy-to-use interface for network scanning operations.","archived":false,"fork":false,"pushed_at":"2025-04-29T10:12:58.000Z","size":47,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-29T11:24:33.832Z","etag":null,"topics":["library","networking","scanning","zmap"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/zmapsdk/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HappyHackingSpace.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-09T00:00:15.000Z","updated_at":"2025-04-29T10:12:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"05dd0183-df54-45d7-a0fd-7a670b789dca","html_url":"https://github.com/HappyHackingSpace/ZmapSDK","commit_stats":null,"previous_names":["happyhackingspace/zmapsdk"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HappyHackingSpace%2FZmapSDK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HappyHackingSpace%2FZmapSDK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HappyHackingSpace%2FZmapSDK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HappyHackingSpace%2FZmapSDK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HappyHackingSpace","download_url":"https://codeload.github.com/HappyHackingSpace/ZmapSDK/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252933671,"owners_count":21827557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","networking","scanning","zmap"],"created_at":"2025-05-07T18:29:40.126Z","updated_at":"2025-05-07T18:29:40.688Z","avatar_url":"https://github.com/HappyHackingSpace.png","language":"Python","readme":"# ZMap SDK\r\n\r\nA Python SDK for the ZMap network scanner that provides an easy-to-use interface for network scanning operations with REST API support.\r\n\r\n## Installation\r\n\r\n### Prerequisites\r\n\r\n- Python 3.6 or higher\r\n- ZMap installed on your system - [ZMap Installation Guide](https://github.com/zmap/zmap/blob/main/INSTALL.md)\r\n\r\n### Installing the SDK\r\n\r\n```bash\r\npip install zmapsdk\r\n```\r\n\r\nOr install from source:\r\n\r\n```bash\r\ngit clone https://github.com/HappyHackingSpace/ZmapSDK\r\ncd zmapsdk\r\npip install .\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\n# Initialize the ZMap SDK\r\nzmap = ZMap()  # Uses 'zmap' from PATH by default\r\n\r\n# Run a basic scan on port 80\r\nresults = zmap.scan(\r\n    target_port=80,\r\n    subnets=[\"192.168.1.0/24\"],  # Scan your local network\r\n    bandwidth=\"1M\"  # Limit bandwidth to 1 Mbps\r\n)\r\n\r\n# Print the results\r\nprint(f\"Found {len(results)} open ports\")\r\nfor ip in results:\r\n    print(f\"Open port at: {ip}\")\r\n\r\n# Create a blocklist\r\nzmap.create_blocklist_file([\"192.168.0.0/16\", \"10.0.0.0/8\"], \"private_ranges.txt\")\r\n\r\n# Generate a standard blocklist\r\nzmap.generate_standard_blocklist(\"standard_blocklist.txt\")\r\n```\r\n\r\n## Core Components\r\n\r\nThe ZMap SDK consists of several core components:\r\n\r\n- **ZMap**: The main class that provides the interface to ZMap\r\n- **ZMapScanConfig**: Handles scan configuration parameters\r\n- **ZMapInput**: Manages input sources (subnets, allowlists, blocklists)\r\n- **ZMapOutput**: Controls output formatting and destinations\r\n- **ZMapRunner**: Executes ZMap commands and captures results\r\n- **ZMapParser**: Parses ZMap output into structured data\r\n\r\n## Basic Usage\r\n\r\n### Specifying a Custom ZMap Path\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\n# Initialize with custom path to the ZMap executable\r\nzmap = ZMap(zmap_path=\"/usr/local/bin/zmap\")\r\n\r\n# Run scan as usual\r\nresults = zmap.scan(target_port=80, subnets=[\"192.168.0.0/24\"])\r\n```\r\n\r\n### Scanning a Specific Port\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\nzmap = ZMap()\r\nresults = zmap.scan(target_port=443, subnets=[\"10.0.0.0/8\"])\r\n```\r\n\r\n### Configuring Bandwidth and Rate\r\n\r\n```python\r\nfrom zmapsdk import ZMap, ZMapScanConfig\r\n\r\n# Option 1: Configure via parameters\r\nresults = zmap.scan(\r\n    target_port=22,\r\n    bandwidth=\"10M\",  # 10 Mbps\r\n    subnets=[\"192.168.0.0/16\"]\r\n)\r\n\r\n# Option 2: Configure via config object\r\nconfig = ZMapScanConfig(\r\n    target_port=22,\r\n    bandwidth=\"10M\"\r\n)\r\nzmap = ZMap()\r\nzmap.config = config\r\nresults = zmap.scan(subnets=[\"192.168.0.0/16\"])\r\n```\r\n\r\n### Specifying Output File\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\nzmap = ZMap()\r\nresults = zmap.scan(\r\n    target_port=80,\r\n    subnets=[\"172.16.0.0/12\"],\r\n    output_file=\"scan_results.csv\"\r\n)\r\n```\r\n\r\n### Using Blocklists and Allowlists\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\nzmap = ZMap()\r\n\r\n# Using a blocklist file\r\nzmap.blocklist_from_file(\"/path/to/blocklist.txt\")\r\n\r\n# Creating a blocklist file\r\nzmap.create_blocklist_file(\r\n    subnets=[\"10.0.0.0/8\", \"192.168.0.0/16\"],\r\n    output_file=\"private_ranges.conf\"\r\n)\r\n\r\n# Using a allowlist file\r\nzmap.allowlist_from_file(\"/path/to/allowlist.txt\")\r\n\r\n# Run scan with blocklist\r\nresults = zmap.scan(\r\n    target_port=443,\r\n    blocklist_file=\"private_ranges.conf\"\r\n)\r\n```\r\n\r\n### Controlling Scan Behavior\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\nzmap = ZMap()\r\nresults = zmap.scan(\r\n    target_port=80,\r\n    max_targets=1000,      # Limit to 1000 targets\r\n    max_runtime=60,        # Run for max 60 seconds\r\n    cooldown_time=5,       # Wait 5 seconds after sending last probe\r\n    probes=3,              # Send 3 probes to each IP\r\n    dryrun=True            # Don't actually send packets (test mode)\r\n)\r\n```\r\n\r\n### Advanced Configuration\r\n\r\n```python\r\nfrom zmapsdk import ZMap, ZMapScanConfig\r\n\r\n# Create configuration\r\nconfig = ZMapScanConfig(\r\n    target_port=443,\r\n    bandwidth=\"100M\",\r\n    interface=\"eth0\",\r\n    source_ip=\"192.168.1.5\",\r\n    source_port=\"40000-50000\",  # Random source port in range\r\n    max_targets=\"10%\",          # Scan 10% of address space\r\n    sender_threads=4,           # Use 4 threads for sending\r\n    notes=\"HTTPS scanner for internal audit\",\r\n    seed=123456                 # Set random seed for reproducibility\r\n)\r\n\r\n# Initialize ZMap with configuration\r\nzmap = ZMap()\r\nzmap.config = config\r\n\r\n# Run scan\r\nresults = zmap.scan(subnets=[\"10.0.0.0/16\"])\r\n```\r\n\r\n## Processing Results\r\n\r\n### Parsing Results\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\nzmap = ZMap()\r\n\r\n# Run scan and save results\r\nzmap.scan(\r\n    target_port=22,\r\n    subnets=[\"192.168.1.0/24\"],\r\n    output_file=\"scan_results.csv\",\r\n    output_fields=[\"saddr\", \"daddr\", \"sport\", \"dport\", \"classification\"]\r\n)\r\n\r\n# Parse the results file\r\nparsed_results = zmap.parse_results(\"scan_results.csv\")\r\n\r\n# Process the structured data\r\nfor result in parsed_results:\r\n    print(f\"Source IP: {result['saddr']}, Classification: {result['classification']}\")\r\n\r\n# Extract just the IPs\r\nip_list = zmap.extract_ips(parsed_results)\r\n```\r\n\r\n### Working with Large Result Sets\r\n\r\n```python\r\nfrom zmapsdk import ZMap\r\n\r\nzmap = ZMap()\r\n\r\n# For large scans, stream the results instead of loading all at once\r\nfor result in zmap.stream_results(\"large_scan_results.csv\"):\r\n    process_result(result)  # Your processing function\r\n\r\n# Count results without loading everything\r\ncount = zmap.count_results(\"large_scan_results.csv\")\r\nprint(f\"Found {count} results\")\r\n```\r\n\r\n## REST API\r\n\r\nZMap SDK includes a REST API that allows you to control ZMap operations remotely.\r\n\r\n### Starting the API Server\r\n\r\nYou can start the API server in two ways:\r\n\r\n#### From Command Line\r\n\r\n```bash\r\n# Start API server on default host (127.0.0.1) and port (8000)\r\nzmapsdk api\r\n\r\n# Start API server with custom host and port\r\nzmapsdk api --host 0.0.0.0 --port 9000\r\n\r\n# Start API server with verbose logging\r\nzmapsdk api -v\r\n```\r\n\r\n#### From Python\r\n\r\n```python\r\nfrom zmapsdk import APIServer\r\n\r\n# Create and start the API server\r\nserver = APIServer(host=\"0.0.0.0\", port=8000)\r\nserver.run()\r\n```\r\n\r\n### API Endpoints\r\n\r\nThe REST API provides the following endpoints:\r\n\r\n| Endpoint | Method | Description |\r\n|----------|--------|-------------|\r\n| `/` | GET | Basic information about the API |\r\n| `/probe-modules` | GET | List available probe modules |\r\n| `/output-modules` | GET | List available output modules |\r\n| `/output-fields` | GET | List available output fields for a probe module |\r\n| `/interfaces` | GET | List available network interfaces |\r\n| `/scan-sync` | POST | Run a scan synchronously and return results |\r\n| `/blocklist` | POST | Create a blocklist file from a list of subnets |\r\n| `/standard-blocklist` | POST | Generate a standard blocklist file |\r\n| `/allowlist` | POST | Create an allowlist file from a list of subnets |\r\n\r\n### API Documentation\r\n\r\nThe API includes automatic documentation using Swagger UI and ReDoc:\r\n\r\n- Swagger UI: http://localhost:8000/docs\r\n- ReDoc: http://localhost:8000/redoc\r\n\r\n### Example API Requests\r\n\r\n#### Basic Information\r\n\r\n```bash\r\ncurl -X GET \"http://localhost:8000/\"\r\n```\r\n\r\nResponse:\r\n```json\r\n{\r\n  \"name\": \"ZMap SDK API\",\r\n  \"version\": \"2.1.1\",\r\n  \"description\": \"REST API for ZMap network scanner\"\r\n}\r\n```\r\n\r\n#### List Available Probe Modules\r\n\r\n```bash\r\ncurl -X GET \"http://localhost:8000/probe-modules\"\r\n```\r\n\r\nResponse:\r\n```json\r\n[\"tcp_synscan\", \"icmp_echoscan\", \"udp\", \"module_ntp\", \"module_dns\"]\r\n```\r\n\r\n#### List Available Output Modules\r\n\r\n```bash\r\ncurl -X GET \"http://localhost:8000/output-modules\"\r\n```\r\n\r\nResponse:\r\n```json\r\n[\"csv\", \"json\", \"extended_file\", \"redis\"]\r\n```\r\n\r\n#### List Available Network Interfaces\r\n\r\n```bash\r\ncurl -X GET \"http://localhost:8000/interfaces\"\r\n```\r\n\r\nResponse:\r\n```json\r\n[\"eth0\", \"lo\", \"wlan0\"]\r\n```\r\n\r\n#### Run a Scan\r\n\r\n```bash\r\ncurl -X POST \"http://localhost:8000/scan-sync\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\r\n    \"target_port\": 80,\r\n    \"bandwidth\": \"10M\",\r\n    \"probe_module\": \"tcp_synscan\",\r\n    \"return_results\": true\r\n  }'\r\n```\r\n\r\nResponse:\r\n```json\r\n{\r\n  \"scan_id\": \"direct_scan\",\r\n  \"status\": \"completed\",\r\n  \"ips_found\": [\"192.168.1.1\", \"192.168.1.2\", \"10.0.0.1\"]\r\n}\r\n```\r\n\r\n#### Create a Blocklist\r\n\r\n```bash\r\ncurl -X POST \"http://localhost:8000/blocklist\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\r\n    \"subnets\": [\"192.168.0.0/16\", \"10.0.0.0/8\"]\r\n  }'\r\n```\r\n\r\nResponse:\r\n```json\r\n{\r\n  \"file_path\": \"/tmp/zmap_blocklist_a1b2c3.txt\",\r\n  \"message\": \"Blocklist file created with 2 subnets\"\r\n}\r\n```\r\n\r\n#### Generate a Standard Blocklist\r\n\r\n```bash\r\ncurl -X POST \"http://localhost:8000/standard-blocklist\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{}'\r\n```\r\n\r\nResponse:\r\n```json\r\n{\r\n  \"file_path\": \"/tmp/zmap_std_blocklist_x1y2z3.txt\",\r\n  \"message\": \"Standard blocklist file created\"\r\n}\r\n```\r\n\r\n#### Create an Allowlist\r\n\r\n```bash\r\ncurl -X POST \"http://localhost:8000/allowlist\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\r\n    \"subnets\": [\"1.2.3.0/24\", \"5.6.7.0/24\"],\r\n    \"output_file\": \"my_allowlist.txt\"\r\n  }'\r\n```\r\n\r\nResponse:\r\n```json\r\n{\r\n  \"file_path\": \"my_allowlist.txt\",\r\n  \"message\": \"Allowlist file created with 2 subnets\"\r\n}\r\n```\r\n\r\n## API Reference\r\n\r\n### ZMap Class\r\n\r\nThe main interface for the ZMap SDK.\r\n\r\n#### Methods\r\n\r\n- `scan(target_port, subnets, output_file, **kwargs)`: Perform a scan and return the results\r\n- `run(**kwargs)`: Run ZMap with specified parameters\r\n- `get_probe_modules()`: Get list of available probe modules\r\n- `get_output_modules()`: Get list of available output modules\r\n- `get_output_fields(probe_module)`: Get list of available output fields\r\n- `get_interfaces()`: Get list of available network interfaces\r\n- `get_version()`: Get ZMap version\r\n- `blocklist_from_file(blocklist_file)`: Validate and use a blocklist file\r\n- `allowlist_from_file(allowlist_file)`: Validate and use a allowlist file\r\n- `create_blocklist_file(subnets, output_file)`: Create a blocklist file\r\n- `create_allowlist_file(subnets, output_file)`: Create a allowlist file\r\n- `create_target_file(targets, output_file)`: Create a file with target IPs\r\n- `generate_standard_blocklist(output_file)`: Generate standard blocklist\r\n- `parse_results(file_path, fields)`: Parse scan results into structured data\r\n- `parse_metadata(file_path)`: Parse scan metadata\r\n- `extract_ips(results, ip_field)`: Extract IPs from results\r\n- `stream_results(file_path, fields)`: Stream results from a file\r\n- `count_results(file_path)`: Count results in a file\r\n\r\n### ZMapScanConfig Class\r\n\r\nHandles configuration for ZMap scans.\r\n\r\n#### Fields\r\n\r\n- **Core Options**:\r\n  - `target_port`: Port number to scan\r\n  - `bandwidth`: Send rate in bits/second (supports G, M, K suffixes)\r\n  - `rate`: Send rate in packets/sec\r\n  - `cooldown_time`: How long to continue receiving after sending last probe\r\n  - `interface`: Network interface to use\r\n  - `source_ip`: Source address for scan packets\r\n  - `source_port`: Source port(s) for scan packets\r\n  - `gateway_mac`: Gateway MAC address\r\n  - `source_mac`: Source MAC address\r\n  - `target_mac`: Target MAC address\r\n  - `vpn`: Send IP packets instead of Ethernet (for VPNs)\r\n\r\n- **Scan Control Options**:\r\n  - `max_targets`: Cap number of targets to probe\r\n  - `max_runtime`: Cap length of time for sending packets\r\n  - `max_results`: Cap number of results to return\r\n  - `probes`: Number of probes to send to each IP\r\n  - `retries`: Max number of times to try to send packet if send fails\r\n  - `dryrun`: Don't actually send packets\r\n  - `seed`: Seed used to select address permutation\r\n  - `shards`: Total number of shards\r\n  - `shard`: Which shard this scan is (0 indexed)\r\n\r\n- **Advanced Options**:\r\n  - `sender_threads`: Threads used to send packets\r\n  - `cores`: Comma-separated list of cores to pin to\r\n  - `ignore_invalid_hosts`: Ignore invalid hosts in allowlist/blocklist file\r\n  - `max_sendto_failures`: Maximum NIC sendto failures before scan is aborted\r\n  - `min_hitrate`: Minimum hitrate that scan can hit before scan is aborted\r\n\r\n- **Metadata Options**:\r\n  - `notes`: User-specified notes for scan metadata\r\n  - `user_metadata`: User-specified JSON metadata\r\n\r\n## Examples\r\n\r\nCheck out the `examples/` directory for practical examples:\r\n\r\n- `basic-scan.py` - Simple port scanning example showing essential ZMap SDK usage\r\n- `advanced-scan.py` - Advanced scanning example with custom configurations and output processing\r\n\r\n## Requirements\r\n\r\n- Python 3.6+\r\n- ZMap network scanner installed on the system\r\n\r\n## Contributing\r\n\r\nContributions to the ZMap SDK are welcome! Here's how you can contribute:\r\n\r\n1. **Report Issues**: Report bugs or suggest features by opening an issue on the GitHub repository.\r\n\r\n2. **Submit Pull Requests**: Implement new features or fix bugs and submit a pull request.\r\n\r\n3. **Improve Documentation**: Help improve the documentation or add more examples.\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/HappyHackingSpace/ZmapSDK.git\r\ncd ZmapSDK\r\n\r\n# Create a virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\r\n\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npytest\r\n```\r\n\r\n### Coding Standards\r\n\r\n- Follow PEP 8 style guidelines\r\n- Write unit tests for new features\r\n- Update documentation to reflect changes\r\n\r\n## Disclaimer\r\n\r\nThe ZMapSDK is provided for legitimate network research and security assessments only. Please use this tool responsibly and ethically.\r\n\r\n**Important considerations:**\r\n\r\n- Always ensure you have proper authorization before scanning any network or system.\r\n- Comply with all applicable laws and regulations regarding network scanning in your jurisdiction.\r\n- Be aware that network scanning may be interpreted as malicious activity by network administrators and may trigger security alerts.\r\n- The authors and contributors of this SDK are not responsible for any misuse or damage caused by this software.\r\n- Network scanning may cause disruption to services or systems; use appropriate bandwidth and rate limiting settings.\r\n\r\nBefore using this SDK for any network scanning operation, especially on production networks, consult with network administrators and obtain proper written permission.\r\n\r\n## License\r\n\r\nMIT\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhappyhackingspace%2Fzmapsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhappyhackingspace%2Fzmapsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhappyhackingspace%2Fzmapsdk/lists"}