浏览示例 →

直接体验 9 份签名回放，查看执行图谱、Agent 会话、访问控制决策和文件正文。 无需安装、注册或 API Key。

AgentProvenance

Agent 实际做了什么？从任务到文件和网络，一路追溯。

记录 Agent 的任务、对话和工具调用，关联它启动的进程、修改的文件与访问的网络。 查看执行过程，追溯产物来源，比较两次执行，再导出可离线验证的证据。

Release Go CI Sensor SQLite License

在线 Demo | 快速开始 | 核心能力 | Agent 会话 | 演示 | 架构 | 文档

English | 简体中文

用类似 Git 的方式追溯 Agent 执行：记录 → 查看行为 → 追溯产物 → 比较执行 → 导出验证。

AgentProvenance 把任务要求、工具返回结果和操作系统中的实际行为放到一起。 任务为什么失败、文件被谁改了、某次网络连接从何而来，都可以沿证据追查； 同一份记录也可以交给安全分析器或外部评估器使用。

核心能力

可以用它调试 Coding Agent、审查生成的产物、调查异常行为，也可以为评测和审计提供执行依据。

本页内容：快速开始 · 证据模型 · Agent 会话 · 可视化界面 · 演示 · 运行时采集 · 安全分析与外部评估 · 架构 · 文档导航

快速开始

先回放一次真实执行

打开在线 Demo，直接在浏览器里查看 图谱、Agent 会话和文件正文，无需安装。同一站点也收录了示例图文说明和使用指南。

需要离线回放时，下载 CLI：

在发行页下载对应平台的 压缩包和同名 .sha256 校验文件。下载示例使用 v0.10.0， 包含下文的调查与修复示例，详情见版本进展。

以 Linux x86-64 为例，下载后校验并解压：

sha256sum -c agentprov_v0.10.0_linux_amd64.tar.gz.sha256
mkdir agentprov-demo
tar -xzf agentprov_v0.10.0_linux_amd64.tar.gz -C agentprov-demo
cd agentprov-demo
./agentprov demo

macOS 使用对应的 darwin 包，并将校验命令换为 shasum -a 256 -c。 Windows 用户在 WSL 中运行 Linux 包。回放可以离线使用， 无需 Go、Docker、Agent 账号或 API Key。

点击打开回放查看签名执行记录，点击阅读指南查看图文说明。 当前示例库共有 9 份签名回放、11 篇示例指南。建议先体验调查与修复流程：

./agentprov demo investigation-workflow
./agentprov demo deepseek-context
./agentprov demo multiagent-provenance
./agentprov demo --list

CLI 校验签名后，用独立的临时目录打开可视化界面。按 Ctrl-C 退出时清理该目录， 不会重新运行记录中的命令。无图形界面或远程机器可添加 --no-browser， 通过端口转发访问输出的本地地址。

如需构建当前源码，先安装 Go 1.23+，再从仓库根目录运行：

go build -o agentprov ./cmd/agentprov
./agentprov demo

全部示例 · 发行包使用指南

记录你自己的 Agent

先安装并登录你使用的 Agent，然后执行：

./agentprov doctor -- claude
./agentprov launch --file-diff -- claude

doctor 检查本机的采集环境。launch 启动 Agent 和可视化界面， 在 Agent 退出后整理会话记录。--file-diff 同时保存工作区变化和变更文件的最终正文。 Claude 使用仅对本次运行生效的 Hooks 配置，保留你的日常设置。

Codex 和 DeepSeek Harness 使用同样的入口：

./agentprov launch --file-diff -- codex
./agentprov launch --file-diff -- dsh headless --json 'Inspect the project and run its tests.'

Linux eBPF 采集需要传感器、受支持的内核和 BPF/perf 权限。 Agent 上下文默认使用详细档。给 launch 添加 --capture basic，可减少补充上下文的留存。 内核、TLS 和工作区采集仍可独立配置。 macOS 支持应用侧记录和回放。自定义会话目录、续跑及格式支持范围， 见 Agent 会话指南。

记录普通命令

不接入 Agent，也可以先记录一条命令：

mkdir -p /tmp/agentprov-record-demo
./agentprov record --run run-record-demo --workdir /tmp/agentprov-record-demo -- \
  sh -c 'echo artifact > artifact.txt'
./agentprov observe summary --run run-record-demo
./agentprov graph explain --run run-record-demo --file artifact.txt

record 保存命令、进程采样和工作区变化。运行 Linux 传感器后，可以加入内核事件； 接入受支持的会话适配器后，可以补充 Agent 上下文。本地记录和回放无需 Docker。

查看行为、追溯产物、导出证据

每次执行都有一个 Run ID。将下面的 ID 替换为记录完成后输出的值：

