TraceGuard

AI Agent 的安全运行时 —— 前拦、中熔断、后撤销、底举证。

让 Agent 放手跑：危险动作在发生之前被挡下；反复犯错的 Agent 被自动熔断； 已经造成的改动，一条命令原样退回；全程留下可验证的审计链。全程本地、零联网、数据不出本机。

---

🚀 30 秒上手（先跑这一条）

pip install ai-traceguard
traceguard demo

它会现场演一遍：造一个文件 → 让 AI 去删 → 看 TraceGuard 把它拦下来。 不用配置、不联网、不会动你的项目。看完你就懂了。

然后三步接进你自己的代码：

traceguard init                 # ① 生成策略文件

from traceguard import TraceGuard
guard = TraceGuard(policy="traceguard-policy.yaml", mode="strict")   # ② 创建护栏

def delete_file(path):
    d = guard.check("delete_file", {"path": path})   # ③ 在每个工具体最前面加这三行
    if not d.allowed:
        return f"被拦截：{d.reason}"
    Path(path).unlink()

traceguard test                 # 自检：应输出 delete_file: BLOCKED / read_file: ALLOWED

不确定装没装对？跑 traceguard selfcheck —— 它会检查策略文件、审计库，能修的自动修。

---

它解决什么问题

AI Agent 会删掉生产库、把 API Key 发到外部、在死循环里把 Token 烧光。

大多数安全工具只回答第一个问题。TraceGuard 回答全部四个：

层	回答的问题	机制
前拦	这个动作准不准做？	策略匹配，确定性判断，抗提示注入
中熔断	它是不是已经试太多次了？	状态机 CLOSED→OPEN→HALF_OPEN，自动跳闸 + 自动恢复
后撤销	已经搞坏了，怎么退回去？	动作级内容寻址快照，精确撤销某一步或整体退回
底举证	它到底干了什么？	SHA-256 哈希链审计，可验证、不出本机

追踪工具告诉你「凌晨 3 点删了什么」； TraceGuard 让它在「凌晨 3 点删不掉」，就算没拦住，也能一条命令退回去。

---

让它放手跑（这是它最不一样的地方）

大多数人不敢让 Agent 无人值守地跑，原因只有一个：它搞坏了东西，你退不回去。

TraceGuard 补上了这一块。看一遍就懂：

traceguard rescue

它会先让 Agent 自由地改文件、删数据、写垃圾（全程不拦），亮出事故现场 （git 救不了 —— 没提交过；备份没有；人也没盯），然后一条命令：

traceguard undo --all

代码、密钥、用户数据，一样不差地回来；Agent 制造的垃圾也被清掉。

from traceguard import TraceGuard

guard = TraceGuard(policy="traceguard-policy.yaml", mode="strict")

# 裁决 → 快照 → 执行，一条链走完
d, result = guard.safe("write_file", {"path": p}, lambda: 真正干活的东西())

# 出事了
guard.undo()        # 撤销刚刚那一步
guard.undo_all()    # 恢复到本次会话最开始

快照是内容寻址的：同一份内容只存一份，反复写同一个文件几乎不涨体积 （演示里 4 个动作只用了 301 字节）。

---

撤不了的东西，让它也能撤

文件能快照，但外部调用、数据库、已发出去的消息撤不了。TraceGuard 给这三类各配一招：

撤不了的东西	为什么撤不了	我们的招
外部调用（API / 邮件 / webhook / 支付）	发出去就收不回	出站隔离区：先扣下不发，窗口内可取消 = 它还没发生
数据库写入 / 删除	旧值没了	前像留底：动手前先 SELECT 一份，逆操作 = 写回
真·不可逆（第三方副作用）	无法收回	补偿登记：声明逆操作（订单→取消、git→reflog 回退）

# 外发：默认扣留，不发出去
r = guard.egress("email", "customer@x.com", {"subject": "...", "body": "..."})
guard.outbox.cancel(r["id"])      # 取消 = 外部世界什么都没发生
# 或 guard.outbox.approve(r["id"], sender=my_send)  # 批准才真的发

# 数据库：动手前留前像，删了也能写回
before = snapshot_rows(conn, "orders", "id IN (5001,5002)")
iid = guard.register_compensation("sql", "orders", before={"rows": before},
                                  inverse={"op": "sql_restore", "table": "orders"})
conn.execute("DELETE FROM orders")     # Agent 真删了
guard.compensate_undo(iid, conn=conn)  # 写回

