Output Formats¶
MCP-Scan supports three output formats optimized for different use cases.
JSON Format (Default)¶
Machine-readable format with complete scan results.
Schema¶
{
"version": "1.0.0",
"scan_id": "20240115-143022-abc123",
"timestamp": "2024-01-15T14:30:22Z",
"config": {
"mode": "fast",
"hash": "sha256:abc123..."
},
"manifest": {
"total_files": 42,
"languages": {
"python": 25,
"typescript": 17
},
"files": [
{
"path": "src/handler.py",
"hash": "sha256:def456...",
"size": 1024,
"language": "python"
}
]
},
"mcp_surface": {
"transport": "stdio",
"tools": [
{
"name": "read_file",
"description": "Read a file from disk",
"handler": "handle_read_file",
"location": {
"file": "src/tools.py",
"line": 45
}
}
],
"auth_signals": [
{
"type": "jwt",
"location": {
"file": "src/auth.py",
"line": 23
}
}
]
},
"msss_score": {
"total": 85.5,
"level": 2,
"compliant": true,
"version": "1.0",
"categories": {
"A": {"score": 18, "max_score": 22, "findings": 2},
"E": {"score": 9, "max_score": 10, "findings": 1}
}
},
"findings": [
{
"id": "abc123def456",
"rule_id": "MCP-A003",
"severity": "critical",
"confidence": "high",
"language": "python",
"location": {
"file": "src/handler.py",
"start_line": 42,
"start_col": 5,
"end_line": 42,
"end_col": 35
},
"mcp_context": {
"tool_name": "execute_command",
"handler_name": "handle_execute",
"transport": "stdio"
},
"trace": {
"source": {
"file": "src/handler.py",
"start_line": 30,
"start_col": 10
},
"sink": {
"file": "src/handler.py",
"start_line": 42,
"start_col": 5
},
"steps": [
{
"location": {"file": "src/handler.py", "start_line": 30},
"action": "source",
"variable": "user_input"
},
{
"location": {"file": "src/handler.py", "start_line": 35},
"action": "assign",
"variable": "cmd"
},
{
"location": {"file": "src/handler.py", "start_line": 42},
"action": "sink",
"variable": "cmd"
}
]
},
"evidence": {
"snippet": "os.system(f'execute {cmd}')",
"snippet_hash": "sha256:789abc..."
},
"description": "Direct shell command execution detected",
"remediation": "Use subprocess with shell=False and explicit command list"
}
],
"summary": {
"total": 15,
"by_severity": {
"critical": 3,
"high": 5,
"medium": 7
},
"by_class": {
"A": 3,
"E": 2,
"L": 1
},
"by_language": {
"python": 10,
"typescript": 5
}
},
"duration": "2.345s"
}
Key Fields¶
| Field | Description |
|---|---|
scan_id |
Unique identifier for this scan |
manifest |
All scanned files with hashes |
mcp_surface |
Detected MCP tools and transport |
msss_score |
Security score and compliance level |
findings |
Array of all detected vulnerabilities |
summary |
Aggregated statistics |
SARIF 2.1.0 Format¶
Standard format for static analysis results, compatible with:
- GitHub Code Scanning
- Azure DevOps
- VS Code SARIF Viewer
- GitLab Security Dashboard
Schema¶
{
"$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "mcp-scan",
"version": "1.0.0",
"informationUri": "https://github.com/mcphub/mcp-scan",
"rules": [
{
"id": "MCP-A003",
"name": "RCE Direct Shell",
"shortDescription": {
"text": "Direct shell command execution detected"
},
"fullDescription": {
"text": "Direct shell command execution detected (os.system, subprocess with shell=True)"
},
"helpUri": "https://docs.mcp-scan.dev/rules/MCP-A003",
"defaultConfiguration": {
"level": "error"
},
"properties": {
"security-severity": "9.8",
"tags": ["security", "rce", "mcp"]
}
}
]
}
},
"results": [
{
"ruleId": "MCP-A003",
"ruleIndex": 0,
"level": "error",
"message": {
"text": "Direct shell command execution detected"
},
"locations": [
{
"physicalLocation": {
"artifactLocation": {
"uri": "src/handler.py"
},
"region": {
"startLine": 42,
"startColumn": 5,
"endLine": 42,
"endColumn": 35
}
}
}
],
"codeFlows": [
{
"threadFlows": [
{
"locations": [
{
"location": {
"physicalLocation": {
"artifactLocation": {"uri": "src/handler.py"},
"region": {"startLine": 30}
},
"message": {"text": "Source: user_input"}
}
},
{
"location": {
"physicalLocation": {
"artifactLocation": {"uri": "src/handler.py"},
"region": {"startLine": 42}
},
"message": {"text": "Sink: os.system()"}
}
}
]
}
]
}
],
"fixes": [
{
"description": {
"text": "Use subprocess with shell=False and explicit command list"
}
}
]
}
]
}
]
}
SARIF Severity Mapping¶
| MCP-Scan Severity | SARIF Level |
|---|---|
| critical | error |
| high | error |
| medium | warning |
| low | note |
| info | note |
GitHub Code Scanning Integration¶
# .github/workflows/security.yml
name: Security Scan
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run MCP-Scan
run: |
mcp-scan scan . --output sarif > results.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
Evidence Bundle Format¶
Directory-based format for security audits and compliance.
Directory Structure¶
evidence-bundle/
├── manifest.json # Scanned files with hashes
├── results.json # Summary and all findings
├── config.json # Scan configuration used
├── surface.json # MCP surface analysis
├── msss-score.json # MSSS compliance details
└── evidences/
├── finding-001.json
├── finding-002.json
└── ...
manifest.json¶
{
"scan_id": "20240115-143022-abc123",
"timestamp": "2024-01-15T14:30:22Z",
"total_files": 42,
"files": [
{
"path": "src/handler.py",
"hash": "sha256:def456...",
"size": 1024,
"language": "python"
}
]
}
Individual Evidence Files¶
Each finding gets its own evidence file:
{
"finding_id": "abc123def456",
"rule_id": "MCP-A003",
"severity": "critical",
"confidence": "high",
"location": {
"file": "src/handler.py",
"start_line": 42,
"end_line": 42
},
"evidence": {
"full_snippet": "def handle_execute(cmd):\n os.system(f'execute {cmd}')",
"context_before": ["def handle_execute(cmd):"],
"context_after": [" return result"],
"snippet_hash": "sha256:789abc..."
},
"trace": {
"complete": true,
"steps": [...]
},
"mcp_context": {
"tool_name": "execute_command",
"handler_name": "handle_execute"
},
"analysis_metadata": {
"mode": "deep",
"scan_duration": "2.345s",
"analyzer_version": "1.0.0"
}
}
Comparing Formats¶
| Feature | JSON | SARIF | Evidence |
|---|---|---|---|
| CI/CD Integration | Good | Best | Limited |
| Human Readable | Good | Poor | Best |
| GitHub Code Scanning | No | Yes | No |
| Audit Trail | Good | Good | Best |
| File Size | Medium | Large | Largest |
| Taint Traces | Yes | Yes (codeFlows) | Yes |
| MSSS Score | Yes | No | Yes |
| Individual Evidence | No | No | Yes |
Choosing a Format¶
- JSON: General purpose, scripting, custom processing
- SARIF: CI/CD, GitHub/GitLab integration, IDE plugins
- Evidence: Security audits, compliance documentation, detailed review