ShakerScan MCP Server

A Model Context Protocol (MCP) server for the ShakerScan control plane. It lets AI assistants like Claude and Cursor trigger DAST scans, run AI Gate deploy checks, inspect evidence, and verify signed release decisions without leaving the IDE.

Features

Tools

| Tool | Description | | ----------------------- | ------------------------------------------------------------------ | | scan_target | Trigger a DAST scan against any URL | | get_scan_status | Check scan progress and completion | | get_findings | Retrieve vulnerability findings with severity, CVSS, OWASP mapping | | verify_finding | Retest a stored finding and persist a verification artifact | | evaluate_policy | Return allow, block, or needs_approval for a scan | | get_evidence | Fetch a stored verification or policy artifact | | issue_approval_token | Mint a short-lived signed approval token | | verify_approval_token | Validate a signed approval token | | request_remediation | Create a persisted remediation artifact with fix steps and PR draft | | get_remediation_job | Fetch a stored remediation artifact | | get_usage | Read current scan, verify, policy, and API usage | | list_scans | List recent scans, filter by target | | compare_scans | Compare two scans to find new/resolved issues | | get_scan_history | View historical security posture for a domain | | list_targets | List configured DAST monitoring targets | | list_ai_targets | List saved AI Gate targets and ownership status | | get_ai_target | Inspect an AI Gate target and recent scan history | | trigger_ai_scan | Queue saved-target or inline AI Gate scans | | get_ai_scan_status | Read AI Gate lifecycle, policy, deploy-gate, and attestation state | | get_ai_scan_diff | Compare AI Gate scans for new/resolved/regressed findings | | get_ai_scan_transcript | Fetch callback-safe AI Gate transcript excerpts | | get_attestation_public_key | Fetch the public AI Gate attestation verification key | | verify_attestation | Verify an AI Gate attestation and optional deploy scope | | evaluate_agent_behavior | Evaluate structured agent, MCP, or CI traces |

Resources

• OWASP Top 10 (2021) - Reference guide for web security risks
• Severity Guide - How vulnerabilities are classified
• Scan Types Guide - Understanding different scan modes and phases

Prompts

• quick_security_check - Fast scan with summarized results
• comprehensive_audit - Full security audit with all phases
• fix_vulnerability - Remediation guidance for specific vuln types
• security_comparison - Analyze security trends over time

Installation

For End Users (via npx)

No installation required. The default configuration path is npx -y shakerscan-mcp.

For Development

cd scanner-mcp
npm install
npm run build

Getting Your API Key

1. Log in to shakerscan.com
2. Go to Control Plane Settings > API Keys
3. Click New API Key
4. Copy the key and store it outside your repo

API keys are available for all authenticated users.

Configuration

Environment Variables

# Required - your API key from shakerscan.com
export SCANNER_API_KEY="<your_shakerscan_api_key>"

# Optional - override API URL (defaults to shakerscan.com for hosted app keys)
# export SCANNER_API_URL="https://shakerscan.com"

Claude Code Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "shakerscan": {
      "command": "npx",
      "args": ["-y", "shakerscan-mcp"],
      "env": {
        "SCANNER_API_KEY": "<your_shakerscan_api_key>"
      }
    }
  }
}

Cursor Configuration

Add to Cursor's MCP settings (Settings → MCP):

{
  "mcpServers": {
    "shakerscan": {
      "command": "npx",
      "args": ["-y", "shakerscan-mcp"],
      "env": {
        "SCANNER_API_KEY": "<your_shakerscan_api_key>"
      }
    }
  }
}

Alternative: Global Install

npm install -g shakerscan-mcp

Then use "command": "shakerscan-mcp" instead of npx.

How It Hooks Into Agent Workflows

Shaker plugs into agentic workflows in two layers:

1. MCP provides executable tools.
2. A skill or workflow prompt tells the agent when to use those tools and how to make a gate decision.

Recommended pattern:

• Claude Code / Cursor: configure MCP with shakerscan-mcp
• Codex-style agents: pair MCP or direct HTTP with the repo skill at skills/shakerscan-agent-gate/
• CI pipelines: call the same API routes directly

Recommended control-plane flow:

• scan_target include repo, branch, and commit_sha when the scan is part of a GitHub PR or release gate
• get_scan_status
• get_findings
• verify_finding on critical and high findings that support deterministic retesting
• evaluate_policy for the deploy decision pass a policy_pack such as preview-fast, release-strict, or a tenant custom pack when the workflow should not rely on the workspace default pass the same repo, branch, and commit_sha if the scan was submitted by another system and the policy evidence must bind to a GitHub release scope
• get_evidence to attach the artifact to CI, a PR, or an audit log
• issue_approval_token when an allow decision needs a downstream proof object
• request_remediation when you need a durable fix plan, patch suggestion, and PR draft for blocked findings

Recommended AI Gate flow:

• list_ai_targets or provide an inline endpoint_url
• trigger_ai_scan with a probe pack such as shaker-ai-smoke, shaker-owasp-llm, shaker-agent-abuse, shaker-mcp-security, or shaker-rag-lite
• Include scan_profile (smoke, trace, standard, or deep) when you need explicit depth
• Include source-control scope (repo, branch, commit_sha, or source_control) so evidence and attestations bind to the release
• get_ai_scan_status until deploy_gate.verification.cli_command or policy evidence is ready
• get_ai_scan_transcript for callback-safe evidence excerpts
• get_ai_scan_diff to compare with the previous scan or a specific baseline
• verify_attestation to enforce signed evidence before an agent recommends deploy

