network-scanner

Scan a /24 from your laptop and get a risk-ranked report on what's sitting on it.

ARP sweep finds the live hosts, nmap fingerprints them, then a local LLM (Ollama) walks the full device list and flags the things worth caring about: the cameras that are phone-home-capable, the unencrypted MQTT brokers, the streaming sticks with open admin ports, the router with seventeen services running when it should have three. Everything stays on the box. No cloud calls, no telemetry, no OpenAI or Anthropic dependencies, not even for the LLM step.

Legal

Scanning networks you don't own, or don't have explicit written permission to scan, is illegal under the CFAA, the UK Computer Misuse Act, and most equivalents elsewhere. The --confirm flag exists as a gate: passing it means you're asserting you own or have permission for the target subnet. If you're not sure whether you need permission, you do. No liability assumed for misuse.

Install

uv sync

For real scans you also need:

• nmap on PATH (brew install nmap / sudo apt install nmap)
• root for the ARP sweep (raw sockets)
• Ollama running with llama3.1:8b pulled (ollama pull llama3.1:8b)

Run

Mock mode: no privileges, no network, no Ollama:

scanner scan --mock
scanner scan --mock --output json
scanner history

Real scan, needs sudo + --confirm:

sudo scanner scan --subnet 192.168.1.0/24 --confirm

Skip Ollama on a real scan (use the deterministic mock LLM):

sudo MOCK_LLM=1 scanner scan --subnet 192.168.1.0/24 --confirm

/22 is the size cap. Anything larger needs --allow-large-subnet and you take responsibility for the load.

Troubleshooting

"Permission denied" on ARP sweep. Raw sockets need root. Re-run with sudo.

nmap not found. Install it: brew install nmap on macOS, sudo apt install nmap on Debian/Ubuntu.

Ollama refuses connection. ollama serve in another terminal, then ollama pull llama3.1:8b. Or set MOCK_LLM=1 and skip it.

Vendor column shows None for everything. The bundled data/oui.csv is a tiny curated subset, about nine rows. For a real run, refresh from the full IEEE registry: make download-oui. (If you've pinned OUI_EXPECTED_SHA256 and set OUI_VERIFY_SHA=1, the loader will reject a mismatched file and fall back to None, no vendor enrichment, but the scan still works.)

No hosts found. Check your interface, ip route or ifconfig. Wrong subnet is the common case.

IPv6. Not supported. ARP is v4-only and we haven't wired up NDP yet (see ROADMAP).

Environment variables

Variable	Default	Description
MOCK_LLM	0	Set to 1 to use the deterministic MockClient instead of Ollama.
SCANNER_HOST_TIMEOUT	30	Per-host nmap timeout in seconds. Overrides the CLI --scan-timeout default.
SCANNER_TOTAL_TIMEOUT	300	Aggregate wall-clock cap for the nmap loop across all hosts. Prevents a /24 scan from running for hours if ARP finds an unexpectedly large host set.
SCANNER_DB_PATH	~/.local/share/network-scanner/scans.db	Override SQLite database path. Must resolve under $HOME or /tmp/scanner-test unless SCANNER_ALLOW_DB_OUTSIDE_HOME=1 is also set.
SCANNER_ALLOW_DB_OUTSIDE_HOME	0	Set to 1 to allow SCANNER_DB_PATH to point outside the home directory.
OUI_VERIFY_SHA	0	Set to 1 to verify the OUI CSV against OUI_EXPECTED_SHA256 on load.
OUI_EXPECTED_SHA256	placeholder	Expected SHA-256 of the OUI CSV. Pin this after running make download-oui.

Non-goals

• No exploitation. No credential testing, no CVE lookups, no port knocking. Risk-ranking only.
• No internet-facing scanning. Home and lab subnets only. The --confirm flag won't let you scan something you don't own.
• No data leaves the machine. The LLM runs locally; scan results go to a local SQLite DB.