Skip to main content

Aran

CI License: MIT Python 3.10+ PyPI Add to Cursor Claude Code: .mcp.json included

A transparent security proxy for Model Context Protocol (MCP) stdio servers. Wraps any existing MCP server — no server-specific integration — and gates traffic in both directions before it reaches your agent or your machine:

  • Blocks dangerous outbound tool calls — destructive commands (rm -rf, chmod 777, fork bombs, ...), before they ever reach the real server.
  • Redacts prompt-injection payloads in inbound tool results — before they reach your agent's context window.
  • Audits every gated call to a local JSONL log, so you can see what was blocked and tune false positives.

Why

Autonomous coding agents (Claude Code, Cursor, Windsurf, ...) use MCP servers to read files, run shell commands, and hit the network. If an agent ingests untrusted content — a webpage, a repo file, a database row — containing a hidden prompt injection, it can be manipulated into running destructive commands or exfiltrating secrets, using your own valid credentials. Static-analysis tools and traditional network firewalls are both blind to this: neither operates at the live protocol layer where the agent and its tools actually talk to each other.

Aran sits inline at that layer instead, as a stdio proxy your IDE launches transparently.

New to Aran? docs/guide/ is a full, beginner-friendly walkthrough — one concept per page, from "what is MCP" through installing, wiring it into your IDE, and a hands-on session that proves every gate case works, with real command output at each step. The rest of this README is the fast, condensed version of the same information.

Install

Aran is on PyPI — no install step needed if your IDE launches it via uvx (recommended, see below). To use the plain aran command yourself:

pip install aran

To work on Aran itself instead, install from source:

git clone https://github.com/aranaisec-cyber/aran.git
cd aran
pip install -e .

Usage

Wrap the command you'd normally use to launch an MCP server, via uvx so nothing needs installing up front:

uvx aran -- npx -y @modelcontextprotocol/server-filesystem /path/to/project

(If you installed Aran yourself with pip install aran above, drop the uvx prefix and just run aran -- ... directly — both forms work identically.)

Wiring into an MCP-speaking IDE

In your IDE's MCP server config, replace the server's command/args with uvx/aran, moving the original command after a -- separator.

Claude Code / Cursor-style JSON config:

{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["aran", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}

That's the whole integration — no prior pip install needed, uvx fetches Aran transparently the first time your IDE launches it. Aran spawns the real server as a child process and relays every message between it and your IDE, gating tool calls and tool results as they pass through — nothing else in your IDE config changes, and the downstream server needs no modification.

Every gated message (allowed or blocked) is logged to ~/.aran/audit.jsonl.

One-click / auto-config

Both badges above wrap a real, production MCP server — mcp-server-fetch, the official reference server for fetching web pages — not a toy demo. It's a deliberate choice: fetching an untrusted URL and having whatever text is on that page land in your agent's context is exactly the attack this project defends against, so wrapping it is the most honest possible demonstration of what Aran does. It needs uv installed (uvx specifically) and needs no per-user path or account setup — it works identically for every developer who clicks it.

  • Cursor: the "Add to Cursor" badge above installs aran-fetch directly — one click, no manual config.
  • Claude Code: this repo ships a working .mcp.json at its root wrapping the same server. Claude Code auto-detects project-level .mcp.json files — clone this repo, open it in Claude Code, and you'll get a one-time approval prompt for aran-fetch. There's no click-to-install deep link for Claude Code (unlike Cursor, it doesn't have one), but .mcp.json is the equivalent "ships with the repo, auto-detected" mechanism.

Once it's running, ask your agent to fetch a URL and watch ~/.aran/audit.jsonl — every fetched page's content passes through the input gate exactly like the manual tests in TESTING.md, just against the live internet instead of a canned fixture. A page containing ignore previous instructions (or anything else in src/aran/default-rules.yaml) gets redacted before your agent ever sees it.

To wrap a different server instead — your own, or another server entirely — the pattern is identical: swap the args in .mcp.json, or generate your own Cursor deep link by base64-encoding {"command":"uvx","args":["aran","--",<your command>,<your args...>]} and using it in cursor://anysphere.cursor-deeplink/mcp/install?name=<name>&config=<that base64> — or run claude mcp add <name> --scope project -- uvx aran -- <your command> <your args...>, which writes the .mcp.json entry for you.

Heads up: mcp-server-fetch's own documentation notes it can reach local/internal network addresses, which is a real consideration for any fetch-capable tool regardless of Aran — worth knowing if you point it at anything beyond public URLs.

How it works

  • Outbound (tools/call requests): the tool name and arguments are checked against a list of destructive-command signatures. A match means the call is never forwarded to the real server — Aran synthesizes a JSON-RPC error response instead.
  • Inbound (tool results and other responses): every string is scanned for prompt-injection signatures. A match in agent-visible content gets replaced with a redaction notice before being relayed; a small, explicit set of protocol-machinery fields (protocolVersion, serverInfo, resource uris, etc.) is exempt from rewriting so a match there doesn't break session negotiation — see the design spec for the exact field list and reasoning.
  • Aran treats the downstream server it wraps as untrusted — the gating guarantees are designed to hold even against a malformed or actively hostile server, not just a well-behaved one. See tests/fixtures/hostile_server.py and tests/test_proxy_hostile.py for the adversarial test suite this is verified against.
  • A blocked outbound call gets a JSON-RPC error with code: -32001 and a data field giving the violation, the matched signature, and a best-effort target_node (which argument the match was found in) — useful context for an agent or developer debugging why a call was blocked. A bare -32000 with no data means Aran itself couldn't safely inspect the message (fail-closed), not a signature match.
  • Optional: scan a public GitHub repo before it's cloned/downloaded (ARAN_SCAN_GITHUB_REPOS=1). If an outbound call references a github.com repo (an HTTPS clone URL or an SSH remote, in any tool's arguments — not tied to a specific tool name), Aran fetches that repo's tarball and scans every file against destructive-command, prompt-injection, hardcoded-secret, and supply-chain (curl | bash-style install hooks) signatures before the call that would clone it is forwarded. A match blocks the call with code: -32002. This is the one feature in Aran that makes outbound network requests, so it's off by default — see Configuration below.
  • Built-in aran_status tool: ask your agent "what's aran's status?" and get a plain-text summary of recent gate activity right in your chat — no log file to open. Aran answers it directly (never forwarded to the wrapped server) and splices its listing into tools/list responses so agents can discover and call it on their own. Always on, read-only, no network calls. Optional hours argument narrows or widens the window (0 = all-time). See 4. Wiring Aran into Your IDE § Confirming Aran is actually running.

Configuration

Environment variables, read once at startup:

  • ARAN_MODE=audit — dry-run mode. Gate decisions still run and are still logged (as would_block instead of blocked), but nothing is actually blocked or redacted — every call and response is forwarded unmodified. Use this to tune signatures against real traffic before turning enforcement on.
  • ARAN_PROFILE=1 (or true/yes/on) — prints a timing line to stderr for every gated message: how long the outbound check took, and how many JSON leaf nodes the inbound scan visited and in how long.
  • ARAN_SCAN_GITHUB_REPOS=1 (or true/yes/on) — enables the GitHub repo scan described above. Prints a one-time startup notice, since this is the only toggle that makes Aran reach the network. If the fetch itself fails (offline, rate-limited, repo not found, ...), the call is forwarded anyway — a failed scan is logged as "error", not treated as a match; see docs/guide/08-modes-and-configuration.md for the full reasoning on why this one check fails open instead of closed.
ARAN_MODE=audit aran -- npx -y @modelcontextprotocol/server-filesystem /path
ARAN_SCAN_GITHUB_REPOS=1 aran -- npx -y @modelcontextprotocol/server-filesystem /path

See TESTING.md for worked examples of ARAN_MODE/ARAN_PROFILE.

Rule config

Signatures live in src/aran/default-rules.yaml, which ships inside the installed package, under four keys: input_gate_signatures and output_gate_signatures (the two live gates, described above) plus secret_signatures and supply_chain_signatures (used only by the optional GitHub repo scan). The latter two are optional in a hand-edited rules file — an older file that predates them loads exactly as before, falling back to a small built-in default for whichever it's missing, with no warning. Refresh the prompt-injection and destructive-command signatures from a live labeled dataset with:

python scripts/sync_threat_intel.py

On false positives: the shipped signature set is generated from a public labeled dataset and, like any pattern-based detector, can flag benign content. If something gets redacted/blocked that shouldn't be, please open an issue with the matched signature (visible in the audit log) and the offending text.

Security

This is a security tool — please report vulnerabilities responsibly. See SECURITY.md for scope and reporting instructions.

Development

git clone https://github.com/aranaisec-cyber/aran.git
cd aran
pip install -e ".[dev]"
pytest -v

See CONTRIBUTING.md for project layout and testing philosophy, and TESTING.md for a step-by-step manual verification procedure — including seeing the output/input gates block a destructive command and redact an injection payload live, not just watching pytest pass.

Status

Early (v0.1, pre-1.0). The core proxy — invocation, bidirectional gating, YAML config, audit log — is implemented and tested, including against an adversarial downstream-server test suite. Not yet covered: a multi-server gateway, enterprise/compliance features, and a hosted control plane — see the design spec for what's explicitly in and out of scope for this stage.

License

MIT

Metadata

Release files for aran 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aran 0.1.1
File Size Uploaded Provenance Actions
aran-0.1.1.tar.gz 90.4 kB Without provenance Details for aran-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aran 0.1.1
File Interpreter ABI Platform Actions
aran-0.1.1-py3-none-any.whl Python 3 none any Details for aran-0.1.1-py3-none-any.whl

Total release size: 142.7 kB

Release files / aran-0.1.1.tar.gz

Download URL aran-0.1.1.tar.gz
Size 90.4 kB
Tags Source
SHA-256 checksum
How to use checksums
6482bed938266627a41a1ad680b3301272e62ed6da94b7006c0b5a4c813d67ca
BLAKE2b-256 checksum
How to use checksums
eba3fdec5e071d959dafd276b6942adf771a2f67c409b9a29a206709cfe3bf94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Release files / aran-0.1.1-py3-none-any.whl

Download URL aran-0.1.1-py3-none-any.whl
Size 52.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f16558e3076ebda3a5f30305f20500a80fe49382526b98b6348840a036d1c1ae
BLAKE2b-256 checksum
How to use checksums
392bb7cb1fa5f676253a72b3466f792b785b177598400cdec881c186e9e8063e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Security for aran 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page