Deep SAST MCP Server

A Model Context Protocol server that gives IBM Consulting Advantage agents deterministic, 100%-file-coverage security findings by wrapping Semgrep, gitleaks, osv-scanner, Checkov and Trivy behind Streamable HTTP.

Scanner Coverage

Endpoint

• MCP protocol: POST /mcp (Streamable HTTP; register without a trailing slash)
• Health: GET /health
• Report downloads: GET /reports/{scan_id}/{filename}

Hugging Face Logs

The Hugging Face Space exposes build and runtime logs through authenticated API endpoints. Set HF_TOKEN in your shell; do not paste or commit the token value.

curl -N \
    -H "Authorization: Bearer $HF_TOKEN" \
    "https://huggingface.co/api/spaces/piyushptiwari/deep-sast-mcp/logs/run"

curl -N \
    -H "Authorization: Bearer $HF_TOKEN" \
    "https://huggingface.co/api/spaces/piyushptiwari/deep-sast-mcp/logs/build"

Use logs/run for live application requests and scanner/report runtime errors. Use logs/build for Docker build, dependency install and Space startup failures.

Expected runtime log noise:

• AuthlibDeprecationWarning and websockets...DeprecationWarning come from FastMCP/Uvicorn

dependencies and do not indicate scanner failure.

• GET /favicon.ico returning 404 is a browser probe and is harmless.
• Streamable HTTP commonly logs POST /mcp 202, GET /mcp 200 and DELETE /mcp 200 during

MCP session setup, streaming and teardown.

• Occasional POST /mcp or GET /mcp 400/404 entries usually mean a malformed probe, stale

MCP session id or request after the client already closed the session. Treat them as noise when tools/list, scans and report downloads still return 200.

• Error in standalone SSE writer ... anyio.ClosedResourceError is emitted by the MCP

stream writer when a client closes an SSE stream early. It is non-blocking if subsequent MCP calls and report downloads continue to succeed.

Files

• server.py - thin entrypoint.
• deep_sast_mcp/app.py - FastMCP tool registration and HTTP/report routes.
• deep_sast_mcp/scan_engine.py - clone, scanner selection and orchestration.
• deep_sast_mcp/scanners/ - one adapter per scanner.
• deep_sast_mcp/reporting.py - Markdown, HTML, JSON, SARIF and ZIP evidence packs.
• requirements.txt - Python dependencies.
• Dockerfile - image with scanner CLIs on PATH.

Tools

Normalized finding fields: id, scanner, rule_id, title, severity, owasp, cwe, path, start_line, end_line, snippet, fix_hint, confidence, details. gitleaks snippets are redacted.

Large Repository Handling

Selection is deterministic and produces an honest coverage ledger instead of asserting 100%. For every discovered file the server records one of: in-scope source, dependency lockfile (kept for SCA), or a categorized skip (excluded_dir, binary, generated_minified, too_large, unsupported_language, gitignored_untracked).

• .gitignore is respected via git ls-files, so ignored content is excluded for free.
• Default-excluded directories (seeded from Semgrep's default.semgrepignore) are pruned

during the walk, e.g. node_modules, vendor, dist, build, __pycache__, .venv, target, .terraform. They never inflate the coverage denominator.

• Binary files (null-byte heuristic + known binary extensions) are never scanned.
• Files larger than MAX_FILE_KB are skipped for SAST and accounted as too_large.
• The same exclude set is pushed into Semgrep (--exclude, --max-target-bytes), Trivy

(--skip-dirs) and Checkov (--skip-path) so scanners do less work and use less memory.

• Each scanner's findings are capped at MAX_FINDINGS_PER_SCANNER to bound memory.

The ledger (coverage block of get_scan_status / report) always satisfies in_scope + sum(skipped) == total_discovered.

Tunable environment variables: MAX_FILE_KB (default 1024), MAX_FINDINGS_PER_SCANNER (default 5000), RESPECT_GITIGNORE (default true), EXCLUDE_DIRS (comma-separated override).

Report Formats

• markdown - human report with executive summary, coverage ledger, scanner inventory,

severity/scanner distributions, detailed findings, dependency appendix and remediation plan.

• html - browser-readable copy of the Markdown report.
• json - raw normalized evidence for downstream automation.
• sarif - importable into code scanning tools.
• zip - evidence pack containing Markdown, HTML, JSON, SARIF and dependency CSV.

Auth

Set MCP_AUTH_TOKEN to require Authorization: Bearer <token> on MCP requests. Leave unset only for development/open access. By default, report download URLs are public when generated; set PUBLIC_REPORTS=false to require the same bearer token for reports.

Register In IBM Consulting Advantage

Register the hosted endpoint in ContextForge / MCP Gateway:

ContextForge federates the MCP tools; group them into a virtual server and attach that virtual server to the Agentic App / DeepAgent.

Agent Workflow

1. scan_repository(repo_url) with scanners omitted unless the user asks for a targeted scan.
2. get_scan_status(scan_id) and reconcile coverage as files_scanned / total_files.
3. list_findings(...) and get_dependency_report(scan_id) for triage.
4. get_finding_context(...) for high-impact evidence validation.
5. generate_report(scan_id, "markdown") for the user-facing report.
6. Generate json, sarif or zip when machine-readable evidence or a full pack is needed.
7. Share the returned download_url with the user.
8. cleanup_scan(scan_id) when done. Reports are preserved by default so the URL remains usable.

Run Locally

pip install -r requirements.txt
python server.py --transport http --host 127.0.0.1 --port 8080

The Docker image installs the scanner CLIs. Local non-Docker runs also need scanner binaries on PATH.

Security Notes

• Scanners parse target code; they do not execute the target repository.
• Repositories are shallow-cloned from allowed hosts only and size-capped by MAX_REPO_MB.
• Each clone uses a per-scan temp workspace removed by cleanup_scan.
• Report artifacts are stored separately from the clone workspace and can be preserved after cleanup.
• Secret values are redacted before leaving the scanner process.
• get_file and report downloads block path traversal outside their scan/report roots.