# 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`](https://github.com/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`](docs/mcp.md) for the MCP server and [`deploy/README.md`](deploy/README.md)
for packaging/deployment.

## Quick start

```bash
# 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:

```bash
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)

```bash
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`](docs/mcp.md).

### Enriching the CVE ruleset from NVD (optional)

```bash
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

```bash
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
```