aletheia-mcp

Aletheia MCP Server 🛡️

Sub-millisecond runtime filter that blocks scope-creep and prompt-injection tool calls before an AI agent can run them.

Aletheia MCP intercepts tool calls from Claude Code, Claude Desktop, and any other MCP-compatible agent before they execute and blocks the destructive ones, with sub-millisecond (~25 µs) overhead and no LLM in the hot path.

It's motivated by the Aletheia research paper's taxonomy of nine behavioral signatures: recurring LLM failure patterns, each with an ID, derived from the interfaces through which a model touches its environment (output/reality, input/trust, task/scope, and so on). This server targets two of them:

• S3 (Scope Creep Beyond Mandate): the agent acts outside the task it was actually given, writing files outside its workspace, reaching into unrelated systems, quietly widening what it was asked to do.
• S2b (Jailbreak Vulnerability, per the paper's naming): this server ships a practical, pattern-based heuristic for the adjacent problem of adversarial instructions smuggled through tool results, file contents, or fetched data. This is an engineering heuristic inspired by S2b, not an implementation of the paper's own empirical S2b findings — the paper explicitly defers S2b's evaluation ("scoped as a defined next step") pending a more stable attack taxonomy, and this server's keyword/pattern matching is a different, narrower thing than what that evaluation would measure.

The paper validates those nine signatures against 2,571 entries across three independent corpora: the AI Incident Database (AIID + hand-curated supplement, n=1,134), the AVID AI Vulnerability Database (n=767), and the MIT AI Risk Repository (n=670). The per-model detection-rate figures from that research are reported in the paper with their methodology; treat them as directional context for why these signatures matter, not as an independently-audited benchmark of this codebase.

Security Model: A Fast Pre-Filter, Not a Sandbox

Aletheia MCP is a deterministic, pattern-based lexical and structural filter, iteratively hardened through many rounds of adversarial red-teaming against the shell, SQL, filesystem, and network surfaces it inspects. Each round of testing has turned up real gaps, and each has been fixed and re-verified. That process is ongoing, not finished, and it never fully finishes: this is honest heuristic pattern-matching over Bash and SQL, not a formal parser or a proof of completeness.

[!IMPORTANT] What this is, and isn't:

• Aletheia is a fast, first-line pre-execution filter: single-digit-to-low-tens-of-microseconds overhead, deterministic, no LLM in the hot path. It catches a wide and continually growing set of known destructive, exfiltration, SSRF, and privilege-escalation patterns before they execute.
• Aletheia is not a sandbox, not a formal guarantee, and not a substitute for least-privilege credentials, non-root system users, scoped database grants, or containerized/VM-level isolation (Docker, gVisor, Firecracker). Because it works by recognizing known-dangerous patterns in shell and SQL text rather than by parsing and fully understanding either language, a sufficiently novel or obfuscated construct can, in principle, always be found that the current pattern set doesn't yet cover. This is an inherent property of pattern-based filtering against a Turing-complete shell, not a bug that a future patch will finally close for good.
• Aletheia does not perform DNS resolution, so a domain name an attacker controls and points at a private IP or cloud metadata endpoint is outside what a string-based filter can ever detect at this layer; that requires DNS-aware egress control (see SECURITY.md).
• The right way to run this: treat Aletheia as one layer that removes the easy, common failure modes cheaply, combined with OS/network-level sandboxing as the actual security boundary, not instead of it.

Known Limitations (non-exhaustive, updated as found)

• Detection is enumerated over known dangerous functions, flags, and syntax shapes (e.g., specific SQL functions, specific shell obfuscation idioms). Sibling or novel variants not yet added to the pattern set will not be caught until they are found and added.
• No DNS resolution: SSRF protection is limited to literal IPs/hostnames in the request text, not what a domain name actually resolves to.
• S2b (prompt-injection) detection is keyword- and pattern-based; it is not a semantic classifier and can be evaded by sufficiently novel phrasing.
• This is a single, actively-iterated implementation; it has not yet had independent, adversarial third-party review beyond the iterative self-testing documented in this repository's commit history.

The Problem: Scope Creep (S3) in Agent Runtimes

When autonomous agents are granted tool execution access (Bash, SQL, filesystem mutation, API calls), the primary failure mode is Scope Creep Beyond Mandate:

• Destructive Shell Mutation: An agent asked to "inspect git diff" runs git reset --hard or rm -rf * to resolve a conflict.
• Credential Harvesting: An agent reading code probes ~/.ssh/id_rsa, .env, or AWS credentials to resolve connection errors.
• Unbounded Database Writes: An agent executes DELETE FROM accounts; or UPDATE users SET role='admin'; without WHERE predicates (or with tautological WHERE 1=1).
• Interpreter Escape Hatches: An agent runs shell commands wrapped inside python3 -c "os.system('...')" or node -e "fs.rmSync('/')".
• SSRF & Cloud Metadata Leaks: An agent probing network endpoints makes calls to 169.254.169.254 (AWS metadata) or internal RFC1918 subnets.
• Self-Mandate Escalation: A prompt-injected or drifting agent attempting to rewrite its own safety policy.

Existing defenses rely on LLM-as-a-judge evaluators that add 1,500–3,000 ms to every tool call. Aletheia MCP provides deterministic, multi-stage lexical and structural filtering in single-digit microseconds.

Key Features

The list below reflects what the pattern set currently catches, built up through iterative adversarial testing rather than designed upfront as a complete taxonomy. See Known Limitations above for what it does not (yet, or ever, in the DNS case) cover.

• ⚡ Sub-Millisecond (~25 µs p99) Overhead: 100,000+ evaluations per second. Zero perceived latency in agent loops.
• 🛡️ Monotonic Mandate Escalation Guard: Prevents autonomous agents from self-granting write, destructive, or network permissions. Mandates can be tightened voluntarily, but loosening requires an operatorSecret.
• 🎯 Evasion-Hardened Engine:
  • Database OS & Filesystem Primitives: Blocks PostgreSQL COPY ... PROGRAM, pg_read_file(), lo_import(); MySQL LOAD DATA INFILE, INTO OUTFILE; SQLite ATTACH DATABASE; and SQL Server xp_cmdshell.
  • Scheme-less & Malformed URL SSRF Defense: Normalizes protocol-relative and scheme-less endpoints (169.254.169.254/latest), enforcing strict fail-closed rejection on invalid URLs and direct cloud metadata access under offline mandates.
  • Direct Shell Metadata & Network Tool Neutralization: Scans direct IP references in curl / wget without URL schemes, and blocks socat raw socket exfiltration channels.
  • Wildcard Credential & Sensitive Directory Boundaries: Enforces wildcard protection across all .env.* variants (.env.secrets, .env.staging, .env.test) and sensitive config roots (~/.kube/, ~/.docker/, ~/.gnupg/, .git-credentials).
  • Linear O(N) Normalization: Token-based non-backtracking brace expansion and bounded parameter resolution ensures sub-millisecond execution on 100KB+ payloads.
  • Bash Socket Pseudo-Device Interception: Inspects /dev/tcp/HOST/PORT and /dev/udp/HOST/PORT redirections, halting cloud metadata SSRF and covert exfiltration channels directly on shell inputs.
  • SQL CTE & Procedural Block Interception: Enforces unbounded mutation guards across Common Table Expressions (WITH ... DELETE) and PL/pgSQL anonymous blocks (DO $$ ... $$).
  • Dynamic Linker Hijacking Defense: Neutralizes LD_PRELOAD, DYLD_INSERT_LIBRARIES, and runtime environment variable hijacking.
  • Quote & Backslash Stripping: Defeats split-token evasion (r'm' -rf /, r\m -rf /).
  • Variable Indirection & Default Fallbacks: Resolves shell variable substitutions (X=rm; $X -rf /) and default parameter expansions (${X:-rm} -rf /).
  • Positional Parameter & IFS Normalization: Neutralizes $IFS$9 word-splitting.
  • Dual-Representation SQL Analysis: Defeats inline comment evasion (DROP/**/TABLE, DR/**/OP, and # MySQL comment).
  • Interpreter Escape Interception: Recursively normalizes string concatenations ('r'+'m'), inspects dynamic imports (import("node:fs")), and parses code passed via -c/-e/-r flags across python, node, ruby, perl, php, and sh.
  • Automated Hex & Base64 Decoding: Automatically extracts, decodes, and recursively evaluates hex (bytes.fromhex(...)) and base64-encoded command payloads.
  • Unicode NFKC & Zero-Width Sanitization: Neutralizes invisible characters (\u200B, \u200C, \uFEFF) and confusable fullwidth/math-bold jailbreaks in prompt injections (S2b).
  • IPv4-Mapped IPv6 SSRF Translation: Converts compressed hex IPv6 notations ([::ffff:a9fe:a9fe]) to canonical dotted-decimal bytes (169.254.169.254).
  • Percent-Encoded Path Traversal: Multi-pass URL decoding catches %2e%2e%2f.env and ..%2f.ssh%2fid_rsa.
  • Generalized Fork Bombs: Detects recursive piped background processes across arbitrary function identifiers.
  • SetUID Privilege Elevation: Halts chmod u+s, chmod 4755, and privilege tampering.
  • Tautological SQL Predicates: Flags WHERE 1=1, WHERE true, and tautologies as unbounded mutations.
  • Polymorphic Argument Inspection: Safely inspects strings, arrays, and objects fail-closed across both native and unrecognized third-party tools.
• 🛡️ Two Operating Modes:
  • Direct Guard Tools: Standalone tools (aletheia_set_mandate, aletheia_intercept, aletheia_safe_bash, aletheia_safe_sql).
  • Fail-Closed Transparent Proxy: Middleware that wraps ANY downstream MCP server (Postgres, Filesystem, Bash), intercepting both single tools/call and JSON-RPC 2.0 batch arrays with strict fail-closed boundaries.
• 📊 Real-Time Observability Resources: Exposes live audit logs, block rates, and latency distributions via aletheia://telemetry/summary.
• 🔒 Zero External API Calls: Zero LLM-as-a-judge latency on the hot execution path.

Performance Benchmarks

Measured on 10,000 consecutive multi-domain evaluations (Bash de-obfuscation, SQL pattern validation, path verification, SSRF check, prompt injection). Numbers below are from a representative local run; p50 is stable across runs, p99 varies with system load (observed range ~24–70 µs) since it's sensitive to GC pauses at microsecond scale; both are still comfortably within the sub-millisecond target:

Metric	Measured Value	Target
p50 (Median)	~0.0085 ms (8.5 µs)	< 0.500 ms
p95 Latency	~0.0180 ms (18 µs)	< 0.800 ms
p99 Latency	~0.024–0.070 ms (24–70 µs)	< 1.000 ms
Throughput	100,000+ evals / second	> 10,000 / s
Hot-Path External APIs	0 (Deterministic local engine)	0

Run locally via npm run benchmark. Results will vary by machine; treat the specific microsecond figures as illustrative of "comfortably sub-millisecond," not as a precise SLA.

How the microsecond-level overhead is actually achieved

There's no single trick — it's the absence of the things that would make this slow, plus a few deliberate implementation choices:

• No LLM anywhere in the hot path. The decision is made entirely by synchronous, in-process JavaScript — no network round-trip, no model inference. This is the single biggest factor: an LLM-as-judge call costs 1.5–3 seconds because it's a remote inference request; this costs microseconds because it's local string matching.
• Regex patterns are precompiled once at module load, not rebuilt per call. Every pattern list (DESTRUCTIVE_SIGNATURES, SENSITIVE_PATH_PATTERNS, OBFUSCATION_PATTERNS, etc.) is a RegExp object constructed at server startup and reused for the life of the process — V8 compiles a regex's internal representation once, so there's no recompilation cost per request.
• Inputs are short, and the operations on them are linear. A shell command, SQL query, path, or URL is typically tens to a few hundred characters; a dozen sequential regex passes over a string that size is inherently a few-microsecond operation. (The one time this assumption broke — an O(n²) normalization step that was fine on typical input but took 18 seconds on a 100KB adversarial payload — is exactly the kind of thing documented and fixed in the commit history; see Known Limitations.)
• Dispatch does bounded work, not exhaustive work. The evaluator first identifies which domain a tool call belongs to (bash, SQL, filesystem, network) via a cheap substring check on the tool name, then runs only that domain's checks — not every check across every domain on every call.
• Fixed-size bookkeeping. The audit log and latency-history buffers are capped (500 and 2,000 entries respectively) via O(1)-amortized operations, so per-call overhead doesn't grow as the server stays up. This was verified directly, not assumed: 3 million sequential evaluations held a flat ~154,000 ops/sec with no degradation trend.

The honest caveat if the exact number gets pushed on: the ~25µs figure is the cost of the in-process evaluation function itself, measured with a high-resolution monotonic clock directly around that call. It does not include JSON-RPC serialization or stdio pipe I/O in a real MCP session, which adds some overhead on top. The claim that holds up is "no LLM in the hot path, comfortably sub-millisecond end to end" — not "exactly 25 microseconds no matter what's measuring it."

Production Readiness & Scale Testing

Beyond the unit test suite, these are real, reproducible tests against actual spawned processes and a real downstream MCP server (@modelcontextprotocol/server-filesystem), not synthetic in-process loops. Run them yourself via npm run test:scale:concurrent and npm run test:scale:isolation (source: test/scale-*.mjs).

Test	What it checks	Result
Sustained load (3M evaluations, single instance)	Memory growth / throughput degradation over an extended run, with periodic mandate changes and telemetry reads mixed in	Heap flat at ~8.3MB after an initial ~500K-eval warmup; ~154,000 evals/sec sustained with zero degradation trend across the full run
Concurrent multi-instance (30 simulated customers, real spawned processes)	Correctness and isolation when many independent Aletheia+downstream-server pairs run at once	4,800 total operations, 0 timeouts, 0 correctness failures — every one of 1,200 concurrent adversarial path-traversal attempts was blocked, every benign write/read-back matched correctly with no cross-contamination
Cross-customer isolation (targeted)	Whether Aletheia's own --allowed-paths boundary — not the wrapped server's — actually prevents one instance from reading another's data	Customer A blocked from reading Customer B's ordinary (non-"sensitive") file, even though the downstream server was deliberately given access to both directories; zero content leakage
Realistic false-positive sweep (114 commands: git, npm/yarn/pnpm, python/pip/poetry, docker/kubectl, make/cargo/maven/gradle, file ops, curl to real APIs, common SQL)	Whether ordinary developer workflows get incorrectly blocked	0 false positives (0.00%) under the recommended --allow-write --allow-network config
Downstream crash handling	Behavior when the wrapped server crashes unexpectedly mid-session	Detected in ~4ms, exit code propagated correctly, clean shutdown with no hang or orphaned process (Aletheia does not auto-restart a crashed downstream — it exits alongside it, same as any stdio MCP server pair)
Node version floor	Whether the engines: >=18.0.0 claim is real	Full test suite (155/155) and a real proxy session against server-filesystem both verified passing on Node 18.20.8, not just the development machine's newer version

None of this substitutes for real, unpredictable usage over time — it rules out the specific failure modes (wrong Node version, memory leak, high false-positive rate, cross-instance interference) that would make early real usage go badly, rather than proving the tool is bug-free.

Quickstart

[!TIP] By default, Aletheia starts fully locked down (read-only, no network, no loopback) and stays that way, on purpose. If your agent needs to write files or make network calls, grant that up front with --allow-write / --allow-network / --allow-loopback (and scope writes to a directory with --allowed-paths), as shown below. These flags set the initial mandate at server startup and are not gated by operatorSecret; that gate only applies to changing an already-running session's mandate mid-flight (e.g. an agent calling aletheia_set_mandate to loosen its own permissions, which is deliberately blocked). Most users want the startup flags below, not operatorSecret.

1. Claude Code CLI

# Read-only (safe default; can inspect but not modify anything):
claude mcp add aletheia -- npx -y aletheia-mcp

# Practical default for a coding agent that needs to edit files in your project:
claude mcp add aletheia -- npx -y aletheia-mcp --allow-write --allowed-paths /path/to/your/project

2. Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aletheia": {
      "command": "npx",
      "args": ["-y", "aletheia-mcp", "--allow-write", "--allowed-paths", "/path/to/your/project"]
    }
  }
}

