vulscan-mcp

A client-deployable vulnerability & PII scanning platform with a central MCP server — a Telivy-style tool for MSPs. A lightweight agent is deployed to client endpoints (or run via RMM), runs a suite of scanners, and reports findings back as structured reports. A central MCP server exposes the fleet's findings to Claude so an analyst can review risk in natural language.

Inspired by RobertoDure/mcp-vulnerability-scanner, extended into an agent-based, multi-scanner, multi-client platform.

⚠️ Authorized use only. Deploy and scan only against systems you are contractually authorized to assess. Reports reference the locations of sensitive data and store redacted previews only — never raw PII — but should still be treated as confidential.

What it does

Scanner	Status	What it finds
local_pii	✅ working	PII in local files (SSNs, credit cards, emails, phones, DOB, …)
system_vuln	✅ working	Outdated/vulnerable software (offline CVE ruleset), firewall/disk-encryption posture, OS end-of-life
network_vuln	✅ working	Open ports, exposed/risky services, version-matched CVEs, and optional nmap vulners CVEs
sharepoint_pii	✅ working	PII in SharePoint/OneDrive document libraries via Microsoft Graph

All four scanners run end-to-end. The two PII scanners currently read text-like files directly; Office/PDF extraction is a shared, documented extension point.

Architecture

vulscan/
├── common/      Shared models (Finding, ScanReport), config, PII engine
├── scanners/    Scanning engines (one file each, common Scanner interface)
├── agent/       Deployable client agent (CLI + report delivery)
├── server/      Central MCP server + report store
└── reporting/   JSON / HTML / PDF report generation

The agent and server share the common models, so a report produced on an endpoint deserializes cleanly on the server and renders identically everywhere.

See docs/mcp.md for the MCP server and deploy/README.md for packaging/deployment.

Quick start

# Install (base agent, no optional extras needed for local_pii)
pip install -e .

# See available scanners and whether each can run here
vulscan-agent list

# Run a local PII scan and write JSON + HTML reports
vulscan-agent scan local_pii --path ./some/dir --client-name "Acme Corp"

# Reports land in ./scan-output/ by default

Add optional capabilities as needed:

pip install -e '.[docs]'      # PDF/DOCX/XLSX text extraction for PII scanning
pip install -e '.[m365]'      # SharePoint/OneDrive scanning
# network_vuln needs only the `nmap` binary on the host (no Python package)
pip install -e '.[pdf]'       # PDF reports
pip install -e '.[server]'    # the central MCP server
pip install -e '.[all,dev]'   # everything + test/lint tooling

The central server (two processes)

pip install -e '.[server]'
# 1) Receive agent uploads over HTTP (agents POST reports here):
VULSCAN_DATA_DIR=/var/lib/vulscan VULSCAN_API_KEY=secret vulscan-ingest
# 2) Answer analyst queries over MCP (point Claude Desktop at this):
VULSCAN_DATA_DIR=/var/lib/vulscan vulscan-server

Agents upload by setting --client-id, VULSCAN_SERVER_URL, and VULSCAN_API_KEY; reports are also always written locally. See docs/mcp.md.

Enriching the CVE ruleset from NVD (optional)

vulscan-update-vulndb -p openssl -p openssh -p "google chrome" -o vulndb-cache.json
VULSCAN_VULNDB=vulndb-cache.json vulscan-agent scan system_vuln   # uses the cache

Configuration

Copy config.example.toml to config.toml, or use VULSCAN_* environment variables (env wins over file). Secrets should come from env vars / RMM site variables, never the committed file. Key settings:

• agent.client_id / client_name — which client this deployment is for
• agent.server_url / api_key — where to upload reports (optional)
• agent.local_pii_paths — default paths for the local PII scanner
• agent.network_targets — default hosts/CIDRs for the network scanner
• agent.m365.* — Microsoft Graph credentials for SharePoint scanning
• server.* — ingest host/port, API key, and optional Autotask PSA ticketing

Development

pip install -e '.[all,dev]'
pytest            # run the test suite
ruff check .      # lint

Roadmap

• [x] Implement system_vuln (software inventory + offline CVE ruleset + posture checks)
• [x] Implement network_vuln (nmap XML → exposed services + CVE findings)
• [x] Implement sharepoint_pii (Graph enumeration + PII engine)
• [x] Enrich the CVE ruleset from the NVD feed (vulscan-update-vulndb)
• [x] PDF/DOCX/XLSX text extraction for the PII scanners (docs extra)
• [x] HTTP ingest endpoint (/api/reports) on the server (vulscan-ingest)
• [x] Autotask PSA ticket reporting (central-server ingest hook)
• [ ] Additional reporting integrations (Datto RMM alerts, Outlook email digests)
• [ ] Presidio-backed PII detection behind the existing engine interface
• [ ] Legacy Office (.doc/.xls/.ppt) extraction; historical scan-to-scan diffing