@cyanheads/pentest-mcp-server

v0.1.4 pre-1.0

Offline methodology engine and payload workshop for authorized penetration testing, CTF, security research, and education via MCP. STDIO or Streamable HTTP.

@cyanheads/pentest-mcp-server
claude mcp add --transport http pentest-mcp-server https://pentest.caseyjhand.com/mcp
codex mcp add pentest-mcp-server --url https://pentest.caseyjhand.com/mcp
{
  "mcpServers": {
    "pentest-mcp-server": {
      "url": "https://pentest.caseyjhand.com/mcp"
    }
  }
}
gemini mcp add --transport http pentest-mcp-server https://pentest.caseyjhand.com/mcp
{
  "mcpServers": {
    "pentest-mcp-server": {
      "command": "bunx",
      "args": [
        "@cyanheads/pentest-mcp-server@latest"
      ]
    }
  }
}
{
  "mcpServers": {
    "pentest-mcp-server": {
      "type": "http",
      "url": "https://pentest.caseyjhand.com/mcp"
    }
  }
}
curl -X POST https://pentest.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Tools

7

pentest_guide

Return a structured attack methodology playbook for the given attack vector and optional target context, for use in authorized penetration testing, CTF, or security research. Covers reconnaissance, enumeration, exploitation, and post-exploitation phases for the vector, filtered to what is relevant given the provided stack and WAF profile. Each phase includes: what to look for, tools to use, common mistakes, detection indicators that would alert defenders, and recommended mitigations. Next-tool suggestions are pre-filled with payload generator and technique lookup calls. Covers 15 vectors via the vector enum. Authorized testing only.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pentest_guide",
    "arguments": {
      "vector": "<vector>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "vector": {
      "type": "string",
      "enum": [
        "auth_bypass",
        "idor",
        "ssrf",
        "xss",
        "sqli",
        "xxe",
        "path_traversal",
        "cors",
        "csrf",
        "open_redirect",
        "deserialization",
        "race_condition",
        "ssti",
        "command_injection",
        "jwt_attack"
      ],
      "description": "Attack vector to retrieve methodology for. Each vector has its own methodology branch covering recon through exploitation. Authorized testing only."
    },
    "target_context": {
      "description": "Optional target profile for authorized engagement. Providing this narrows the playbook to what is most relevant for the specific environment.",
      "type": "object",
      "properties": {
        "stack": {
          "description": "Technology stack (e.g., \"Node.js + Express + PostgreSQL\", \"PHP 7.4 + Apache\", \"Spring Boot\"). Narrows methodology to stack-specific techniques.",
          "type": "string"
        },
        "waf": {
          "description": "WAF or filter in use (e.g., \"Cloudflare\", \"AWS WAF\", \"ModSecurity CRS\", \"custom regex\"). Triggers bypass-aware variants in payload suggestions.",
          "type": "string"
        },
        "recon_notes": {
          "description": "Freeform recon findings to incorporate. E.g., \"endpoint /api/users/{id} reflects user input in JSON response\". Narrows which phases are most relevant.",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "phase": {
      "default": "all",
      "description": "Restrict output to a specific phase. Use \"all\" for a complete playbook. Use a specific phase when working through a step-by-step flow.",
      "type": "string",
      "enum": [
        "all",
        "recon",
        "enumeration",
        "exploitation",
        "post_exploitation"
      ]
    }
  },
  "required": [
    "vector",
    "phase"
  ],
  "additionalProperties": false
}
view source ↗

pentest_analyze_response

Analyze a server response from authorized probing for information leakage, fingerprinting signals, and exploitation opportunities scoped to the authorized engagement. Accepts raw HTTP response headers and body (paste from Burp, curl, or any HTTP client) and returns structured findings grouped by category. Each finding includes: what was detected, why it matters for an authorized tester, how a defender detects misuse, and recommended remediation. Identifies version disclosures, stack traces, debug headers, internal paths, JWT/cookie patterns, CORS misconfigurations, and other common leakage patterns. Use as the bridge between recon/probing output and the methodology and payload tools.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pentest_analyze_response",
    "arguments": {}
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "response_headers": {
      "description": "Raw HTTP response headers (paste from Burp, curl -v, or similar). Include the status line if available. Max 20,000 characters.",
      "type": "string",
      "maxLength": 20000
    },
    "response_body": {
      "description": "Response body text. Paste raw HTML, JSON, XML, or error text. Truncate to the first 10,000 characters for very large responses — the first portion carries most leakage signals.",
      "type": "string",
      "maxLength": 10000
    },
    "status_code": {
      "description": "HTTP status code (100–599). Helps classify the response type.",
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "context": {
      "description": "Freeform context about the authorized test target — e.g., \"login endpoint\", \"GraphQL API\", \"file upload handler\". Narrows the pattern matching to relevant categories. Max 2,000 characters.",
      "type": "string",
      "maxLength": 2000
    }
  },
  "additionalProperties": false
}
view source ↗