3. Transparent Proxy Mode

Wrap existing downstream MCP servers with Aletheia safety filtering:

{
  "mcpServers": {
    "secure-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "aletheia-mcp",
        "--allow-write",
        "--proxy",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/dir"
      ]
    }
  }
}

Tool Reference

Tool	Mode	Annotation	Description
aletheia_set_mandate	State	readOnlyHint: false	Establish or tighten operational safety envelope. Loosening requires operatorSecret.
aletheia_get_mandate	Observability	readOnlyHint: true	Retrieve active mandate, allowed paths, and risk tolerance.
aletheia_intercept	Gatekeeper	readOnlyHint: true	Pre-flight check for candidate tool calls. Returns ALLOW or BLOCK with violation details.
aletheia_safe_bash	Execution	readOnlyHint: false	Verified shell executor. Blocks rm -rf, fork bombs, exfiltration before running.
aletheia_safe_sql	Audit	readOnlyHint: true	Validates SQL against DROP, TRUNCATE, and unbounded DELETE/UPDATE (including WHERE 1=1).
aletheia_get_telemetry	Observability	readOnlyHint: true	Emits evaluation counts, block rate %, and microsecond latency percentiles.

Resource & Prompt Reference

Resources (resources/read)

Clients can inspect server state on-demand via standard MCP resources/read:

