Aletheia Runtime Safety & Scope Creep Filter

Aletheia MCP 服务 🛡️

亚毫秒级运行时过滤器，可在 AI Agent 执行工具调用前拦截越权扩展和提示词注入。

Aletheia MCP 会在 Claude Code、Claude Desktop 及其他任何兼容 MCP 的 Agent 执行工具调用之前进行拦截，并阻止具有破坏性的调用，开销仅为亚毫秒级（约 25 µs），且关键路径中不使用大模型。

本项目受到 Aletheia 研究论文中九种行为特征分类法的启发：这些特征是反复出现的大模型失效模式，每种都有一个 ID，源自模型与环境交互的接口（输出／现实、输入／信任、任务／范围等）。本服务针对其中两种：

• S3（超出授权范围）：Agent 超出实际接到的任务范围行事，在其工作区之外写入文件、访问无关系统，或悄然扩大任务范围。
• S2b（越狱漏洞，按论文中的命名）：本服务提供了一种实用的、基于模式的启发式方法，用于处理相邻问题：通过工具结果、文件内容或获取的数据夹带对抗性指令。这是一种受 S2b 启发的工程启发式方法，并非对论文自身 S2b 实证研究结果的实现——论文明确将 S2b 评估推迟到“定义好的下一步”，以等待更稳定的攻击分类法；而本服务的关键词／模式匹配与该评估衡量的内容不同，范围也更窄。

论文使用三个独立语料库中的2,571 条记录验证了这九种特征：AI 事件数据库（AIID + 人工整理的补充数据，n=1,134）、AVID AI 漏洞数据库（n=767）和 MIT AI 风险知识库（n=670）。论文报告了按模型划分的检测率及其方法；应将其视为理解这些特征为何重要的方向性参考，而非对本代码库进行的独立审计基准。

---

安全模型：快速预过滤器，而非沙箱

Aletheia MCP 是一种确定性的、基于模式的词法与结构过滤器，针对其检查的 shell、SQL、文件系统和网络攻击面，经过多轮对抗性红队测试不断加固。每轮测试都发现了实际漏洞，并且每个漏洞都已修复并重新验证。这一过程仍在持续，并且永远不会彻底结束：这是针对 Bash 和 SQL 的启发式模式匹配，而非正式解析器，也不构成完备性证明。

重要

这是什么，以及不是什么：

• Aletheia 是一个快速的执行前第一道过滤器：开销为个位数至十几微秒，具有确定性，关键路径中不使用 LLM。它能在执行前拦截范围广泛且不断扩大的已知破坏性、数据窃取、SSRF 和权限提升模式。
• Aletheia不是沙箱，不提供正式保证，也不能替代最小权限凭据、非 root 系统用户、受限数据库授权，或容器/虚拟机级隔离（Docker、gVisor、Firecracker）。它通过识别 shell 和 SQL 文本中的已知危险模式来工作，而不是解析并全面理解这两种语言，因此原则上总能找到足够新颖或经过混淆的构造，使其尚未被当前模式集覆盖。这是基于模式的过滤器面对图灵完备 shell 时固有的局限，并非未来某个补丁就能一劳永逸解决的漏洞。
• Aletheia不会执行 DNS 解析，因此，攻击者控制并指向私有 IP 或云元数据端点的域名，不在字符串过滤器能在这一层检测的范围内；这需要支持 DNS 感知的出站流量控制（参见 SECURITY.md）。
• 正确的使用方式：将 Aletheia 视为一个低成本消除常见、易发故障模式的安全层，并与作为实际安全边界的操作系统/网络级沙箱结合使用，而非用它取代沙箱。

已知局限（并非详尽列表，发现后持续更新）

• 检测针对已知危险函数、标志和语法形式逐项列举（例如特定 SQL 函数、特定 shell 混淆惯用写法）。尚未加入模式集的同类变体或新变体，在被发现并加入之前不会被拦截。
• 不执行 DNS 解析：SSRF 防护仅限请求文本中的字面 IP/主机名，不包括域名实际解析到的地址。
• S2b（提示词注入）检测基于关键词和模式；它不是语义分类器，足够新颖的措辞即可绕过检测。
• 这是一项单独且持续迭代的实现；除本仓库提交历史中记录的迭代式自测外，尚未接受独立的第三方对抗性审查。