pentest_lookup_technique

Look up a MITRE ATT&CK technique by ID or keyword for authorized penetration testing and security research. Returns the full technique record: name, associated tactics, description, detection opportunities (log sources, behavioral indicators), real-world procedure examples from public reporting, recommended mitigations, and related sub-techniques. The detection and mitigation sections make this equally useful for defenders building detection coverage. Accepts exact IDs (T1190, T1059.001) or keyword search (e.g., "sql injection", "pass the hash", "web shell upload").

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pentest_lookup_technique",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "ATT&CK technique ID (e.g., \"T1190\", \"T1059.001\") or keyword describing the technique (e.g., \"sql injection\", \"pass the hash\", \"web shell upload\"). ID lookup is exact; keyword lookup returns the best match plus related techniques."
    },
    "include_subtechniques": {
      "default": true,
      "description": "Include sub-techniques in the result. Set to false when only the parent technique summary is needed.",
      "type": "boolean"
    }
  },
  "required": [
    "query",
    "include_subtechniques"
  ],
  "additionalProperties": false
}
view source ↗

pentest_lookup_group

Look up a MITRE ATT&CK threat group (intrusion set) or software entry by name or ID for authorized penetration testing and threat intelligence. Returns the group or software record: ATT&CK ID, display name, known aliases, type (group vs. software), description, and the techniques it uses with procedure-level context from public ATT&CK reporting. Accepts exact ATT&CK IDs (G0007 for threat groups, S0002 for software) or keyword/name search (e.g., "APT28", "Mimikatz", "Lazarus Group"). Equally useful for defenders building detection coverage around specific adversary tradecraft.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pentest_lookup_group",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "ATT&CK threat group ID (e.g., \"G0007\"), software ID (e.g., \"S0002\"), or name/keyword (e.g., \"APT28\", \"Mimikatz\", \"Lazarus Group\"). ID lookup is exact and case-insensitive; name/keyword search returns the best match."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
view source ↗

pentest_map_techniques

Given a profile of the authorized test target (technology stack, exposed services, authentication type, OS), return a ranked list of ATT&CK techniques and OWASP test cases most relevant to that profile — not a generic dump of all techniques. Ranking factors: platform match, service match, auth type exposure, technique prevalence. Each result includes why it is relevant to this specific profile, the detection opportunity, and the recommended mitigation. Use when starting an authorized engagement to prioritize the testing scope; pair with pentest_guide to get the full methodology for each top-ranked vector.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pentest_map_techniques",
    "arguments": {}
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "stack": {
      "description": "Technology stack components (e.g., [\"Node.js\", \"Express\", \"PostgreSQL\", \"Redis\"]). Each element matched against technique platform and procedure examples.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A technology stack component."
      }
    },
    "services": {
      "description": "Exposed services and interfaces (e.g., [\"REST API\", \"GraphQL\", \"file upload\", \"admin panel\"]). Narrows technique relevance.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "An exposed service or interface."
      }
    },
    "auth_type": {
      "description": "Authentication mechanism in use. Surfaces auth-specific attack techniques.",
      "type": "string",
      "enum": [
        "jwt",
        "session_cookie",
        "api_key",
        "oauth2",
        "basic_auth",
        "ntlm",
        "kerberos",
        "none",
        "unknown"
      ]
    },
    "os": {
      "description": "Target operating system. Narrows to OS-specific techniques.",
      "type": "string",
      "enum": [
        "linux",
        "windows",
        "macos",
        "unknown"
      ]
    },
    "limit": {
      "default": 15,
      "description": "Maximum number of techniques to return (1–50, default 15). Higher values give broader coverage; lower values focus on highest-relevance items.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "limit"
  ],
  "additionalProperties": false
}
view source ↗

