PyNetworkIntel

Discover what's on your network. Map how it's connected. Find what's vulnerable.

PyNetworkIntel scans a network target with nmap, optionally pulls configuration from reachable devices over SSH, checks discovered services against known vulnerability rules and the NVD CVE database, and derives a subnet/gateway topology graph from the results - in plain Python, with no hidden network calls beyond nmap/SSH/NVD/(optional) Anthropic.

Before you scan anything

This tool actively probes network hosts. Only scan networks and devices you own or have explicit written permission to test. Unauthorized network scanning may be illegal in your jurisdiction. Both the CLI and the underlying commands require you to confirm authorization before a scan runs (see Security below) - this isn't a formality, it's there so the tool never scans a target silently just because it was handed one.

30-Second Start

pip install pynetworkintel
# nmap must also be installed and on PATH (brew install nmap / apt install nmap / etc.)

pynetworkintel scan 192.168.1.0/24
# -> prompts to confirm you're authorized to scan this target, then runs

from pynetworkintel import Scanner

scanner = Scanner()  # no SSH by default - see "SSH config grabbing" below
result = scanner.scan("192.168.1.0/24")

for device in result.devices:
    print(f"{device.ip} ({device.hostname or 'unknown'})")
    for service in device.services:
        print(f"  - {service.name} {service.version or ''} on port {service.port}")

print(result.topology().to_dict())  # subnet groupings + inferred gateway edges

Use cases

• A one-off network inventory — pynetworkintel scan <subnet> for "what's actually on this network right now," with a real topology graph, not a flat list.
• Recurring drift/change detection — repeated scans against the same SQLite history to catch new/removed devices between runs.
• Pairing discovery with vulnerability triage — analyze cross-checks discovered services against config-based rules and live NVD CVE lookups in one pass.
• Not yet a good fit for: enterprise multitenancy/HA/auth/REST API, or a conversational architecture advisor — both are explicitly excluded from the package (see Module status), not partially built.

Key Features

• Device discovery - nmap -sV based host/port/service discovery (pynetworkintel.discovery)
• Topology mapping - a real graph (nodes/edges), not just a flat device list: devices are grouped into inferred subnets, with gateway-style edges derived from IP addressing (pynetworkintel.topology)
• Vulnerability detection - config-based rule checks (weak SSH settings, telnet exposure, etc.) plus live NVD CVE lookups by service/version (pynetworkintel.analysis)
• Optional SSH config grabbing - pulls sshd_config, firewall rules, etc. from devices you have credentials for, concurrently across devices
• Change tracking - detects new/removed devices across scans, backed by a local SQLite/SQLAlchemy history (pynetworkintel.changes, pynetworkintel.db)
• Reports & alerts - Markdown/JSON reports, chat-webhook/email/generic webhook alert channels (pynetworkintel.reporting, pynetworkintel.alerts)
• Optional AI summary - plain-English findings summary via the Anthropic API, only when --summarize / summarize=True is used

vs nmap

PyNetworkIntel doesn't replace nmap - its own discovery step is an nmap -sV subprocess call (pynetworkintel/discovery/scanner.py). The honest comparison isn't "who scans faster," it's "what do you get beyond raw nmap output for roughly the same scan time."

Measured live against this machine's own local /24 (2026-09-22, 2 hosts up: a gateway router and this laptop - a small real network, not a lab fixture):

