VibeDefender MCP Server

/** * Workflow Prompts * * User-friendly guided workflows for non-technical developers. * Each prompt tells the AI exactly what to do at each step. */ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { z } from 'zod'; // ============================================================================ // WORKFLOW PROMPTS // ============================================================================ const WORKFLOWS = { // ------------------------------------------------------------------------- // SETUP - First-time setup wizard // ------------------------------------------------------------------------- setup: { name: 'setup', description: 'Help set up security scanning tools on this machine', content: `# Security Tools Setup Wizard You are helping a non-technical user set up security scanning tools. Be friendly, explain things simply, and guide them step by step. ## Step 1: Check What's Already Installed Run these commands to check which tools are installed: \`\`\`bash trivy --version 2>/dev/null && echo "Trivy: INSTALLED" || echo "Trivy: NOT INSTALLED" semgrep --version 2>/dev/null && echo "Semgrep: INSTALLED" || echo "Semgrep: NOT INSTALLED" gitleaks version 2>/dev/null && echo "Gitleaks: INSTALLED" || echo "Gitleaks: NOT INSTALLED" nuclei --version 2>/dev/null && echo "Nuclei: INSTALLED" || echo "Nuclei: NOT INSTALLED" \`\`\` ## Step 2: For Each Missing Tool Explain what each tool does in simple terms, then help install it: ### Trivy (Vulnerability Scanner) **What it does:** Checks your project's dependencies (npm packages, Python libraries, etc.) for known security vulnerabilities that hackers could exploit. **Install on macOS:** \`\`\`bash brew install aquasecurity/trivy/trivy \`\`\` **Install on Linux:** \`\`\`bash curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin \`\`\` ### Semgrep (Code Analyzer) **What it does:** Reads your code and finds common security mistakes like SQL injection, XSS, and hardcoded passwords. **Install on macOS:** \`\`\`bash brew install semgrep \`\`\` **Install on Linux/Any:** \`\`\`bash pip install semgrep \`\`\` ### Gitleaks (Secret Scanner) **What it does:** Finds accidentally committed secrets like API keys, passwords, and tokens that should never be in code. **Install on macOS:** \`\`\`bash brew install gitleaks \`\`\` **Install on Linux:** \`\`\`bash # Download from GitHub releases or use Go: go install github.com/gitleaks/gitleaks/v8@latest \`\`\` ### Nuclei (Live Scanner) - Optional **What it does:** Tests live websites for vulnerabilities. Only needed if you want to test running applications. **Install on macOS:** \`\`\`bash brew install nuclei nuclei -update-templates \`\`\` ## Step 3: Verify Installation After installing, verify each tool works: \`\`\`bash trivy --version semgrep --version gitleaks version nuclei --version # if installed \`\`\` ## Step 4: Confirm Ready Once all tools are installed, tell the user: "You're all set! You can now run security scans on your code. Just say 'scan my code' or 'check before I push' to get started." ## Important Notes - Be patient - installations can take a few minutes - If homebrew isn't installed on macOS, help them install it first - If any tool fails to install, search for alternative installation methods - Don't overwhelm the user - install one tool at a time`, }, // ------------------------------------------------------------------------- // VALIDATE-TOOLS - Required tool validation (MANDATORY before scanning) // ------------------------------------------------------------------------- 'validate-tools': { name: 'validate-tools', description: 'Validate security tools are installed and working (required before scanning)', content: `# Security Tools Validation **IMPORTANT:** This step is REQUIRED before running any security scans. ## Step 1: Check Current Tool Status Run these checks in parallel: \`\`\`bash # Check trivy trivy --version 2>/dev/null && echo "✅ Trivy: INSTALLED" || echo "❌ Trivy: NOT INSTALLED" # Check semgrep semgrep --version 2>/dev/null && echo "✅ Semgrep: INSTALLED" || echo "❌ Semgrep: NOT INSTALLED" # Check nuclei nuclei --version 2>/dev/null && echo "✅ Nuclei: INSTALLED" || echo "❌ Nuclei: NOT INSTALLED" \`\`\` ## Step 2: Install Missing Tools (If Any) **If ALL required tools (trivy, semgrep, nuclei) are installed:** → Skip to Step 3 (Validation) **If ANY required tools are missing:** Tell the user: "I need to install [X] security tools before we can scan. This will take about 3-5 minutes." **Don't ask permission - just guide the installation:** ### macOS Installation \`\`\`bash # Install all missing tools at once brew install aquasecurity/trivy/trivy semgrep nuclei # Verify installations trivy --version && semgrep --version && nuclei --version \`\`\` ### Linux Installation \`\`\`bash # Trivy curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin # Semgrep pip3 install semgrep # Nuclei go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest export PATH=$PATH:$(go env GOPATH)/bin nuclei -update-templates # Verify trivy --version && semgrep --version && nuclei --version \`\`\` **If installation fails (no sudo, network issues, etc.):** → Explain the issue clearly → Provide manual installation documentation links → Ask user if they want to proceed with manual review only (as fallback) ## Step 3: Validation Tests **CRITICAL:** After installation, verify each tool works correctly: \`\`\`bash # Validate trivy can scan echo "Testing trivy..." && trivy fs --format json --severity CRITICAL . 2>/dev/null | head -c 100 && echo "\\n✅ Trivy: WORKING" || echo "❌ Trivy: FAILED" # Validate semgrep can scan echo "Testing semgrep..." && semgrep --version >/dev/null 2>&1 && semgrep scan --config auto --json . 2>/dev/null | head -c 100 && echo "\\n✅ Semgrep: WORKING" || echo "❌ Semgrep: FAILED" # Validate nuclei (check templates are installed) echo "Testing nuclei..." && nuclei --version >/dev/null 2>&1 && nuclei -tl 2>/dev/null | head -5 && echo "✅ Nuclei: WORKING" || echo "❌ Nuclei: FAILED" \`\`\` **If any validation fails:** - Identify which tool failed - Check if it's a PATH issue: \`which <tool>\` - Try absolute path if needed - If still failing, report detailed error and suggest reinstallation ## Step 4: Report Status **If ALL tools validated successfully:** Tell the user: "✅ All security tools are installed and validated! - Trivy (CVE scanning): Ready - Semgrep (Code analysis): Ready - Nuclei (Runtime testing): Ready You're ready to run security scans. Use the \`scan\` workflow to analyze your codebase." **If some tools failed validation:** Tell the user what's working and what's not, then guide troubleshooting. ## Error Recovery Common issues and fixes: 1. **"command not found" after install:** - Check PATH: \`echo $PATH\` - Source shell config: \`source ~/.bashrc\` or \`source ~/.zshrc\` - Try absolute path: \`/usr/local/bin/trivy --version\` 2. **Permission denied:** - Some steps need sudo - Use \`sudo\` for installation commands - Check file permissions: \`ls -la /usr/local/bin/trivy\` 3. **Network timeout during install:** - Check internet connection - Try alternative installation method - Use package manager cache if available ## Important Notes - This validation should take 30-60 seconds if tools are already installed - First-time installation takes 3-5 minutes depending on network speed - Once validated, tools remain available for future scans - Re-validation only needed if tools are updated or removed`, }, // ------------------------------------------------------------------------- // SCAN - Full codebase security scan // ------------------------------------------------------------------------- scan: { name: 'scan', description: 'Run a complete security scan with static analysis and runtime testing', content: `# Complete Security Scan You are running a comprehensive security scan that combines static analysis with runtime testing. Runtime analysis is essential for finding real vulnerabilities. ## Step 1: Tool Validation (MANDATORY - DO NOT SKIP) **STOP: Before scanning, ALL required tools MUST be installed and validated.** ### Check Tool Status \`\`\`bash trivy --version 2>/dev/null && echo "✅ Trivy: OK" || echo "❌ Trivy: MISSING" semgrep --version 2>/dev/null && echo "✅ Semgrep: OK" || echo "❌ Semgrep: MISSING" nuclei --version 2>/dev/null && echo "✅ Nuclei: OK" || echo "❌ Nuclei: MISSING" \`\`\` ### If ANY tools are missing: **DO NOT proceed with scan. Instead:** Tell the user: "⚠️ Required security tools are missing. I need to install them before scanning. This is a one-time setup that takes about 3-5 minutes. I'll install the missing tools now..." **Then IMMEDIATELY guide installation** (don't ask for permission): **For macOS:** \`\`\`bash brew install aquasecurity/trivy/trivy semgrep nuclei \`\`\` **For Linux:** \`\`\`bash # Trivy curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin # Semgrep pip3 install semgrep # Nuclei go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest export PATH=$PATH:$(go env GOPATH)/bin nuclei -update-templates \`\`\` **After installation, VALIDATE each tool:** \`\`\`bash trivy --version && echo "✅ Trivy validated" || echo "❌ Trivy validation failed" semgrep --version && echo "✅ Semgrep validated" || echo "❌ Semgrep validation failed" nuclei --version && echo "✅ Nuclei validated" || echo "❌ Nuclei validation failed" \`\`\` **If validation fails:** - Report which tool failed - If still failing: "Tool installation issue detected. Please run the \`validate-tools\` workflow for detailed troubleshooting." - **STOP the scan** - do not proceed without tools **If ALL validations pass:** → Continue to Step 2 (Identify the Project) ## Step 2: Identify the Project First, understand what you're scanning: - Look for package.json (Node.js), requirements.txt (Python), go.mod (Go), etc. - Note the main language and framework - Tell the user: "I see this is a [Node.js/Python/etc.] project using [Express/Django/etc.]" ## Step 3: Run Dependency Scan (Trivy) Tell the user: "First, I'm checking if any of your dependencies have known security issues..." \`\`\`bash trivy fs . --format json --severity CRITICAL,HIGH,MEDIUM 2>/dev/null \`\`\` **IMPORTANT: Validate output before parsing:** 1. Check if the command succeeded (exit code 0) 2. Check if output is valid JSON (try parsing it first) 3. If JSON is invalid or empty: - Check stderr for error messages - Verify trivy is still working: \`trivy --version\` - If trivy broken, tell user: "Trivy scan failed. Please run \`validate-tools\` workflow to check tool status." - Skip this scan and continue to next step 4. If JSON is valid, proceed to parse and explain **Parse the results and explain:** - For CRITICAL: "URGENT: Found [X] critical vulnerabilities that hackers actively exploit" - For HIGH: "Found [X] high-severity issues that should be fixed soon" - For MEDIUM: "Found [X] medium issues to review when you have time" **For each critical finding, explain:** - Which package has the problem - What the vulnerability allows (e.g., "allows attackers to run code on your server") - How to fix it (usually: "update [package] to version [X]") ## Step 4: Run Code Analysis (Semgrep) Tell the user: "Now I'm scanning your code for security mistakes..." \`\`\`bash semgrep scan --config auto --json 2>/dev/null \`\`\` **IMPORTANT: Validate output before parsing:** 1. Check if the command succeeded (exit code 0) 2. Check if output is valid JSON (try parsing it first) 3. If JSON is invalid or empty: - Check stderr for error messages - Verify semgrep is still working: \`semgrep --version\` - If semgrep broken, tell user: "Semgrep scan failed. Please run \`validate-tools\` workflow to check tool status." - Skip this scan and continue to next step 4. If JSON is valid, proceed to parse and explain **Parse the results and explain in plain English:** - SQL Injection: "Found code that could let hackers access your database" - XSS: "Found code that could let hackers inject malicious scripts" - Hardcoded secrets: "Found passwords or keys written directly in code" - Path traversal: "Found code that could let hackers access files they shouldn't" **For each finding, show:** - The file and line number - A simple explanation of the risk - How to fix it (be specific!) ## Step 5: Runtime Analysis (MANDATORY) **CRITICAL: Static analysis alone is not sufficient. Runtime testing is essential to find real vulnerabilities.** ### Detect How to Run the Application Look for: - package.json scripts: "dev", "start", "serve" - Python: manage.py, app.py, main.py - Go: main.go - Docker: docker-compose.yml, Dockerfile ### Start the Application **If you can detect how to start the application:** Start it in the background: \`\`\`bash # Example for Node.js npm run dev & # Wait for server to be ready sleep 5 \`\`\` Verify it's running: \`\`\`bash curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 \`\`\` → Continue to Runtime Testing below **If you CANNOT start the application OR server fails to start:** **ASK THE USER for a live URL:** "I need a live URL to complete the security scan. Runtime analysis is essential for finding real vulnerabilities. Can you provide: 1. A live URL (staging, development, or production) that I'm authorized to test? 2. OR help me start your local development server? Without runtime testing, the scan will be incomplete and may miss critical vulnerabilities." **If user provides URL:** → Continue to Runtime Testing below **If user says NO URL available:** **ASK THE USER if they want to proceed:** "⚠️ Without runtime analysis, this scan will be incomplete. Static analysis alone often misses critical vulnerabilities like: - Authentication bypasses - Authorization flaws - Business logic bugs - API security issues Do you want to: A) Proceed with static-only scan (not recommended) B) Cancel and come back when you have a live URL C) Let me help you start your dev server" **Only proceed with static-only if user explicitly chooses option A.** ### Runtime Testing Tell the user: "Running live security tests against the application..." Run nuclei scans: \`\`\`bash # Technology detection nuclei -u {URL} -t technologies/ -json 2>/dev/null # Exposed files and endpoints nuclei -u {URL} -t exposures/ -json 2>/dev/null # Security misconfigurations nuclei -u {URL} -t misconfiguration/ -json 2>/dev/null # HTTP security issues nuclei -u {URL} -t http/ -json 2>/dev/null \`\`\` **Parse nuclei results and explain each finding in plain English.** ### Stop Development Server (if you started it) \`\`\`bash pkill -f "npm run dev" || pkill -f "node" || pkill -f "python" \`\`\` ## Step 6: Generate Referenceable Artifacts **IMPORTANT: Save all scan results to files for future reference.** Create artifact directory: \`\`\`bash mkdir -p security-scan-$(date +%Y%m%d-%H%M%S) cd security-scan-$(date +%Y%m%d-%H%M%S) \`\`\` Save results: \`\`\`bash # Save trivy results trivy fs .. --format json --severity CRITICAL,HIGH,MEDIUM > trivy-results.json # Save semgrep results semgrep scan --config auto --json .. > semgrep-results.json # Save nuclei results (if runtime testing was done) # Already captured from previous step \`\`\` Create summary report: \`\`\`markdown # Security Scan Report **Date:** $(date) **Project:** [project name] **Scanned by:** Security MCP ## Summary - Critical issues: X - High issues: X - Medium issues: X ## Detailed Findings [List all findings with severity, description, location, remediation] ## Artifacts - trivy-results.json - Dependency vulnerability scan - semgrep-results.json - Code security analysis - nuclei-results.json - Runtime security testing (if performed) ## Recommendations [Prioritized list of actions] \`\`\` Tell the user: "✅ Scan complete! All results saved to: security-scan-[timestamp]/ Artifacts created: - trivy-results.json - Full dependency scan results - semgrep-results.json - Full code analysis results - nuclei-results.json - Runtime testing results - REPORT.md - Human-readable summary You can reference these files in tickets, documentation, or share with your team." ## Step 7: Summary Report Give a clear summary: "## Security Scan Complete **Summary:** - Critical issues: X (fix immediately!) - High issues: X (fix before deploying) - Medium issues: X (review when possible) - Runtime issues: X (found during live testing) **Artifacts Generated:** All scan results saved to: security-scan-[timestamp]/ **What to do next:** 1. [Most urgent action] 2. [Second priority] 3. [Third priority] Would you like me to help you fix any of these issues?" ## Command Execution Notes When running commands that output JSON (trivy, semgrep, nuclei): 1. **Get raw JSON output** without piping to jq or other parsers 2. **Parse the JSON yourself** using your built-in JSON parsing capabilities 3. **Don't use bash jq pipelines** - this causes shell escaping issues and syntax errors 4. **Example pattern:** \`trivy fs . --format json\` → parse JSON in your code → extract findings 5. **Why:** Bash escaping with jq is error-prone (e.g., \`!=\` becomes \`\\!=\` and fails). Your native JSON parsing is more reliable. ## Important Notes - Always explain WHY something is a problem, not just that it is - Provide specific fix instructions, not just "fix this" - Don't scare the user - be reassuring that these are fixable - Offer to help fix issues one by one`, }, // ------------------------------------------------------------------------- // SCAN-LIVE - Start dev server and test // ------------------------------------------------------------------------- 'scan-live': { name: 'scan-live', description: 'Start development server and run live security tests', content: `# Live Security Testing You are helping test a running application for security issues. This involves starting the dev server and running live tests. ## Step 0: Verify Nuclei Installation (MANDATORY) **STOP: Live testing requires nuclei. Verify it's installed before proceeding.** ### Check Nuclei Status \`\`\`bash nuclei --version 2>/dev/null && echo "✅ Nuclei: OK" || echo "❌ Nuclei: MISSING" \`\`\` ### If nuclei is missing: **DO NOT proceed with live testing. Instead:** Tell the user: "⚠️ Nuclei is required for live security testing but isn't installed. This is a one-time setup that takes about 2 minutes. After this, live testing will work immediately. I'll install nuclei now..." **Then IMMEDIATELY guide installation** (don't ask for permission): #### macOS Installation \`\`\`bash # Install nuclei via Homebrew brew install nuclei # Update nuclei templates to latest nuclei -update-templates # Verify installation nuclei --version \`\`\` #### Linux Installation \`\`\`bash # Install via go (requires Go to be installed) go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest # Add to PATH if needed export PATH=$PATH:$(go env GOPATH)/bin # Update templates nuclei -update-templates # Verify installation nuclei --version \`\`\` **If Go is not installed on Linux:** \`\`\`bash # Download pre-built binary wget https://github.com/projectdiscovery/nuclei/releases/latest/download/nuclei_3.1.0_linux_amd64.zip unzip nuclei_3.1.0_linux_amd64.zip sudo mv nuclei /usr/local/bin/ rm nuclei_3.1.0_linux_amd64.zip # Update templates nuclei -update-templates # Verify nuclei --version \`\`\` ### Validate Nuclei Installation **After installation, VALIDATE nuclei works:** \`\`\`bash # Test nuclei is accessible nuclei --version && echo "✅ Nuclei validated" || echo "❌ Nuclei validation failed" # Verify templates are up to date nuclei -update-templates 2>&1 | grep -q "successfully" && echo "✅ Templates updated" || echo "⚠️ Template update failed" \`\`\` **If validation fails:** - Report which step failed (installation or template update) - Check PATH: \`echo $PATH | grep -o '/usr/local/bin'\` - Try absolute path: \`/usr/local/bin/nuclei --version\` - Check Go installation if using go install: \`go version\` - If still failing: "Nuclei installation issue detected. Please check: 1. Go is installed (for go install method): \`go version\` 2. /usr/local/bin is in PATH: \`echo $PATH\` 3. You have write permissions to /usr/local/bin Cannot proceed with live testing without nuclei." - **STOP the scan-live workflow** - do not proceed without nuclei **If ALL validations pass:** Tell the user: "✅ Nuclei is ready! Starting live security testing..." → Continue to Step 1 (Detect How to Start the Server) ## Step 1: Detect How to Start the Server Look for common patterns: - package.json scripts: "dev", "start", "serve" - Python: manage.py, app.py, main.py - Go: main.go - Ruby: rails server Tell the user: "I found your project uses [framework]. I'll start it with [command]." ## Step 2: Start the Development Server **For Node.js:** \`\`\`bash npm run dev & # or npm start & \`\`\` **For Python:** \`\`\`bash python manage.py runserver & # or python app.py & \`\`\` Wait for the server to be ready (look for "listening on" or similar messages). Tell the user: "Server is starting... I'll wait for it to be ready." ## Step 3: Determine the Local URL Common defaults: - Node.js/Express: http://localhost:3000 - Next.js: http://localhost:3000 - Python/Django: http://localhost:8000 - Python/Flask: http://localhost:5000 Verify the server is responding: \`\`\`bash curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 \`\`\` ## Step 4: Run Nuclei Security Tests Tell the user: "Server is ready! Now I'm testing it for common vulnerabilities..." **Safe templates to run (won't damage anything):** \`\`\`bash # Technology detection nuclei -u http://localhost:3000 -t technologies/ -json 2>/dev/null # Exposed files and panels nuclei -u http://localhost:3000 -t exposures/ -json 2>/dev/null # Misconfigurations nuclei -u http://localhost:3000 -t misconfiguration/ -json 2>/dev/null \`\`\` **IMPORTANT: Validate each nuclei output before parsing:** 1. Check if the command succeeded (exit code 0) 2. Check if output is valid JSON (try parsing it first) 3. If JSON is invalid or command failed: - Check if server is still responding: \`curl -s http://localhost:3000\` - Verify nuclei is still working: \`nuclei --version\` - Check if templates exist: \`nuclei -tl 2>&1 | head -5\` - If nuclei broken, tell user: "Nuclei scan failed. Please run \`validate-tools\` workflow to check tool status." - Skip this template and continue to next template 4. If JSON is valid, proceed to parse and explain 5. Note: Empty JSON array \`[]\` means no findings (this is normal, not an error) **DO NOT run these without explicit permission:** - cves/ templates (could be dangerous) - vulnerabilities/ templates (active exploitation) ## Step 5: Explain Findings For each finding, explain in plain English: - "Found: Your server is exposing [X]" - "Risk: This could let attackers [Y]" - "Fix: [Specific instructions]" ## Step 6: Stop the Server \`\`\`bash # Find and stop the dev server pkill -f "npm run dev" || pkill -f "node" || pkill -f "python" \`\`\` Tell the user: "Tests complete! I've stopped the dev server." ## Step 7: Summary "## Live Test Results **Server tested:** http://localhost:3000 **Technologies detected:** [list] **Issues found:** [count] **Findings:** 1. [Finding with explanation] 2. [Finding with explanation] **Recommendations:** - [Specific action items]" ## Command Execution Notes When running nuclei commands that output JSON: 1. **Get raw JSON output** without piping to jq or other parsers 2. **Parse the JSON yourself** using your built-in JSON parsing capabilities 3. **Don't use bash jq pipelines** - this causes shell escaping issues and syntax errors 4. **Example pattern:** \`nuclei -u URL -t templates/ -json\` → parse JSON in your code → extract findings 5. **Why:** Bash escaping with jq is error-prone. Your native JSON parsing is more reliable and avoids syntax errors. ## Important Notes - Always stop the server when done - Only run safe, read-only tests - Never run destructive or exploit templates - If server won't start, help debug the issue - Ask user before testing non-localhost URLs`, }, // ------------------------------------------------------------------------- // SCAN-URL - Test a provided URL // ------------------------------------------------------------------------- 'scan-url': { name: 'scan-url', description: 'Run security tests against a provided URL', argsSchema: { url: z.string().describe('The URL to test (must be owned by the user)'), }, content: `# URL Security Testing You are testing a URL provided by the user. This is for testing their own applications only. ## Step 0: Verify Nuclei Installation (MANDATORY) **STOP: Live URL testing requires nuclei. Verify it's installed before proceeding.** ### Check Nuclei Status \`\`\`bash nuclei --version 2>/dev/null && echo "✅ Nuclei: OK" || echo "❌ Nuclei: MISSING" \`\`\` ### If nuclei is missing: **DO NOT proceed with URL testing. Instead:** Tell the user: "⚠️ Nuclei is required for live URL testing but isn't installed. This is a one-time setup that takes about 2 minutes. I'll install nuclei now..." **Then IMMEDIATELY guide installation:** **macOS:** \`\`\`bash brew install nuclei nuclei -update-templates nuclei --version \`\`\` **Linux:** \`\`\`bash go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest export PATH=$PATH:$(go env GOPATH)/bin nuclei -update-templates nuclei --version \`\`\` ### Validate Nuclei Installation **After installation, VALIDATE nuclei works:** \`\`\`bash nuclei --version && echo "✅ Nuclei validated" || echo "❌ Nuclei validation failed" \`\`\` **If validation fails:** - STOP the scan-url workflow - Report the issue to the user - Suggest running the \`validate-tools\` workflow **If validation passes:** Tell the user: "✅ Nuclei is ready! Starting URL security testing..." → Continue to Step 1 ## Step 1: Validate the Target **IMPORTANT:** Before testing, confirm: 1. The user owns or has permission to test this URL 2. The URL is accessible \`\`\`bash curl -s -o /dev/null -w "%{http_code}" {url} \`\`\` If the URL returns 4xx/5xx or times out, help troubleshoot. ## Step 2: Authorization Check Ask the user: "Before I test {url}, please confirm: - You own this application, OR - You have written permission to test it Testing without permission is illegal. Do you have authorization? (yes/no)" **Only proceed if they confirm yes.** ## Step 3: Technology Detection Tell the user: "Let me first see what technologies your site is using..." \`\`\`bash nuclei -u {url} -t technologies/ -json 2>/dev/null \`\`\` **IMPORTANT: Validate output before parsing:** 1. Check if the command succeeded (exit code 0) 2. Check if output is valid JSON (try parsing it first) 3. If JSON is invalid or command failed: - Verify nuclei is working: \`nuclei --version\` - Check templates: \`nuclei -tl 2>&1 | grep technologies\` - Skip technology detection and continue to security checks 4. If JSON is valid, proceed to explain Explain what you found: "Your site appears to be running [technology] version [X]" ## Step 4: Safe Security Checks Tell the user: "Now checking for common security issues..." **Run these safe templates:** \`\`\`bash # Exposed sensitive files nuclei -u {url} -t exposures/ -json 2>/dev/null # Security misconfigurations nuclei -u {url} -t misconfiguration/ -json 2>/dev/null # HTTP security headers nuclei -u {url} -t http/misconfiguration/ -json 2>/dev/null \`\`\` **IMPORTANT: Validate each nuclei output before parsing:** 1. Check if the command succeeded (exit code 0) 2. Check if output is valid JSON (try parsing it first) 3. If JSON is invalid or command failed: - Check if URL is still accessible: \`curl -s {url}\` - Verify nuclei is still working: \`nuclei --version\` - Check if templates exist: \`nuclei -tl 2>&1 | head -5\` - If nuclei broken, tell user: "Nuclei scan failed. Please run \`validate-tools\` workflow to check tool status." - Skip this template and continue to next template 4. If JSON is valid, proceed to parse and explain 5. Note: Empty JSON array \`[]\` means no findings (this is normal, not an error) ## Step 5: Explain Each Finding For each issue found, explain: - **What:** "Found [issue type]" - **Where:** "At [URL path]" - **Risk:** "This means [plain English explanation]" - **Fix:** "To fix this, [specific steps]" ## Step 6: Summary Report "## Security Test Results for {url} **Target:** {url} **Tested at:** [timestamp] **Technologies:** [detected stack] ### Findings | Severity | Issue | Location | |----------|-------|----------| | [HIGH] | [Issue] | [Path] | | [MEDIUM] | [Issue] | [Path] | ### Recommendations 1. **High Priority:** [Action item] 2. **Medium Priority:** [Action item] 3. **Low Priority:** [Action item] ### What These Mean [Plain English explanations of each finding type]" ## Command Execution Notes When running nuclei commands that output JSON: 1. **Get raw JSON output** without piping to jq or other parsers 2. **Parse the JSON yourself** using your built-in JSON parsing capabilities 3. **Don't use bash jq pipelines** - this causes shell escaping issues and syntax errors 4. **Example pattern:** \`nuclei -u {url} -t templates/ -json\` → parse JSON in your code → extract findings 5. **Why:** Bash escaping with jq is error-prone. Your native JSON parsing is more reliable and avoids syntax errors. ## Important Notes - NEVER test without explicit authorization - Only run safe, non-destructive templates - Don't run CVE or exploit templates unless specifically asked - Be clear about what each finding means - Provide actionable fix instructions`, }, // ------------------------------------------------------------------------- // PRE-PUSH - Quick check before commit/PR // ------------------------------------------------------------------------- 'pre-push': { name: 'pre-push', description: 'Quick critical-only security check before pushing code (fast scan)', content: `# Pre-Push Security Check You are running a quick security check before the user pushes their code. This is a fast, focused check for CRITICAL issues only. ## Purpose This is a lightweight gate check before code goes to a PR or production. Focus on: 1. Critical dependency vulnerabilities (actively exploited CVEs) 2. Critical code issues (high-confidence security bugs) This check is fast (< 30 seconds) and skips: - Runtime analysis (too slow for pre-commit) - Medium/low severity issues (review later) - Full security audit (use the \`scan\` workflow instead) ## Step 1: Quick Tool Check (MANDATORY) Check which tools are available (fast check): \`\`\`bash which trivy >/dev/null 2>&1 && echo "trivy: OK" || echo "trivy: MISSING" which semgrep >/dev/null 2>&1 && echo "semgrep: OK" || echo "semgrep: MISSING" \`\`\` **If ANY tools missing:** Tell user: "⚠️ Required tools are missing. I'll install them quickly..." **macOS:** \`\`\`bash brew install aquasecurity/trivy/trivy semgrep \`\`\` **Linux:** \`\`\`bash # Trivy curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin # Semgrep pip3 install semgrep \`\`\` **Validate:** \`\`\`bash trivy --version && semgrep --version && echo "✅ Tools ready" || echo "❌ Installation failed" \`\`\` **If installation fails:** - STOP the pre-push check - Tell user: "Tool installation failed. Please run \`validate-tools\` workflow for help." **If all tools present:** → Continue to Step 2 (Critical Checks) ## Step 2: Critical Vulnerabilities Only Tell the user: "Checking for critical security issues..." \`\`\`bash trivy fs . --format json --severity CRITICAL 2>/dev/null \`\`\` **IMPORTANT: Validate trivy output:** 1. Check if command succeeded (exit code 0) 2. Check if output is valid JSON 3. If invalid: Verify \`trivy --version\` works, skip trivy results if broken 4. If valid: Proceed to parse \`\`\`bash semgrep scan --config auto --json --severity ERROR 2>/dev/null \`\`\` **IMPORTANT: Validate semgrep output:** 1. Check if command succeeded (exit code 0) 2. Check if output is valid JSON 3. If invalid: Verify \`semgrep --version\` works, skip semgrep results if broken 4. If valid: Proceed to parse **If critical issues found - WARN:** "Found [X] critical issue(s): 1. [Package] has [CVE] - [brief explanation] 2. [Code issue] in [file]:[line] - [brief explanation] These should ideally be fixed before merging. Continue anyway? (yes/no)" ## Step 3: Quick Decision **If NO critical issues:** "✅ All clear! No critical security issues found. Safe to push." **If CRITICAL issues found:** "⚠️ WARNING: Found [X] critical security issues. You can push, but please fix these before merging to main." ## Output Format Keep it short and actionable: \`\`\` PRE-PUSH CHECK RESULTS ====================== Critical CVEs: [PASS/WARN - X found] Critical Code: [PASS/WARN - X found] Status: [SAFE TO PUSH / PROCEED WITH CAUTION] [If issues, list them briefly with file locations] \`\`\` ## Important Note This is a QUICK check for critical issues only. For a comprehensive security audit including runtime analysis: → Use the \`scan\` workflow instead ## Command Execution Notes When running commands that output JSON (trivy, semgrep): 1. **Get raw JSON output** without piping to jq or other parsers 2. **Parse the JSON yourself** using your built-in JSON parsing capabilities 3. **Don't use bash jq pipelines** - this causes shell escaping issues and syntax errors 4. **Example pattern:** \`trivy fs . --format json --severity CRITICAL\` → parse JSON in your code → extract findings 5. **Why:** Bash escaping with jq is error-prone (e.g., \`!=\` becomes \`\\!=\` and fails). Your native JSON parsing is more reliable. ## Important Notes - Speed matters - this should complete in under 30 seconds - Only check CRITICAL severity, not everything - Secrets are always a blocker - CVEs and code issues are warnings, not blockers - Be clear and decisive in the recommendation - Don't overwhelm with details - just essentials`, }, }; // ============================================================================ // PROMPT REGISTRATION // ============================================================================ export function registerWorkflowPrompts(server: McpServer): void { for (const [id, workflow] of Object.entries(WORKFLOWS)) { if ('argsSchema' in workflow && workflow.argsSchema) { // Prompt with arguments server.prompt( id, workflow.description, workflow.argsSchema as any, async (params: any) => { let content = workflow.content; // Replace any {param} placeholders with actual values if (params) { for (const [key, value] of Object.entries(params)) { content = content.replace(new RegExp(`\\{${key}\\}`, 'g'), String(value)); } } return { messages: [ { role: 'user' as const, content: { type: 'text' as const, text: content, }, }, ], }; } ); } else { // Prompt without arguments server.prompt(id, workflow.description, async () => { return { messages: [ { role: 'user' as const, content: { type: 'text' as const, text: workflow.content, }, }, ], }; }); } } }