shakerscan-mcp 1.0.0

package/README.md

@@ -0,0 +1,295 @@
+# ShakerScan MCP Server
+
+A Model Context Protocol (MCP) server for the Shaker Scan control plane. It lets AI assistants like Claude and Cursor trigger scans, inspect findings, and plug security checks into agent workflows 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                            |
+
+### 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! Just configure your AI IDE (see Configuration below).
+
+### For Development
+
+```bash
+cd scanner-mcp
+npm install
+npm run build
+```
+
+## Getting Your API Key
+
+1. Log in to [shakerscan.com](https://shakerscan.com)
+2. Go to **Control Plane Settings > API Keys**
+3. Click **New API Key**
+4. Copy the key (starts with `sk_live_`)
+
+> API keys are available for all authenticated users.
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required - your API key from shakerscan.com
+export SCANNER_API_KEY="sk_live_your_key_here"
+
+# Optional - override API URL (defaults to shakerscan.com for sk_live_ keys)
+# export SCANNER_API_URL="https://shakerscan.com"
+```
+
+### Claude Code Configuration
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "shakerscan": {
+      "command": "npx",
+      "args": ["-y", "shakerscan-mcp"],
+      "env": {
+        "SCANNER_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor Configuration
+
+Add to Cursor's MCP settings (Settings → MCP):
+
+```json
+{
+  "mcpServers": {
+    "shakerscan": {
+      "command": "npx",
+      "args": ["-y", "shakerscan-mcp"],
+      "env": {
+        "SCANNER_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Alternative: Global Install
+
+```bash
+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`
+- `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
+- `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
+
+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"
+```
+
+### 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
+
+```bash
+# 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 (sk_live_*)
+┌───────▼─────────────────────────────┐
+│   ShakerScan Web App v1 API          │
+│   /api/v1/scan, /api/v1/scans,       │
+│   /api/v1/findings                   │
+└───────┬─────────────────────────────┘
+        │
+┌───────▼─────────────────────────────┐
+│   AWS Scanner Infrastructure         │
+│   Lambda/ECS + S3                    │
+└───────┬─────────────────────────────┘
+        │
+┌───────▼─────────────────────────────┐
+│   Supabase (PostgreSQL)              │
+│   Scans, Findings, API Keys          │
+└─────────────────────────────────────┘
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * ShakerScan MCP Server
+ *
+ * A Model Context Protocol server for Dynamic Application Security Testing (DAST).
+ * Enables AI assistants like Claude to trigger security scans, analyze vulnerabilities,
+ * and help developers fix security issues without leaving their IDE.
+ *
+ * Usage:
+ *   SCANNER_API_KEY=xxx npx shakerscan-mcp
+ *
+ * Environment Variables:
+ *   SCANNER_API_KEY      - Required: API key for ShakerScan AWS API
+ *   SCANNER_API_URL      - Optional: API endpoint (default: production)
+ *   SUPABASE_URL         - Optional: Supabase URL for direct DB access
+ *   SUPABASE_SERVICE_KEY - Optional: Supabase service role key
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;GAeG"}