NeuralScan

Auto-detect every AI agent, MCP server, and data connector running on your machine — and watch them light up in a live NEXUS-style neural map, with governance, data classification, and behavioral anomaly detection.

NeuralScan is a local, zero-database daemon that scans your host for AI infrastructure (MCP server configs, running LLM processes, open local-LLM ports, API keys in .env files, AI IDE extensions, and the connector catalogs of Claude, ChatGPT, GitHub Copilot, and Perplexity), probes MCP servers for the tools they expose, and renders the whole topology as an animated force-directed graph in your browser.

On top of inventory, NeuralScan is a security posture tool:

• Capability & risk classifier — tags each connector read / write / exec / network, scores risk low→critical, and maps its blast radius (your files / the internet / your machine).
• Data classification — infers what kind of sensitive data each connector and MCP tool can touch (PII, FINANCIAL, PCI, HEALTH, CREDENTIALS, …) and raises HIPAA / PCI / GDPR / SOX compliance flags.
• Policy engine — YAML policies evaluated every scan; violations surface in the dashboard and an immutable, hash-chained audit log.
• Behavioral baselines — learns what "normal" looks like over time and flags anomalies (new high-risk connector, capability expansion, risk escalation, exfil-capable connector appeared, …).

Everything stays on localhost. No telemetry. API key values are never read or transmitted — only key names.

Install

npm install -g neuralscan
neuralscan start --open      # opens http://localhost:4000/

Or run without installing:

npx neuralscan start --open

On first launch the dashboard shows a setup screen to pick which AI tools you use (Claude, ChatGPT, GitHub Copilot, Perplexity, local LLMs); the map focuses on those and the connectors linked to them. Change it anytime from the ⚙ button.

Quick start

# from the project directory
npm install
node src/index.js start --open

Or, once published / linked globally:

npm install -g neuralscan
neuralscan start --open

Then open http://localhost:4000/.

CLI

| Command | What it does | | --- | --- | | neuralscan start | Start the daemon in the foreground | | neuralscan start --bg | Start as a detached background process | | neuralscan start --open | Start and open the dashboard | | neuralscan stop | Stop the background daemon | | neuralscan scan | Run one scan, print topology JSON to stdout | | neuralscan scan --pretty | Pretty-printed JSON | | neuralscan scan --no-probe | Skip MCP tools/list probing (faster) | | neuralscan status | Human-readable summary of what's detected | | neuralscan watch | Continuously re-scan and print changes | | neuralscan open | Open the dashboard (starts the daemon if needed) | | neuralscan export -o file.json | Export the topology to a file | | neuralscan classify | Data-sensitivity summary (--report, --compliance, --node <id>) | | neuralscan anomalies | Behavioral anomalies from the latest scan (--history) | | neuralscan baseline | Per-node behavioral baselines (--node <id>, --reset) | | neuralscan policy [list\|check\|risk\|install] | Governance policies & risk score | | neuralscan audit | Immutable audit log (--summary, --tail, --verify, --export) |

Add --port <n> to any daemon command (default 4000).

What it detects

