BetterQA Security MCP Server

Model Context Protocol (MCP) server for AI-powered security scanning. Provides comprehensive SAST, SCA, DAST, and secrets detection capabilities that can be invoked by Claude Code, Claude Desktop, or any MCP-compatible client.

Overview

The security MCP server exposes three tools:

| Tool | Description | |------|-------------| | scan | Start a V4 Maximum Coverage security scan (SAST + SCA + DAST + Secrets) | | scan_status | Check progress of a running scan | | scan_results | Get findings from a completed scan |

Prerequisites

Required

• Node.js 18+
• ANTHROPIC_API_KEY environment variable (for AI-powered analysis)

Security Tools (install for full coverage)

SAST (Static Application Security Testing):

pip3 install semgrep bandit

SCA (Software Composition Analysis):

brew install trivy syft
pip3 install pip-audit

DAST (Dynamic Application Security Testing):

pip3 install wapiti3
brew install sqlmap nuclei ffuf gitleaks testssl

Secrets Detection:

brew install gitleaks trufflehog

Quick Start

1. Build the Server

cd mcp-server
npm install
npm run build

2. Configure Claude Code

Add to your ~/.claude/claude_desktop_config.json or project .mcp.json:

{
  "mcpServers": {
    "security": {
      "command": "node",
      "args": ["/path/to/security-tool/mcp-server/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Use from Claude

Once configured, you can ask Claude to run security scans:

Scan https://example.com for security vulnerabilities

Run a SAST scan on ./src with SARIF output

Check the status of scan abc123

Tool Reference

scan

Start a comprehensive security scan.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | target_url | string | Yes* | URL to scan (required for DAST) | | source_path | string | No | Path to source code for SAST/SCA | | api_spec | string | No | OpenAPI/Swagger/HAR file path | | auth_type | enum | No | cookie, bearer, basic, oauth | | auth_value | string | No | Auth credential value | | exclude_paths | array | No | URL paths to skip | | rate_limit | number | No | Max requests/second | | quick | boolean | No | Skip cross-pollination for speed | | skip_sast | boolean | No | Skip SAST/SCA analysis | | skip_dast | boolean | No | Skip DAST tools | | skip_gaps | boolean | No | Skip gap filling phase |

Example:

{
  "target_url": "https://ginandjuice.shop",
  "source_path": "./src",
  "auth_type": "cookie",
  "auth_value": "session=abc123"
}

scan_status

Check scan progress.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | scan_id | string | Yes | Scan ID from scan tool |

Example Response:

{
  "status": "running",
  "phase": "DAST",
  "progress": 65,
  "agents": {
    "semgrep": "completed",
    "trivy": "completed",
    "nuclei": "running",
    "wapiti": "pending"
  }
}

scan_results

Get findings from a completed scan.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | scan_id | string | Yes | Scan ID from scan tool | | severity_filter | enum | No | Minimum severity: critical, high, medium, low, info | | min_confidence | enum | No | Minimum confidence: high, medium, low |

Example Response:

{
  "findings": [
    {
      "id": "semgrep-001",
      "title": "SQL Injection in user input",
      "severity": "critical",
      "confidence": "high",
      "category": "SAST",
      "source": "semgrep",
      "description": "User input passed directly to SQL query",
      "evidence": "query = f\"SELECT * FROM users WHERE id = {user_id}\"",
      "endpoint": "src/db.py:42",
      "cwe": "CWE-89",
      "remediation": "Use parameterized queries"
    }
  ],
  "coverage": {
    "sast": true,
    "sca": true,
    "dast": true,
    "secrets": true
  },
  "summary": {
    "critical": 1,
    "high": 3,
    "medium": 12,
    "low": 5
  }
}

Auditi Integration

The MCP server is designed to integrate with Auditi, BetterQA's accessibility and security auditing platform.

Configuration for Auditi

Create .mcp.json in your Auditi project root:

{
  "mcpServers": {
    "security": {
      "command": "node",
      "args": ["./node_modules/@betterqa/security-mcp/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

Workflow Example

1. Pre-commit hook: Run SAST-only scan on changed files
2. CI/CD pipeline: Run full scan with SARIF output
3. Production monitoring: Periodic DAST scans with authentication

SARIF Output for IDE Integration

The server generates SARIF (Static Analysis Results Interchange Format) output compatible with:

• VS Code SARIF Viewer extension
• GitHub Code Scanning
• Azure DevOps
• SonarQube

Runners Architecture

The MCP server uses modular runners for each scanning category:

mcp-server/
├── dist/
│   ├── index.js          # MCP server entry point
│   ├── tools/
│   │   ├── scan.js       # Scan orchestration
│   │   ├── status.js     # Progress tracking
│   │   └── results.js    # Results formatting
│   └── runners/
│       ├── sast.js       # Semgrep, Bandit, njsscan, gosec
│       ├── sca.js        # Trivy, Syft, pip-audit
│       ├── dast.js       # Wapiti, Nuclei, sqlmap, ffuf
│       ├── secrets.js    # Gitleaks, Trufflehog
│       └── exec.js       # Common utilities

Runner Functions

SAST Runners (sast.js):

• runSemgrep(sourcePath) - Multi-language SAST with security-audit config
• runBandit(sourcePath) - Python security linter
• runNjsscan(sourcePath) - Node.js/JavaScript SAST
• runGosec(sourcePath) - Go security checker
• runAllSast(sourcePath) - Run all applicable SAST tools

SCA Runners (sca.js):

• runTrivy(sourcePath) - Dependency vulnerability scan
• runSyft(sourcePath, outputPath) - Generate CycloneDX SBOM
• runPipAudit(sourcePath) - Python dependency audit
• runAllSca(sourcePath, sbomDir) - Run all SCA tools

Secrets Runners (secrets.js):

• runGitleaks(sourcePath) - Fast secrets detection
• runTrufflehog(sourcePath) - Deep secrets scan with verification
• runAllSecrets(sourcePath) - Run all secrets tools

Output Formats

JSON (Default)

All tools output structured JSON for programmatic consumption.

SARIF

SARIF output is generated in the sarif/ directory when enabled:

reports/scan_TIMESTAMP/
├── sarif/
│   ├── semgrep.sarif.json
│   ├── bandit.sarif.json
│   ├── trivy.sarif.json
│   └── gitleaks.sarif.json

SBOM (CycloneDX)

Software Bill of Materials in CycloneDX format:

reports/scan_TIMESTAMP/
└── sbom/
    └── sbom.cyclonedx.json

Bash Scripts Alternative

For environments without Node.js or when MCP isn't available, use the bash scripts directly:

# SAST/SCA only
./scripts/run-all-tests.sh --sast-only --source-path . --sarif --sbom

# DAST only
./scripts/run-all-tests.sh https://example.com --comprehensive

# Combined SAST/SCA + DAST
./scripts/run-all-tests.sh https://example.com --source-path ./src --sarif

Troubleshooting

"ANTHROPIC_API_KEY environment variable is required"

Set the API key in your MCP config or shell:

export ANTHROPIC_API_KEY="sk-ant-..."

"Tool not found" errors

Run the prerequisites checker:

./scripts/check-prerequisites.sh

Scan hangs or times out

• Check network connectivity to target URL
• Verify source path exists and is readable
• Try quick: true mode for faster results

No findings from SAST

• Ensure source code contains supported languages
• Check that semgrep rules are downloaded: semgrep --config=auto --dry-run .

License

BetterQA Security Toolkit - Comprehensive Security Testing at $0 Cost

Built by BetterQA - Software Testing Company