• aletheia://telemetry/summary: Real-time evaluation counters, block rate %, and microsecond latency distribution.
• aletheia://telemetry/audit-log: Rolling log of the last 50 tool clearance requests with inputs, verdicts, violation signatures, and timestamps.
• aletheia://mandate/current: Active session mandate parameters, allowed tool lists, path boundaries, and permission toggles.
• aletheia://signatures/s3: Specification, risk taxonomy, and benchmark failure rate data for Signature S3 (Scope Creep).

Prompts (prompts/get)

• aletheia_mandate_enforcer: System prompt directive that establishes operational safety boundaries and instructs the agent to route risky actions through Aletheia before execution. Accepts task_description (required), workspace_root (optional), and allow_write (optional).

Architecture

                    ┌───────────────────────────────────────────────┐
                    │          Claude / Agent Host Runtime          │
                    └───────┬───────────────────────────────┬───────┘
                            │                               │
                  Mode 1: Guard Tools              Mode 2: Transparent Proxy
                  (aletheia_intercept,             (Intercepts tools/call
                   aletheia_safe_bash)              to downstream MCPs)
                            │                               │
                            ▼                               ▼
            ┌───────────────────────────────────────────────────────────────┐
            │                      Aletheia MCP Server                      │
            │                                                               │
            │  ┌─────────────────────────────────────────────────────────┐  │
            │  │              S3 Scope Creep Engine (<10µs)              │  │
            │  │  ├─ Multi-stage Token Unquoting & De-obfuscation        │  │
            │  │  ├─ Variable Indirection Resolver                       │  │
            │  │  ├─ Positional IFS & Brace Expansion Normalizer         │  │
            │  │  ├─ Dual-Representation SQL Comment Analyzer            │  │
            │  │  ├─ Interpreter Escape Filter (python -c, node -e)      │  │
            │  │  ├─ Destructive Filter (rm -rf, fork bombs, find -del)  │  │
            │  │  ├─ SetUID / Privilege Escalation Guard                 │  │
            │  │  ├─ Credential & Sensitive File Access Guard            │  │
            │  │  ├─ SSRF & Cloud Metadata Validator                     │  │
            │  │  ├─ SQL DDL & Tautological Predicate Guard (WHERE 1=1)  │  │
            │  │  ├─ Monotonic Mandate Escalation Guard (operatorSecret) │  │
            │  │  └─ S2b Adversarial Prompt Injection Filter             │  │
            │  └─────────────────────────────────────────────────────────┘  │
            │                                                               │
            │  ┌─────────────────────────────────────────────────────────┐  │
            │  │ Telemetry & Audit Stream (aletheia://telemetry/summary) │  │
            │  └─────────────────────────────────────────────────────────┘  │
            └───────────────────────────────┬───────────────────────────────┘
                                            │
                              [ALLOW]       │       [BLOCK]
                    ┌───────────────────────┴───────────────────────┐
                    ▼                                               ▼
          Execute Tool Safely                         Emit Structured Policy Breach
                                                      (Explains boundary violation)

Research Attribution & Empirical Corpus

Aletheia MCP is developed by Vikas Shivpuriya as part of the broader Aletheia AI Safety Research Core. The underlying behavioral failure signatures are motivated by incidents cataloged in the AI Incident Database (AIID), the AVID AI Vulnerability Database, and the MIT AI Risk Repository. The per-model detection rates referenced for frontier systems (Claude Sonnet 4.6, GPT-4o, Gemini 2.5 Flash) come from that paper's evaluation harness; treat them as directional context for why Signature S3 matters rather than as a verifiable benchmark of this codebase. Signature S2b specifically is not yet part of that empirical evaluation — the paper defers it as future work, so this server's S2b filter should be read as an independent, practical heuristic motivated by the taxonomy, not as an implementation validated by the paper's own findings.

What is independently verifiable in this repository: the test suite (npm test), the latency benchmark (npm run benchmark), and the commit history documenting each round of adversarial testing and the fixes it produced.

• Research Paper & Taxonomy: github.com/vikasny30/aletheia-paper
• License: Apache 2.0