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 回答全部四个：

追踪工具告诉你「凌晨 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 给这三类各配一招：

# 外发：默认扣留，不发出去
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 / 你自己的模型端点）也可以，接进去做更细的意图判断——但默认值必须是不依赖外部服务的。

安全设计：它自己不会变成新的泄露面

一个保护数据的东西，如果自己明文存了数据，就成了新的漏洞。所以：

⚠️ 诚实边界：如果 Agent 有全盘读写权限，它也能读到密钥、也能改任何文件—— 没有任何本地方案防得住这个。 TraceGuard 防的是「手滑、意外、以及每步都合法的组合攻击」， 不是「有全盘权限的对手」。请按这个定位使用它。

安装

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）

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

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")   # 第三方可独立复核

三种模式

合规与安全

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

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

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

商业版（TraceGuard Pro）

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

未持有效授权时，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.