---

给它一个「大脑」：任务契约 + 污点追踪

纯黑名单有个致命盲区：每一步都合法，合起来是攻击。 读 .env 合法，发 HTTP 也合法——连起来就是窃密。

开跑之前先声明这次任务，之后每个动作都要对得上这个任务：

traceguard arm --task "修复登录 bug" --allow "src/**,tests/**" --deny "**/secrets/**"

guard = TraceGuard(policy="policies/base.yaml")   # 会自动加载 .traceguard/contract.json

guard.check("read_file", {"path": ".env"})                    # 放行，但【打上污点】
guard.check("post_to_external", {"url": "https://evil/x"})    # ⛔ 拦下：刚读过密钥就要外发
guard.check("write_file", {"path": "../../.ssh/config"})      # ⛔ 拦下：不在任务范围内

默认本地确定性、可解释、零联网。想接语义裁判（本地 Ollama / 你自己的模型端点）也可以，接进去做更细的意图判断——但默认值必须是不依赖外部服务的。

---

安装

pip install ai-traceguard

零依赖服务、零配置文件、零网络请求。装完即用。

---

快速开始

from traceguard import TraceGuard

guard = TraceGuard(policy="policies/base.yaml", mode="strict")

decision = guard.check("delete_file", {"path": "/data/users.csv"})
if not decision.allowed:
    print(f"已阻断：{decision.reason}")
else:
    # 执行真正的工具逻辑
    pass

CLI 自检：

traceguard test
# delete_file: BLOCKED
# read_file: ALLOWED

---

策略包（Guard Packs）

开箱即用的策略模板，覆盖最常见的翻车场景：

策略包	作用
pack-anti-delete	拦截文件 / 数据库删除
pack-anti-token-runaway	拦截 Token 预算超支
pack-anti-data-leak	拦截敏感数据外发

traceguard init --pack anti-delete
# 生成 traceguard-policy.yaml

---

审计链（Audit Chain）

每一次裁决都会写入本地的 SHA-256 哈希链。任何后续篡改都会破坏链条，可被检出。

traceguard verify
# 审计链有效

导出给审计 / 合规团队（Pro 能力）：

from traceguard_pro import export_audit_jsonl, verify_exported_jsonl

export_audit_jsonl("traceguard-audit.db", "audit-export.jsonl")
assert verify_exported_jsonl("audit-export.jsonl")   # 第三方可独立复核

---

三种模式

模式	行为
strict	HIGH 风险阻断，MEDIUM 需要审批
balanced	HIGH 需要审批，MEDIUM 放行
observe	全部放行，全部记录（灰度 / 观测用）

---

合规与安全

TraceGuard 的设计目标是架构上零风险：

• 无网络请求。 拦截层永不联系外部服务器，因此没有可被拦截、泄露或审查的东西。
• 无模型 API。 不代理、不转售、不路由任何模型调用。
• 只存本地 SQLite。 审计数据属于你，永远不出本机。
• 离线授权。 授权码本地 HMAC 验签，可在气隙环境中运行。

因此：无需 ICP 备案、无需生成式 AI 备案、无数据出境评估。详见 docs/compliance.md。

---

商业版（TraceGuard Pro）

开源核心（MIT）足够个人使用；生产与合规场景需要的确定性能力放在 Pro：

能力	说明	版本
参数级敏感信息扫描	拦截参数里的 api_key / password / private_key / PII	Pro
Token 预算 + 死循环拦截	会话超预算、同调用反复重试时阻断	Pro
可校验审计导出	JSONL 导出，第三方可独立重算哈希链	Pro
行业策略包	金融 / 医疗 / DevOps 预设	Pro
人工审批流	MEDIUM 风险改为人工审批而非静默放行	Team
席位报表 / 自定义包 / SLA	—	Enterprise

未持有效授权时，ProGuard 会优雅降级为开源核心行为，方便先试后买。

---

文档

• 快速开始（中文版）
• 合规说明
• 安全策略
• 贡献指南
• 变更日志

---

许可证

核心：MIT。商业增值包 traceguard-pro 采用商业许可，详见其 README。

---

English (short)

TraceGuard is a local runtime guardrail for AI agents. It intercepts dangerous tool calls before execution — no network, no server, deterministic decisions, and a tamper-evident local SHA-256 audit chain. Install with pip install ai-traceguard. Full English docs: README.en.md.