---

问题：Agent 运行时中的越权扩张（S3）

当自主 Agent 获得工具执行权限（Bash、SQL、文件系统修改、API 调用）时，主要的失效模式是超出授权范围：

• 破坏性 Shell 修改：Agent 被要求“检查 git diff”，却运行 git reset --hard 或 rm -rf * 来解决冲突。
• 窃取凭据：Agent 在读取代码时，为了解决连接错误而探查 ~/.ssh/id_rsa、.env 或 AWS 凭据。
• 无边界数据库写入：Agent 执行 DELETE FROM accounts; 或 UPDATE users SET role='admin';，但没有 WHERE 条件（或使用恒真的 WHERE 1=1）。
• 解释器逃逸通道：Agent 通过 python3 -c "os.system('...')" 或 node -e "fs.rmSync('/')" 执行封装在其中的 Shell 命令。
• SSRF 和云元数据泄漏：Agent 探查网络端点时，向 169.254.169.254（AWS 元数据）或内部 RFC1918 子网发起调用。
• 自我授权升级：受到提示词注入或行为漂移的 Agent 试图改写自身的安全策略。

现有防御依赖 LLM-as-a-judge 评估器，会让每次工具调用额外耗时 1,500–3,000 毫秒。Aletheia MCP 通过确定性的多阶段词法和结构过滤，将耗时控制在个位数微秒。

---

核心功能

以下列表反映了该模式集目前能够捕获的情况。这些模式是在反复进行对抗性测试的过程中逐步积累的，并非一开始就被设计成一套完整的分类体系。对于其尚未覆盖的情况（DNS 场景中则永远不会覆盖），请参阅上文的已知限制。

• ⚡ 亚毫秒级（p99 约 25 µs）开销：每秒评估 100,000 次以上。在 Agent 循环中感知不到延迟。
• 🛡️ 单调授权升级防护：防止自主 Agent 自行授予写入、破坏性操作或网络权限。授权可以自愿收紧，但放宽需要 operatorSecret。
• 🎯 强化规避防护的引擎：
  • 数据库、操作系统和文件系统原语：阻止 PostgreSQL COPY ... PROGRAM、pg_read_file()、lo_import()；MySQL LOAD DATA INFILE、INTO OUTFILE；SQLite ATTACH DATABASE；以及 SQL Server xp_cmdshell。
  • 无协议 URL 和格式错误 URL 的 SSRF 防护：规范化协议相对地址和无协议端点（169.254.169.254/latest），对无效 URL 严格执行失效关闭拒绝，并在离线授权下阻止直接访问云元数据。
  • 直接 Shell 元数据和网络工具中和：扫描 curl / wget 中不带 URL 协议的直接 IP 引用，并阻止 socat 原始套接字外传通道。
  • 通配符凭据和敏感目录边界：对所有 .env.* 变体（.env.secrets、.env.staging、.env.test）和敏感配置根目录（~/.kube/、~/.docker/、~/.gnupg/、.git-credentials）实施通配符防护。
  • 线性 O(N) 规范化：基于令牌且不使用回溯的花括号展开和有界参数解析，确保对 100KB 以上的载荷也能在亚毫秒内执行。
  • Bash 套接字伪设备拦截：检查 /dev/tcp/HOST/PORT 和 /dev/udp/HOST/PORT 重定向，在 Shell 输入处直接阻止云元数据 SSRF 和隐蔽外传通道。
  • SQL CTE 和过程块拦截：对公用表表达式（WITH ... DELETE）和 PL/pgSQL 匿名块（DO $$ ... $$）实施无界变更防护。
  • 动态链接器劫持防护：中和 LD_PRELOAD、DYLD_INSERT_LIBRARIES 和运行时环境变量劫持。
  • 去除引号和反斜杠：防止拆分令牌规避（r'm' -rf /、r\m -rf /）。
  • 变量间接引用和默认回退：解析 Shell 变量替换（X=rm; $X -rf /）和默认参数展开（${X:-rm} -rf /）。
  • 位置参数和 IFS 规范化：中和 $IFS$9 分词。
  • 双重表示 SQL 分析：防止内联注释规避（DROP/**/TABLE、DR/**/OP 和 # MySQL comment）。
  • 解释器逃逸拦截：递归规范化字符串拼接（'r'+'m'），检查动态导入（import("node:fs")），并解析通过 -c/-e/-r 标志传入 python、node、ruby、perl、php 和 sh 的代码。
  • 自动解码十六进制和 Base64：自动提取、解码并递归评估十六进制（bytes.fromhex(...)）和 Base64 编码的命令载荷。
  • Unicode NFKC 和零宽字符清理：中和提示词注入（S2b）中的不可见字符（\u200B、\u200C、\uFEFF）以及易混淆的全角字符和数学粗体字符越狱内容。
  • IPv4 映射 IPv6 SSRF 转换：将压缩的十六进制 IPv6 表示法（[::ffff:a9fe:a9fe]）转换为规范的点分十进制字节（169.254.169.254）。
  • 百分号编码路径遍历：通过多轮 URL 解码捕获 %2e%2e%2f.env 和 ..%2f.ssh%2fid_rsa。
  • 通用 Fork 炸弹：检测任意函数标识符下递归管道连接的后台进程。
  • SetUID 权限提升：阻止 chmod u+s、chmod 4755 和权限篡改。
  • 永真 SQL 谓词：将 WHERE 1=1、WHERE true 和其他永真条件标记为无界变更。
  • 多态参数检查：对原生工具和无法识别的第三方工具，安全检查字符串、数组和对象，并在无法确定时拒绝。