./agentprov observe summary --run RUN_ID
./agentprov graph explain --run RUN_ID --file path/to/artifact
./agentprov graph diff --run RUN_ID --file path/to/artifact
./agentprov graph blame --run RUN_ID --file path/to/artifact
./agentprov context coverage --run RUN_ID
./agentprov graph verify --run RUN_ID
./agentprov forensics export RUN_ID

在可视化界面中，可以从工具调用定位到运行时事件、打开已保存的文件正文， 也可以比较不同时间的任务或配置。执行差异和产物来源查询见证据图命令。 如需给执行记录签名，在记录时添加 --sign-key；签名默认关闭。

核心模型

会话记录说明 Agent 接到了什么任务、调用了什么工具；运行时遥测记录进程、文件和网络中的实际行为。 AgentProvenance 再把这些信息与文件变化、最终产物关联起来：

任务 / 对话 / Agent 委派
  → 工具调用
    → 进程与子进程
      → 文件访问 / 网络连接 / 运行时事件
        → 文件变化 / 产物 / 证据对象

关联依据包括进程身份、cgroup、容器、工作目录、时间范围和已记录的工具标识， 不要求原始内核事件带有 tool_call_id。推断关系保留依据和置信度； 上下文缺失或归属不明确时，也会在结果中体现。

证据对象保存内容哈希和父引用。校验检查对象及其关联；可选签名让接收者能够用签名公钥验证证据包。 模型意图指采集到的消息和动作声明，不代表能读取模型内部的思考过程。

完整证据模型 · 关联与证据图查询

Agent 会话

任务、对话和执行证据在同一页面阅读。执行图谱在上，Agent 会话在下，默认收起。

支持的 Agent

支持显式指定自定义目录和续跑会话。增量导入保留来源位置，对重复记录去重； 任务与配置快照可以在同一次执行内或跨执行比较。 具体测试版本和日志格式见兼容性表。

会话在 Agent 退出后整理。权限历史保存日志中实际记录的内容，缺少审批决定时显示“未记录”。 采集报告说明缺口，图谱与签名校验则分别检查相应的证据完整性。

体验 DeepSeek 示例 · 会话命令与 API

可视化界面

可视化界面把执行图谱、时间线、进程树、网络活动、风险信号和已保存的证据放在一起，方便沿线索追查。

查看自己的执行记录：

./agentprov dashboard serve

本地界面的页面资源内置于 CLI，无需外部网页服务。在线 Demo 可只读浏览公开示例。 面对大量事件，界面先展示汇总关系，再按需展开详情，避免把全部原始事件堆在一张图里。

演示

调查失败，再比较修复结果

一个真实 DeepSeek 会话完成两次执行：委派代码审查、运行七项测试、发现可选诊断被拒绝， 再关闭多余诊断，成功生成报表。沿父子会话查看协作，搜索具体报错，检查 AppArmor/seccomp 记录，对比文件变化，最后选择证据导出只读回放。

在当前源码目录中运行：

go build -o agentprov ./cmd/agentprov
./agentprov demo investigation-workflow

命令会同时加载两份签名记录。在对比中，将 A 设为诊断修复 · 修复前， 将 B 设为诊断修复 · 修复后。在文件证据中查看 settings.json 和生成的报表； 配置维度展示 Harness 设置。查看完整调查路线。

追踪一次多 Agent 协作

一个 Agent 委派任务，协作消息引导另一个 Agent 安装被投毒的依赖。 沿消息和工具调用，可以追踪到这次执行对应的文件读取与网络连接； 记录中也保留了此前一次被拒绝的动作。

./agentprov demo multiagent-provenance

查看完整调查过程。共享进程中的 Agent 归属， 依据已记录的 Hooks 和命令证据进行推断。

追踪跨 Pod 执行

一个节点传感器采集两个 Pod 的行为，保留各自的 cgroup 身份与 Kubernetes 元数据。 可以在同一张图里查看工作负载位置、跨 Pod 连接和执行端的运行时活动。

./agentprov demo k8s-cross-pod-a2a

网络与系统调用来自实机采集，委派 Hooks 复用了多 Agent 示例的记录。 示例指南说明了这些来源如何关联。

全部示例

9 份签名回放均可离线体验。LLM Judge 和 Jev 是可选集成指南， 实时评估需要按各自说明配置模型服务。Grok 示例是有明确采集时间和复现范围的历史记录， 不代表其当前服务的行为。

运行时采集

原生传感器支持 Linux amd64、arm64 的进程、文件和网络事件采集。 可部署在 Linux 主机、KVM 虚拟机内部，或 Kubernetes/K3s 节点上。 Pod 元数据用于识别工作负载；事件先于绑定到达时，通过磁盘缓冲和补关联保留证据。 能力报告逐项说明当前环境可用的系统调用、DNS 和 TLS 采集路径。

KVM/K3s 部署与 TLS 支持 · 持久化采集 · Kubernetes 事件归属