pentest_generate_payloads

Generate payload templates for authorized testing against systems the tester owns or is permitted to test. Payloads are annotated templates — each includes why it works in the specified context, what vulnerability class it tests, detection signatures that WAF/IDS products might fire, and recommended mitigations. Context-awareness is core: an XSS payload for an HTML attribute differs entirely from one for a JS template literal, and both differ from a DOM-based sink. When a WAF profile is specified, bypass variants reference known public research for that WAF product. All payloads are illustrative templates for authorized testing only.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pentest_generate_payloads",
    "arguments": {
      "category": "<category>",
      "injection_context": "<injection_context>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "xss",
        "sqli",
        "ssrf",
        "xxe",
        "path_traversal",
        "ssti",
        "command_injection",
        "open_redirect",
        "csrf",
        "deserialization",
        "jwt",
        "ldap_injection",
        "nosql_injection",
        "http_header"
      ],
      "description": "Vulnerability category for payload generation."
    },
    "injection_context": {
      "type": "string",
      "enum": [
        "html_attribute",
        "html_body",
        "js_string",
        "js_template",
        "js_script_block",
        "url_parameter",
        "url_path",
        "sql_where",
        "sql_integer",
        "xml_element",
        "xml_attribute",
        "http_header",
        "json_value",
        "cookie_value",
        "file_name",
        "generic"
      ],
      "description": "Precise injection context. Critical for XSS: an HTML attribute payload differs from a JS string payload. Provide the most specific context for the best results."
    },
    "waf_profile": {
      "default": "none",
      "description": "WAF or filter in front of the authorized test target. When a specific WAF is named, bypass variants referencing known public research are included.",
      "type": "string",
      "enum": [
        "cloudflare",
        "aws_waf",
        "modsecurity_crs",
        "imperva",
        "akamai",
        "f5_bigip_asm",
        "nginx_modsecurity",
        "fortinet_fortiwaf",
        "none",
        "unknown"
      ]
    },
    "encoding": {
      "description": "Apply an encoding chain to payloads at generation time. Applied in order (left to right). Use pentest_encode for more control over per-payload encoding.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "none",
          "url",
          "double_url",
          "html_entity",
          "unicode",
          "hex",
          "base64",
          "js_escape"
        ],
        "description": "An encoding step to apply."
      }
    },
    "count": {
      "default": 5,
      "description": "Number of payload variants to return (1–20, default 5). More variants cover different bypass approaches for the same context.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "category",
    "injection_context",
    "waf_profile",
    "count"
  ],
  "additionalProperties": false
}
view source ↗

pentest_encode

Transform a payload string through one or more encoding layers for bypass research during authorized testing. Accepts a chain of encodings applied in order (e.g., ["unicode", "url", "base64"] applies Unicode → URL-encode → base64). Returns the transformed payload with a step-by-step decoding explanation: how a WAF or server would decode each layer, and why the combined encoding might bypass a specific filter. Use to understand filter bypass mechanics in an authorized engagement and to confirm that a target's decoding pipeline matches an expected bypass path. Payloads are transformed mathematically — no live probing occurs.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pentest_encode",
    "arguments": {
      "payload": "<payload>",
      "chain": "<chain>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "payload": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000,
      "description": "Input payload string to encode. Max 10,000 characters."
    },
    "chain": {
      "minItems": 1,
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "url",
          "double_url",
          "html_entity",
          "unicode",
          "hex",
          "base64",
          "js_escape",
          "null_byte",
          "mixed_case",
          "comment_break"
        ],
        "description": "An encoding step."
      },
      "description": "Ordered list of encodings to apply (1–6 steps). Applied left to right. E.g., [\"unicode\", \"url\"] applies Unicode escape first, then URL-encodes the result."
    },
    "explain": {
      "default": true,
      "description": "Include step-by-step decode explanation. Set to false for raw transform output only.",
      "type": "boolean"
    }
  },
  "required": [
    "payload",
    "chain",
    "explain"
  ],
  "additionalProperties": false
}
view source ↗