Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,6 @@
+__pycache__
+*.pyc
+.git
+tests
+*.db
+.env

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Dockerfile]
+indent_size = 4

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        args: [--ignore-missing-imports]
+        additional_dependencies:
+          - fastapi
+          - uvicorn
+          - httpx
+          - jinja2
+          - plotly
+          - pydantic
+          - rich
+        files: ^mcpscope/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files

CHANGELOG.md

@@ -0,0 +1,28 @@
+# MCPscop
+
+## [Unreleased]
+
+### Added
+- Security events API and dashboard views
+- JSON logging output
+- Dashboard authentication
+- MCPGuard event forwarder integration
+
+### Fixed
+- API key validation in REST endpoints
+- CORS headers for cross-origin dashboard access
+- HTML sanitization in scan result display
+
+## [0.1.0] - 2025-08-01
+
+### Added
+- Unified dashboard for MCP/A2A scanner results
+- FastAPI REST API for scan ingestion and querying
+- SQLite storage backends
+- Plotly-based interactive charts and visualizations
+- Support for Cisco MCP/A2A scanner output
+- Support for mcp-scan output
+- Support for MCPwn output
+- SARIF format ingestion
+- Rich CLI output for terminal usage
+- Scan comparison and trend analysis

CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing our standards.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Thanks for your interest in MCP-Scope!
+
+## Development Setup
+
+```bash
+git clone https://github.com/Carlos-Projects/mcpscope
+cd mcpscope
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest -v
+```
+
+All tests must pass before submitting a PR.
+
+## Code Style
+
+- Format: `ruff format .`
+- Lint: `ruff check .`
+- No commented-out code
+- Type hints required for all public functions
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Write tests for your changes
+3. Ensure all tests pass
+4. Update `CHANGELOG.md` if applicable
+5. Open a PR with a clear description
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new scanner parser
+fix: handle null severity in report
+deps: bump fastapi to 0.136.0
+docs: update README badges
+```
+
+## Adding a New Scanner
+
+1. Create `mcpscope/ingest/new_scanner.py` extending `BaseParser`
+2. Implement `parse()` and set `SCANNER_NAME`
+3. Add to `PARSERS` dict in `cli.py`
+4. Create test fixtures in `tests/fixtures/`
+5. Add tests in `tests/test_parsers.py`
+6. Update `README.md` supported scanners table
+
+## Reporting Issues
+
+Open a [GitHub Issue](https://github.com/Carlos-Projects/mcpscope/issues/new/choose) using the appropriate template.

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY mcpscope/ mcpscope/
+
+RUN pip install --no-cache-dir -e .
+
+EXPOSE 8080
+
+VOLUME /root/.mcpscope
+
+CMD ["mcpscope", "serve", "--host", "0.0.0.0", "--port", "8080"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP-Scope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,19 +1,225 @@
+<div align="center">
+
+# MCP-Scope
+
+**Unified security dashboard for MCP/A2A scanner results**
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![Tests](https://img.shields.io/github/actions/workflow/status/Carlos-Projects/mcpscope/scan.yml?label=tests)](https://github.com/Carlos-Projects/mcpscope/actions)
+[![License](https://img.shields.io/github/license/Carlos-Projects/mcpscope)](LICENSE)
+[![GitHub release](https://img.shields.io/github/v/release/Carlos-Projects/mcpscope)](https://github.com/Carlos-Projects/mcpscope/releases)
+[![Code style](https://img.shields.io/badge/code%20style-ruff-261230)](https://docs.astral.sh/ruff)
+
 ---
-title: MCP-Scope
-emoji: 📊
-colorFrom: blue
-colorTo: purple
-sdk: docker
-pinned: false
-app_port: 8080
-fullWidth: true
-short_description: Unified security dashboard for MCP/A2A scanner results
----
 
-# MCP-Scope 📊
+</div>
+
+Consumes output from multiple MCP/A2A security scanners (Cisco MCP Scanner, Cisco A2A Scanner, mcp-scan, MCPwn, SARIF) and presents a consolidated view of your security posture via a web dashboard, REST API, and CLI.
+
+## Quick Start
+
+```bash
+pip install -e .
+
+# Generate demo data and explore
+mcpscope seed
+mcpscope serve
+
+# Run a scan directly against a server
+mcpscope scan mcp-scan https://mcp-server.example.com/mcp
+
+# Import results from different scanners
+mcpscope import cisco-mcp results.json
+mcpscope import cisco-a2a results.json
+mcpscope import mcpwn results.json
+mcpscope import sarif report.sarif
+
+# Export a compliance report
+mcpscope report --format csv --output report.csv
+
+# Backup/Restore
+mcpscope backup backup.db
+mcpscope restore backup.db
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `serve` | Start the FastAPI web dashboard |
+| `scan` | Run a scanner directly against a target |
+| `import` | Import scanner JSON/SARIF results into SQLite |
+| `report` | Export JSON, CSV, or PDF compliance report |
+| `seed` | Generate demo scan data |
+| `prune` | Delete scans older than N days |
+| `backup` | Backup the SQLite database |
+| `restore` | Restore the SQLite database from backup |
+| `config` | View or set configuration options |
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /` | Dashboard UI with filters and tabs |
+| `GET /findings/{id}` | Finding detail page |
+| `GET /docs` | Swagger UI |
+| `GET /api/health` | Health check |
+| `GET /api/scans` | List scans (paginated) |
+| `GET /api/scans/{id}` | Scan details with findings |
+| `GET /api/scans/{a}/diff/{b}` | Compare two scans |
+| `GET /api/findings` | Query findings (paginated, filterable) |
+| `GET /api/findings/{id}` | Single finding |
+| `GET /api/stats/summary` | Aggregated statistics |
+| `GET /api/stats/top-tools` | Most vulnerable tools |
+| `GET /api/stats/severity-trend` | Findings over time |
+| `GET /api/stats/duplicates` | Deduplicated findings |
+| `GET /api/report/json` | Full JSON report |
+| `GET /api/report/csv` | CSV export |
+
+## API Usage Examples
+
+```bash
+# Health check
+curl http://localhost:8080/api/health
+
+# List scans (paginated)
+curl "http://localhost:8080/api/scans?page=1&page_size=10"
+
+# Get scan with findings
+curl http://localhost:8080/api/scans/scan-id-here
+
+# Query findings with filters
+curl "http://localhost:8080/api/findings?severity=critical&page=1"
+
+# Search findings
+curl "http://localhost:8080/api/findings?search=command"
+
+# Compare two scans
+curl "http://localhost:8080/api/scans/scan-a/diff/scan-b"
+
+# Get stats summary
+curl http://localhost:8080/api/stats/summary
+
+# Get duplicates
+curl http://localhost:8080/api/stats/duplicates
+
+# Export as CSV
+curl http://localhost:8080/api/report/csv -o report.csv
+
+# Full JSON report
+curl http://localhost:8080/api/report/json
+
+# With API key authentication
+curl -H "X-API-Key: your-key" http://localhost:8080/api/scans
+
+# Swagger docs
+open http://localhost:8080/docs
+```
+
+## Dashboard Features
+
+- **Overview tab** — Severity pie chart, top tools bar chart, severity trend over time
+- **Findings tab** — Filterable table with severity/scanner/tool/search, pagination, clickable rows for detail view
+- **Duplicates tab** — Grouped findings by tool + title + severity across scans
+- **Diff tab** — Side-by-side comparison between any two scans
+- **Scans tab** — Historical scan table with severity counts
+- **Auto-refresh** — Configurable auto-refresh interval
+- **Finding detail page** — Full details including raw JSON data
+
+## Supported Scanners
+
+| Scanner | CLI Name | Format |
+|---------|----------|--------|
+| Cisco MCP Scanner | `cisco-mcp` | `scan_results` with analyzer-grouped findings |
+| Cisco A2A Scanner | `cisco-a2a` | `findings` with AI Security Taxonomy metadata |
+| mcp-scan (Invariant Labs) | `mcp-scan` / `mcpscan` | `issues` array with severity codes |
+| MCPwn (ressl) | `mcpwn` | Standard findings with MCP-XXX IDs |
+| MCPwn (Teycir legacy) | `mcpwn` | Legacy test-based format |
+| SARIF | `sarif` | Standard SARIF 2.1 format |
+
+## Screenshots
+
+| Dashboard Overview | Findings Table |
+|---|---|
+| ![Overview](https://via.placeholder.com/600x300/1e293b/3b82f6?text=Severity+Pie+%2B+Trend+%2B+Top+Tools) | ![Findings](https://via.placeholder.com/600x300/1e293b/3b82f6?text=Filterable+Findings+Table) |
+| **Scan Diff** | **Finding Detail** |
+| ![Diff](https://via.placeholder.com/600x300/1e293b/3b82f6?text=Scan+Comparison) | ![Detail](https://via.placeholder.com/600x300/1e293b/3b82f6?text=Finding+Detail+View) |
+
+_Run `mcpscope seed && mcpscope serve` and open http://localhost:8080 to see the live dashboard._
+
+## CI/CD Integration
+
+Secure the API with an API key:
+```bash
+mcpscope config set api_key "your-secret-key"
+mcpscope serve
+# All /api/* endpoints now require: X-API-Key: your-secret-key
+```
+
+A [GitHub Actions workflow](.github/workflows/scan.yml) is included for automated scanning.
+
+Slack alerts for critical/high findings:
+```bash
+mcpscope config set slack_webhook_url "https://hooks.slack.com/services/..."
+```
+
+Webhook URLs for custom integrations:
+```bash
+mcpscope config set webhook_urls '["https://your-server.com/webhook"]'
+```
+
+## Configuration
+
+Config file at `~/.mcpscope/config.json`:
+
+```bash
+mcpscope config show
+mcpscope config set port 9090
+mcpscope config set auto_refresh_seconds 60
+mcpscope config set max_upload_mb 100
+```
+
+## Docker
+
+```bash
+docker build -t mcpscope .
+docker run -p 8080:8080 -v mcpscope-data:/root/.mcpscope mcpscope
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Security Events (MCPGuard Integration)
+
+MCP-Scope can receive real-time security events from MCPGuard:
+
+```bash
+# Configure MCPGuard's config.yaml:
+mcpscop_url: http://localhost:8000
+
+# Events appear in the "Live Events" dashboard tab
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/events` | POST | Ingest a security event |
+| `/api/events` | GET | List events (filters: severity, event_type) |
+| `/api/events/stats` | GET | Event statistics |
+| `/api/events` | DELETE | Clear all events |
+
+## Related Projects
+
+MCPscop is part of the **Carlos-Projects** security ecosystem for AI agents:
 