• 🛡️ 两种运行模式：
  1. 直接防护工具：独立工具（aletheia_set_mandate、aletheia_intercept、aletheia_safe_bash、aletheia_safe_sql）。
  2. 失效关闭透明代理：可包装任意下游 MCP 服务（Postgres、Filesystem、Bash）的中间件，可拦截单个 tools/call 和 JSON-RPC 2.0 批量数组，并严格执行失效关闭边界。
• 📊 实时可观测性资源：通过 aletheia://telemetry/summary 提供实时审计日志、拦截率和延迟分布。
• 🔒 不调用外部 API：关键执行路径上没有 LLM-as-a-judge 延迟。

---

性能基准测试

在连续进行 10,000 次多域评估（Bash 去混淆、SQL 模式验证、路径验证、SSRF 检查、提示词注入）时测得。以下数据来自一次具有代表性的本地运行；p50 在不同运行中保持稳定，p99 会随系统负载变化（观察到的范围约为 24–70 µs），因为它对微秒级的 GC 暂停很敏感；不过，两者都轻松满足亚毫秒目标：

指标	测量值	目标
p50（中位数）	约 0.0085 ms（8.5 µs）	< 0.500 ms
p95 延迟	约 0.0180 ms（18 µs）	< 0.800 ms
p99 延迟	约 0.024–0.070 ms（24–70 µs）	< 1.000 ms
吞吐量	每秒 100,000+ 次评估	> 10,000 / s
热路径外部 API	0（确定性本地引擎）	0

通过 npm run benchmark 在本地运行。 结果会因机器而异；请将具体的微秒数视为“轻松低于毫秒级”的示例，而非精确的 SLA。

如何实际实现微秒级开销

这并非依靠某个单一技巧，而是因为避免了会拖慢速度的因素，并采用了一些经过深思熟虑的实现方式：