Concrete assets in this repo:

• scanner-mcp/examples/github-actions-preview-gate.yml
• skills/shakerscan-agent-gate/SKILL.md
• skills/shakerscan-agent-gate/references/workflows.md

Usage Examples

Quick Security Check

You: "Scan https://example.com for security issues"

Claude: [Uses scan_target tool]
        [Uses get_scan_status to wait]
        [Uses get_findings to retrieve results]

        "The scan completed with a grade of B (82/100).
         Found 3 medium severity issues:
         1. Missing Content-Security-Policy header
         2. HSTS max-age is below recommended value
         3. Cookie missing SameSite attribute

         Recommendations: ..."

Comprehensive Audit

You: "Run a full security audit on my staging server https://staging.myapp.com"

Claude: [Uses scan_target with all phases enabled]
        [Monitors progress with get_scan_status]
        [Retrieves and analyzes findings]

        "Comprehensive audit complete. Grade: C (71/100)

         Critical Issues:
         - SQL injection in /api/search endpoint

         High Issues:
         - XSS vulnerability in comment form
         - Missing rate limiting on login

         Remediation roadmap: ..."

Track Security Over Time

You: "How has our security improved since last month?"

Claude: [Uses get_scan_history for domain]
        [Uses compare_scans on oldest vs newest]

        "Security has improved! Score increased from 65 to 82.

         Resolved:
         - SQL injection (critical)
         - 2 XSS vulnerabilities (high)

         New issues:
         - 1 medium severity header misconfiguration

         Trend: Improving"

AI Gate Deploy Decision

You: "Run the AI Gate smoke profile for our support bot target and verify the deploy decision"

Claude: [Uses trigger_ai_scan with target_id, scan_profile, repo, branch, commit_sha]
        [Uses get_ai_scan_status until deploy_gate is ready]
        [Uses verify_attestation when evidence includes a signed attestation]

        "AI Gate completed with decision: block.
         Finding: RAG citation canary leaked in turn 2.
         Evidence is hash-bound to commit abc123 and target ait_...
         Recommendation: block deploy, fix tenant filtering, then rerun."

Concrete MCP proof path:

{
  "tool": "trigger_ai_scan",
  "arguments": {
    "target_id": "ait_123",
    "probe_pack": "shaker-ai-smoke",
    "scan_profile": "smoke",
    "environment": "preview",
    "repo": "acme/support-bot",
    "branch": "feature/ai-gate",
    "commit_sha": "abc123"
  }
}

After get_ai_scan_status returns a deploy gate, pass the evidence attestation to verify_attestation with the expected release scope:

{
  "tool": "verify_attestation",
  "arguments": {
    "document": "<evidence.attestation>",
    "expected_scope": {
      "repo": "acme/support-bot",
      "branch": "feature/ai-gate",
      "commit_sha": "abc123",
      "environment": "preview",
      "target_id": "ait_123",
      "probe_pack": "shaker-ai-smoke",
      "decision": "allow",
      "evidence_hash": "sha256:8b7c...e21f"
    }
  }
}

Fix a Vulnerability

You: "Help me fix the XSS vulnerability in our React app"

Claude: [Uses fix_vulnerability prompt]

        "XSS (Cross-Site Scripting) allows attackers to inject
         malicious scripts. Here's how to fix it:

         Vulnerable pattern:
         ```jsx
         <div dangerouslySetInnerHTML={{__html: userInput}} />
         ```

         Secure pattern:
         ```jsx
         import DOMPurify from 'dompurify';
         <div dangerouslySetInnerHTML={{__html: DOMPurify.sanitize(userInput)}} />
         ```

         Additional hardening: ..."

Vulnerability Categories

| Category | Flag | Checks Included | | ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------- | | Authentication & Access | vuln_auth | CSRF, IDOR, Default Credentials, Rate Limiting, 2FA Bypass, Password Reset, Session Management | | Injection | vuln_injection | Path Traversal, Deserialization | | Web Application | vuln_web | File Upload, Open Redirect, Host Header, Business Logic, API Security | | Client-Side Exposure | exposure_client | JS Dependencies, JS Secrets | | Infrastructure Exposure | exposure_infra | CI/CD Exposure, Cloud Buckets, Backups, Package Files | | Threat Intelligence | threat_intel | IP Reputation, Breach Check, Vendor Risk, Typosquatting |

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test with MCP Inspector
npm run inspect

Architecture

┌─────────────────────────────────────┐
│   Claude Code / Cursor / IDE        │
└──────────────────┬──────────────────┘
                   │ JSON-RPC (stdio)
┌──────────────────▼──────────────────┐
│      ShakerScan MCP Server          │
│  ┌─────────┐ ┌─────────┐ ┌───────┐  │
│  │  Tools  │ │Resources│ │Prompts│  │
│  └────┬────┘ └─────────┘ └───────┘  │
└───────┼─────────────────────────────┘
        │ HTTPS + API Key
┌───────▼─────────────────────────────┐
│   ShakerScan Web App v1 API          │
│   /api/v1/scan, /api/v1/ai/scans,    │
│   /api/v1/findings, /api/v1/evidence │
└───────┬─────────────────────────────┘
        │
┌───────▼─────────────────────────────┐
│   AWS Scanner Infrastructure         │
│   Lambda/ECS + S3                    │
└───────┬─────────────────────────────┘
        │
┌───────▼─────────────────────────────┐
│   Supabase (PostgreSQL)              │
│   Scans, Findings, API Keys          │
└─────────────────────────────────────┘

License

MIT