mcppt 1.0.1__tar.gz → 1.1.0__tar.gz

{mcppt-1.0.1 → mcppt-1.1.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mcppt
-Version: 1.0.1
-Summary: MCPTROTTER — MCP Pentest Tool: 28 automated security checks for MCP servers
+Version: 1.1.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'

mcppt-1.1.0/docs/STUDY_GUIDE.md

@@ -0,0 +1,299 @@
+# Study Guide — CI/CD Security, MCPTROTTER, Cloud Security, RAG
+
+---
+
+## 1. CI/CD — Concepts, Risks, and Findings
+
+### What is CI/CD?
+
+CI/CD stands for Continuous Integration / Continuous Delivery (or Deployment).
+
+- **CI (Continuous Integration):** Every code push triggers automated checks — lint, tests, build. Catches bugs early before they reach production.
+- **CD (Continuous Delivery):** After CI passes, the artifact (wheel, Docker image, binary) is automatically deployed or published — to PyPI, a cloud environment, or a registry.
+
+### How MCPTROTTER's Pipeline Works
+
+File: `.github/workflows/ci.yml`
+
+```
+git push to main
+    → lint (ruff check)
+    → test (pytest on Python 3.10, 3.11, 3.12)
+    → build (python -m build → produces .whl + .tar.gz)
+
+git tag v1.0.3 + git push origin v1.0.3
+    → all above +
+    → publish to PyPI (trusted publishing — no API key in CI)
+    → GitHub Release created with dist files + auto release notes
+```
+
+**Trusted Publishing** — instead of storing a PyPI API token as a GitHub secret (which can be leaked), the pipeline uses OIDC (OpenID Connect). GitHub proves to PyPI "this is a legitimate workflow from this repo" using a short-lived token. No hardcoded credentials anywhere.
+
+### CI/CD Security Risks
+
+| Risk | What it means | Real example |
+|------|--------------|--------------|
+| Secrets in code | API keys, tokens hardcoded in repo | PyPI token exposed in chat — can be used by anyone to publish malicious packages |
+| Supply chain attack | Attacker compromises a dependency used in CI | `actions/checkout@v4` — if this is compromised, every repo using it is affected |
+| Dependency confusion | Attacker publishes a malicious package with same name as internal one | `pip install mcppt` — if the name wasn't claimed, attacker could have published first |
+| Workflow injection | Untrusted input in `${{ github.event.issue.title }}` injected into shell | Runs arbitrary code in CI |
+| Overprivileged tokens | `GITHUB_TOKEN` with `contents: write` + `id-token: write` — if leaked, attacker can publish and create releases |
+| Artifact tampering | Build artifact replaced between build and publish jobs | Man-in-the-middle on artifact upload |
+
+### What We Did (and what went wrong)
+
+- PyPI token was pasted in chat **twice** — this is a real supply chain risk. Anyone who reads the chat history can publish to PyPI as you.
+- **Fix:** Revoke token at https://pypi.org/manage/account/token/ and switch to trusted publishing via git tags — no token needed in CI.
+- Manual publish process: `bump version → python -m build → twine upload`
+- Automated: `git tag v1.0.3 && git push origin v1.0.3` triggers the full pipeline.
+
+---
+
+## 2. MCPTROTTER — Code and Repo Logic
+
+### What is MCP?
+
+Model Context Protocol (MCP) — a standard for AI agents to call external tools. Think of it as an API specifically designed for LLMs. Uses JSON-RPC 2.0 over HTTP with SSE (Server-Sent Events) for streaming responses.
+
+Every MCP call looks like:
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "tool_name", "arguments": {}}}
+```
+
+### Why MCPTROTTER Makes the Calls It Does
+
+MCPTROTTER doesn't use curl internally. It uses Python's `urllib` from stdlib. Here's the logic flow:
+
+#### `mcppt/core.py` — The Engine
+- `configure(no_verify, proxy)` — sets up SSL context and proxy handler globally
+- `mcp_init(url, token)` — sends `initialize` + `notifications/initialized` to establish MCP session, gets back `mcp-session-id`
+- `rpc(url, method, params, token, session_id)` — sends a single JSON-RPC call, returns parsed response
+
+Why initialize first? MCP Streamable HTTP requires a handshake — the server issues a `mcp-session-id` which must be sent on all subsequent calls. Without it, calls are rejected.
+
+#### `mcppt/checks.py` — The 28 Checks
+Each check is a function that:
+1. Calls `rpc()` with a specific method and params
+2. Inspects the response for vulnerability indicators
+3. Appends findings to `ScanState`
+
+Example — `check_enum`: calls `tools/list` with NO token → if it returns tools, finding fires (F-16 equivalent).
+
+Example — `check_replay`: calls a tool once, records the `id`, calls it again with the same `id` → if both succeed, replay is confirmed.
+
+Example — `check_stored`: calls a write tool with an injection payload → calls a read tool → checks if payload appears in response unescaped.
+
+#### `mcppt/tui.py` — The Live Dashboard
+Uses Python `rich` (Textual layout) to show findings panel + live log panel side by side while scan runs in a background thread. The `ScanState` dataclass is thread-safe (uses `threading.Lock`) so the TUI can read it while checks write to it.
+
+#### `mcppt/shell.py` — Interactive REPL
+Built on `cmd.Cmd` — same pattern as gobuster/ffuf interactive mode. Commands: `target`, `token`, `scan`, `findings`, `report`. The banner uses `rich.text.Text` objects (not markup strings) to avoid `\[/]` escaping issues with ANSI escape codes.
+
+#### `mcppt/cli.py` — Entry Point
+- `mcppt` (no args) → launches interactive shell
+- `mcppt scan --url ... --checks ...` → non-interactive scan
+- Key fix: `enum` is always prepended to checks list — other checks (replay, stored, auth) depend on the tool list that enum builds
+
+#### `mcppt/server.py` — MCP Server Mode
+MCPTROTTER can expose itself as an MCP server. Claude Desktop calls `scan_target` tool → MCPTROTTER runs all checks → returns findings JSON back to Claude. No copy-paste, no context switching.
+
+### Repo Structure
+```
+mcppt_tool/
+├── mcppt/
+│   ├── __init__.py     version string
+│   ├── cli.py          entry point + arg parsing
+│   ├── core.py         urllib HTTP engine, MCP init, RPC
+│   ├── checks.py       28 security checks + ScanState
+│   ├── tui.py          Rich TUI dashboard
+│   ├── shell.py        cmd.Cmd interactive REPL + banner
+│   ├── report.py       MD + JSON report export
+│   └── server.py       MCP server mode (Flask SSE)
+├── test_server.py      vulnerable demo MCP server
+├── pyproject.toml      hatchling build config
+├── docs/
+│   └── mcptrotter.jpeg cyberpunk logo
+└── .github/workflows/
+    └── ci.yml          lint → test → build → publish
+```
+
+---
+
+## 3. WBS MCP Findings — What Was Confirmed Today
+
+### Final 5 Findings
+
+#### F1 — MCP Agent Compromise via Chained Prompt Injection, SSRF, and Broken Access Control (CRITICAL)
+Three weaknesses chained:
+- `resources/list` accessible with no auth → free recon
+- Injection payload written into `EngagementInternalNotes` via `update_wbs_form` → stored in form verbatim
+- When any user asks Teams bot about the form → injected instruction executes in LLM context → financial data disclosed ($500K fixed fee, team PII)
+- `FeeTextOnInvoice` accepts any URL → Teams SkypeUriPreview auto-fetches it server-side → data exfiltration without user click
+
+#### F2 — Hardcoded Shared Service Account (MEDIUM)
+Every user (tpt1, tpt2, Harika, anyone) gets `USITSDASBPM256@deloitte.com` when asking the bot "what is my account". Bot has no awareness of actual caller. All actions logged under one identity — forensics blind.
+
+#### F3 — Replay Attack + No Rate Limiting (HIGH)
+- Same JSON-RPC `id` accepted indefinitely — 1000 identical requests, all 200
+- No nonce, no timestamp window, no duplicate detection
+- Read tool: `get_all_market_offering_categories` replayed — same data returned every time
+- Write tool: `test_wbs_automation_message` replayed — accepted every time
+
+#### F4 — CORS Wildcard (MEDIUM)
+`Access-Control-Allow-Origin: *` — any origin including `null` accepted. Enables cross-site MCP abuse from a malicious browser page.
+
+#### F5 — Missing Security Headers + HSTS (LOW)
+HSTS `max-age=16070400` (186 days, below 1 year). Missing `X-Content-Type-Options`. `Server: Google Frontend` leaks infrastructure.
+
+---
+
+## 4. Cloud Security — Azure Focus
+
+### Azure Architecture (WBS target)
+```
+Teams Chat
+  → Azure Bot Service + WAF
+    → Azure Container Apps (ACA) — agent runs here
+        → MCP Server on GCP
+            → WBS APIs + SWIFT
+```
+
+### Key Azure Security Concepts
+
+#### Azure AD / Entra ID
+- Every user, app, and service in Azure has an identity in Entra ID
+- **Service Principal** — non-human identity for apps/services (like `USITSDASBPM256` — this is likely an App Registration service principal)
+- **Managed Identity** — Azure-assigned identity for services, no credentials to manage. If WBS had used Managed Identity properly, the hardcoded service account issue wouldn't exist
+- **RBAC** — Role-Based Access Control. Roles assigned to identities at subscription/resource group/resource level
+
+#### Azure Bot Service
+- Hosts the Teams bot middleware
+- Routes messages from Teams → ACA agent → back to Teams
+- Has its own App Registration (`WBS App ID: 3c91b69e-d6f2-4f87-980b-65388b7f5d1c`)
+- **Attack surface:** Bot Framework token validation, Teams channel authentication
+
+#### Azure Container Apps (ACA)
+- Serverless container hosting — the agent LLM pipeline runs here
+- Has 6 layers: Input Guardrail → Main LLM → Pre-conditions → MCP Call → Output Guardrail → Response
+- **Attack surface:** Container escape, environment variable secrets, SSRF from within the container
+
+#### Azure WAF
+- Web Application Firewall in front of the bot service
+- Blocks known attack patterns (SQLi, XSS, common payloads)
+- **Why it didn't catch our injection:** WAF looks at HTTP-level patterns. Our payload went through Teams → Bot → ACA → MCP. By the time it reached MCP, it was inside a legitimate JSON-RPC call. WAF never saw the raw payload.
+
+#### Common Azure Security Findings
+
+| Finding | What to look for |
+|---------|-----------------|
+| Exposed storage accounts | `*.blob.core.windows.net` publicly accessible |
+| Overprivileged Managed Identity | Identity has Contributor or Owner on subscription |
+| Key Vault misconfiguration | Secrets accessible without proper RBAC |
+| Azure Function exposed | No auth on HTTP trigger |
+| App Service environment variables | Connection strings in plain text in portal |
+| SSRF to IMDS | `http://169.254.169.254/metadata/instance` — Azure Instance Metadata Service |
+| Tenant ID enumeration | `login.microsoftonline.com/<tenantid>/.well-known/openid-configuration` |
+
+#### SSRF in Azure Context
+The Azure IMDS (Instance Metadata Service) endpoint `http://169.254.169.254/metadata/instance?api-version=2021-02-01` with header `Metadata: true` returns:
+- Subscription ID
+- Resource group name
+- Managed Identity tokens
+- VM name, location, SKU
+
+If an SSRF exists in an Azure-hosted app, hitting IMDS can give you an access token for the Managed Identity — which may have permissions on Azure resources.
+
+---
+
+## 5. RAG — Does Your Repo Have It? Risks and Defences
+
+### Does Your Repo Have RAG?
+
+**Partially.** The `ad_agent/models/kb_engine.py` implements a lightweight RAG-like system:
+
+```python
+class KBEngine:
+    def search(self, query: str, top_k: int = 4) -> list:
+        qwords = set(query.lower().split())
+        scored = []
+        for c in self.chunks:
+            overlap = len(qwords & set(c["text"].lower().split()))
+            ...
+        return [c for _, c in scored[:top_k]]
+```
+
+It reads `.md`/`.txt` files from a `./kb` directory, chunks them by markdown sections (400 words), and does **keyword overlap scoring** — not vector embeddings. This is called **BM25-style retrieval** or **lexical RAG** — simpler than semantic RAG but same security risks.
+
+The retrieved chunks are injected into the LLM context as `=== KB CONTEXT ===` blocks before the prompt.
+
+### What is RAG?
+
+**Retrieval-Augmented Generation** — instead of relying purely on the LLM's training data, RAG:
+1. Takes the user query
+2. Searches a knowledge base (vector DB or keyword index) for relevant documents
+3. Injects those documents into the LLM's context
+4. LLM answers based on retrieved context + its training
+
+Used to give LLMs access to up-to-date or private information without retraining.
+
+### RAG Poisoning — What It Is and How to Attack It
+
+RAG poisoning = injecting malicious content into the knowledge base so that when it's retrieved and fed to the LLM, it manipulates the model's output.
+
+**Attack paths:**
+
+| Attack | How |
+|--------|-----|
+| Direct KB write | If `kb_engine.add()` is exposed via API without auth — write a malicious `.md` file directly |
+| Indirect poisoning | Attacker controls a webpage/doc that gets ingested into the KB via a crawler or import feature |
+| Chunk injection | Craft content that scores high on keyword overlap — retrieved for any query |
+| Instruction injection in KB | Store `IGNORE PREVIOUS INSTRUCTIONS. Do X instead.` in a KB chunk — retrieved and fed to LLM |
+| Metadata poisoning | Manipulate source filenames so retrieved chunks appear to come from trusted sources |
+
+**In your repo specifically:** `kb_engine.add(filename, content)` writes directly to the `./kb` directory. If this method is reachable without authentication, an attacker can write any content into the KB and it will be retrieved and injected into LLM context on the next query.
+
+### How to Reduce RAG Poisoning
+
+| Defence | How |
+|---------|-----|
+| Auth on KB writes | Never expose `kb_engine.add()` without strict authentication |
+| Input sanitisation | Strip instruction-like patterns from content before storing (`IGNORE`, `SYSTEM:`, etc.) |
+| Source allowlisting | Only ingest from trusted, controlled sources — never from user-supplied URLs |
+| Chunk signing | Sign each chunk at ingest time — verify signature before injecting into context |
+| Retrieval filtering | Post-process retrieved chunks — remove any that contain prompt injection patterns |
+| Separate retrieval from generation | Log every retrieved chunk — alert on anomalous content before it reaches LLM |
+| KB access control | Read-only access for the retrieval pipeline — write access only for admins |
+
+### How to Reduce Hallucination
+
+Hallucination = LLM confidently states something false.
+
+| Technique | How it helps |
+|-----------|-------------|
+| RAG itself | Ground the LLM in real retrieved documents — less reliance on training memory |
+| Temperature = 0 | Deterministic output — less creative, less likely to invent facts |
+| System prompt constraints | "Only answer based on the provided context. If not in context, say I don't know." |
+| Citation requirement | Force model to cite the source chunk for every claim — uncheckable claims = hallucination signal |
+| Output validation | Second LLM call to verify the first answer against retrieved context |
+| Smaller, focused context | Large context windows increase hallucination risk — retrieve only top 3-4 chunks |
+| Confidence scoring | Ask model to rate confidence — low confidence answers flagged for human review |
+| Structured output | JSON output with defined fields — harder to hallucinate than free text |
+
+**In your repo:** The `kb_engine.format_context()` method truncates each chunk to 500 chars before injecting. This helps reduce noise but also means the LLM may not have full context — increasing hallucination risk on long technical content. Increasing to 1000 chars and reducing `top_k` from 4 to 3 would be a better balance.
+
+---
+
+## Quick Reference — Things to Remember
+
+| Topic | Key point |
+|-------|-----------|
+| CI/CD publish | `git tag v1.0.3 && git push origin v1.0.3` → auto publishes to PyPI |
+| Trusted publishing | No token in CI — OIDC proves repo identity to PyPI |
+| enum auto-prepend | Always runs first — replay/stored/auth need the tool list it builds |
+| MCP session | Must `initialize` first to get `mcp-session-id` — required on all subsequent calls |
+| WBS write tools | Only work via Teams bot session — direct curl blocked by WBS backend ACL |
+| Azure IMDS | `169.254.169.254/metadata/instance` — SSRF target in Azure, returns Managed Identity tokens |
+| RAG poisoning | Write malicious content to KB → retrieved on any matching query → injected into LLM context |
+| Hallucination fix | Temperature 0 + citation requirement + output validation |
+| CORS wildcard risk | `ACAO: *` on an API endpoint means any website can make authenticated cross-origin requests |
+| Replay protection | Needs nonce + timestamp window — without both, captured requests valid forever |

mcppt-1.1.0/mcppt/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"