| Scanner | Source | | --- | --- | | mcp-config | claude_desktop_config.json (macOS/Win/Linux), ~/.cursor/mcp.json, Windsurf config, project .mcp.json (CWD + 3 parents), ~/mcp.json | | process | ps aux / wmic — Ollama, LM Studio, LocalAI, llama.cpp, vLLM, text-generation-webui, Claude/Cursor/Windsurf/Copilot, and any process named after a known provider | | ports | TCP-probes 11434, 1234, 8080, 8000, 5000, 3000, 8888, 11435, 1337, 7860, 8501 (200 ms each, in parallel); fingerprints via /api/tags, /api/version, /v1/models | | env-keys | .env files in ~, CWD + 4 parents, ~/projects/*; 30+ provider/connector key patterns. Names only, never values. | | vscode | AI extensions in VS Code / Cursor extension dirs + AI/MCP keys in settings.json |

Probers

• mcp-prober — spawns each stdio MCP server (or POSTs to HTTP/SSE ones), runs initialize + tools/list, and surfaces each tool as a capability sub-edge.
• health-prober — pings port-backed nodes every 30 s and pushes online / degraded / offline + latency over WebSocket.

API

Daemon runs on http://localhost:4000 (CORS open — it's localhost-only).

| Method | Endpoint | Description | | --- | --- | --- | | GET | /health | { status, version, uptime } | | GET | /api/topology | Full topology JSON (latest scan) | | GET | /api/nodes | Just the nodes array | | GET | /api/scan | Trigger a fresh scan, return new topology | | GET | /api/node/:id | Single node details + tools | | POST | /api/node/:id/probe | Force re-probe one node | | GET | / | The NEXUS dashboard | | WS | /ws | Live topology_update / node_update / scan_start pushes |

Topology shape

{
  "scanTime": "2026-05-31T18:00:00.000Z",
  "hostInfo": { "os": "...", "hostname": "...", "nodeVersion": "v22.18.0" },
  "hub": { "id": "local-ai-hub", "name": "AI Hub", "label": "Multi-LLM", "providers": ["Claude","OpenAI"] },
  "nodes": [ { "id": "...", "name": "...", "type": "mcp-server", "status": "online", "tools": [...], "metadata": {} } ],
  "edges": [ { "id": "...", "from": "...", "to": "local-ai-hub", "type": "data-flow", "label": "mcp" } ]
}

The hub label is derived from detected LLMs: a single Claude key → Claude; Claude + OpenAI → Multi-LLM; only local models → Local LLM.

Dashboard

• Force-directed neural map on <canvas>; drag nodes, scroll to zoom, drag background to pan.
• Click a node for details + its MCP tool list. MCP nodes have a Re-probe button.
• Rescan FAB triggers GET /api/scan; the graph animates new nodes in and fades removed ones out.
• Live status dot reflects the WebSocket connection; node status dots update from the health prober.
• If the daemon isn't reachable, an overlay shows install instructions and a retry button.
• Each node shows the detected tool's real brand logo (GitHub, PostgreSQL, Redis, MongoDB, Claude, Mistral, Ollama, Qdrant, Notion, Linear, …), rendered in the brand's colour. Brands not covered by the logo set fall back to a clean monogram badge.

Node colours (hex border + glow encode the type; the logo encodes the brand): LLM provider (teal), MCP server (blue), local LLM (violet), data connector (gold), IDE extension (green), API key (blue, small).

Brand logos

Logos are baked into src/dashboard/icons.js from simple-icons (CC0 1.0) at build time — the dashboard ships them statically and needs no runtime dependency. To refresh or extend the set, edit the WANT map in scripts/build-icons.mjs and run:

npm run build:icons

Logos are used purely for nominative identification of the tools NeuralScan detects.

Authentication (optional OAuth/SSO)

NeuralScan is open on localhost by default — no login, zero config. For shared machines or when you expose it beyond localhost, you can turn on OAuth/SSO login (Google and/or GitHub). It's opt-in and stays off until you configure it.

neuralscan auth init        # scaffold ~/.neuralscan/auth.json (auth stays OFF)
neuralscan auth status      # show providers / allowlist / enabled state
neuralscan auth enable      # flip it on (after configuring), then restart

Setup:

1. Register an OAuth app — GitHub (https://github.com/settings/developers) and/or Google (https://console.cloud.google.com/apis/credentials).
2. Set the callback URL to http://localhost:4000/auth/github/callback (and/or .../google/callback).
3. Put the client id/secret into ~/.neuralscan/auth.json, add your account to allowedUsers (e.g. "[email protected]" or "github:yourlogin"), set "enabled": true.

When enabled, the dashboard, every /api/* route, and the WebSocket all require a valid session. Sessions are stateless signed cookies (HMAC, httpOnly, 7-day TTL); no passwords are stored. The allowlist is fail-closed — if it's empty, nobody gets in. The flow uses the OAuth Authorization-Code grant with a signed state cookie for CSRF protection. Public paths: /health, /login, /auth/*.

Built local-first but seam-clean for a hosted multi-user deployment later.

State

In-memory while running; written to ~/.neuralscan/state.json on exit and restored on next start for an instant first paint. Background PID and logs live in ~/.neuralscan/. Auth config (with your OAuth secrets) lives in ~/.neuralscan/auth.json and is never part of the npm package.

Packaging a standalone binary

npx pkg . --targets node20-macos-arm64,node20-linux-x64,node20-win-x64

(The dashboard HTML is served from src/dashboard/ — include it as an asset when packaging.)

Privacy & scope

NeuralScan is read-only reconnaissance of your own machine. It never reads secret values, never phones home, and binds only to localhost. The optional network tap in src/scanners/network.js is disabled by default.

License

MIT