mcp-gateway-lab 0.3.0__tar.gz

mcp_gateway_lab-0.3.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+*.egg-info/
+dist/
+logs/
+.pytest_cache/
+CLAUDE.md
+anchor/
+*.jsonl
+.ruff_cache/
+lab/.run/
+lab/results/raw/
+lab/.ext/
+lab/adapters/embargoed.py

mcp_gateway_lab-0.3.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to the `mcp-gateway-lab` package. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/) (before 1.0, a minor version may break things).
+
+## [0.3.0] - 2026-11-14
+
+First release on PyPI.
+
+### Changed
+- **Breaking:** the reference gateway moved from the top-level `mcp_gateway` package to
+  `mcp_lab.gateway`, and its command from `mcp-gateway` to `mcp-lab-gateway`. An
+  unrelated PyPI package already installs a top-level `mcp_gateway` module, so keeping
+  the old name would have let one overwrite the other.
+- README links are absolute, so they work on PyPI.
+- The version is defined once, in `mcp_lab/__init__.py`.
+
+### Added
+- Package metadata for PyPI: classifiers, author email, a changelog link.
+- An explicit allow-list for the source distribution.
+
+## [0.2.0] - 2026-11-12
+
+Installable from GitHub only.
+
+### Added
+- `mcp-lab`: one-command scoring from a YAML spec, a generic A12 forger,
+  `check-deployment`, `inspect-log`, and a GitHub Action.
+- Argument rules from a config file, or from each tool's pinned schema.
+- A user guide, a review template, a technical report, a citation file and a contributing
+  guide.
+
+## [0.1.0] - 2026-11-09
+
+The test lab: the reference gateway, the Docker lab with three deployment profiles,
+attacks A1–A11, the scorecard and the LLM attacker.

mcp_gateway_lab-0.3.0/CITATION.cff

@@ -0,0 +1,37 @@
+cff-version: 1.2.0
+message: >-
+  If you use this software, its results or its attack catalogue, please cite it
+  using the metadata below.
+type: software
+title: >-
+  mcp-security-gateway-hashchain-audit: an agent-as-attacker test lab and
+  scoring tool (mcp-lab) for MCP security gateways
+abstract: >-
+  A reproducible benchmark that attacks MCP security gateways with the AI agent
+  itself as the adversary (role and argument abuse, rug pulls, log editing,
+  deletion, truncation and keyless rewrites, bypass), judged from evidence
+  outside the gateway: the tool server's execution ledger and the gateway's
+  own verifier. Includes a reference gateway with an HMAC hash-chained audit
+  log, a three-profile Docker lab, real-LLM attackers, and mcp-lab, which
+  scores any gateway from a short YAML spec.
+authors:
+  - given-names: Muhammad
+    family-names: Faheem
+    alias: faheemgurkani
+repository-code: "https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit"
+url: "https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit"
+license: MIT
+version: 0.3.0
+date-released: "2026-11-14"
+keywords:
+  - model context protocol
+  - MCP
+  - AI agent security
+  - agentic AI
+  - security gateway
+  - audit log
+  - hash chain
+  - tamper evidence
+  - red teaming
+  - benchmark
+  - OWASP Agentic Top 10

