NetDocIT

NetDocIT is a Windows-first network discovery and documentation tool. It collects interface and route information, performs live host discovery, enriches data with host and SNMP details, and exports topology and inventory reports.

Requirements

For contributors, maintainers, and users forking this repository:

• Python 3.14+
• Windows PowerShell (for discovery scripts)

For end users using the packaged installer:

• No Python setup required

Installation

Using uv:

uv sync

Using pip:

python -m pip install -e .

Quick Start

Run full discovery and generate reports:

uv run netdocit scan

Run report generation from stored data:

uv run netdocit report

Generate topology from stored data:

uv run netdocit map

Open interactive dashboard:

uv run netdocit

Outputs

• REPORT.md: Markdown inventory report
• inventory.html: Printable HTML inventory dashboard
• topology.html: Interactive topology map
• data/netdocit.sqlite: Local scan database

Generated report/map artifacts are intended as runtime outputs and can be regenerated on demand.

Source Of Truth

• SNMP enrichment source of truth: src/backend/snmp_engine.py (Python pysnmp implementation)

Version Control Policy

• Commit source code, tests, templates, and configuration
• Do not rely on committed generated artifacts for operational state
• Regenerate REPORT.md, inventory.html, and topology.html from current scan data when needed

Commands

• scan / discover: Run full discovery pipeline
• report: Build report artifacts from database state
• map: Build topology artifact from database state
• logs: Show persisted scanner logs
• schedule --time HH:mm: Register daily scheduled scan task (Administrator required)

Secret Hygiene (Wave 4.3)

• Production mode expects SNMP communities from an external JSON file path set by NETDOCIT_SECRETS_FILE.
• Legacy data/config.json credentials remain available for backward-compatible development mode.
• If legacy credentials are empty in development mode, NetDocIT falls back to built-in default guesses (public, monitor, read-only).
• When NETDOCIT_ENV=production and no external secrets file is configured, scans continue but credential loading failures are explicit in run metadata and logs.

Example external secrets file:

{
	"credentials": {
		"snmp": ["public", "monitor"]
	},
	"metadata": {
		"rotation_due": "2026-06-01T00:00:00",
		"expires_at": "2026-12-01T00:00:00"
	}
}

Usage:

$env:NETDOCIT_SECRETS_FILE = "C:\secrets\netdocit-secrets.json"
uv run netdocit scan --profile safe

Testing

python -m unittest discover -v

Notes

• The discovery pipeline is currently Windows-oriented because it depends on PowerShell scripts and Windows networking cmdlets.
• SNMP enrichment is handled in Python via pysnmp.