-**Unified security dashboard** for MCP/A2A scanner results.
+- [**MCPGuard**](https://github.com/Carlos-Projects/mcpguard) — Runtime security proxy for MCP/A2A protocols with HTMX dashboard
+- [**MCPwn**](https://github.com/Carlos-Projects/mcpwn) — Offensive security testing framework for MCP servers
+- [**Palisade Scanner**](https://github.com/Carlos-Projects/palisade-scanner) — Scan web content for prompt injection and adversarial content
+- [**AgentGate**](https://github.com/Carlos-Projects/agentgate) — Policy-based firewall and honeypot middleware for AI agents accessing websites
 
-Consumes output from MCPGuard, MCPwn, Cisco MCP Scanner, mcp-scan, SARIF.
+## License
 
-Visit the [GitHub repo](https://github.com/Carlos-Projects/mcpscope) for usage.
+[MIT](LICENSE)

SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in MCP-Scope, please report it privately.
+
+**Do not create a public GitHub issue.**
+
+Send details to: **carlos@aiagentobservatory.org**
+
+Please include:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Any suggested mitigation (optional)
+
+We will acknowledge receipt within 48 hours and provide a timeline for a fix.
+
+## Scope
+
+- The web dashboard (FastAPI)
+- The REST API
+- CLI commands that process external input
+- Dependencies with known CVEs
+
+## Out of Scope
+
+- The SQLite database file (local by default)
+- Scanner tools that MCP-Scope wraps (report issues to their respective projects)
+
+## Preferred Languages
+
+English or Spanish.

mcpscope/api/__init__.py

@@ -0,0 +1,3 @@
+from .server import create_app
+
+__all__ = ["create_app"]

mcpscope/api/routes.py

@@ -0,0 +1,476 @@
+from __future__ import annotations
+import csv
+import hmac
+import io
+import re
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Request, HTTPException, Query, Response
+from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
+
+from mcpscope.models.finding import Severity
+from mcpscope.models.security_event import SecurityEvent
+from mcp_taxonomy import (
+    AttackCategory, Severity as TaxSeverity, DetectionMethod,
+    palisade_finding_to_taxonomy,
+    mcpguard_event_to_taxonomy,
+    mcpwn_finding_to_taxonomy,
+    agentgate_signal_to_taxonomy,
+)
+from mcp_taxonomy.core import CATEGORY_SEVERITY
+
+router = APIRouter()
+PAGE_SIZE = 50
+
+_JS_UNSAFE_RE = re.compile(r"</[sS][cC][rR][iI][pP][tT]|<!\[CDATA\[|]]>")
+
+
+def _sanitize_js(val: str, max_len: int = 200) -> str:
+    s = str(val)
+    s = _JS_UNSAFE_RE.sub("", s)
+    s = s.replace("\0", "")
+    return s[:max_len]
+
+
+def _sanitize_tools(tools: list[dict]) -> list[dict]:
+    return [
+        {k: _sanitize_js(v) if isinstance(v, str) else v for k, v in t.items()}
+        for t in tools
+    ]
+
+
+def _sanitize_trend(trend: list[dict]) -> list[dict]:
+    return [
+        {k: _sanitize_js(v) if isinstance(v, str) else v for k, v in t.items()}
+        for t in trend
+    ]
+
+
+def get_store(request: Request):
+    return request.app.state.store
+
+
+def get_templates(request: Request):
+    return request.app.state.templates
+
+
+@router.get("/api/health")
+def health():
+    return {"status": "ok"}
+
+
+@router.get("/api/taxonomy")
+def taxonomy_info():
+    """Return the canonical taxonomy definition."""
+    return {
+        "attack_categories": [c.value for c in AttackCategory],
+        "severities": [s.value for s in TaxSeverity],
+        "detection_methods": [m.value for m in DetectionMethod],
+        "category_severity": {c.value: s.value for c, s in CATEGORY_SEVERITY.items()},
+    }
+
+
+@router.post("/api/taxonomy/normalize")
+def normalize_taxonomy(body: dict):
+    """Normalize a finding/event from any project into the canonical taxonomy."""
+    source = body.get("source", "")
+    raw = body.get("raw", body)
+    if source == "palisade-scanner":
+        event = palisade_finding_to_taxonomy(raw)
+    elif source == "mcpguard":
+        event = mcpguard_event_to_taxonomy(raw)
+    elif source == "mcpwn":
+        event = mcpwn_finding_to_taxonomy(raw)
+    elif source == "agentgate":
+        event = agentgate_signal_to_taxonomy(
+            signal_type=raw.get("signal_type", ""),
+            weight=raw.get("weight", 0),
+            action=raw.get("action", ""),
+            path=raw.get("path", ""),
+            user_agent=raw.get("userAgent", raw.get("user_agent", "")),
+            score=raw.get("score", 0),
+        )
+    else:
+        return JSONResponse({"error": f"Unknown source: {source}"}, status_code=400)
+    return JSONResponse({
+        "source": event.source,
+        "attack_category": event.attack_category.value,
+        "severity": event.severity.value,
+        "confidence": event.confidence.value,
+        "detection_method": event.detection_method.value if isinstance(event.detection_method, DetectionMethod) else event.detection_method,
+        "title": event.title,
+        "description": event.description,
+        "recommendation": event.recommendation,
+        "target": event.target,
+        "snippet": event.snippet[:200] if event.snippet else "",
+        "blocked": event.blocked,
+        "risk_score": event.risk_score,
+    })
+
+
+def _session_value(password: str, client_ip: str) -> str:
+    h = hmac.new(password.encode(), client_ip.encode(), "sha256")
+    return h.hexdigest()
+
+
+@router.get("/login", response_class=HTMLResponse)
+def login_page(request: Request):
+    templates = get_templates(request)
+    if not templates:
+        return HTMLResponse("<h1>Not found</h1>", status_code=500)
+    return templates.TemplateResponse(request, "login.html", {})
+
+
+@router.post("/api/login")
+def login(request: Request, response: Response, body: dict | None = None):
+    cfg = request.app.state
+    if not cfg.dashboard_password:
+        return JSONResponse({"error": "Dashboard auth not configured"}, status_code=403)
+    password = (body or {}).get("password", "")
+    if not hmac.compare_digest(password, cfg.dashboard_password):
+        return JSONResponse({"error": "Invalid password"}, status_code=401)
+    ip = request.client.host if request.client else ""
+    session = _session_value(cfg.dashboard_password, ip)
+    response.set_cookie(
+        key="mcpscope_session",
+        value=session,
+        max_age=86400,
+        httponly=True,
+        samesite="lax",
+        secure=False,
+    )
+    return {"status": "ok"}
+
+
+@router.post("/api/logout")
+def logout(response: Response):
+    response.delete_cookie("mcpscope_session")
+    return {"status": "ok"}
+
+
+@router.get("/api/scans")
+def list_scans(
+    request: Request,
+    page: int = Query(1, ge=1),
+    page_size: int = Query(PAGE_SIZE, ge=1, le=200),
+):
+    store = get_store(request)
+    scans, total = store.get_scans_paginated(page, page_size)
+    return {
+        "scans": [s.model_dump() for s in scans],
+        "total": total,
+        "page": page,
+        "page_size": page_size,
+        "pages": (total + page_size - 1) // page_size,
+    }
+
+
+@router.get("/api/scans/{scan_id}")
+def get_scan(
+    request: Request,
+    scan_id: str,
+    page: int = Query(1, ge=1),
+    page_size: int = Query(PAGE_SIZE, ge=1, le=200),
+):
+    store = get_store(request)
+    scan = store.get_scan(scan_id)
+    if not scan:
+        raise HTTPException(404, "Scan not found")
+    findings, total = store.get_findings(
+        scan_id=scan_id, page=page, page_size=page_size
+    )
+    return {
+        "scan": scan.model_dump(),
+        "findings": [f.model_dump() for f in findings],
+        "total": total,
+        "page": page,
+        "page_size": page_size,
+    }
+
+
+@router.get("/api/scans/{scan_id}/diff/{other_id}")
+def diff_scans(request: Request, scan_id: str, other_id: str):
+    store = get_store(request)
+    try:
+        result = store.diff_scans(scan_id, other_id)
+    except ValueError as e:
+        raise HTTPException(404, str(e))
+    return result
+
+
+@router.get("/api/findings")
+def list_findings(
+    request: Request,
+    scan_id: str | None = Query(None),
+    severity: str | None = Query(None),
+    tool_name: str | None = Query(None),
+    scanner: str | None = Query(None),
+    search: str | None = Query(None),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(PAGE_SIZE, ge=1, le=200),
+):
+    store = get_store(request)
+    findings, total = store.get_findings(
+        scan_id=scan_id,
+        severity=severity,
+        tool_name=tool_name,
+        scanner=scanner,
+        search=search,
+        page=page,
+        page_size=page_size,
+    )
+    return {
+        "findings": [f.model_dump() for f in findings],
+        "total": total,
+        "page": page,
+        "page_size": page_size,
+        "pages": (total + page_size - 1) // page_size,
+    }
+
+
+@router.get("/api/findings/{finding_id}")
+def get_finding(request: Request, finding_id: str):
+    store = get_store(request)
+    finding = store.get_finding(finding_id)
+    if not finding:
+        raise HTTPException(404, "Finding not found")
+    scan = store.get_scan(finding.scan_id)
+    return {
+        "finding": finding.model_dump(),
+        "scan": scan.model_dump() if scan else None,
+    }
+
+
+@router.get("/api/stats/top-tools")
+def top_tools(request: Request):
+    store = get_store(request)
+    return {"tools": store.get_top_tools()}
+
+
+@router.get("/api/stats/severity-trend")
+def severity_trend(request: Request):
+    store = get_store(request)
+    return {"trend": store.get_severity_trend()}
+
+
+@router.get("/api/stats/scanners")
+def list_scanners(request: Request):
+    store = get_store(request)
+    return {"scanners": store.get_scanners()}
+
+
+@router.get("/api/stats/tool-names")
+def list_tool_names(request: Request):
+    store = get_store(request)
+    return {"tools": store.get_tool_names()}
+
+
+@router.get("/api/stats/duplicates")
+def list_duplicates(request: Request):
+    store = get_store(request)
+    return {"duplicates": store.get_duplicates()}
+
+
+@router.get("/api/stats/summary")
+def summary(request: Request):
+    store = get_store(request)
+    history = store.get_scan_history()
+    top = store.get_top_tools()
+    dups = store.get_duplicates()
+    return {
+        "total_scans": len(history.scans),
+        "total_findings": history.total_findings,
+        "critical": history.total_critical,
+        "high": history.total_high,
+        "medium": history.total_medium,
+        "low": history.total_low,
+        "info": history.total_info,
+        "top_tools": top,
+        "duplicates": dups,
+        "scans": [s.model_dump() for s in history.scans],
+    }
+
+
+@router.get("/api/report/csv")
+def report_csv(request: Request):
+    store = get_store(request)
+    findings, _ = store.get_findings(page_size=100000)
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(
+        [
+            "id",
+            "scan_id",
+            "scanner",
+            "tool_name",
+            "severity",
+            "title",
+            "description",
+            "recommendation",
+            "cvss_score",
+            "cve_id",
+            "created_at",
+        ]
+    )
+    for f in findings:
+        sev = f.severity.value if isinstance(f.severity, Severity) else str(f.severity)
+        writer.writerow(
+            [
+                f.id,
+                f.scan_id,
+                f.scanner,
+                f.tool_name,
+                sev,
+                f.title,
+                f.description or "",
+                f.recommendation or "",
+                f.cvss_score or "",
+                f.cve_id or "",
+                f.created_at,
+            ]
+        )
+    return PlainTextResponse(
+        output.getvalue(),
+        media_type="text/csv",
+        headers={"Content-Disposition": "attachment; filename=mcpscope-report.csv"},
+    )
+
+
+@router.get("/api/report/json")
+def report_json(request: Request):
+    store = get_store(request)
+    history = store.get_scan_history()
+    top = store.get_top_tools()
+    trend = store.get_severity_trend()
+    dups = store.get_duplicates()
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "summary": {
+            "total_scans": len(history.scans),
+            "total_findings": history.total_findings,
+            "critical": history.total_critical,
+            "high": history.total_high,
+            "medium": history.total_medium,
+            "low": history.total_low,
+            "info": history.total_info,
+        },
+        "top_tools": top,
+        "duplicates": dups,
+        "severity_trend": trend,
+        "scans": [s.model_dump() for s in history.scans],
+    }
+
+
+@router.post("/api/events")
+async def ingest_event(request: Request):
+    store = get_store(request)
+    body = await request.json()
+    event = SecurityEvent(**body)
+    saved = store.save_event(event)
+    return {"status": "ok", "id": saved.id}
+
+
+@router.get("/api/events")
+def list_events(
+    request: Request,
+    limit: int = Query(50, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+    severity: str | None = Query(None),
+    event_type: str | None = Query(None),
+):
+    store = get_store(request)
+    events, total = store.get_events(
+        limit=limit,
+        offset=offset,
+        severity=severity,
+        event_type=event_type,
+    )
+    return {
+        "events": [e.model_dump() for e in events],
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+    }
+
+
+@router.get("/api/events/stats")
+def event_stats(request: Request):
+    store = get_store(request)
+    return store.get_event_stats()
+
+
+@router.delete("/api/events")
+def clear_events(request: Request):
+    store = get_store(request)
+    store.clear_events()
+    return {"status": "ok"}
+
+
+@router.get("/", response_class=HTMLResponse)
+def dashboard(request: Request):
+    store = get_store(request)
+    history = store.get_scan_history()
+    top_tools_data = store.get_top_tools()
+    trend_data = store.get_severity_trend()
+    scanners = store.get_scanners()
+    tool_names = store.get_tool_names()
+    dups = store.get_duplicates()
+
+    templates = get_templates(request)
+    if not templates:
+        return HTMLResponse("<h1>Dashboard templates not found</h1>", status_code=500)
+
+    return templates.TemplateResponse(
+        request,
+        "dashboard.html",
+        {
+            "total_scans": len(history.scans),
+            "total_findings": history.total_findings,
+            "critical": history.total_critical,
+            "high": history.total_high,
+            "medium": history.total_medium,
+            "low": history.total_low,
+            "info": history.total_info,
+            "top_tools": _sanitize_tools(top_tools_data),
+            "trend_data": _sanitize_trend(trend_data),
+            "scans": history.scans,
+            "scanners": scanners,
+            "tool_names": tool_names,
+            "duplicates": dups,
+            "auto_refresh": getattr(request.app.state, "auto_refresh", 30),
+        },
+    )
+
+
+@router.get("/findings/{finding_id}", response_class=HTMLResponse)
+def finding_detail(request: Request, finding_id: str):
+    store = get_store(request)
+    finding = store.get_finding(finding_id)
+    if not finding:
+        return HTMLResponse("<h1>Finding not found</h1>", status_code=404)
+    scan = store.get_scan(finding.scan_id)
+    templates = get_templates(request)
+    if not templates:
+        return HTMLResponse("<h1>Not found</h1>", status_code=500)
+    return templates.TemplateResponse(
+        request,
+        "dashboard.html",
+        {
+            "total_scans": 0,
+            "total_findings": 0,
+            "critical": 0,
+            "high": 0,
+            "medium": 0,
+            "low": 0,
+            "info": 0,
+            "top_tools": [],
+            "trend_data": [],
+            "scans": [],
+            "scanners": [],
+            "tool_names": [],
+            "duplicates": [],
+            "detail_finding": finding,
+            "detail_scan": scan,
+            "auto_refresh": 0,
+        },
+    )

mcpscope/api/server.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+import hmac
+import json
+import logging
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, RedirectResponse
+
+from mcpscope.storage.store import Store
+from mcpscope.config import Settings
+
+
+API_KEY_HEADER = "X-API-Key"
+DASHBOARD_COOKIE = "mcpscope_session"
+
+
+class JSONLogFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps(
+            {
+                "time": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
+                "level": record.levelname,
+                "logger": record.name,
+                "message": record.getMessage(),
+                "module": record.module,
+                "function": record.funcName,
+            }
+        )
+
+
+def setup_logging(settings: Settings) -> None:
+    root = logging.getLogger("mcpscope")
+    root.setLevel(getattr(logging, settings.log_level.upper(), logging.INFO))
+    handler = logging.StreamHandler()
+    if settings.log_json:
+        handler.setFormatter(JSONLogFormatter())
+    else:
+        handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+    root.handlers.clear()
+    root.addHandler(handler)
+
+
+def _verify_session(request: Request, password: str) -> bool:
+    cookie = request.cookies.get(DASHBOARD_COOKIE, "")
+    if not cookie:
+        return False
+    expected = _session_value(password, request.client.host if request.client else "")
+    return hmac.compare_digest(cookie, expected)
+
+
+def _session_value(password: str, client_ip: str) -> str:
+    h = hmac.new(password.encode(), client_ip.encode(), "sha256")
+    return h.hexdigest()
+
+
+def create_app(store: Store | None = None, settings: Settings | None = None) -> FastAPI:
+    cfg = settings or Settings.load()
+    setup_logging(cfg)
+    logger = logging.getLogger("mcpscope.api")
+
+    app = FastAPI(
+        title="MCP-Scope API",
+        description="Unified security dashboard for MCP/A2A scanner results",
+        version="0.1.0",
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/api/openapi.json",
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*", API_KEY_HEADER],
+    )
+
+    app.state.store = store or Store(db_path=cfg.db_path)
+    app.state.auto_refresh = cfg.auto_refresh_seconds
+    app.state.api_key = cfg.api_key
+    app.state.dashboard_password = cfg.dashboard_password
+
+    @app.middleware("http")
+    async def auth_middleware(request: Request, call_next):
+        path = request.url.path
+
+        if path in ("/health", "/api/health", "/api/login", "/api/logout"):
+            return await call_next(request)
+
+        if cfg.api_key and path.startswith("/api/") and request.method != "OPTIONS":
+            req_key = request.headers.get(API_KEY_HEADER)
+            if not hmac.compare_digest(req_key or "", cfg.api_key):
+                logger.warning("API key rejected for %s", path)
+                return JSONResponse(
+                    status_code=401, content={"error": "Invalid or missing API key"}
+                )
+
+        if cfg.dashboard_password and not path.startswith("/api/"):
+            if not _verify_session(request, cfg.dashboard_password):
+                if path != "/login":
+                    return RedirectResponse(url="/login")
+
+        response = await call_next(request)
+        return response
+
+    templates_dir = Path(__file__).resolve().parent.parent / "templates"
+    if templates_dir.exists():
+        from fastapi.templating import Jinja2Templates
+
+        app.state.templates = Jinja2Templates(directory=str(templates_dir))
+
+    from mcpscope.api.routes import router
+
+    app.include_router(router)
+
+    return app

mcpscope/cli.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+import sys
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+from rich.progress import Progress
+
+from mcpscope.api.server import create_app
+from mcpscope.storage.store import Store
+from mcpscope.ingest.cisco_mcp import CiscoMCPParser
+from mcpscope.ingest.cisco_a2a import CiscoA2AParser
+from mcpscope.ingest.mcpscan import MCPScanParser
+from mcpscope.ingest.mcpwn import MCPwnParser
+from mcpscope.ingest.sarif import SarifParser
+from mcpscope.ingest.base import ParseError
+from mcpscope.models.scan import ScanRun
+from mcpscope.config import Settings
+from mcpscope.scanner import ScannerRunner
+
+console = Console()
+PARSERS = {
+    "cisco-mcp": CiscoMCPParser(),
+    "cisco-a2a": CiscoA2AParser(),
+    "mcp-scan": MCPScanParser(),
+    "mcpscan": MCPScanParser(),
+    "mcpwn": MCPwnParser(),
+    "sarif": SarifParser(),
+}
+
+
+def cmd_import(args: list[str]):
+    if len(args) < 2:
+        console.print("[red]Usage: mcpscope import <scanner> <file> [target][/red]")
+        sys.exit(1)
+
+    scanner_name = args[0].lower()
+    file_path = Path(args[1])
+    target = args[2] if len(args) > 2 else None
+
+    parser = PARSERS.get(scanner_name)
+    if not parser:
+        console.print(
+            f"[red]Unknown scanner: {scanner_name}. Available: {', '.join(PARSERS)}[/red]"
+        )
+        sys.exit(1)
+
+    if not file_path.exists():
+        console.print(f"[red]File not found: {file_path}[/red]")
+        sys.exit(1)
+
+    store = Store()
+
+    try:
+        with Progress() as progress:
+            task = progress.add_task(f"Parsing {file_path.name}...", total=None)
+            findings = parser.parse_file(file_path)
+            progress.update(task, completed=True)
+    except ParseError as e:
+        console.print(f"[red]Parse error: {e}[/red]")
+        if e.details:
+            console.print(f"[dim]{e.details}[/dim]")
+        sys.exit(1)
+
+    scanner_label = findings[0].scanner
+    scan = ScanRun(
+        id=file_path.stem,
+        scanner=scanner_label,
+        target=target or scanner_label,
+        raw_file=str(file_path.resolve()),
+    )
+    saved = store.save_scan(scan, findings)
+
+    table = Table(title=f"Imported: {file_path.name}")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", style="green")
+    table.add_row("Scanner", scanner_label)
+    table.add_row("Findings", str(len(findings)))
+    table.add_row("Critical", str(saved.critical_count))
+    table.add_row("High", str(saved.high_count))
+    table.add_row("Medium", str(saved.medium_count))
+    table.add_row("Low", str(saved.low_count))
+    table.add_row("Info", str(saved.info_count))
+    table.add_row("Scan ID", saved.id)
+    console.print(table)
+
+
+def cmd_serve(args: list[str]):
+    settings = Settings.load()
+    for i, a in enumerate(args):
+        if a == "--port" and i + 1 < len(args):
+            settings.port = int(args[i + 1])
+        elif a == "--host" and i + 1 < len(args):
+            settings.host = args[i + 1]
+        elif a == "--config" and i + 1 < len(args):
+            settings = Settings.load(args[i + 1])
+
+    import uvicorn
+
+    store = Store(db_path=settings.db_path)
+    app = create_app(store)
+    app.state.auto_refresh = settings.auto_refresh_seconds
+    console.print(
+        f"[green]MCP-Scope dashboard running at http://{settings.host}:{settings.port}[/green]"
+    )
+    console.print(
+        f"[dim]DB: {settings.db_path} | Auto-refresh: {settings.auto_refresh_seconds}s[/dim]"
+    )
+    uvicorn.run(
+        app, host=settings.host, port=settings.port, log_level=settings.log_level
+    )
+
+
+def cmd_report(args: list[str]):
+    fmt = "json"
+    output = "mcpscope-report.json"
+    for i, a in enumerate(args):
+        if a == "--format" and i + 1 < len(args):
+            fmt = args[i + 1].lower()
+        elif a == "--output" and i + 1 < len(args):
+            output = args[i + 1]
+
+    store = Store()
+    history = store.get_scan_history()
+    top = store.get_top_tools()
+
+    report_data = {
+        "generated_at": __import__("datetime").datetime.utcnow().isoformat(),
+        "summary": {
+            "total_scans": len(history.scans),
+            "total_findings": history.total_findings,
+            "critical": history.total_critical,
+            "high": history.total_high,
+            "medium": history.total_medium,
+            "low": history.total_low,
+            "info": history.total_info,
+        },
+        "scans": [s.model_dump() for s in history.scans],
+        "top_tools": top,
+    }
+
+    out_path = Path(output)
+    if fmt == "json":
+        with open(out_path, "w") as f:
+            json.dump(report_data, f, indent=2)
+        console.print(f"[green]Report written to {out_path.resolve()}[/green]")
+
+    elif fmt == "csv":
+        import csv
+
+        store = Store()
+        findings, _ = store.get_findings(page_size=100000)
+        with open(out_path, "w", newline="") as f:
+            writer = csv.writer(f)
+            writer.writerow(
+                [
+                    "id",
+                    "scan_id",
+                    "scanner",
+                    "tool_name",
+                    "severity",
+                    "title",
+                    "description",
+                    "recommendation",
+                    "created_at",
+                ]
+            )
+            for finding in findings:
+                sev = (
+                    finding.severity.value
+                    if hasattr(finding.severity, "value")
+                    else finding.severity
+                )
+                writer.writerow(
+                    [
+                        finding.id,
+                        finding.scan_id,
+                        finding.scanner,
+                        finding.tool_name,
+                        sev,
+                        finding.title,
+                        (finding.description or "")[:200],
+                        (finding.recommendation or "")[:200],
+                        finding.created_at,
+                    ]
+                )
+        console.print(f"[green]CSV report written to {out_path.resolve()}[/green]")
+
+    elif fmt == "pdf":
+        try:
+            from weasyprint import HTML
+        except ImportError:
+            console.print(
+                "[red]PDF generation requires: pip install mcpscope[pdf][/red]"
+            )
+            sys.exit(1)
+
+        html_content = _render_report_html(report_data)
+        HTML(string=html_content).write_pdf(str(out_path))
+        console.print(f"[green]PDF report written to {out_path.resolve()}[/green]")
+
+    else:
+        console.print(f"[red]Unsupported format: {fmt}. Use json, csv, or pdf.[/red]")
+        sys.exit(1)
+
+
+def cmd_seed(args: list[str]):
+    store = Store()
+    store.seed_demo_data()
+    history = store.get_scan_history()
+    console.print(
+        f"[green]Seeded {len(history.scans)} demo scans with {history.total_findings} findings[/green]"
+    )
+
+
+def cmd_backup(args: list[str]):
+    output = (
+        args[0]
+        if args
+        else f"mcpscope-backup-{__import__('datetime').datetime.now().strftime('%Y%m%d_%H%M%S')}.db"
+    )
+    store = Store()
+    store.backup(output)
+    console.print(f"[green]Backup saved to {Path(output).resolve()}[/green]")
+
+
+def cmd_restore(args: list[str]):
+    if not args:
+        console.print("[red]Usage: mcpscope restore <backup-file>[/red]")
+        sys.exit(1)
+    path = Path(args[0])
+    if not path.exists():
+        console.print(f"[red]Backup not found: {path}[/red]")
+        sys.exit(1)
+    store = Store()
+    store.restore(path)
+    history = store.get_scan_history()
+    console.print(
+        f"[green]Restored {len(history.scans)} scans, {history.total_findings} findings[/green]"
+    )
+
+
+def cmd_config(args: list[str]):
+    settings = Settings.load()
+    if not args:
+        console.print("[bold]Current configuration:[/bold]")
+        for k, v in settings.as_dict().items():
+            console.print(f"  {k}: {v}")
+        console.print(f"\nConfig file: {Path.home() / '.mcpscope' / 'config.json'}")
+        return
+
+    action = args[0]
+    if action == "show":
+        for k, v in settings.as_dict().items():
+            console.print(f"  {k}: {v}")
+    elif action == "set" and len(args) >= 3:
+        key, value = args[1], args[2]
+        if hasattr(settings, key):
+            current = getattr(settings, key)
+            if value.lower() in ("none", "null", ""):
+                setattr(settings, key, None)
+            elif isinstance(current, bool):
+                setattr(settings, key, value.lower() in ("true", "1", "yes"))
+            elif isinstance(current, int):
+                setattr(settings, key, int(value))
+            elif isinstance(current, list):
+                import json
+
+                try:
+                    setattr(settings, key, json.loads(value))
+                except (json.JSONDecodeError, TypeError):
+                    console.print(f"[red]Expected JSON array for {key}[/red]")
+                    sys.exit(1)
+            else:
+                setattr(settings, key, value)
+            settings.save()
+            console.print(f"[green]{key} set to {value}[/green]")
+        else:
+            console.print(f"[red]Unknown config key: {key}[/red]")
+            sys.exit(1)
+    else:
+        console.print("Usage: mcpscope config [show|set <key> <value>]")
+
+
+def cmd_scan(args: list[str]):
+    if len(args) < 2:
+        console.print("[red]Usage: mcpscope scan <scanner> <target>[/red]")
+        console.print(f"Scanners: {', '.join(ScannerRunner.PARSERS)}")
+        sys.exit(1)
+
+    scanner_name = args[0].lower()
+    target = args[1]
+    runner = ScannerRunner()
+    store = Store()
+
+    try:
+        with Progress() as progress:
+            task = progress.add_task(
+                f"Running {scanner_name} against {target}...", total=None
+            )
+            scan = runner.scan(scanner_name, target, store=store)
+            progress.update(task, completed=True)
+    except (ValueError, RuntimeError) as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+
+    table = Table(title=f"Scan: {scan.id[:12]}")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", style="green")
+    table.add_row("Scanner", scan.scanner)
+    table.add_row("Target", target)
+    table.add_row("Findings", str(scan.findings_count))
+    table.add_row("Critical", str(scan.critical_count))
+    table.add_row("High", str(scan.high_count))
+    table.add_row("Medium", str(scan.medium_count))
+    table.add_row("Low", str(scan.low_count))
+    table.add_row("Info", str(scan.info_count))
+    table.add_row("Scan ID", scan.id)
+    console.print(table)
+
+
+def cmd_prune(args: list[str]):
+    keep_days = 30
+    for i, a in enumerate(args):
+        if a == "--keep" and i + 1 < len(args):
+            keep_days = int(args[i + 1])
+
+    store = Store()
+    count = store.prune(keep_days)
+    if count:
+        console.print(
+            f"[green]Pruned {count} scans older than {keep_days} days[/green]"
+        )
+    else:
+        console.print(f"[yellow]No scans older than {keep_days} days to prune[/yellow]")
+
+
+def _render_report_html(data: dict) -> str:
+    summary = data["summary"]
+    scans_rows = ""
+    for s in data["scans"]:
+        scans_rows += f"""<tr>
+            <td>{s["id"]}</td>
+            <td>{s["scanner"]}</td>
+            <td>{s["findings_count"]}</td>
+            <td>{s["critical_count"]}</td>
+            <td>{s["high_count"]}</td>
+            <td>{s["medium_count"]}</td>
+            <td>{s["low_count"]}</td>
+            <td>{s["info_count"]}</td>
+            <td>{s["created_at"]}</td>
+        </tr>"""
+
+    tools_rows = ""
+    for t in data.get("top_tools", []):
+        tools_rows += f"""<tr>
+            <td>{t["tool_name"]}</td>
+            <td>{t["total"]}</td>
+            <td>{t["critical_high"]}</td>
+        </tr>"""
+
+    return f"""<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>MCP-Scope Report</title>
+<style>
+body {{ font-family: Helvetica, Arial, sans-serif; margin: 40px; }}
+h1 {{ color: #1e293b; }}
+h2 {{ color: #334155; margin-top: 30px; }}
+table {{ width: 100%; border-collapse: collapse; margin: 10px 0 30px 0; }}
+th, td {{ border: 1px solid #cbd5e1; padding: 8px 12px; text-align: left; }}
+th {{ background: #f1f5f9; }}
+.summary-grid {{ display: grid; grid-template-columns: repeat(3, 1fr); gap: 15px; }}
+.card {{ border: 1px solid #e2e8f0; border-radius: 8px; padding: 15px; }}
+.card h3 {{ margin: 0 0 5px 0; color: #64748b; font-size: 14px; }}
+.card .value {{ font-size: 28px; font-weight: bold; color: #0f172a; }}
+</style></head><body>
+<h1>MCP-Scope Security Report</h1>
+<p>Generated: {data["generated_at"]}</p>
+<h2>Summary</h2>
+<div class="summary-grid">
+    <div class="card"><h3>Total Scans</h3><div class="value">{summary["total_scans"]}</div></div>
+    <div class="card"><h3>Total Findings</h3><div class="value">{summary["total_findings"]}</div></div>
+    <div class="card"><h3>Critical</h3><div class="value">{summary["critical"]}</div></div>
+    <div class="card"><h3>High</h3><div class="value">{summary["high"]}</div></div>
+    <div class="card"><h3>Medium</h3><div class="value">{summary["medium"]}</div></div>
+    <div class="card"><h3>Low</h3><div class="value">{summary["low"]}</div></div>
+</div>
+<h2>Scan History</h2>
+<table><thead><tr><th>ID</th><th>Scanner</th><th>Total</th><th>Critical</th><th>High</th><th>Medium</th><th>Low</th><th>Info</th><th>Date</th></tr></thead>
+<tbody>{scans_rows}</tbody></table>
+<h2>Top Vulnerable Tools</h2>
+<table><thead><tr><th>Tool</th><th>Total Findings</th><th>Critical/High</th></tr></thead>
+<tbody>{tools_rows}</tbody></table>
+</body></html>"""
+
+
+def cli():
+    if len(sys.argv) < 2:
+        console.print("[bold]MCP-Scope[/bold] - Unified Security Dashboard")
+        console.print("Usage:")
+        console.print("  mcpscope serve [--port PORT] [--host HOST] [--config FILE]")
+        console.print("  mcpscope scan <scanner> <target>")
+        console.print("  mcpscope import <scanner> <file> [target]")
+        console.print("  mcpscope report [--format json|csv|pdf] [--output FILE]")
+        console.print("  mcpscope seed")
+        console.print("  mcpscope prune [--keep DAYS]")
+        console.print("  mcpscope backup [file]")
+        console.print("  mcpscope restore <file>")
+        console.print("  mcpscope config [show|set <key> <value>]")
+        console.print("\nScanners (import): " + ", ".join(PARSERS))
+        console.print("Scanners (scan): " + ", ".join(ScannerRunner.PARSERS))
+        return
+
+    command = sys.argv[1]
+    args = sys.argv[2:]
+
+    commands = {
+        "serve": cmd_serve,
+        "scan": cmd_scan,
+        "import": cmd_import,
+        "report": cmd_report,
+        "seed": cmd_seed,
+        "prune": cmd_prune,
+        "backup": cmd_backup,
+        "restore": cmd_restore,
+        "config": cmd_config,
+    }
+
+    fn = commands.get(command)
+    if fn:
+        fn(args)
+    else:
+        console.print(f"[red]Unknown command: {command}[/red]")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

mcpscope/config.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from dataclasses import dataclass, field
+
+DEFAULT_CONFIG_PATH = Path.home() / ".mcpscope" / "config.json"
+
+
+@dataclass
+class Settings:
+    db_path: str = str(Path.home() / ".mcpscope" / "mcpscope.db")
+    host: str = "127.0.0.1"
+    port: int = 8080
+    log_level: str = "info"
+    auto_refresh_seconds: int = 30
+    api_key: str | None = None
+    webhook_urls: list[str] = field(default_factory=list)
+    slack_webhook_url: str | None = None
+    max_upload_mb: int = 50
+    dashboard_password: str | None = None
+    log_json: bool = False
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> Settings:
+        path = Path(path) if path else DEFAULT_CONFIG_PATH
+        if path.exists():
+            try:
+                with open(path) as f:
+                    data = json.load(f)
+                return cls(
+                    **{k: v for k, v in data.items() if k in cls.__dataclass_fields__}
+                )
+            except (json.JSONDecodeError, TypeError):
+                pass
+        return cls()
+
+    def save(self, path: str | Path | None = None):
+        path = Path(path) if path else DEFAULT_CONFIG_PATH
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            json.dump(self.as_dict(), f, indent=2)
+
+    def as_dict(self) -> dict:
+        return {k: getattr(self, k) for k in self.__dataclass_fields__}

mcpscope/ingest/__init__.py

@@ -0,0 +1,11 @@
+from .base import BaseParser, ParseError
+from .cisco_mcp import CiscoMCPParser
+from .cisco_a2a import CiscoA2AParser
+from .mcpscan import MCPScanParser
+from .mcpwn import MCPwnParser
+from .sarif import SarifParser
+
+__all__ = [
+    "BaseParser", "ParseError",
+    "CiscoMCPParser", "CiscoA2AParser", "MCPScanParser", "MCPwnParser", "SarifParser",
+]

mcpscope/ingest/base.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from mcpscope.models.finding import Finding
+from mcpscope.config import Settings
+
+MAX_UPLOAD_MB = Settings.load().max_upload_mb
+
+
+class ParseError(Exception):
+    def __init__(
+        self, message: str, path: str | None = None, details: str | None = None
+    ):
+        self.path = path
+        self.details = details
+        super().__init__(message)
+
+
+class BaseParser(ABC):
+    SCANNER_NAME: str = "base"
+
+    @abstractmethod
+    def parse(self, data: dict) -> list[Finding]: ...
+
+    def validate(self, data: Any, path: str | None = None):
+        if not isinstance(data, dict):
+            raise ParseError(
+                f"Expected a JSON object at root, got {type(data).__name__}",
+                path=path,
+            )
+
+    def load_json(self, path: str | Path) -> dict:
+        path = Path(path)
+        if not path.exists():
+            raise ParseError(f"File not found: {path}", path=str(path))
+        if path.suffix not in (".json", ".sarif"):
+            raise ParseError(
+                f"Unsupported file type: {path.suffix} (expected .json or .sarif)",
+                path=str(path),
+            )
+
+        size_mb = path.stat().st_size / (1024 * 1024)
+        if size_mb > MAX_UPLOAD_MB:
+            raise ParseError(
+                f"File too large: {size_mb:.1f}MB exceeds limit of {MAX_UPLOAD_MB}MB",
+                path=str(path),
+            )
+
+        try:
+            with open(path) as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            raise ParseError(
+                f"Invalid JSON: {e.msg} at line {e.lineno} col {e.colno}",
+                path=str(path),
+                details=str(e),
+            )
+
+    def parse_file(self, path: str | Path) -> list[Finding]:
+        path = Path(path)
+        raw = self.load_json(path)
+        self.validate(raw, path=str(path))
+        results = self.parse(raw)
+        if not results:
+            raise ParseError("No findings could be extracted", path=str(path))
+        return results

mcpscope/ingest/cisco_a2a.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+from mcpscope.ingest.base import BaseParser, ParseError
+from mcpscope.models.finding import Finding, Severity
+
+
+class CiscoA2AParser(BaseParser):
+    SCANNER_NAME = "cisco-a2a"
+
+    def validate(self, data: dict, path: str | None = None):
+        super().validate(data, path)
+        if "findings" not in data and "results" not in data:
+            raise ParseError(
+                "Missing 'findings' or 'results' key — not a Cisco A2A Scanner output",
+                path=path,
+            )
+
+    def parse(self, data: dict) -> list[Finding]:
+        findings = []
+        scanner = self.SCANNER_NAME
+        target = data.get("target", data.get("card", data.get("endpoint", "unknown")))
+
+        raw_findings = data.get("findings", data.get("results", data.get("assessments", [])))
+        if not isinstance(raw_findings, list):
+            raise ParseError(f"Expected 'findings' to be a list, got {type(raw_findings).__name__}")
+
+        for item in raw_findings:
+            if not isinstance(item, dict):
+                continue
+            threat_name = item.get("threat_name", "")
+            sev_raw = (item.get("severity") or item.get("risk") or "info").upper()
+            sev = Severity.CRITICAL if sev_raw == "CRITICAL" else (
+                Severity.HIGH if sev_raw == "HIGH" else (
+                    Severity.MEDIUM if sev_raw == "MEDIUM" else (
+                        Severity.LOW if sev_raw == "LOW" else Severity.INFO)))
+            analyzer = item.get("analyzer", "unknown")
+            summary = item.get("summary", "")
+            description = item.get("description", summary)
+            aitech = item.get("aitech", "")
+            aitech_name = item.get("aitech_name", "")
+            aisubtech = item.get("aisubtech", "")
+            aisubtech_name = item.get("aisubtech_name", "")
+
+            location = ""
+            if isinstance(item.get("details"), dict):
+                location = item["details"].get("field", "")
+
+            title = threat_name or f"[{analyzer}] {summary[:60]}" if summary else f"{analyzer} finding"
+            if aitech:
+                title = f"[{aitech}] {aitech_name}"
+            if aisubtech:
+                title = f"[{aisubtech}] {aisubtech_name or title}"
+
+            findings.append(Finding(
+                scan_id=target,
+                scanner=scanner,
+                tool_name=f"a2a-{analyzer.lower()}",
+                severity=sev,
+                title=title,
+                description=description or summary,
+                raw_data={
+                    "threat_name": threat_name,
+                    "analyzer": analyzer,
+                    "aitech": aitech,
+                    "aitech_name": aitech_name,
+                    "aisubtech": aisubtech,
+                    "aisubtech_name": aisubtech_name,
+                    "location": location,
+                    "details": item.get("details"),
+                },
+            ))
+
+        return findings

mcpscope/ingest/cisco_mcp.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+from mcpscope.ingest.base import BaseParser, ParseError
+from mcpscope.models.finding import Finding, Severity
+
+SEVERITY_MAP = {
+    "CRITICAL": Severity.CRITICAL,
+    "HIGH": Severity.HIGH,
+    "MEDIUM": Severity.MEDIUM,
+    "LOW": Severity.LOW,
+    "INFO": Severity.INFO,
+    "SAFE": Severity.INFO,
+    "UNKNOWN": Severity.INFO,
+}
+
+ANALYZER_DISPLAY_NAMES = {
+    "api_analyzer": "API",
+    "yara_analyzer": "YARA",
+    "llm_analyzer": "LLM",
+    "behavioral_analyzer": "Behavioral",
+    "readiness_analyzer": "Readiness",
+}
+
+
+class CiscoMCPParser(BaseParser):
+    SCANNER_NAME = "cisco-mcp"
+
+    def validate(self, data: dict, path: str | None = None):
+        super().validate(data, path)
+        if "scan_results" not in data and "results" not in data:
+            raise ParseError(
+                "Missing 'scan_results' or 'results' key — not a Cisco MCP Scanner output",
+                path=path,
+            )
+
+    def parse(self, data: dict) -> list[Finding]:
+        findings = []
+        scanner = self.SCANNER_NAME
+        server_url = data.get("server_url", "unknown")
+        scan_results = data.get("scan_results", data.get("results", [data]))
+
+        for result in scan_results:
+            tool_name = result.get("tool_name", result.get("prompt_name", result.get("resource_uri", "unknown")))
+            item_type = result.get("item_type", "tool")
+            status = result.get("status", "unknown")
+            is_safe = result.get("is_safe", True)
+
+            result_findings = result.get("findings", {})
+            if not isinstance(result_findings, dict):
+                continue
+
+            for analyzer_key, analyzer_data in result_findings.items():
+                analyzer_label = ANALYZER_DISPLAY_NAMES.get(analyzer_key, analyzer_key)
+                sev_raw = analyzer_data.get("severity", "INFO").upper()
+                sev = SEVERITY_MAP.get(sev_raw, Severity.INFO)
+
+                total = analyzer_data.get("total_findings", 0)
+
+                threat_names = analyzer_data.get("threat_names", [])
+                threat_summary = analyzer_data.get("threat_summary", "")
+                threats = analyzer_data.get("threats", {})
+
+                threat_items = threats.get("items", []) if isinstance(threats, dict) else []
+
+                if threat_items:
+                    for technique in threat_items:
+                        technique_id = technique.get("technique_id", "")
+                        technique_name = technique.get("technique_name", "")
+                        sub_items = technique.get("items", [])
+                        for sub in sub_items:
+                            sub_id = sub.get("sub_technique_id", "")
+                            sub_name = sub.get("sub_technique_name", "")
+                            max_sev = sub.get("max_severity", sev_raw)
+                            desc = sub.get("description", threat_summary)
+
+                            title = f"[{technique_id}] {technique_name}"
+                            if sub_id:
+                                title = f"[{sub_id}] {sub_name}"
+
+                            findings.append(Finding(
+                                scan_id=server_url,
+                                scanner=scanner,
+                                tool_name=tool_name,
+                                severity=SEVERITY_MAP.get(max_sev.upper(), sev),
+                                title=title,
+                                description=desc,
+                                raw_data={
+                                    "analyzer": analyzer_label,
+                                    "item_type": item_type,
+                                    "status": status,
+                                    "is_safe": is_safe,
+                                    "technique": technique,
+                                    "sub_technique": sub,
+                                },
+                            ))
+                elif threat_names:
+                    for threat in threat_names:
+                        findings.append(Finding(
+                            scan_id=server_url,
+                            scanner=scanner,
+                            tool_name=tool_name,
+                            severity=sev,
+                            title=f"[{analyzer_label}] {threat}",
+                            description=threat_summary,
+                            raw_data={
+                                "analyzer": analyzer_label,
+                                "item_type": item_type,
+                                "status": status,
+                                "is_safe": is_safe,
+                                "threat": threat,
+                            },
+                        ))
+                elif total > 0 and threat_summary:
+                    findings.append(Finding(
+                        scan_id=server_url,
+                        scanner=scanner,
+                        tool_name=tool_name,
+                        severity=sev,
+                        title=f"[{analyzer_label}] {threat_summary[:80]}",
+                        description=threat_summary,
+                        raw_data={
+                            "analyzer": analyzer_label,
+                            "item_type": item_type,
+                            "status": status,
+                            "is_safe": is_safe,
+                        },
+                    ))
+
+        return findings

mcpscope/ingest/mcpscan.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+from mcpscope.ingest.base import BaseParser, ParseError
+from mcpscope.models.finding import Finding, Severity
+
+SEVERITY_MAP = {
+    "critical": Severity.CRITICAL,
+    "high": Severity.HIGH,
+    "medium": Severity.MEDIUM,
+    "low": Severity.LOW,
+    "info": Severity.INFO,
+    "safe": Severity.INFO,
+}
+
+
+class MCPScanParser(BaseParser):
+    SCANNER_NAME = "mcp-scan"
+
+    def validate(self, data: dict, path: str | None = None):
+        super().validate(data, path)
+        if "issues" not in data and "results" not in data:
+            raise ParseError(
+                "Missing 'issues' or 'results' key — not an mcp-scan JSON output",
+                path=path,
+            )
+
+    def parse(self, data: dict) -> list[Finding]:
+        findings = []
+        scanner = self.SCANNER_NAME
+        target = data.get("target", data.get("config", "unknown"))
+
+        issues = data.get("issues", data.get("results", data.get("findings", [])))
+        if not isinstance(issues, list):
+            raise ParseError(f"Expected 'issues' to be a list, got {type(issues).__name__}")
+
+        servers = data.get("servers", [])
+        server_map = {}
+        for srv in servers:
+            if isinstance(srv, dict):
+                srv_name = srv.get("name", srv.get("server_name", ""))
+                server_map[srv.get("id", "")] = srv_name
+
+        for issue in issues:
+            if not isinstance(issue, dict):
+                continue
+            code = issue.get("code", issue.get("id", ""))
+            sev_raw = issue.get("severity", "info").lower()
+            sev = SEVERITY_MAP.get(sev_raw, Severity.INFO)
+            message = issue.get("message", issue.get("summary", issue.get("title", "")))
+            description = issue.get("description", issue.get("detail", ""))
+            recommendation = issue.get("recommendation", issue.get("remediation", ""))
+            tool_name = issue.get("tool_name", issue.get("tool", ""))
+            server_id = issue.get("server_id", issue.get("server", ""))
+            server_name = issue.get("server_name", server_map.get(server_id, ""))
+            if not tool_name and server_name:
+                tool_name = f"server:{server_name}"
+
+            title = f"[{code}] {message}" if code else message
+            if not title:
+                title = f"mcp-scan {sev_raw} finding"
+
+            findings.append(Finding(
+                scan_id=target,
+                scanner=scanner,
+                tool_name=tool_name or "mcp-scan",
+                severity=sev,
+                title=title,
+                description=description or message,
+                recommendation=recommendation,
+                raw_data={
+                    "code": code,
+                    "server_name": server_name,
+                    **issue,
+                },
+            ))
+
+        return findings

mcpscope/ingest/mcpwn.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from mcpscope.ingest.base import BaseParser, ParseError
+from mcpscope.models.finding import Finding, Severity
+
+SEVERITY_MAP = {
+    "critical": Severity.CRITICAL,
+    "high": Severity.HIGH,
+    "medium": Severity.MEDIUM,
+    "low": Severity.LOW,
+    "info": Severity.INFO,
+}
+
+
+class MCPwnParser(BaseParser):
+    SCANNER_NAME = "mcpwn"
+
+    def validate(self, data: dict, path: str | None = None):
+        super().validate(data, path)
+        if "findings" not in data and "exploits" not in data and "modules" not in data:
+            raise ParseError(
+                "Missing 'findings', 'exploits', or 'modules' key — not an MCPwn output",
+                path=path,
+            )
+
+    def parse(self, data: dict) -> list[Finding]:
+        findings = []
+        scanner = self.SCANNER_NAME
+        target = data.get("target", data.get("tool", data.get("card", "unknown")))
+
+        raw_findings = data.get("findings", data.get("exploits", data.get("modules", [])))
+        if not isinstance(raw_findings, list):
+            raise ParseError(f"Expected findings to be a list, got {type(raw_findings).__name__}")
+
+        for item in raw_findings:
+            if not isinstance(item, dict):
+                continue
+            sev_raw = item.get("severity", "info").lower()
+            sev = SEVERITY_MAP.get(sev_raw, Severity.INFO)
+            vuln_id = item.get("id", item.get("type", ""))
+            title = item.get("title", item.get("name", ""))
+            test = item.get("test", item.get("module", ""))
+            tool_name = item.get("tool", item.get("tool_name", ""))
+            if not tool_name:
+                tool_name = test or "mcpwn"
+            description = item.get("description", item.get("output", item.get("detection", "")))
+            recommendation = item.get("recommendation", item.get("fix", ""))
+            evidence = item.get("detection", item.get("evidence", ""))
+
+            if not title and vuln_id:
+                title = f"[{vuln_id}] {test}" if test else vuln_id
+            if not title and description:
+                title = description[:80]
+
+            findings.append(Finding(
+                scan_id=target,
+                scanner=scanner,
+                tool_name=tool_name,
+                severity=sev,
+                title=title or "MCPwn finding",
+                description=description,
+                recommendation=recommendation,
+                raw_data={
+                    "vuln_id": vuln_id,
+                    "test": test,
+                    "evidence": evidence,
+                    **item,
+                },
+            ))
+
+        return findings

mcpscope/ingest/sarif.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+from mcpscope.ingest.base import BaseParser, ParseError
+from mcpscope.models.finding import Finding, Severity
+
+SEVERITY_MAP = {
+    "error": Severity.CRITICAL,
+    "warning": Severity.MEDIUM,
+    "note": Severity.LOW,
+    "none": Severity.INFO,
+}
+
+
+class SarifParser(BaseParser):
+    SCANNER_NAME = "sarif"
+
+    def validate(self, data: dict, path: str | None = None):
+        super().validate(data, path)
+        if "$schema" not in str(data.get("$schema", "")):
+            if "version" not in data or "runs" not in data:
+                raise ParseError(
+                    "Missing '$schema'/'version' and 'runs' — not a SARIF file",
+                    path=path,
+                )
+
+    def parse(self, data: dict) -> list[Finding]:
+        findings = []
+        scanner = self.SCANNER_NAME
+        target = data.get("target", "sarif-report")
+
+        runs = data.get("runs", [])
+        if not isinstance(runs, list):
+            raise ParseError(f"Expected 'runs' to be a list, got {type(runs).__name__}")
+
+        for run in runs:
+            tool_name = "unknown"
+            if isinstance(run.get("tool"), dict):
+                driver = run["tool"].get("driver", {})
+                tool_name = driver.get("name", driver.get("fullName", "unknown"))
+                tool_version = driver.get("version", "")
+
+            run_results = run.get("results", [])
+            if not isinstance(run_results, list):
+                continue
+
+            rules_map = {}
+            if isinstance(run.get("tool"), dict):
+                driver = run["tool"].get("driver", {})
+                rules = driver.get("rules", [])
+                if isinstance(rules, list):
+                    for rule in rules:
+                        rule_id = rule.get("id", "")
+                        rules_map[rule_id] = {
+                            "name": rule.get("name", ""),
+                            "shortDescription": "",
+                            "fullDescription": "",
+                        }
+                        if isinstance(rule.get("shortDescription"), dict):
+                            rules_map[rule_id]["shortDescription"] = rule["shortDescription"].get("text", "")
+                        if isinstance(rule.get("fullDescription"), dict):
+                            rules_map[rule_id]["fullDescription"] = rule["fullDescription"].get("text", "")
+
+            for result in run_results:
+                if not isinstance(result, dict):
+                    continue
+                rule_id = result.get("ruleId", "")
+                rule_info = rules_map.get(rule_id, {})
+
+                level = result.get("level", "warning")
+                sev = SEVERITY_MAP.get(level, Severity.INFO)
+
+                message = ""
+                if isinstance(result.get("message"), dict):
+                    message = result["message"].get("text", "")
+
+                title = rule_info.get("name", rule_id) or rule_id
+                description = rule_info.get("fullDescription", rule_info.get("shortDescription", message))
+                if not description:
+                    description = message
+
+                locations = result.get("locations", [])
+                loc_str = ""
+                if isinstance(locations, list) and locations:
+                    phys = locations[0].get("physicalLocation", {})
+                    artifact = phys.get("artifactLocation", {})
+                    loc_str = artifact.get("uri", "")
+
+                findings.append(Finding(
+                    scan_id=target,
+                    scanner=scanner,
+                    tool_name=tool_name,
+                    tool_version=tool_version,
+                    severity=sev,
+                    title=title,
+                    description=description,
+                    raw_data={
+                        "rule_id": rule_id,
+                        "level": level,
+                        "location": loc_str,
+                        **result,
+                    },
+                ))
+
+        return findings

mcpscope/main.py

@@ -0,0 +1,4 @@
+from mcpscope.cli import cli
+
+if __name__ == "__main__":
+    cli()

mcpscope/models/__init__.py

@@ -0,0 +1,4 @@
+from .finding import Finding, Severity
+from .scan import ScanRun, ScanHistory
+
+__all__ = ["Finding", "Severity", "ScanRun", "ScanHistory"]

mcpscope/models/finding.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+from enum import Enum
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+SEVERITY_ORDER = {s: i for i, s in enumerate(Severity)}
+SEVERITY_COLORS = {
+    Severity.CRITICAL: "#dc2626",
+    Severity.HIGH: "#ea580c",
+    Severity.MEDIUM: "#ca8a04",
+    Severity.LOW: "#2563eb",
+    Severity.INFO: "#6b7280",
+}
+
+
+class Finding(BaseModel):
+    id: str | None = None
+    scan_id: str
+    scanner: str
+    tool_name: str
+    tool_version: str | None = None
+    severity: Severity
+    title: str
+    description: str | None = None
+    recommendation: str | None = None
+    cvss_score: float | None = None
+    cve_id: str | None = None
+    raw_data: dict | None = None
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def severity_order(self) -> int:
+        return SEVERITY_ORDER.get(self.severity, 99)

mcpscope/models/scan.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+
+
+class ScanRun(BaseModel):
+    id: str
+    scanner: str
+    target: str | None = None
+    findings_count: int = 0
+    critical_count: int = 0
+    high_count: int = 0
+    medium_count: int = 0
+    low_count: int = 0
+    info_count: int = 0
+    raw_file: str | None = None
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+
+class ScanHistory(BaseModel):
+    scans: list[ScanRun] = []
+    total_findings: int = 0
+    total_critical: int = 0
+    total_high: int = 0
+    total_medium: int = 0
+    total_low: int = 0
+    total_info: int = 0

mcpscope/models/security_event.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+from enum import Enum
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+
+
+class EventSeverity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+class SecurityEvent(BaseModel):
+    id: str | None = None
+    event_type: str
+    severity: str
+    message: str
+    source: str = "mcpguard"
+    tool: str | None = None
+    details: dict | None = None
+    blocked: bool = True
+    created_at: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )

mcpscope/scanner.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+import json
+import subprocess
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Any
+
+from mcpscope.ingest.base import ParseError
+from mcpscope.ingest.cisco_mcp import CiscoMCPParser
+from mcpscope.ingest.mcpscan import MCPScanParser
+from mcpscope.ingest.mcpwn import MCPwnParser
+from mcpscope.models.scan import ScanRun
+from mcpscope.storage.store import Store
+
+
+class ScannerRunner:
+    PARSERS: dict[str, dict[str, Any]] = {
+        "mcp-scan": {
+            "parser": MCPScanParser(),
+            "install": "pip install mcp-scan",
+            "cmd": ["mcp-scan", "--json"],
+        },
+        "cisco-mcp": {
+            "parser": CiscoMCPParser(),
+            "install": "pip install cisco-ai-mcp-scanner",
+            "cmd": ["mcp-scanner", "scan", "--output-format", "raw"],
+        },
+        "mcpwn": {
+            "parser": MCPwnParser(),
+            "install": "pip install mcpwn",
+            "cmd": ["mcpwn", "scan", "--format", "json"],
+        },
+    }
+
+    def scan(
+        self, scanner_name: str, target: str, store: Store | None = None
+    ) -> ScanRun:
+        info = self.PARSERS.get(scanner_name)
+        if not info:
+            raise ValueError(
+                f"Unknown scanner: {scanner_name}. Supported: {', '.join(self.PARSERS)}"
+            )
+
+        parser = info["parser"]
+        cmd = info["cmd"] + [target]
+
+        with tempfile.NamedTemporaryFile(suffix=".json", delete=False, mode="w") as tmp:
+            tmp_path = tmp.name
+
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+            if result.returncode != 0:
+                raise RuntimeError(
+                    f"Scanner failed (exit {result.returncode}): {result.stderr[:500]}"
+                )
+            raw = json.loads(result.stdout)
+        except FileNotFoundError:
+            raise RuntimeError(
+                f"Scanner '{scanner_name}' not found. Install it: {info['install']}"
+            )
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"Scanner output is not valid JSON: {e}")
+        except subprocess.TimeoutExpired:
+            raise RuntimeError("Scanner timed out (120s)")
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+
+        findings = parser.parse(raw)
+        if not findings:
+            raise RuntimeError("Scanner completed but no findings were detected")
+
+        scan = ScanRun(
+            id=str(uuid.uuid4()),
+            scanner=findings[0].scanner,
+            target=target,
+        )
+        if store:
+            store.save_scan(scan, findings)
+        return scan

mcpscope/storage/__init__.py

@@ -0,0 +1,3 @@
+from .store import Store
+
+__all__ = ["Store"]