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.**

[![MCP Compliant](https://img.shields.io/badge/MCP-Protocol%20Compliant-blue.svg)](https://modelcontextprotocol.io)
[![Latency](https://img.shields.io/badge/p99%20Latency-~25%C2%A0%C2%B5s-brightgreen.svg)](#performance-benchmarks)
[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/Tests-155%20passed-success.svg)](test/s3-scope.test.ts)

![Aletheia MCP blocking an out-of-scope file write and reporting it in the telemetry audit log](https://raw.githubusercontent.com/vikasny30/aletheia-mcp/main/assets/demo.gif)

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](https://github.com/vikasny30/aletheia-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](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](#known-limitations-non-exhaustive-updated-as-found) 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