1. 热路径中完全没有 LLM。 决策完全由同步、进程内的 JavaScript 做出——没有网络往返，也没有模型推理。这是影响最大的因素：作为裁判的 LLM 调用需要 1.5–3 秒，因为它需要向远程服务发起推理请求；而这里的处理只需微秒，因为它是在本地进行字符串匹配。
2. 正则表达式模式在模块加载时预编译一次，而不是每次调用时重新构建。所有模式列表（DESTRUCTIVE_SIGNATURES、SENSITIVE_PATH_PATTERNS、OBFUSCATION_PATTERNS 等）都是在服务启动时构造的 RegExp 对象，并在进程整个生命周期内重复使用——V8 只会编译一次正则表达式的内部表示，因此每个请求都无需承担重新编译的开销。
3. 输入很短，对其执行的操作也是线性的。 Shell 命令、SQL 查询、路径或 URL 通常只有几十到几百个字符；对这类长度的字符串依次进行十几个正则表达式检查，本质上只需几微秒。（有一次这一假设不成立——一个 O(n²) 规范化步骤在典型输入下没有问题，但处理 100KB 的对抗性负载时耗时 18 秒——这正是提交历史中记录并修复的这类问题；参见已知限制（非穷尽，发现后更新）。）
4. 分派只执行有界的工作，而非穷举检查。 评估器先通过对工具名称进行廉价的子字符串检查，识别工具调用所属的领域（bash、SQL、文件系统、网络），然后只运行该领域的检查——而不是每次调用都运行所有领域的所有检查。
5. 固定大小的簿记数据。 审计日志和延迟历史缓冲区的容量都有上限（分别为 500 和 2,000 条），并通过摊销 O(1) 的操作进行管理，因此服务持续运行时，每次调用的开销不会增加。这一点经过了直接验证，而非假设：连续进行 300 万次评估后，吞吐量仍稳定在约 154,000 次操作/秒，没有出现性能下降趋势。

**如果有人质疑这个精确数字，需要坦诚说明的是：**约 25 µs 是进程内评估函数本身的耗时，直接在该调用前后使用高精度单调时钟测得。它不包括实际 MCP 会话中的 JSON-RPC 序列化或标准输入输出管道 I/O，这些还会带来额外开销。站得住脚的说法是“热路径中没有 LLM，端到端耗时轻松低于毫秒级”，而不是“不管用什么方式测量，耗时都精确为 25 微秒”。

---

生产就绪性与规模测试

除了单元测试套件，这些都是针对实际启动的进程和真实下游 MCP 服务（@modelcontextprotocol/server-filesystem）进行的真实、可复现测试，而非进程内模拟循环。可通过 npm run test:scale:concurrent 和 npm run test:scale:isolation（来源：test/scale-*.mjs）自行运行。

测试	检查内容	结果
持续负载（单个实例，300 万次评估）	长时间运行时的内存增长／吞吐量下降情况，并穿插定期变更授权和读取遥测数据	初始约 50 万次评估的预热后，堆内存稳定在约 8.3MB；整个运行期间持续达到 约 154,000 次评估／秒，且无性能下降趋势
多实例并发（模拟 30 位客户，实际启动的进程）	多组彼此独立的 Aletheia 与下游服务同时运行时的正确性和隔离性	共 4,800 次操作，0 次超时，0 次正确性错误——1,200 次并发的对抗性路径遍历尝试全部被拦截；所有良性写入／回读均匹配正确，且未发生交叉污染
跨客户隔离（定向测试）	Aletheia 自身的 --allowed-paths 边界（而非封装的服务）是否确实能阻止一个实例读取另一个实例的数据	即使特意让下游服务同时访问两个目录，客户 A 仍无法读取客户 B 的普通（非“敏感”）文件；内容泄漏为零
真实场景误报率测试（114 条命令：git、npm/yarn/pnpm、python/pip/poetry、docker/kubectl、make/cargo/maven/gradle、文件操作、访问真实 API 的 curl、常见 SQL）	常规开发工作流是否会被错误拦截	使用建议的 --allow-write --allow-network 配置时，误报为 0（0.00%）
下游崩溃处理	封装的服务在会话中意外崩溃时的行为	约 4ms 内检测到崩溃，正确传递退出代码，且能干净关停，不会卡住或遗留进程（Aletheia 不会自动重启已崩溃的下游服务，而是与其一同退出，与任何 stdio MCP 服务对的行为一致）
Node 版本下限	engines: >=18.0.0 的声明是否属实	完整测试套件（155/155）和针对 server-filesystem 的真实代理会话均已在 Node 18.20.8 上通过验证，而非仅在开发机器的较新版本上通过