On this run, neither tool recovered version strings for the services found (router's https/pharos ports, laptop's postgresql/rtsp/http-proxy ports all fingerprinted as bare service names by nmap's own -sV probe) - so the live NVD CVE check correctly returned 0 findings rather than guessing. That's a real limitation of this specific network's service fingerprints, not a PyNetworkIntel bug - worth knowing before expecting CVE hits on a quiet home network.

Bottom line: if you just want "what's listening where," raw nmap is lighter-weight and has no Python dependency. PyNetworkIntel is worth it when you want the same scan turned into a structured, versioned, CVE-annotated, graphable asset inventory instead of scrollback text - at roughly a 9% time cost on top of the nmap call it already makes.

Installation

pip install pynetworkintel

Requires the nmap binary to be installed separately and on PATH (the Python package wraps it via subprocess; without it, discovery returns no results but the rest of the API still works, e.g. for testing).

Optional extras for the lighter-tested cloud/kubernetes asset-discovery modules (see Module status):

pip install "pynetworkintel[cloud]"       # boto3, azure-mgmt-*, google-cloud-*
pip install "pynetworkintel[kubernetes]"  # kubernetes python client

CLI Usage

# Scan a subnet (prompts for scan authorization the first time)
pynetworkintel scan 192.168.1.0/24

# Scan and grab SSH config from reachable devices (explicit --ssh-user required;
# there is no default user, on purpose - see Security below)
pynetworkintel scan 192.168.1.0/24 --ssh-user admin --ssh-key ~/.ssh/id_rsa

# Non-interactive / CI use: skip the confirmation prompt explicitly
pynetworkintel scan 192.168.1.0/24 --i-am-authorized

# Full pipeline: scan + vulnerability analysis + AI summary
pynetworkintel analyze 192.168.1.0/24 --summarize

# JSON output (includes devices, findings, and the topology graph)
pynetworkintel scan 192.168.1.0/24 --output json

# Save results to a file
pynetworkintel analyze 192.168.1.0/24 --output-file results.json

SSH passwords are never accepted as a CLI flag (they'd end up in shell history and process listings). Use --ssh-key or set PYNETWORKINTEL_SSH_PASSWORD in the environment instead.

Python API

from pynetworkintel import Pipeline

pipeline = Pipeline(
    ssh_username="admin",       # optional; omit to skip SSH config grabbing
    ssh_key_path="~/.ssh/id_rsa",
)
result = pipeline.run("192.168.1.0/24", summarize=False)

print(result["summary"])   # counts: devices, findings by severity, subnets
print(result["topology"])  # {"nodes": [...], "edges": [...], "subnets": [...]}
for finding in result["findings"]:
    print(finding["severity"], finding["title"])

Security

PyNetworkIntel is a dual-use network scanning tool, and the security posture of the tool itself is treated as a first-class concern, not an afterthought:

• Scan authorization is required. scan/analyze will not run without --i-am-authorized, PYNETWORKINTEL_I_AM_AUTHORIZED=1, or an interactive confirmation.
• No default SSH user. You must pass --ssh-user explicitly; the tool will not assume root (or anything else) on your behalf.
• No --ssh-password flag. Use --ssh-key or the PYNETWORKINTEL_SSH_PASSWORD environment variable.
• SSH passwords are never written to disk, including in the persisted config file (~/.pynetworkintel/config.yaml, which is chmod'd 0600).
• SSH host key verification uses paramiko.WarningPolicy (logs loudly on an unknown/changed host key rather than silently trusting it). See pynetworkintel/discovery/ssh_config.py for the documented tradeoff - first-contact scanning of arbitrary devices is fundamentally in tension with strict known-hosts verification.
• Scan targets are validated before reaching the nmap command line, rejecting anything that isn't a plausible IP/CIDR/hostname (in particular anything starting with -, which would otherwise be parsed as an nmap flag).
• Dependency versions are pinned with upper bounds in pyproject.toml.

See SECURITY.md for how to report a vulnerability.

Module status

Being direct about what's tested and what's real-but-lighter-tested vs. not shipped at all:

Requirements

• Python 3.10+
• nmap installed and on PATH for live scanning
• SSH access (key or password) to a device, only if you want config grabbing
• An Anthropic API key, only if you use --summarize

Documentation

• Dashboard - the live terminal stats viewer (--dashboard)
• CLAUDE.md - accurate architecture description for engineers (human or AI) working on this codebase
• ROADMAP_HONEST.md - current honest status: what's fixed, what's broken, what's a fake stub, what's genuinely pending, and technical debt with file:line specifics
• CHANGELOG.md, CONTRIBUTING.md, SECURITY.md

docs/ARCHITECTURE.md, docs/PRODUCT_VISION.md, and docs/ROADMAP.md are stale/placeholder documents from earlier planning and are not kept in sync with the implementation (each now has an in-file banner saying so); refer to CLAUDE.md and ROADMAP_HONEST.md instead. docs/VERSION_MANAGEMENT.md was corrected in this pass and is accurate.

Known Issues

• Lighter-tested modules: cloud, kubernetes, iot, ml, and devops are real, shipped code but have less test coverage than the core scan -> analyze -> topology path; see Module status.
• Stale planning docs: docs/ARCHITECTURE.md, docs/PRODUCT_VISION.md, and docs/ROADMAP.md predate the current implementation and are not kept in sync - each now carries an in-file banner saying so; use CLAUDE.md and ROADMAP_HONEST.md for accurate descriptions instead.
• Misleading git tag: the local v2.0.0 tag points at a commit older and less complete than v1.4.0 (an out-of-order/mislabeled tag from earlier history) - don't trust tag names as a version indicator; see ROADMAP_HONEST.md.
• paramiko 3.5.1 has an open advisory (PYSEC-2026-2858, SHA-1 allowed in rsakey.py) with no fixed release available yet as of this pass; see ROADMAP_HONEST.md for tracking.
• No committed performance benchmarks. There is no benchmark script or results file in this repo, so no throughput/latency numbers are claimed anywhere in this README.
• No open GitHub issues and no TODO/FIXME markers in pynetworkintel/ as of this pass (though there is real lint debt - 23 bare except: clauses and ~48 files not black-formatted; see ROADMAP_HONEST.md).
• pynetworkintel/__init__.py's __version__ had drifted to 1.3.1 while pyproject.toml moved on to 1.4.0 - fixed in this pass, and scripts/check-version-sync.sh now checks both files so it won't silently recur.

License

This project is licensed under the Apache License 2.0.