mcppt 1.0.2__tar.gz → 3.0.0__tar.gz

{mcppt-1.0.2 → mcppt-3.0.0}/.github/workflows/ci.yml

@@ -64,17 +64,14 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/v')
-    environment:
-      name: pypi
-      url: https://pypi.org/project/mcppt/
-    permissions:
-      id-token: write   # trusted publishing (no API key needed)
     steps:
       - uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist/
       - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
 
   # ── Create GitHub Release on version tag ───────────────────────────────────
   release:

{mcppt-1.0.2 → mcppt-3.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mcppt
-Version: 1.0.2
-Summary: MCPTROTTER — MCP Pentest Tool: 28 automated security checks for MCP servers
+Version: 3.0.0
+Summary: MCPTROTTER — MCP Security Framework: 31 automated checks + manual exploration shell
 Project-URL: Homepage, https://github.com/gurudeepmallam-cmd/mcppt
 Project-URL: Repository, https://github.com/gurudeepmallam-cmd/mcppt
 Project-URL: Issues, https://github.com/gurudeepmallam-cmd/mcppt/issues
@@ -21,6 +21,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Security
 Requires-Python: >=3.10
 Requires-Dist: flask>=3.0
+Requires-Dist: requests>=2.28.0
 Requires-Dist: rich>=13.0
 Provides-Extra: ai
 Requires-Dist: anthropic>=0.25; extra == 'ai'
@@ -29,7 +30,7 @@ Provides-Extra: ui
 Requires-Dist: streamlit>=1.30; extra == 'ui'
 Description-Content-Type: text/markdown
 
-# MCPTROTTER — MCP Pentest Tool
+# MCPTROTTER — MCP Security Framework
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/gurudeepmallam-cmd/mcppt/main/docs/mcptrotter.jpeg" alt="MCPTROTTER" width="380"/>
@@ -38,7 +39,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <img src="https://img.shields.io/pypi/v/mcppt?label=PyPI&color=orange"/>
   <img src="https://img.shields.io/badge/python-3.10%2B-blue"/>
-  <img src="https://img.shields.io/badge/checks-28-red"/>
+  <img src="https://img.shields.io/badge/checks-31-red"/>
   <img src="https://img.shields.io/badge/license-MIT-green"/>
   <img src="https://img.shields.io/badge/part%20of-Bugtrotter-black"/>
 </p>
@@ -50,19 +51,15 @@ Description-Content-Type: text/markdown
 
 ---
 
-## What it does
+## What it is
 
-MCPTROTTER is a command-line security scanner for **MCP (Model Context Protocol)** servers. Point it at any MCP endpoint and it runs 28 automated checks across:
+MCPTROTTER is a **security framework** for testing MCP (Model Context Protocol) servers. It works two ways:
 
-- Authentication bypass and token abuse
-- Prompt injection (direct, stored, poison-all fields)
-- SSRF, command injection, path traversal
-- Session entropy and replay attacks
-- Tenant isolation and IDOR
-- Tool poisoning and rug pulls
-- Transport misconfigurations and secret leaks
+**Manual exploration** — connect to any MCP server and interact with it the way an attacker would. Call tools directly, inspect schemas, fuzz parameters, read resources, send raw JSON-RPC methods. No scan needed. You control every request.
 
-Works against any MCP server using Streamable HTTP transport (POST + SSE response). Integrates with Burp Suite for manual follow-up. Exports pentest-ready Markdown reports.
+**Automated scanning** — run 31 security checks in under 60 seconds. Auth bypass, stored injection, replay attacks, session entropy, tenant isolation, tool poisoning, command injection, and more.
+
+Both modes route through Burp Suite so you see every request in HTTP History and can follow up in Repeater.
 
 ---
 
@@ -106,29 +103,26 @@ python test_server.py
 mcppt
 ```
 
-You'll see:
 ```
   __  __   ___  ___  _____ ____   ___ _____ _____ ___ ___
  |  \/  | / __|| _ \|_   _|  _ \ / _ \_   _|_   _| __| _ \
  | |\/| || (__|  _/ | | |   /  | (_) || |   | | | _||   /
  |_|  |_| \___||_|  |_| |_|_\  \___/ |_|   |_| |___|_|_\
 
-  MCP Pentest Tool  v2.1  --  16 automated security checks
+  MCP Pentest Framework  v3.0  --  31 checks  +  manual exploration
 
   by Gurudeep Mallam
-  github  : https://github.com/gurudeepmallam-cmd
-  linkedin: https://in.linkedin.com/in/mallam-gurudeep-7734941aa
-
-  type 'help' for commands, 'exit' to quit
 
-mcppt>
+  Quick start:  target <url>  →  connect  →  list  →  scan
+  Manual test:  call <tool> <args>  |  raw <method>  |  fuzz <tool> <param> <type>
 ```
 
 **Paste these commands one by one:**
 ```
 target http://127.0.0.1:8888/mcp
 token  valid-token-abc123
-status
+connect
+list
 scan
 findings
 report demo.md
@@ -138,10 +132,10 @@ report demo.md
 
 ## Expected output — demo server scan
 
-Running `scan` with token set produces this (6.7 seconds):
+Running `scan` with token set produces this (under 60 seconds):
 
 ```
-Duration: 6.7s   Findings: 6 CRITICAL  6 HIGH  13 MEDIUM  3 LOW
+Duration: ~45s   Findings: 6 CRITICAL  6 HIGH  13 MEDIUM  3 LOW
 ```
 
 | Severity | Check | Finding |
@@ -168,43 +162,80 @@ Duration: 6.7s   Findings: 6 CRITICAL  6 HIGH  13 MEDIUM  3 LOW
 
 ---
 
-## All commands (interactive shell)
+## All commands
 
+### Setup
+```
+target  <url>          Set MCP server URL
+token   <bearer>       Set primary auth token
+token2  <bearer>       Set second user token (IDOR / scope / tenant checks)
+noverify               Toggle SSL verification skip (needed for self-signed certs)
+proxy   <url|off>      Set Burp proxy:  proxy http://127.0.0.1:8080
+verbose                Toggle raw HTTP request/response logging
+status                 Show current session configuration
 ```
-Setup
-  target  <url>          Set MCP server URL
-  token   <bearer>       Set primary auth token
-  token2  <bearer>       Set second user token (IDOR / scope / tenant checks)
-  noverify               Toggle SSL verification skip (needed for self-signed certs)
-  proxy   <url|off>      Set Burp proxy:  proxy http://127.0.0.1:8080
-  status                 Show current config before scanning
 
-Enumerate
-  list                   List all tools the server exposes (names, params, descriptions)
-  call <tool> [json]     Manually call any tool
-                           call get_notes
-                           call get_user {"id": 1}
-                           call save_note {"text": "hello"}
+### Manual exploration
+```
+connect                Test connection + show server name, version, capabilities
+list                   List all tools the server exposes (names, schemas, params)
+inspect <tool>         Show full JSON schema for a specific tool
+call <tool> [json]     Call any tool directly with your own arguments
+                         call get_notes
+                         call get_user {"id": 1}
+                         call save_note {"text": "test injection payload"}
+raw <method> [params]  Send any raw JSON-RPC method
+                         raw tools/list
+                         raw resources/list
+                         raw sampling/createMessage {...}
+resources [read <uri>] List resources or read a specific URI
+prompts [get <name>]   List prompts or get a specific prompt
+headers                Show HTTP response headers from the last request
+```
 
-Scan
-  scan                   Run all checks
-  scan auth ssrf idor    Run specific checks only
-  scan stored injection  Mix and match any check names
+### Targeted testing
+```
+fuzz <tool> <param> <type|file>   Fuzz a specific tool parameter
+
+  Built-in wordlists:
+    sqli        SQL injection payloads
+    xss         XSS and template injection
+    traversal   Path traversal (../etc/passwd, encoded variants)
+    cmd         OS command injection (; id, $(id), | whoami)
+    ssrf        SSRF targets (169.254.169.254, localhost)
+    ssti        Server-side template injection
+    inject      Prompt injection payloads for LLM tools
+
+  Custom:  fuzz read_file path /path/to/payloads.txt
+
+  Examples:
+    fuzz get_user id sqli
+    fuzz save_note text inject
+    fuzz read_file path traversal
+```
 
-Results
-  findings               Colour-coded findings table
-  clear                  Clear findings from last scan
-  report out.md          Export Markdown report
-  report out.json        Export JSON report
+### Automated scan
+```
+scan                   Run all 31 checks
+scan auth ssrf idor    Run specific checks only
+scan stored injection  Mix and match any check names
+```
 
-AI analysis (optional — paste your key first)
-  ai claude  sk-ant-...  Configure Claude for analysis
-  ai openai  sk-...      Configure OpenAI GPT-4o
-  analyze                Attack narrative + remediation priority from findings
+### Findings
+```
+note <sev> <check> <title> [| detail]   Manually log a finding
+                         note HIGH manual_test Input reflected | seen in 500 response
+findings               Colour-coded findings table (scan + manual notes)
+clear                  Clear findings and tool cache
+report out.md          Export Markdown report
+report out.json        Export JSON report
+```
 
-Shell
-  help                   Full command reference
-  exit                   Quit
+### AI analysis (optional)
+```
+ai claude  sk-ant-...  Configure Claude for analysis
+ai openai  sk-...      Configure OpenAI GPT-4o
+analyze                Attack narrative + remediation priority from findings
 ```
 
 ---
@@ -237,7 +268,7 @@ Burp Suite → **Proxy → Proxy Settings**
 
 Confirm the listener is `127.0.0.1:8080` (it is by default). No changes needed.
 
-### Step 2 — Run scan through proxy
+### Step 2 — Run through proxy
 
 Inside the shell:
 ```
@@ -257,9 +288,11 @@ mcppt scan --url https://target.com/mcp --token eyJ... --proxy http://127.0.0.1:
 
 Burp → **Proxy → HTTP History**
 
-Every MCP tool call appears as a `POST /mcp` request. Each row shows the JSON-RPC method and the response. You'll see one row per check — `initialize`, `tools/list`, `tools/call` for each tool tested.
+Every MCP tool call appears as a `POST /mcp` request. You'll see `initialize`, `tools/list`, `tools/call` for each check. Manual commands (`call`, `raw`, `fuzz`) also appear here — every request MCPTROTTER makes goes through Burp.
+
+### Step 4 — Send to Repeater for manual testing
 
-Click any row to see the full request and response body:
+Right-click any request → **Send to Repeater** (`Ctrl+R`).
 
 ```
 POST /mcp HTTP/1.1
@@ -270,42 +303,17 @@ Content-Type: application/json
 {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_notes","arguments":{}}}
 ```
 
-### Step 4 — Send to Repeater for manual testing
-
-In HTTP History, right-click any request → **Send to Repeater** (or `Ctrl+R`).
-
-Switch to the **Repeater** tab. You'll see the exact request MCPTROTTER sent.
-
-**To keep the connection alive and replay successfully:**
-
-1. Check the **Host** field matches your target (e.g. `127.0.0.1` port `8888` for demo server, or your real target host/port)
-2. If targeting HTTP (not HTTPS), make sure the **lock icon** in Repeater shows unlocked — click it to toggle if needed
-3. The MCP session ID in `mcp-session-id` header may expire — if you get a session error, re-initialize:
-   - Copy the `initialize` request from HTTP History into Repeater first
-   - Send it, copy the `mcp-session-id` from the response header
-   - Paste it into the header of your target request
-4. Click **Send** — response appears on the right
-
-**Modifying requests in Repeater:**
-
-```json
-{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
-  "name":"get_user",
-  "arguments":{"id": 2}
-}}
-```
+Change `"id": 2` to `"id": 1` to test IDOR. Swap the token to another user's. Modify `"name"` to call a different tool.
 
-Change `"id": 2` to `"id": 1` to test IDOR. Change the token in Authorization to another user's token. Modify `"name"` to call a different tool. Repeater sends exactly what you write.
+If you get a session error, copy the `initialize` request from HTTP History into Repeater first, send it, and copy the `mcp-session-id` header value into your target request.
 
 ### Step 5 — Fuzz with Intruder
 
-Right-click a request in Repeater → **Send to Intruder**.
-
-Highlight the value you want to fuzz (e.g. a tool parameter), click **Add §**. Load a wordlist (Burp's built-in fuzzing strings, or a custom injection list). Run the attack and sort by response length or status code to spot anomalies.
+Right-click any Repeater request → **Send to Intruder**. Highlight the parameter value, click **Add §**, load a wordlist, run the attack.
 
 ---
 
-## All 28 checks
+## All 31 checks
 
 | # | Check | Severity | What it tests |
 |---|---|---|---|
@@ -337,6 +345,9 @@ Highlight the value you want to fuzz (e.g. a tool parameter), click **Add §**.
 | 26 | `tool_shadowing` | CRITICAL | Duplicate tool names, homoglyphs, name/desc mismatch |
 | 27 | `sampling` | CRITICAL | `sampling/createMessage` accessible without auth |
 | 28 | `schema_leak` | LOW | Sensitive field names / enum values in tool schemas |
+| 29 | `http_method_confusion` | MEDIUM | GET/DELETE/PUT/PATCH accepted on MCP endpoint |
+| 30 | `protocol_downgrade` | MEDIUM | Old protocol versions accepted, server version leaked |
+| 31 | `batch_injection` | MEDIUM | JSON-RPC batch requests, unusual method name injection |
 
 ---
 
@@ -349,9 +360,13 @@ Highlight the value you want to fuzz (e.g. a tool parameter), click **Add §**.
 | Check all response fields for injection | 30+ min | `scan poison_all` — 5s |
 | Verify session ID entropy | 10 min | `scan session` — 2s |
 | Check replay on every tool | 20 min | `scan replay` — 5s |
-| Full 28-check assessment | 3–6 hours | `scan` — 30s |
+| Full 31-check assessment | 3–6 hours | `scan` — under 60s |
+| Inspect tool schema before testing | 5 min reading docs | `inspect <tool>` — instant |
+| Call a tool with custom payload | Set up in Burp Repeater | `call <tool> {"param": "payload"}` |
+| Fuzz a parameter with 50 payloads | Intruder setup + run | `fuzz <tool> <param> sqli` — 30s |
+| Test any JSON-RPC method directly | Build request in Repeater | `raw <method> <params>` |
 
-MCPTROTTER gives you the baseline in 30 seconds. You spend your time on what matters: manually verifying findings in Burp Repeater and chaining them into a demonstrated attack path.
+MCPTROTTER gives you the baseline in under 60 seconds and puts every request in Burp HTTP History. You spend your time on what matters: manually verifying findings in Repeater and chaining them into a demonstrated attack path.
 
 ---
 
@@ -363,8 +378,8 @@ MCPTROTTER is the public automated scanner extracted from **Bugtrotter** — a f
 
 | Capability | MCPTROTTER | Bugtrotter |
 |---|---|---|
-| Automated MCP scan (28 checks) | ✓ | ✓ |
-| Manual finding verification | You do it in Burp | Guided playbooks |
+| Automated MCP scan (31 checks) | ✓ | ✓ |
+| Manual tool exploration framework | ✓ | ✓ |
 | Chained exploit paths across tools | — | ✓ Full attack chain |
 | SAST review of MCP server code | — | ✓ |
 | Burp Suite MCP — business logic abuse | — | ✓ AI-driven |
@@ -373,27 +388,25 @@ MCPTROTTER is the public automated scanner extracted from **Bugtrotter** — a f
 | Web / API / network pentesting | — | ✓ Full engagement |
 | Final pentest report | Markdown export | Engagement-grade report |
 
-**MCPTROTTER in fingertips inside Bugtrotter:**
+**MCPTROTTER inside Bugtrotter:**
 
 In Bugtrotter, MCPTROTTER runs as a registered MCP server. Claude Code or Claude Desktop calls it directly:
 
 ```
 "Scan https://target.com/mcp for security issues and prioritise findings"
 → Claude calls scan_target tool
-→ MCPTROTTER runs all 28 checks
+→ MCPTROTTER runs all 31 checks
 → Findings returned as structured JSON to Claude
 → Claude reasons over them, chains the critical ones, drafts the report section
 ```
 
 No copy-paste. No context switching. The scan output feeds straight into the AI-driven engagement workflow — SSRF finding becomes an SSRF exploit attempt, auth bypass becomes a credential theft chain, stored injection becomes a demonstrated prompt hijack.
 
-That's the difference: MCPTROTTER finds the candidates in 30 seconds. Bugtrotter turns the candidates into proven, chained, client-ready findings.
-
 ---
 
 ## Use MCPTROTTER as an MCP server itself
 
-MCPTROTTER can become an MCP server — exposing its scan capability as tools that any MCP client (Claude Desktop, MCP Inspector, another agent) can call.
+MCPTROTTER can expose its scan capability as tools that any MCP client (Claude Desktop, MCP Inspector, another agent) can call.
 
 ```bash
 mcppt serve-mcp --port 8899
@@ -415,12 +428,7 @@ Tools exposed:
 - `scan_target` — full scan, returns findings JSON
 - `list_tools` — enumerate tools on any MCP server
 - `call_tool` — call any tool on any MCP server
-- `get_checks` — list all 28 checks with descriptions
-
-Inspect with MCP Inspector:
-```bash
-npx @modelcontextprotocol/inspector http://127.0.0.1:8899/mcp
-```
+- `get_checks` — list all 31 checks with descriptions
 
 ---