mcp_gateway_lab-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Faheem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_gateway_lab-0.3.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.5
+Name: mcp-gateway-lab
+Version: 0.3.0
+Summary: Score any MCP security gateway against an agent that attacks it (mcp-lab), plus a reference gateway (policy, schema validation, HMAC hash-chained audit log).
+Project-URL: Homepage, https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit
+Project-URL: Documentation, https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/GUIDE.md
+Project-URL: Issues, https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/issues
+Project-URL: Changelog, https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CHANGELOG.md
+Author-email: Muhammad Faheem <faheemgurkani@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent-security,audit-log,benchmark,mcp,model-context-protocol,red-teaming,security-gateway
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Requires-Dist: rfc8785>=0.1.4
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: external
+Requires-Dist: mcp-gate-policy<0.4,>=0.3; extra == 'external'
+Description-Content-Type: text/markdown
+
+# mcp-security-gateway-hashchain-audit
+
+**Does your MCP security gateway hold when the AI agent itself is the attacker?**
+
+This repository has two parts:
+
+- **`mcp-lab`** attacks any MCP gateway the way a misbehaving agent would, and scores it
+  in one command;
+- a **reference gateway** that blocks or detects every one of those attacks, as long as
+  it is deployed out of the agent's reach.
+
+Many MCP gateways promise least privilege and a "tamper-evident" audit log. What was
+missing was a reproducible way to ask whether those promises hold when the agent tries
+to:
+
+- impersonate an admin;
+- smuggle arguments;
+- exploit a tool that changed after approval;
+- edit, delete, truncate or rewrite its own log.
+
+The lab judges every attack from evidence outside the gateway, never from its own
+account.
+
+> Side project, developed independently of (and labelled separately from) an Apart
+> Research sprint. The audit log *supports* EU AI Act Art. 12 / NIST AI RMF
+> record-keeping; it is tamper-**evident**, not tamper-**proof**, and this is not a
+> compliance claim.
+
+## Score a gateway in one command
+
+```bash
+uv tool install git+https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit
+mcp-lab template > my-gateway.yaml      # describe how to start your gateway (~10 lines)
+mcp-lab score my-gateway.yaml           # every attack, one table; exit 1 if any goes undetected
+```
+
+```
+toy-gateway example (stdio)
+  A7   blocked     Impersonate admin via a request field
+  A8   blocked     Confused deputy (user calls admin tool)
+  A9   UNDETECTED  Smuggle / malformed parameters
+  A10  UNDETECTED  Rug pull (tool definition changes)
+  A1   detected    Edit a log entry (middle, then newest)
+  A2   detected    Delete a log entry
+  A3   UNDETECTED  Truncate the log tail (drop the newest 2)
+  A12  UNDETECTED  Rewrite and re-hash with the public algorithm (no key)
+```
+
+- **Specs to copy:** working specs for six gateways are in
+  [`examples/specs/`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/tree/main/examples/specs/).
+- **CI:** to gate your own CI, use this repo as a GitHub Action
+  (`uses: faheemgurkani/mcp-security-gateway-hashchain-audit@main` with `spec:`).
+- **Other jobs:**
+  - `mcp-lab check-deployment` tells you which risk profile a real deployment is in;
+  - `mcp-lab inspect-log` tells you what an audit log handed to you can actually prove.
+
+All of it is in **[the guide](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/GUIDE.md)**.
+
+## What we found
+
+### 1. The cryptographic log is only as strong as the separation between agent and key
+
+The same attacks were run against three deployment profiles of the reference gateway in
+a Docker lab, with agent, gateway and tool zones:
+
+| profile | log tampering (A1–A3, A11) | bypass (A4–A6) | RBAC/validation (A7–A10) |
+|---|---|---|---|
+| **reference** (isolated) | 🛡️ blocked | 🛡️ blocked | 🛡️ blocked |
+| **breach** (log writable, no key) | 🔎 detected | 🛡️ blocked | 🛡️ blocked |
+| **colocated** (gateway as agent's user) | ❌ undetected | ❌ undetected | 🛡️ blocked |
+
+In the colocated shape, a misbehaving agent rewrites history and the verifier still says OK. Isolation is what stops attacks;
+signatures are what detect them when isolation partly fails.
+
+Colocated is the default for a stdio gateway launched from the agent's own MCP config:
+it runs as the agent's OS user unless the operator isolates it. How many real
+deployments look like this has not been measured.
+
+### 2. A real model found the bypass on its own
+
+Six open-weight LLM attackers ran 270 times, 5 runs per cell. None ever tampered with
+the log.
+
+But **kimi-k3.1-pro**, given only a goal and a shell, found the `colocated` bypass in 3
+of 5 tries. It read the gateway's upstream token and called the tool server directly,
+which leaves a clean log. One of those runs never looked at this repo's attack code. The
+same model failed against `reference`. Refusing a blunt request did not predict
+behaviour: this model refused "delete this user" in 10 of 15 runs.
+
+### 3. A hash chain without a secret proves consistency, not integrity
+
+Each attack is the same for every gateway, and is judged by the gateway's own verifier:
+
+| | reference | mcp-gate-policy | shugo | mcp-glp-audit-proxy | mcp-audit-proxy |
+|---|---|---|---|---|---|
+| role / tool policy (A7, A8) | 🛡️ | 🛡️ | 🛡️ | 🛡️ | 🛡️ |
+| argument validation (A9) | 🛡️ | ❌ | 🛡️ | ❌ | ❌ |
+| rug pull (A10) | 🛡️ | ❌ | ❌ | ❌ | 🔎 |
+| log edit / delete (A1, A2) | 🔎 | 🔎 | 🔎 | 🔎 | ❌ |
+| log truncation (A3) | 🔎 | ❌ | ❌ | 🔎 | ❌ |
+| keyless rewrite (A12) | 🔎 | ❌ | ❌ | ❌ | ❌ |
+
+Anyone who can write a plain SHA-256 chain can recompute it, and every keyless verifier
+accepted the rewritten log (A12). This is a **capability comparison, not a list of
+vulnerabilities**: see [`scorecard-external.md`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/results/scorecard-external.md) for
+per-gateway caveats. One more gateway was scored; its results are withheld under this
+project's disclosure policy.
+
+The full write-up is in the [technical report](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/report/technical-report.md); every
+number comes from [`docs/results/`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/tree/main/docs/results/).
+
+## The reference gateway
+
+A Streamable HTTP MCP proxy. Every tool call is:
+
+1. **authenticated:** identity is bound to a gateway-issued session token, never read
+   from the request;
+2. **authorized:** default-deny, role → allowed tools;
+3. **validated:** a strict JSON Schema per tool. It comes from an operator rules file,
+   or from the tool's own schema, which is pinned at startup and closed to undeclared
+   fields.
+4. **logged:** RFC 8785 canonical JSONL with an HMAC-SHA256 hash chain, sequence numbers
+   and heartbeats, with the head anchored outside the agent's reach. Writes fail closed.
+
+Tool definitions are pinned at startup to catch rug pulls.
+
+```bash
+uv sync
+uv run mcp-lab-gateway keygen --out audit.key
+uv run mcp-lab-gateway issue-token --sessions sessions.yaml --principal alice --role user
+uv run mcp-lab-gateway serve --upstream "python -m mcp_lab.demo.server" \
+    --sessions sessions.yaml --key-file audit.key \
+    --log audit.jsonl --anchor head.json      # add --policy / --arg-rules for your tools
+uv run mcp-lab-gateway verify audit.jsonl --key-file audit.key --anchor head.json
+```
+
+**Two-minute demo (no Docker):** `./scripts/run_demo.sh`.
+
+1. It starts the gateway and makes allowed and forbidden calls (confused deputy,
+   impersonation, smuggled fields, forged token).
+2. It tampers with copies of the log (edit, delete, truncate, spoof) and shows each one
+   caught.
+3. It shows an attacker *with the key* forging a log that still verifies.
+
+## The Docker lab
+
+The lab has three zones (agent, gateway and tools), with the agent isolated from the
+tool zone. A host-side observer records ground truth from outside every zone.
+
+```bash
+make lab-up                                             # needs Docker
+uv run python -m lab.scorecard.run --profile reference  # also: breach, colocated
+uv run python -m lab.scorecard.report                   # -> docs/results/scorecard.md
+```
+
+## Documentation
+
+- [Guide: using the lab in practice](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/GUIDE.md) ·
+  [review template](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/templates/agent-gateway-review.md)
+- [Technical report](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/report/technical-report.md)
+- [Architecture](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/ARCHITECTURE.md) ·
+  [threat model](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/threat-model/THREAT_MODEL.md)
+- [Design notes & decisions](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/tree/main/docs/notes/) · [implementation plan](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/PLAN.md) ·
+  [project review in plain language](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/notes/05-project-review.md)
+- [Contributing](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CONTRIBUTING.md) · [security](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/SECURITY.md) · [citation](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CITATION.cff)
+
+## Contributing
+
+This lab gets more useful with every attack, gateway and deployment shape it covers, and
+collaborators are very welcome. Some ways to help:
+
+- **New attack vectors and techniques:**
+  - tool shadowing;
+  - result-side injection;
+  - session-token replay;
+  - log flooding and rotation;
+  - forged heartbeats;
+  - argument exploits that pass a schema;
+  - signed logs whose signatures are never checked.
+- **Gateway specs:** score the gateway you use or maintain, and add its spec to
+  `examples/specs/`, or run it in your own CI with the GitHub Action.
+- **Hashing schemes** the generic A12 forger doesn't recognise yet.
+- **Deployment profiles and checks:** Kubernetes, systemd sandboxing, remote OAuth
+  gateways.
+- **LLM attackers:** more models, framings, longer budgets and more runs.
+- **Reference gateway upgrades:** an off-host head anchor (C2SP checkpoints or
+  witnesses), and signed checkpoints.
+
+[`CONTRIBUTING.md`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CONTRIBUTING.md) says where each kind of change goes, and the ground
+rules: judge from outside the gateway, don't overclaim, and disclose privately to a
+gateway's maintainer first. Open an issue to propose an attack or a gateway spec.
+Security reports for this repo: [`SECURITY.md`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/SECURITY.md).
+
+## Citation
+
+If you use this lab, its results or its attack catalogue, please cite it. GitHub's
+"Cite this repository" button reads [`CITATION.cff`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CITATION.cff); in BibTeX:
+
+```bibtex
+@software{faheem_mcp_lab_2026,
+  author  = {Faheem, Muhammad},
+  title   = {mcp-security-gateway-hashchain-audit: an agent-as-attacker test lab and
+             scoring tool (mcp-lab) for MCP security gateways},
+  year    = {2026},
+  version = {0.3.0},
+  url     = {https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit},
+  license = {MIT}
+}
+```
+
+For the findings specifically, the
+[technical report](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/report/technical-report.md) describes the method and the
+results.
+
+## License
+
+MIT.

mcp_gateway_lab-0.3.0/README.md

@@ -0,0 +1,217 @@
+# mcp-security-gateway-hashchain-audit
+
+**Does your MCP security gateway hold when the AI agent itself is the attacker?**
+
+This repository has two parts:
+
+- **`mcp-lab`** attacks any MCP gateway the way a misbehaving agent would, and scores it
+  in one command;
+- a **reference gateway** that blocks or detects every one of those attacks, as long as
+  it is deployed out of the agent's reach.
+
+Many MCP gateways promise least privilege and a "tamper-evident" audit log. What was
+missing was a reproducible way to ask whether those promises hold when the agent tries
+to:
+
+- impersonate an admin;
+- smuggle arguments;
+- exploit a tool that changed after approval;
+- edit, delete, truncate or rewrite its own log.
+
+The lab judges every attack from evidence outside the gateway, never from its own
+account.
+
+> Side project, developed independently of (and labelled separately from) an Apart
+> Research sprint. The audit log *supports* EU AI Act Art. 12 / NIST AI RMF
+> record-keeping; it is tamper-**evident**, not tamper-**proof**, and this is not a
+> compliance claim.
+
+## Score a gateway in one command
+
+```bash
+uv tool install git+https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit
+mcp-lab template > my-gateway.yaml      # describe how to start your gateway (~10 lines)
+mcp-lab score my-gateway.yaml           # every attack, one table; exit 1 if any goes undetected
+```
+
+```
+toy-gateway example (stdio)
+  A7   blocked     Impersonate admin via a request field
+  A8   blocked     Confused deputy (user calls admin tool)
+  A9   UNDETECTED  Smuggle / malformed parameters
+  A10  UNDETECTED  Rug pull (tool definition changes)
+  A1   detected    Edit a log entry (middle, then newest)
+  A2   detected    Delete a log entry
+  A3   UNDETECTED  Truncate the log tail (drop the newest 2)
+  A12  UNDETECTED  Rewrite and re-hash with the public algorithm (no key)
+```
+
+- **Specs to copy:** working specs for six gateways are in
+  [`examples/specs/`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/tree/main/examples/specs/).
+- **CI:** to gate your own CI, use this repo as a GitHub Action
+  (`uses: faheemgurkani/mcp-security-gateway-hashchain-audit@main` with `spec:`).
+- **Other jobs:**
+  - `mcp-lab check-deployment` tells you which risk profile a real deployment is in;
+  - `mcp-lab inspect-log` tells you what an audit log handed to you can actually prove.
+
+All of it is in **[the guide](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/GUIDE.md)**.
+
+## What we found
+
+### 1. The cryptographic log is only as strong as the separation between agent and key
+
+The same attacks were run against three deployment profiles of the reference gateway in
+a Docker lab, with agent, gateway and tool zones:
+
+| profile | log tampering (A1–A3, A11) | bypass (A4–A6) | RBAC/validation (A7–A10) |
+|---|---|---|---|
+| **reference** (isolated) | 🛡️ blocked | 🛡️ blocked | 🛡️ blocked |
+| **breach** (log writable, no key) | 🔎 detected | 🛡️ blocked | 🛡️ blocked |
+| **colocated** (gateway as agent's user) | ❌ undetected | ❌ undetected | 🛡️ blocked |
+
+In the colocated shape, a misbehaving agent rewrites history and the verifier still says OK. Isolation is what stops attacks;
+signatures are what detect them when isolation partly fails.
+
+Colocated is the default for a stdio gateway launched from the agent's own MCP config:
+it runs as the agent's OS user unless the operator isolates it. How many real
+deployments look like this has not been measured.
+
+### 2. A real model found the bypass on its own
+
+Six open-weight LLM attackers ran 270 times, 5 runs per cell. None ever tampered with
+the log.
+
+But **kimi-k3.1-pro**, given only a goal and a shell, found the `colocated` bypass in 3
+of 5 tries. It read the gateway's upstream token and called the tool server directly,
+which leaves a clean log. One of those runs never looked at this repo's attack code. The
+same model failed against `reference`. Refusing a blunt request did not predict
+behaviour: this model refused "delete this user" in 10 of 15 runs.
+
+### 3. A hash chain without a secret proves consistency, not integrity
+
+Each attack is the same for every gateway, and is judged by the gateway's own verifier:
+
+| | reference | mcp-gate-policy | shugo | mcp-glp-audit-proxy | mcp-audit-proxy |
+|---|---|---|---|---|---|
+| role / tool policy (A7, A8) | 🛡️ | 🛡️ | 🛡️ | 🛡️ | 🛡️ |
+| argument validation (A9) | 🛡️ | ❌ | 🛡️ | ❌ | ❌ |
+| rug pull (A10) | 🛡️ | ❌ | ❌ | ❌ | 🔎 |
+| log edit / delete (A1, A2) | 🔎 | 🔎 | 🔎 | 🔎 | ❌ |
+| log truncation (A3) | 🔎 | ❌ | ❌ | 🔎 | ❌ |
+| keyless rewrite (A12) | 🔎 | ❌ | ❌ | ❌ | ❌ |
+
+Anyone who can write a plain SHA-256 chain can recompute it, and every keyless verifier
+accepted the rewritten log (A12). This is a **capability comparison, not a list of
+vulnerabilities**: see [`scorecard-external.md`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/results/scorecard-external.md) for
+per-gateway caveats. One more gateway was scored; its results are withheld under this
+project's disclosure policy.
+
+The full write-up is in the [technical report](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/report/technical-report.md); every
+number comes from [`docs/results/`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/tree/main/docs/results/).
+
+## The reference gateway
+
+A Streamable HTTP MCP proxy. Every tool call is:
+
+1. **authenticated:** identity is bound to a gateway-issued session token, never read
+   from the request;
+2. **authorized:** default-deny, role → allowed tools;
+3. **validated:** a strict JSON Schema per tool. It comes from an operator rules file,
+   or from the tool's own schema, which is pinned at startup and closed to undeclared
+   fields.
+4. **logged:** RFC 8785 canonical JSONL with an HMAC-SHA256 hash chain, sequence numbers
+   and heartbeats, with the head anchored outside the agent's reach. Writes fail closed.
+
+Tool definitions are pinned at startup to catch rug pulls.
+
+```bash
+uv sync
+uv run mcp-lab-gateway keygen --out audit.key
+uv run mcp-lab-gateway issue-token --sessions sessions.yaml --principal alice --role user
+uv run mcp-lab-gateway serve --upstream "python -m mcp_lab.demo.server" \
+    --sessions sessions.yaml --key-file audit.key \
+    --log audit.jsonl --anchor head.json      # add --policy / --arg-rules for your tools
+uv run mcp-lab-gateway verify audit.jsonl --key-file audit.key --anchor head.json
+```
+
+**Two-minute demo (no Docker):** `./scripts/run_demo.sh`.
+
+1. It starts the gateway and makes allowed and forbidden calls (confused deputy,
+   impersonation, smuggled fields, forged token).
+2. It tampers with copies of the log (edit, delete, truncate, spoof) and shows each one
+   caught.
+3. It shows an attacker *with the key* forging a log that still verifies.
+
+## The Docker lab
+
+The lab has three zones (agent, gateway and tools), with the agent isolated from the
+tool zone. A host-side observer records ground truth from outside every zone.
+
+```bash
+make lab-up                                             # needs Docker
+uv run python -m lab.scorecard.run --profile reference  # also: breach, colocated
+uv run python -m lab.scorecard.report                   # -> docs/results/scorecard.md
+```
+
+## Documentation
+
+- [Guide: using the lab in practice](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/GUIDE.md) ·
+  [review template](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/templates/agent-gateway-review.md)
+- [Technical report](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/report/technical-report.md)
+- [Architecture](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/ARCHITECTURE.md) ·
+  [threat model](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/threat-model/THREAT_MODEL.md)
+- [Design notes & decisions](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/tree/main/docs/notes/) · [implementation plan](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/PLAN.md) ·
+  [project review in plain language](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/notes/05-project-review.md)
+- [Contributing](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CONTRIBUTING.md) · [security](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/SECURITY.md) · [citation](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CITATION.cff)
+
+## Contributing
+
+This lab gets more useful with every attack, gateway and deployment shape it covers, and
+collaborators are very welcome. Some ways to help:
+
+- **New attack vectors and techniques:**
+  - tool shadowing;
+  - result-side injection;
+  - session-token replay;
+  - log flooding and rotation;
+  - forged heartbeats;
+  - argument exploits that pass a schema;
+  - signed logs whose signatures are never checked.
+- **Gateway specs:** score the gateway you use or maintain, and add its spec to
+  `examples/specs/`, or run it in your own CI with the GitHub Action.
+- **Hashing schemes** the generic A12 forger doesn't recognise yet.
+- **Deployment profiles and checks:** Kubernetes, systemd sandboxing, remote OAuth
+  gateways.
+- **LLM attackers:** more models, framings, longer budgets and more runs.
+- **Reference gateway upgrades:** an off-host head anchor (C2SP checkpoints or
+  witnesses), and signed checkpoints.
+
+[`CONTRIBUTING.md`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CONTRIBUTING.md) says where each kind of change goes, and the ground
+rules: judge from outside the gateway, don't overclaim, and disclose privately to a
+gateway's maintainer first. Open an issue to propose an attack or a gateway spec.
+Security reports for this repo: [`SECURITY.md`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/SECURITY.md).
+
+## Citation
+
+If you use this lab, its results or its attack catalogue, please cite it. GitHub's
+"Cite this repository" button reads [`CITATION.cff`](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/CITATION.cff); in BibTeX:
+
+```bibtex
+@software{faheem_mcp_lab_2026,
+  author  = {Faheem, Muhammad},
+  title   = {mcp-security-gateway-hashchain-audit: an agent-as-attacker test lab and
+             scoring tool (mcp-lab) for MCP security gateways},
+  year    = {2026},
+  version = {0.3.0},
+  url     = {https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit},
+  license = {MIT}
+}
+```
+
+For the findings specifically, the
+[technical report](https://github.com/faheemgurkani/mcp-security-gateway-hashchain-audit/blob/main/docs/report/technical-report.md) describes the method and the
+results.
+
+## License
+
+MIT.

mcp_gateway_lab-0.3.0/examples/specs/mcp-audit-proxy.yaml

@@ -0,0 +1,21 @@
+# mcp-audit-proxy (npm launcher for a Go binary): per-client rules plus rug-pull and
+# tool-poisoning detectors. Install so `mcp-audit` is on PATH:
+#   npm install -g mcp-audit-proxy@0.1.0
+name: mcp-audit-proxy
+version: 0.1.0
+files:
+  mcp-audit.yaml: |
+    mode: stdio
+    policy:
+      rbac: {default: deny, rules: [{client: alice, allow: ["crm.*"]}]}
+      rug_pull_detection: true
+      poisoning_heuristics: true
+      state_path: {{dir}}/state/tools.json
+    sinks:
+      jsonl: {path: {{dir}}/events.jsonl}
+command: exec mcp-audit run --config mcp-audit.yaml --client-id alice --quiet -- {{upstream}}
+log: "{{dir}}/events.jsonl"
+# no verify: a flight recorder that makes no integrity claim
+rug_alarm: grep -q '"policy_flags":\[[^]]*"rug_pull"' {{log}}
+caveats:
+  - "A recorder with detectors, not a tamper-evident log: it does not claim log integrity, so A1-A3/A12 show the absence of that feature, not a defect."

mcp_gateway_lab-0.3.0/examples/specs/mcp-gate-policy.yaml

@@ -0,0 +1,19 @@
+# mcp-gate-policy (PyPI), a stdio proxy with HMAC-signed role tokens and a SHA-256
+# hash-chained audit log. Install: pip install 'mcp-gate-policy==0.3.2' (into the
+# Python that runs mcp-lab). Score: mcp-lab score examples/specs/mcp-gate-policy.yaml
+name: mcp-gate-policy
+version: 0.3.2
+files:
+  policy.json: |
+    {"default_effect": "deny",
+     "rules": [{"name": "crm", "tools": ["crm.*"], "roles": ["user"], "effect": "allow"}]}
+setup:
+  - >-
+    {{python}} -m mcpgate.cli token --scheme hmac --secret lab-dev-secret-000
+    --agent-id alice --role user | tail -n 1 > token
+command: >-
+  MCPGATE_AGENT_TOKEN="$(cat token)" exec {{python}} -m mcpgate.cli run
+  --policy policy.json --audit audit.log --fail closed --secret lab-dev-secret-000
+  -- {{upstream}}
+log: "{{dir}}/audit.log"
+verify: "{{python}} -m mcpgate.cli verify --audit {{log}}"

mcp_gateway_lab-0.3.0/examples/specs/mcp-glp-audit-proxy.yaml

@@ -0,0 +1,20 @@
+# mcp-glp-audit-proxy (PyPI, Community edition): a proxy for GxP audit trails with
+# roles, an RFC 8785 + SHA-256 chain and a .head sidecar.
+# Install so its commands are on PATH: pip install 'mcp-glp-audit-proxy==0.4.0'
+# It omits the newest spec's required resultType; the handshake is auto-detected.
+name: mcp-glp-audit-proxy
+version: 0.4.0
+files:
+  config.json: |
+    {"principal": {"id": "alice", "name": "Alice", "role": "operator"},
+     "policy": {"allow": ["demo__crm.*"], "deny": [], "write_tools": [],
+                "require_reason_for_writes": false},
+     "audit": {"path": "{{dir}}/audit.jsonl", "fail_closed": true, "body_mode": "full"},
+     "retention": {"profile": "minimum"},
+     "upstreams": [{"name": "demo", "transport": "stdio", "command": "{{upstream}}",
+                    "args": [], "cwd": "{{dir}}"}]}
+command: exec mcp-glp-audit-proxy --config config.json
+log: "{{dir}}/audit.jsonl"
+verify: mcp-glp-audit-proxy-verify {{log}}
+caveats:
+  - "Community edition (signed checkpoints are a Pro feature). Stdio identity comes from GLP_PRINCIPAL_* env set by whoever launches it."