这些测试无法替代长期真实且不可预测的使用；它们旨在排除一些可能导致早期真实使用不顺利的特定故障模式（Node 版本不兼容、内存泄漏、误报率过高、实例间相互干扰），而非证明该工具毫无缺陷。

---

快速开始

提示

默认情况下，Aletheia 会完全锁定（只读、无网络、无环回访问），并会有意保持这种状态。 如果你的 Agent 需要写入文件或发起网络请求，请按下文所示，通过 --allow-write／--allow-network／--allow-loopback 预先授予权限（并使用 --allowed-paths 将写入范围限定到某个目录）。这些标志用于设置服务启动时的初始授权，不受 operatorSecret 限制；该限制只适用于在会话运行期间更改授权（例如，Agent 调用 aletheia_set_mandate 来放宽自身权限，这种行为会被有意拦截）。大多数用户需要的是下面的启动标志，而不是 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

添加到你的 claude_desktop_config.json：

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

3. 透明代理模式

使用 Aletheia 安全过滤来封装现有下游 MCP 服务：

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

---

工具参考

工具	模式	注释	描述
aletheia_set_mandate	状态	readOnlyHint: false	建立或收紧操作安全边界。放宽限制需要 operatorSecret。
aletheia_get_mandate	可观测性	readOnlyHint: true	获取当前生效的授权、安全允许路径和风险容忍度。
aletheia_intercept	守门器	readOnlyHint: true	对候选工具调用进行执行前检查。返回 ALLOW 或 BLOCK，并提供违规详情。
aletheia_safe_bash	执行	readOnlyHint: false	经过验证的 Shell 执行器。运行前会拦截 rm -rf、fork 炸弹和数据外泄。
aletheia_safe_sql	审计	readOnlyHint: true	验证 SQL，拦截 DROP、TRUNCATE 和无界 DELETE/UPDATE（包括 WHERE 1=1）。
aletheia_get_telemetry	可观测性	readOnlyHint: true	输出评估计数、拦截率百分比和微秒级延迟百分位数。

---

资源与提示词参考

资源（resources/read）

客户端可以通过标准 MCP resources/read 按需检查服务状态：

• aletheia://telemetry/summary：实时评估计数器、拦截率百分比和微秒级延迟分布。
• aletheia://telemetry/audit-log：最近 50 次工具放行请求的滚动日志，包含输入、判定结果、违规特征和时间戳。
• aletheia://mandate/current：当前会话的授权参数、允许的工具列表、路径边界和权限开关。
• aletheia://signatures/s3：Signature S3（范围蔓延）的规范、风险分类和基准测试失败率数据。

提示词（prompts/get）

• aletheia_mandate_enforcer：系统提示词指令，用于设定操作安全边界，并指示 Agent 在执行高风险操作前先通过 Aletheia 进行检查。接受 task_description（必需）、workspace_root（可选）和 allow_write（可选）。

---

架构

                    ┌───────────────────────────────────────────────┐
                    │          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)

---

研究出处与实证语料库

Aletheia MCP 由 Vikas Shivpuriya 开发，是更广泛的 Aletheia AI Safety Research Core 的一部分。其底层行为失效特征的设计依据，来自 AI Incident Database（AIID）、AVID AI Vulnerability Database 和 MIT AI Risk Repository 中记录的事件。文中提及的前沿系统（Claude Sonnet 4.6、GPT-4o、Gemini 2.5 Flash）各自的检测率，来自该论文的评估框架；应将其视为说明 Signature S3 为何重要的方向性背景，而非对该代码库的可验证基准测试。Signature S2b 尚未纳入该实证评估——论文将其留待未来研究，因此应将此服务的 S2b 过滤器视为受该分类体系启发的独立实用启发式方法，而非经论文自身研究结果验证的实现。

本代码库中可独立验证的内容包括：测试套件（npm test）、延迟基准测试（npm run benchmark），以及记录每轮对抗性测试及其修复结果的提交历史。

• 研究论文与分类体系：github.com/vikasny30/aletheia-paper
• 许可证：Apache 2.0