TLS 自动发现会跟踪受支持的 OpenSSL 库和 Go 二进制，也会处理容器重建后的目标变化。 Go TLS 响应采集目前支持 amd64、有符号信息的 Go 1.23–1.26 二进制。 ARM64 Go 响应采集、BoringSSL 和任意自定义 TLS 实现尚未覆盖。 实际挂载了哪些探针，可查看当前机器的能力报告。

部署方式

传感器部署在需要观测的 Linux 主机或虚拟机内部。AgentProvenance 使用已有的运行与编排环境， 不负责创建虚拟机或替代 Kubernetes。Falco/Tetragon 接收器保留兼容支持； 中心化、多租户的证据服务仍属于后续设计。

安全分析与外部评估

通过策略和行为基线，检查异常凭据访问、网络外发和进程活动。 证据图把风险关联到工具、进程与产物，数据流视图展示可能的敏感数据传播路径。 意图比较可以检查声明动作与实际行为之间的差异，包括已经拒绝、却仍发生的动作。

./agentprov security risks --run RUN_ID
./agentprov policy decisions --run RUN_ID
./agentprov security responses --run RUN_ID
./agentprov intent diff --run RUN_ID

阻断通过对应的策略门禁或响应集成生效，决策和响应历史记录要求采取的动作与实际结果。 导入历史证据不会阻断已经完成的操作。OWASP Agentic 和 NIST 映射则说明哪些控制项有证据支持， 哪些地方仍有缺口。

外部评估器可以读取执行轨迹、评分，再将带有证据引用的信号写回。 LLM Judge 和 Jev 提供了这种接入示例；具体评分与奖励规则由评测或训练系统决定。

./agentprov signal context --run RUN_ID
./agentprov ai tools --provider openai
./agentprov ai mcp

其他工具可通过 CLI/JSON、HTTP API、Python SDK 或 MCP 使用证据。 MCP 还提供动作预检和显式上下文写入；写入 Agent 上下文不会执行动作或生成内核遥测。

安全命令 · 合规映射 · AI 工具与 MCP · Python SDK

架构

1. 采集会话日志、Hooks、命令与文件变化，以及运行时事件。
2. 统一格式并关联归属，识别对应的执行、工具范围、进程和工作负载； 进行敏感信息脱敏，并按配置对事件流做缓冲。
3. 保存证据到 SQLite 和内容寻址对象，保留来源标识、历史版本及推断关系的依据。
4. 查询与交换，通过图谱、时间线、CLI、API、签名包和只读回放使用证据； 安全规则与外部评估器把结论关联回相应记录。

默认部署由本地 CLI / 服务和可选的高权限传感器组成，无需搭建云端控制平台。

类 Git 溯源用于查看历史、比较差异、追查来源和校验证据，不会撤销已发生的外部操作。 哈希和签名检查已保存的记录，采集报告另行说明实际观察到什么、遗漏了什么。

完整架构与仓库结构 · 与其他系统的关系

功能与文档

新增会话区域与原有时间线、进程树、网络、风险信号、数据流和规则覆盖视图一起使用。 安全分析与外部评估器读取同一份执行证据。

网页首次打开时跟随浏览器语言，其他语言回退到英文；手动切换后保留选择。 CLI 和工具输出默认英文，原始证据不翻译。

版本进展

v0.10.0 把关联会话、正文搜索、执行对比和选择性离线分享 串成完整的调查流程，并接入 AppArmor、seccomp 的访问控制记录。 采集支持基础档和详细档，用户可以按需要选择 Agent 上下文的留存范围。

后续暂不新增功能，重点提升准确性、采集稳定性和使用体验。

升级前请备份数据目录；升级后的数据库不支持直接用旧版程序打开。 macOS 包尚未经过 Apple 公证；下载校验和用于检查压缩包完整性。

发行说明 · 变更记录 · 后续方向

开发

go test -race ./...
go vet ./...
gofmt -l internal cmd

# 可在本地运行的端到端证据与验证冒烟测试。
./scripts/accept_phase1.sh

CI运行上述检查，并验证 Linux amd64/arm64 静态构建、 原生 eBPF 绑定文件是否与源代码一致、本地服务在故障时的就绪状态，以及 Go 1.23–1.26 下的 amd64 系统调用、OpenSSL 和 Go TLS 采集。 ARM64 实机与 KVM/K3s 实验环境的验收结果另有报告，不等同于托管 CI 的覆盖范围。

各验收脚本的环境要求不同。部分脚本需要 root、会创建 Pod 或安装服务， 请勿直接批量执行全部 scripts/accept_*.sh。 环境测试请按 KVM/K3s 部署指南操作， 单节点压力测试见部署与性能基线。

作者与许可

由 ByteYellow 开发和维护。

采用 Apache License 2.0 许可证，详见 LICENSE。 Copyright 2026 ByteYellow。

本文为 README.md 的中文说明；如有内容差异，以英文版为准。