🛡️ NetSentry

AI-assisted network security auditor. Scan a network you own or are authorized to test, and let Claude turn raw scan data into a prioritized security report — severities, weakness classes (CWE), likely CVEs, and concrete remediation steps.

Built for the Microsoft Hackathon · Creative Apps track (AI-assisted development).

   scan (pure-Python, async)  ──▶  heuristics (offline)  ──▶  Claude analysis  ──▶  report
   hosts · ports · banners        risky-exposure rules        opus-4-8, structured     md / json / html

---

Why it's interesting

Most scanners hand you a wall of open ports and leave the interpretation to you. NetSentry does the interpretation: it fingerprints services, applies a deterministic risk knowledge base, then asks Claude to reason about attacker value, rank issues by real impact, and write remediation a human can act on — with an executive summary for non-specialists and a CI-friendly exit code for gating.

• No external scanner needed — pure-Python async TCP scanning. No nmap, no root.
• Bring your own AI — analyze with Claude, GitHub Copilot / Models, or a local Ollama model. Auto-selects whatever is configured.
• Works offline — if no AI is configured, deterministic heuristics still produce a useful report.
• Defensive by design — recommends fixes only; requires an authorization acknowledgment before scanning.
• Three surfaces — CLI, FastAPI web dashboard, and Markdown/JSON/HTML reports.

AI providers

Pick a backend with --provider (CLI) or the dashboard dropdown. auto (default) uses the first one configured, falling back to offline heuristics.

Provider	Select with	Configure	Default model
Claude (Anthropic)	--provider claude	ANTHROPIC_API_KEY	claude-opus-4-8
GitHub Copilot / Models	--provider copilot	GITHUB_MODELS_TOKEN (or GITHUB_TOKEN)	openai/gpt-4o
Ollama (local)	--provider ollama	ollama serve running (OLLAMA_HOST)	llama3.1
Heuristic (offline)	--provider heuristic / --no-ai	nothing	—

Override the model per run with --model (CLI) or the Model field (dashboard). Run netsentry x --list-providers to see what's configured. Claude uses the SDK's structured outputs; Copilot and Ollama use a JSON-schema-instructed prompt over their HTTP APIs (stdlib only, no extra deps).

---

Install

pip install -e ".[web]"        # core + web dashboard
# or: pip install -r requirements.txt

cp .env.example .env           # add your ANTHROPIC_API_KEY (optional — heuristics work without it)

Requires Python 3.10+.

Usage — CLI

# Scan your local subnet, AI-analyzed Markdown report to stdout
netsentry 192.168.1.0/24

# Custom ports, HTML report to a file
netsentry scanme.example.com -p 22,80,443,8000-8100 -f html -o report.html

# Analyze with a specific provider/model
netsentry 10.0.0.5 --provider copilot --model openai/gpt-4o-mini
netsentry 10.0.0.5 --provider ollama --model llama3.1

# Offline only (no AI), machine-readable JSON
netsentry 10.0.0.5 --no-ai -f json

# See which providers are configured
netsentry x --list-providers

# Non-interactive (skip the authorization prompt) — for automation you control
netsentry 10.0.0.0/24 -y -f json -o scan.json

Exit codes: 0 clean · 3 critical/high findings present (handy in CI) · 1 aborted/unauthorized · 2 bad arguments.

Usage — Web dashboard

python -m netsentry.web          # → http://127.0.0.1:8787
# or: uvicorn netsentry.web.app:app --reload

Enter a target, tick "I am authorized to scan this target", and run. Results render with a risk score, severity breakdown, prioritized fix list, and per-finding remediation.

API: POST /api/scan with {"target": "...", "ports": "22,80", "use_ai": true, "authorized": true}.

---

How it works

Stage	Module	What it does
Scan	scanner.py	Async TCP-connect scan over a CIDR/host list; banner grab + service fingerprint.
Knowledge	knowledge.py	Port→service map and deterministic risky-exposure rules (unauth data stores, cleartext protocols, exposed admin/RDP/VNC…).
Analysis	analyzer.py + providers.py	Sends the factual scan to the chosen provider (Claude / Copilot / Ollama) and returns a schema-validated Assessment. Falls back to offline heuristics when no provider is configured or a call fails.
Report	report.py	Renders Markdown, JSON, or a standalone styled HTML report.

Every provider returns the same Pydantic Assessment, so the model's output is validated against the structure the rest of the app expects — no brittle JSON string-parsing. Claude uses the Anthropic SDK's messages.parse() structured outputs; the Copilot and Ollama providers use a JSON-schema-instructed prompt over their HTTP APIs (standard-library urllib — no extra dependencies).

---

⚠️ Authorized use only

NetSentry is a defensive tool. Scan only systems you own or have explicit, documented permission to test. Unauthorized port scanning may be illegal in your jurisdiction. The CLI and dashboard both require you to confirm authorization before a scan runs.

Development

pip install -e ".[dev,web]"
pytest                          # 18 tests: parsing, live localhost scan, heuristics, reports

License

MIT