Async Python wrapper for Nmap
Run network scans, parse XML results into typed dataclasses, and integrate Nmap into modern asyncio applications.
| Information | Value |
|---|---|
| Version | 0.1.5 |
| Python | 3.11+ |
| License | MIT |
| PyPI | https://pypi.org/project/netrax/ |
| Repository | https://github.com/code-1py/NetraX |
| Issues | https://github.com/code-1py/NetraX/issues |
Note: netrax requires Nmap to be installed on your system. Nmap is a separate open-source tool distributed under the Nmap Public Source License. NetraX does not bundle or redistribute Nmap — it invokes it as an external process.
- Fully async — built on
asyncio, no blocking calls - 7 built-in scan types — service, SYN, UDP, OS, aggressive, ping, and fully custom
- Typed dataclass models — structured access to every field in the Nmap XML output
- Rich exception hierarchy — granular error handling for timeouts, bad targets, missing Nmap, and more
- Configurable timeouts — global defaults or per-scan overrides
- Admin privilege check — fails fast with a clear error if root/administrator access is missing
- JSON and dict export —
report.to_dict()andreport.to_json()built in - Zero dependencies — uses only the Python standard library
- Python 3.11+
- Nmap installed and available in
PATH - Administrator / root privileges (required by Nmap for most scan types)
pip install netraxThen make sure Nmap is installed on your system:
| OS | Command |
|---|---|
| Ubuntu / Debian | sudo apt install nmap |
| Fedora / RHEL | sudo dnf install nmap |
| macOS | brew install nmap |
| Windows | Download from nmap.org |
import asyncio
import netrax
async def main():
scanner = netrax.Scanner()
# Service and version detection
report = await scanner.service_scan("192.168.1.1")
for host in report.hosts:
for addr in host.address:
print(f"Host: {addr.addr}")
for port in host.ports:
print(port.portid, port.state.state, port.services.name)
asyncio.run(main())All scan methods return a ScanReport object.
| Method | Nmap Flag | Description |
|---|---|---|
service_scan(target) |
-sV |
Service and version detection |
syn_scan(target) |
-sS |
TCP SYN scan (fast, stealthy) |
udp_scan(target) |
-sU |
UDP port scan |
os_scan(target) |
-O |
Operating system detection |
aggressive_scan(target) |
-A |
OS + version + scripts + traceroute |
ping_scan(target) |
-sn |
Host discovery only (no port scan) |
scan(target, *arguments) |
custom | Pass any Nmap flags directly |
report = await scanner.scan(
"10.0.0.0/24",
"-sV",
"-O",
"-T4",
"--open",
)Every scan method accepts an optional timeout parameter (seconds). If omitted, the global default is used.
# Per-scan timeout
report = await scanner.aggressive_scan("192.168.1.1", timeout=300)
# Change the global default
from netrax.config import timeouts
timeouts.DEFAULT_SCAN_TIMEOUT = 120Note: Slow timing templates (
-T0,-T1,-T2) will trigger an automatic warning suggesting you increase the timeout.
ScanReport is a fully typed dataclass. You can access every field directly, or export to dict/JSON.
report = await scanner.service_scan("192.168.1.1")
# Access structured data
for host in report.hosts:
for addr in host.address:
print(f"IP: {addr.addr} Type: {addr.addrtype}")
for port in host.ports:
svc = port.services
print(f"Port {port.portid}/{port.protocol} — {port.state.state}")
if svc:
print(f" Service: {svc.name} {svc.product} {svc.version}")
# Export
data = report.to_dict()
json_str = report.to_json(indent=4)
raw_xml = report.raw_xmlScanReport
├── nmaprun (NmapRun) — scanner metadata, args, version
├── scaninfo (ScanInfo) — scan type, protocol, service count
├── verbose_level (int)
├── debugging_level (int)
├── raw_xml (str) — raw Nmap XML output
└── hosts (list[Host])
├── starttime / endtime
├── address (list[Address]) — IP and MAC addresses
├── hostnames (list[HostName])
├── extraports (ExtraPorts)
├── times (Times) — RTT statistics
└── ports (list[Port])
├── portid / protocol
├── state (State) — open/closed/filtered + reason
└── services (Service) — name, product, version, tunnel
from netrax.exceptions import (
AdminRequiredError,
NmapNotFoundError,
NmapExecutionError,
ScanTimeoutError,
InvalidTargetError,
XmlParseError,
)
try:
report = await scanner.service_scan("192.168.1.1")
except AdminRequiredError:
print("Run as root / administrator.")
except NmapNotFoundError:
print("Nmap is not installed or not in PATH.")
except ScanTimeoutError as e:
print(f"Scan timed out after {e.timeout}s.")
except NmapExecutionError as e:
print(f"Nmap error (exit {e.returncode}): {e.stderr}")
except XmlParseError:
print("Could not parse Nmap XML output.")NetraxError (base)
├── AdminRequiredError
├── NmapNotFoundError
├── NmapExecutionError
├── ScanTimeoutError
├── ProcessTimeoutError
├── InvalidTargetError
├── InvalidScanProfileError
├── XmlParseError
├── AIProviderError
└── ReportGenerationError
scanner = Scanner()Instantiating Scanner checks for root/administrator privileges immediately.
All scan methods are coroutines and must be awaited.
Run Nmap with arbitrary arguments.
Service and version detection (-sV).
TCP SYN scan (-sS).
UDP scan (-sU).
OS detection (-O).
Aggressive scan (-A): OS + version + scripts + traceroute.
Host discovery only (-sn).
| Method | Returns | Description |
|---|---|---|
to_dict() |
dict |
Full report as a Python dictionary |
to_json(indent=None) |
str |
Full report as a JSON string |
from netrax.config import timeouts
timeouts.DEFAULT_SCAN_TIMEOUT = 120 # seconds (default: 60)
timeouts.NMAP_LOCATE_TIMEOUT = 5 # seconds (default: 3)GitHub: https://github.com/code-1py
NetraX is released under the MIT License.
This project invokes Nmap as an external subprocess. Nmap is not bundled with NetraX and is distributed under its own Nmap Public Source License. Users are responsible for complying with Nmap's license and all applicable laws when performing network scans. Only scan networks and systems you own or have explicit permission to scan.