功能与架构参考

English | 中文

这里汇总证据模型、进阶命令、部署方式和架构。首次使用请从快速开始进入。 会话、配置、搜索、对比和采集设置见 Agent 会话指南。

安全闭环

安全分析围绕以下链路展开：

application context   应用上下文
  run / trajectory / execution_scope / tool_call / user / task / workspace

system telemetry      系统遥测
  process / file / network / resource / sandbox / eBPF event

correlation           关联
  container_id / cgroup_id / pid / ppid / cwd / timestamp / file diff

security analysis     安全分析
  behavior baseline / suspicious event / taint lineage / risk decision

response              响应
  audit / deny / kill / quarantine / taint / forensics

传统主机监控关注“这个进程做了什么”。AgentProvenance 在此基础上补充 Agent、任务和工具调用的上下文，进一步回答：“这次行为属于哪个任务？ 改变了什么？判断依据是什么？是否需要响应？”

当前已实现证据图、运行时关联、diff/blame、遥测批次清单、策略判定、 风险与基线偏差信号、响应记录、污点标记、隔离、取证导出和原生 eBPF 传感器。 暂不扩展飞书、钉钉等通知适配器；Falco、Tetragon 接收器保留兼容性维护。

核心模型

证据采用内容寻址存储，通过哈希校验完整性，并支持可选的数字签名。 这里的 Git-like 执行溯源，指的是对执行记录进行比较、追溯和回放； 不包含 Git 分支合并、检出，也不支持撤销已经发生的外部操作。

最基本的用法，是用 record 启动你原本就要运行的命令：

agentprov record -- <agent command>

record 记录执行前后的文件状态，运行命令并采样进程树，将这些证据写入 有向无环图（DAG），无需在应用中接入 SDK。 在此基础上，可以通过受支持的 Hook、会话记录适配器或自定义上下文来源补充 应用信息；内核事件则由运行中的传感器采集。可用的证据会汇入同一份执行记录。

证据分层

运行时证据说明“实际发生了什么”，应用上下文帮助回答“属于哪个 Agent、 哪次工具调用、什么任务”。例如，编排器的 agent_spawn、agent_message 关系，以及模型拒绝执行某个动作，都无法仅靠系统调用推断出来。

应用上下文是可选的补充。运行框架可以通过 Hooks 或 MCP 接口提供这些信息， 并关联到同一次执行；缺少这类信息时，已有的运行时记录仍可独立查询。

运行时事实与关联

关联引擎根据以下运行信息，将事件归属到相应的执行上下文：

root process / process tree / cwd / timestamp / container_id / cgroup_id
  / file diff / artifact refs

内核事件通常只包含 PID、cgroup、命名空间、容器 ID、时间戳和进程树信息， 无需携带应用侧的 tool_call_id。AgentProvenance 使用这些关联信息， 将系统事件与任务、执行作用域和工具调用连接起来。

也可以通过 CLI 显式建立绑定：

agentprov telemetry bind --run <run_id> --substrate-scope <substrate_scope_id> \
  --execution-scope <execution_scope_id> --tool-call <tool_call_id> --process <process_id> \
  --container-id <container_id> --cgroup-id <cgroup_id> --pid <pid>

建立绑定后，即可导入不含 tool_call_id 的原始事件：

agentprov telemetry ingest --raw-event raw-execve-1 --pid <pid> \
  --timestamp <event_time> --source tetragon_jsonl --type execve \
  --payload '{"argv":["./async_child.sh"]}'
agentprov telemetry ingest-jsonl --format tetragon --file tetragon-events.jsonl
agentprov telemetry ingest-jsonl --format native --file agentprov-sensor-events.jsonl
agentprov telemetry ingest-falco --file falco-events.jsonl

ingest-jsonl 会生成遥测批次清单，记录输入文件哈希、映射后的事件 ID 及其哈希、 接收摘要和逐行处理结果，便于追溯一批数据的来源与处理过程。 默认还会对导入的事件执行策略评估：访问云元数据地址、内网地址或敏感路径等事件， 可产生 policy_decisions、risk_signals、response_actions 及相应的图关系和时间线记录。 如果只需规范化和存储事件，可使用 --no-policy。

原生 eBPF 传感器（cmd/agentprov-sensor，source="agentprov_ebpf"）输出的 native 格式会被自动识别。它采集的进程执行、网络连接和文件访问事件， 与第三方遥测共用关联、策略、风险和统一信号处理流程。 文件事件可以保留宿主机上的绝对路径，例如 /home/agent/.aws/credentials， 并接受路径规则检查；工作区文件节点则使用相对路径。 scripts/accept_native_sensor_risk.sh 验证了从原生采集到 security 信号的完整链路。

已有 Falco 的主机也可使用 ingest-falco，将 Falco 的 JSON/stdout 输出接入 同一流程。用法见 Falco 接收器说明。

与现有系统的关系

AgentProvenance 可以接收系统可观测性工具和沙箱提供的数据，也可以与 LLM 调用追踪平台配合使用。各自关注的重点如下：

核心链路是：

系统运行记录 + Agent 应用上下文
  -> 可验证的执行证据图
  -> 安全分析与风险判定
  -> 响应记录与审计追溯

意图一致性

意图一致性分析比较声明要执行的操作与实际观测到的行为。 除了关联“哪个模型调用引发了这次操作”，它还检查行为是否超出声明范围， 以及被拒绝的动作是否仍然发生。

agentprov intent diff --run <run_id>

每份 **IntentContract（意图契约）**记录一次工具调用、Agent 间消息或拒绝决策 所允许和禁止的行为。系统将它与归属到同一作用域的 RuntimeEffects（运行时行为） 进行比较，输出以下结果：

判定以具体操作的声明范围为依据。例如，网络连接可能超出只读文件工具的职责， 却属于 bash 的可用能力；读取未声明的敏感凭证也可能构成偏差。 Agent 正常读取自身凭证的情况，则由同一套策略引擎中的相应规则识别。

结果写入统一信号模型的 intent_conformance 维度，可影响 launch 的最终判断， 并在 Conformance · declared vs actual 视图中展示“声明 → 判定 → 观测行为”。 多 Agent 示例中，alice 诱导 bob 安装恶意依赖，相关偏差被标记为 peer_message_intent_mismatch。

部署模式

目前可以使用单机 CLI 或本地服务两种部署方式；中心化证据服务还处于设计阶段。 本地开发、基准测试、评估器和 RL 流水线通常可以从 CLI 开始。 需要持续接收事件、共享本机查询接口时，再使用本地服务。

本地服务的磁盘缓冲队列（spool）同时限制批次数、总字节数和单批大小， 并通过 telemetry producer-health 报告背压、丢弃和关联覆盖情况。 scripts/accept_telemetry_100k_pressure.sh 生成包含吞吐量、延迟、资源占用、 队列状态和覆盖率的机器可读报告。参考测试接收了全部 10 万条事件，没有失败或 丢弃的批次，健康检查和分页事件查询也能正常响应。 这是单节点 SQLite 基准，不代表生产环境 SLA。具体范围见 收尾标准和中心化服务设计。

Kubernetes 验收会部署特权传感器 DaemonSet，启动多个独立 Pod， 将 Pod、容器身份与内核 cgroup 对应起来，再导入并验证采集结果。 2026-08-05 的 ARM64 K3s 实验使用了 8 个 BusyBox Pod，识别到 8 个独立 cgroup， 记录 1,140 条事件，graph verify 无错误、无告警。 该结果验证了单个节点传感器同时观测多个工作负载的能力，不是集群吞吐量测试。

同一负载还通过了不同采集模式的语义一致性验收：主动启动的 local-record 与被动采集的 k8s-daemonset 均通过证据校验，且记录了相同的负载命令、execve 证据、运行时事件节点和“进程 → 事件”关系。比较不要求 PID、cgroup、容器标识 或事件数量相同，各模式的关联置信度也分别保留。

可通过 agentprov sandbox profiles（支持 --json）查看采集模式及其验证状态。 标记为 planned 的模式在通过真实环境验收前，作用域置信度和采集覆盖率均为零。

另一个轻量 DaemonSet 运行 agentprov sandbox watch，负责维护事件归属： 它使用 client-go informer 监听本节点 Pod，将运行中的容器映射到内核遥测使用的 cgroup inode，并在容器重启、Pod 删除后更新绑定。所需 RBAC 权限仅为 Pod 的 get/list/watch，事件采集仍由独立传感器负责。 K3s 生命周期验收记录了 1 次重启、2 次绑定创建和 2 次绑定关闭， 结束时无活跃绑定残留或解析失败。这验证了节点内的绑定维护，不代表完整的 Kubernetes Operator 或集群控制能力。

AGENTPROV=/path/to/linux/agentprov \
SENSOR=/path/to/linux/agentprov-sensor \
AGENTPROV_MULTIWORKLOAD_REPORT=/tmp/agentprov-k8s-multiworkload.json \
  ./scripts/accept_k8s_node_multiworkload.sh

AGENTPROV=/path/to/linux/agentprov \
AGENTPROV_K8S_INFORMER_REPORT=/tmp/agentprov-k8s-informer.json \
  ./scripts/accept_k8s_informer_controller.sh

RL 和评估流水线可以采用轻量的离线工作流：

• 安装：下载一个可执行文件；需要 Python 接口时再安装辅助库。
• 接入：用 record 启动已有命令。受支持的 launch 配置、Hook 和会话记录 适配器可补充应用上下文；自定义集成也可通过 MCP 写入上下文。
• 批量处理：每条轨迹都有 run_id、证据清单和评估上下文，查询接口支持分页。
• 采集范围：默认记录进程、文件变化、产物、退出状态和资源信息； 更详细的 eBPF 或第三方遥测按需启用。
• 职责划分：AgentProvenance 提供证据、偏差、风险和轨迹信号； 奖励、排序、数据集管理和轨迹筛选由 RL 系统决定。
• 安全策略：拒绝、终止和隔离属于可选控制。离线评估可以在执行结束后， 直接读取 EvalContext JSONL，不要求启用这些控制。

EvalContext、EvalSignal 协议及 Python 自定义规则的用法，见 外部评估器协议。

安全证据命令

以下命令用于查看一次执行中的证据、风险和响应。 查询结果支持 --json，并提供相应的结果集或分页完整性信息：

./agentprov observe summary --run <run_id>       # 覆盖率：应用上下文、遥测、风险、响应
./agentprov observe flow --run <run_id>          # 运行时事件 -> 风险 -> 策略 -> 响应
./agentprov timeline --run <run_id> --view causality
./agentprov security risks --run <run_id>        # 另有：deviations / responses
./agentprov baseline learn --template <t> --run <run_id>   # 然后：baseline check
./agentprov policy test examples/events/metadata-egress.jsonl
./agentprov forensics export <run_id>            # 带哈希、可选签名的审计包

• observe summary/coverage/scopes/event/process/flow：查看执行概况，或按作用域、 事件、进程进一步排查。
• evidence manifest / telemetry correlations：查看带哈希索引的证据目录， 以及每条事件的归属依据。
• security risks/deviations/responses + baseline learn/check：基于关联后的证据 查看风险、基线偏差和响应记录。
• policy test/decisions：测试策略规则、查看策略判定。
• forensics export[-batch]：导出可审计的证据包。

完整命令列表及每条命令的用途： docs/security-commands.md。

外部评估器协议

AgentProvenance 为外部评分系统提供证据，奖励函数、排序和数据集策略仍由 外部系统管理。

./agentprov signal context --run <run_id> > eval-context.json

./agentprov signal run --run <run_id> \
  --external "PYTHONPATH=python python3 examples/evaluators/python_signal_eval.py" \
  --json

./agentprov signal import --run <run_id> --file external-signals.json --json

协议包含以下内容：

• EvalContext 包含轨迹、文件变更、运行时事件、风险信号和响应动作。
• 外部评估器从 stdin 读取 EvalContext，返回 { "signals": [...] }。
• EvalSignal 可以表示奖励特征、惩罚、数据集标签或质量信号。
• signal import-batch 接受 JSONL 格式的 EvalReport 记录，这样 RL 流水线 可以一次导入多条轨迹的离线评估结果。

基准测试、RL、红队测试和数据筛选流程可以自行决定，如何根据这些证据评分、 拒绝结果或发起人工复核。

可选参考实现：LLM 安全评估示例和 Jev 结构化评估器。模型服务调用、规则对比和复核页面由这些 外部示例提供，采集、回放和主可视化界面都不依赖它们。 分析结果通过已有的信号接口写回。

用 Python 写自定义规则

安装、完整方法说明和可运行示例见 Python 接入指南。

python/agentprov_eval（可通过 import agentprov 使用）是基于 CLI 的轻量辅助库， 不内置奖励函数。自定义规则就是读取 EvalContext 并返回信号的普通 Python 函数； 采集、关联、证据清单和完整性校验仍由 Go 程序负责。 下面的例子通过一个函数完成“批量记录 → 执行评估规则 → 导入信号”的本地离线流程：

from agentprov import Registry, Signal, run_batch_pipeline

registry = Registry(name="rl-reward-signals")

@registry.rule("file_change_reward")
def file_change_reward(ctx):
    return Signal.reward_feature(
        "file_change_reward",
        float(len(ctx.file_changes())),
        "reward feature from file state changes",
    )

@registry.rule("metadata_penalty")
def metadata_penalty(ctx):
    if ctx.has_event_type("metadata_ip"):
        return Signal.penalty("metadata_ip", -1.0, "metadata service access")
    return None

result = run_batch_pipeline(
    [
        {"run_id": "traj-0001", "workdir": "/tmp/job1", "command": ["pytest", "-q"]},
        {"run_id": "traj-0002", "workdir": "/tmp/job2", "command": ["pytest", "-q"]},
    ],
    registry,
    binary="./agentprov",
    data_dir=".agentprov-rl",
    engine="rl-reward-signals",
    import_signals=True,
    include_forensics=True,
)

print(result.batch_id, result.signal_count)

如果已有流水线负责调度或分片，也可以分别调用各个步骤：

from agentprov import Client, evaluate_batch

client = Client(binary="./agentprov", data_dir=".agentprov-batch")
batch = client.record_batch(
    [
        {"run_id": "traj-0001", "workdir": "/tmp/job1", "command": ["pytest", "-q"]},
        {"run_id": "traj-0002", "workdir": "/tmp/job2", "command": ["pytest", "-q"]},
    ],
)
contexts = client.batch_eval_contexts(batch_id=batch["batch_id"])
reports = evaluate_batch(contexts, registry=registry)
client.import_signal_reports(reports, engine=registry.name)

结果写入本地存储后，可按批次、分片、任务或单次执行查询：

./agentprov evidence batch-summary --latest --json
./agentprov evidence batch-summary --shard shard-0 --json
./agentprov evidence batch-summary --run traj-0001 --json
./agentprov signal batch-context --shard shard-0 --latest > eval-contexts.jsonl
./agentprov forensics export-batch --latest --json

本地服务（Daemon）模式

运行本地服务时，也可以通过 HTTP API 使用同一套协议：

GET  /v1/signal/context?run=<run_id>
POST /v1/signal/run
POST /v1/signal/import

自定义评估器在客户端进程中运行。客户端先获取 EvalContext，执行评估器， 再将结果提交给服务校验。CLI 设置 --daemon-url 后也采用这一流程。

合规映射

将执行记录中的检测结果映射到 OWASP Agentic Security、NIST AI Agent 等安全框架的检查项，查看规则命中、阻断决策和待处理问题，用于自评和审计准备：

./agentprov compliance map --framework owasp-asi --run <run_id>
./agentprov compliance gaps --framework owasp-asi --run <run_id>   # 已检测未阻止或尚无规则的待办

每个检查项映射到具体检测规则及其在本次执行中的命中记录，报告 enforced（阻断）、detected（仅检测）、not_triggered（未触发）或 no_rule（尚无规则），同时给出 evidence_refs 和处理建议。 自定义 YAML 目录可增加框架，--rules 可加载实际检测规则。

完整命令、检查项含义和 YAML 规则格式，见合规证据说明。

AI 可调用的证据工具

AgentProvenance 将证据查询和部分上下文写入接口封装成 AI 可调用的工具， 供 Agent 运行框架、评估器或辅助复核工具使用：

./agentprov ai tools --provider generic
./agentprov ai tools --provider openai
./agentprov ai tools --provider anthropic

./agentprov ai call verify_run --input '{"run":"run-demo-bugfix"}'
./agentprov ai call list_events --input '{"run":"run-demo-bugfix","type":"execve","limit":10}'
./agentprov ai call get_timeline --input '{"run":"run-demo-bugfix","view":"causality"}'
./agentprov ai call evaluate_action --input '{"event_type":"execve","args":["python","-m","pytest","-q"]}'
./agentprov ai call evaluate_action --input '{"event_type":"network_connect","dst_ip":"169.254.169.254"}'

./agentprov ai mcp   # 通过 stdio MCP（JSON-RPC 2.0）提供同一份目录

工具定义可导出为 generic、OpenAI 或 Anthropic 格式，通过 ai call 在本地调用， 也可以由 ai mcp 提供给 MCP 客户端。后者使用 stdio JSON-RPC 2.0， 协议版本为 2025-06-18。这些入口共用同一份工具定义：

查询工具和 evaluate_action 标记为只读；bind_scope 与 record_tool_call 会写入应用上下文，因此在 MCP 中标记为 readOnlyHint=false。 这些写入接口不用于提交原始内核事件或修改签名。模型提供的上下文以应用侧声明 保存，不能当作传感器观测到的事实；动作预检则由策略引擎完成。

实例：让 LLM 分析安全证据

外部模型可以读取证据并给出分析，再将结论作为信号写回，而不修改原始记录。 demo/llm-judge 提供了一个完整示例：

python3 demo/llm-judge/judge.py run            # 导入示例证据包并评估
python3 demo/llm-judge/judge.py run --run <id> --data-dir <dir>   # 评估已有的执行记录

该示例通过 EvalContext、ai call 和图查询接口读取已记录的执行轨迹， 不按事件类型预先筛掉证据。模型返回结构化结果 agentprovenance.llm_judge/v1， 包括 benign、suspicious 或 malicious 判定，以及引用具体证据 ID 的发现。 结果通过 signal import 写回，成为关联在图上的分析信号。

轨迹超过上下文预算时，示例会按时间分块评估，再汇总结果，并记录实际处理的 覆盖情况。评估器本身也运行在 agentprov record 下：它的模型请求和响应会被 整理为独立执行记录中的 llm_call 节点，便于追溯评估结论的来源。

示例支持兼容 Anthropic 或 OpenAI 协议的模型服务，例如 Claude、DeepSeek、 Qwen，以及本地 vLLM/Ollama 服务。未配置 API Key 时会使用离线测试数据完成 流程验证；这不代表真实模型作出的判断。

可视化界面

图谱下方提供默认收起的 Agent 会话，包含对话与工具、权限与配置、采集情况。 完整工具输出和文件正文在独立阅读区打开，不依赖会话展开。 操作步骤和最新截图见 Agent 会话指南及 DeepSeek 示例。

DeepSeek 示例指南还展示权限配置、 最终文件正文和采集情况。

./agentprov dashboard serve            # http://127.0.0.1:7396
./agentprov dashboard serve --data-dir <dir> --addr 127.0.0.1:7396

Dashboard 是本地运行的只读单页界面，用于浏览和查询证据图。 它与 CLI、AI 工具复用内部查询逻辑，HTML 和 JavaScript 内嵌在可执行文件中， 不依赖外部前端资源。

命令行默认使用英文。添加 --lang zh-CN 可查看中文帮助和终端输出，例如：

./agentprov --lang zh-CN --help
./agentprov --lang zh-CN demo

显式指定语言时，打开的网页会采用同一语言；未指定时，由浏览器语言决定。JSON 输出、参数名和原始证据保持原样。

首次访问按浏览器语言显示中文或英文，其他语言回退到英文。页面右上角可以切换语言，手动选择会保留。切换后会保留当前执行记录、图视图、展开层级、选中节点和叠加标记。界面说明随语言切换，命令、路径、ID 和原始证据保留原文。

面对大量事件，界面先展示摘要，再按问题逐步展开。 原始遥测仍可查询，但不会一次性全部绘制成图。

原始遥测事件
  -> 提取关键执行证据，构建溯源图
  -> 补充带依据的派生关系
  -> 按分析主题生成视图
  -> 展示图布局、侧栏和原始证据

主要功能：

• Agent 会话：默认折叠，展开后查看对话与工具、权限与配置、 采集情况。已有证据链接支持与图谱双向定位；完整正文在独立查看器中分页读取。 旧记录没有会话内容时，覆盖情况仍显示未知。参见 DeepSeek 回放。
• 执行概览（Run Overview / Ask）：从“为什么有风险”“哪些文件被修改” “外发前后发生了什么”“产物从哪里来”等问题进入对应的局部视图。
• 图浏览器（Graph Explorer）：/api/lens 与 CLI 的 graph lens 共用查询接口， 提供 12 种视图：默认因果、安全、进程树、文件与产物、网络外发、数据流与污点传播、 Agent 意图、编排、意图一致性、运行环境、信任来源、沙箱边界。 支持叠加风险和信任信息，并通过分层 DAG 展示节点关系。
• 细节层级：summary 按进程、事件、文件、风险等分组展示概览； expanded 展开关键证据并过滤低价值噪声；raw 用于查看更完整的局部证据。 process_group、event_burst、file_group、risk_group、egress_group、 intent_group、trust_group 和 boundary_group 等分组均可点击展开，原始记录仍然保留。
• 关系与依据：派生关系（如 possible_sensitive_data_flow）使用虚线， 并附带规则、置信度和证据引用，以区别于直接记录的关系。 摘要模式会按进程或工具作用域聚合复杂的数据流关系，保留数量和原始证据引用。 网络外发按 risky_egress、dns、loopback、tls、network 分类。
• 局部展开：选中节点后，可通过 lineage、upstream、downstream、 children 和 raw events 查看来源、上下游、子节点和原始事件。 默认调查路径为“概览 → 问题 → 局部图 → 原始事件”，避免整张图过于拥挤。
• 时间回放（Time-scrubber）：按记录中的时间顺序回放，例如观察凭证读取 和后续网络连接依次出现。
• 节点侧栏（Side Panel）：显示节点 ID、命令、PID、路径、目标地址、 策略与风险、派生规则、置信度、证据引用及哈希。 产物预览通过 /api/artifact 提供，限制内容长度并进行脱敏。
• 相关证据（Focused Evidence）：通过 /api/events 分页展示当前所选问题、 分组、信号或节点对应的原始事件。选中对象后才加载，便于核对摘要背后的具体记录。
• 执行时间线（Run Timeline）：按时间顺序查看整次执行的事件； 与只展示当前选择依据的 Focused Evidence 配合使用。
• 验证与状态：展示完整性校验、签名、信号、风险、进程树和网络外发信息， 并支持实时刷新。

Demo：追溯恶意依赖引发的文件读取与网络连接

一个真实的编程 Agent（Claude Code，使用 DeepSeek 后端）在沙箱中开发贪吃蛇 游戏。安装依赖时，它引入了被投毒的 pysnake-helper；包的安装脚本随后读取 预先放置的模拟凭证，并尝试连接云元数据地址。

原生 eBPF 传感器记录文件访问和网络连接，数据流与污点传播视图根据这些证据 展示可能的“敏感文件读取 → 网络外发”关系。 示例在 Linux/eBPF 实验虚拟机中采集，提供已签名的取证包，可在本地离线回放。 以下命令适用于需要保留调查数据的手动导入流程：

./agentprov --data-dir /tmp/snake-replay forensics import \
  demo/snake-supply-chain/run-snake-supervised.forensics.json.gz \
  --pub-key demo/snake-supply-chain/attestation.pub        # 先验签，再导入
./agentprov --data-dir /tmp/snake-replay dashboard serve   # 选择执行记录 "run-snake-supervised"

界面操作见供应链示例指南， 签名包和采集脚本见 demo/snake-supply-chain/。

凭证访问的判定。 捕获到的凭证访问会记录为 secret_path 事件， 其中也可能包含 Agent 启动时对自身凭证的正常读取，如 ~/.claude/.credentials.json。 传感器记录系统调用；是否需要告警由上层策略判断。 默认的 self_credential_access 规则允许已识别的自身凭证访问，同时保留事件记录。 对应路径名单可以配置，原始访问记录不会因此被删除。

Demo：关联多 Agent 的任务委派、协作消息与系统调用

这个示例记录了一个 Agent 团队：主 Agent 将任务分配给子 Agent， 其中一个子 Agent 发出带有恶意指令的协作消息，另一个执行了恶意依赖的安装操作。 应用侧 Hooks 记录任务分工与消息传递，内核遥测独立记录 openat 和 connect 等行为。

关联后的签名证据图可以用于追查：消息由谁发出、哪次工具调用执行了操作、 哪些系统调用记录了实际行为，以及对应的风险和响应是什么。

./agentprov --data-dir /tmp/multiagent-replay forensics import \
  demo/multiagent-provenance/run-double-attempt.forensics.json.gz \
  --pub-key demo/multiagent-provenance/attestation.pub
./agentprov --data-dir /tmp/multiagent-replay graph verify --run run-double-attempt
./agentprov --data-dir /tmp/multiagent-replay graph lens --run run-double-attempt --lens orchestration
./agentprov --data-dir /tmp/multiagent-replay dashboard serve

签名包、回放命令和采集过程见 demo/multiagent-provenance/。 其中包含两次尝试：显式的恶意请求被模型拒绝；随后通过依赖安装触发的行为， 则被内核遥测记录，并关联回 Agent 协作过程。

Demo：Kubernetes 跨 Pod 调用与事件归属

这个示例将 alice 和 bob 放到同一 Kubernetes 节点的两个 Pod 中。 alice 通过 Pod 网络调用 bob，后者执行恶意安装命令，读取模拟凭证并连接 云元数据地址。节点上的一个 agentprov-sensor 观测两个 Pod 的 cgroup， 并结合命名空间、Pod 和容器身份，将事件关联到同一份执行记录。

该示例对应 k8s-daemonset 采集模式。Kubernetes 提供运行位置和容器身份， 核心证据图仍使用通用模型。验收脚本使用真实 DaemonSet、stdout JSONL、 Pod/容器元数据和宿主机 cgroup，无需在工作负载中接入采集代码。 应用侧委派日志复用了多 Agent 示例；跨 Pod 网络与运行时事件则是在本场景中实测采集的。

回放包、采集脚本和证据范围说明见 demo/k8s-cross-pod-a2a/。 本次记录中的 secret_path 和 metadata_ip 事件归属于 Bob 的 Pod/cgroup， Alice 的 Pod 未出现对应事件；图中也保留了跨 Pod 的 alice → bob 调用关系。

证据图命令

以下命令提供类似 Git 的查询方式，用于追溯、比较和验证执行证据：

./agentprov graph trace --run <run_id>           # 上下文 + 因果 + 风险，一个视图
./agentprov graph verify --run <run_id>          # 完整性：哈希、父链接、证据链
./agentprov graph diff --run <run_id> --file <path>
./agentprov graph blame --run <run_id> --file <path>
./agentprov graph explain --run <run_id> --file <path>   # 有界、分页的因果解释
./agentprov graph lens --run <run_id> --lens data-flow-taint --overlay risk --json
./agentprov graph trajectories --run <run_id> --json     # 给评估器/RL 的证据包

其他命令包括：refs / log / objects 用于查看引用、历史和内容寻址对象； materialize / materialize-llm 将已有证据整理成图对象； replay 生成重建计划，不直接重做外部操作。 完整用法见证据图命令说明。

当前能力

采集与接收

原生节点采集支持有容量上限的持久化批次、重启恢复、等待迟到绑定后重试关联、 事务级去重，以及逐项探针能力报告。 具体系统调用和 TLS 范围见部署与验收指南， 恢复机制见原生采集缓冲队列说明。

关联与验证

图视图的交互与各主题说明见可视化界面。 命令匹配属于有依据的关联推断，不等于为每个子 Agent 分配独立的内核身份。

查询与观测

安全与信号

接口与集成

核心 Demo 验收

核心验收覆盖以下行为：

• 多个执行作用域可以基于同一个初始状态进行比较。
• 原始遥测不需要 tool_call_id。
• 分页的 graph objects 和 graph explain 响应提供稳定的 result_set_id 和每页的 page_hash 完整性元数据。
• PID、cgroup、容器和时间窗绑定能够解析出执行上下文。
• 证据图保留 tool_call -> process -> runtime_event 的运行时关联链路。
• PID/PPID/TGID 遥测能创建进程树因果边。
• 运行时观测到的 file_write 能出现在产生了某个文件差异的同一条轨迹里。
• 运行时观测到的文件事件会创建 workspace_file/<path> 图节点， 并能结合 diff/blame 追溯文件变化。
• 无需 SDK 的进程采样能够识别根进程退出后仍在运行的子进程， 并保留相应的生命周期记录和策略判定。
• Timeline JSON 展示进程采样产生的 process_observed 事件，含 PID、PPID、命令、 首次/末次出现时间戳、outlived_root 和作用域边界元数据。
• 风险事件能生成污点和响应记录；第一阶段不负责最终奖励或轨迹筛选决策。
• graph diff 支持统一差异格式（unified diff）和 JSON 输出。
• graph blame 说明文件的创建、修改、删除或未变状态及其归属。
• graph trajectories --json 为外部评估器输出结构化证据包。

运行：

./scripts/demo_telemetry_jsonl.sh
./scripts/accept_phase1.sh
./scripts/accept_zero_sdk_realistic.sh

架构

flowchart TD
    Agent["Agent / 运行框架 / 基准测试 / 红队 / RL 流水线"] --> CLI["agentprov CLI"]
    Agent --> ModelIntent["模型意图\n会话记录 / TLS 模型调用 / 拒绝 / 评估"]
    Agent --> Enrich["应用上下文补充\nhooks bridge / MCP 上下文写入"]
    Agent --> Recorder["无需 SDK 的记录器\nagentprov record -- <cmd>"]

    CLI --> Boundary
    ModelIntent --> Boundary
    Enrich --> Boundary
    Recorder --> Boundary
    RuntimeTelemetry["运行时遥测\n原生 eBPF / Falco / Tetragon / auditd"] --> Boundary
    SandboxIdentity["沙箱身份与运行信息\ncontainer / cgroup / PID / cwd / 时间"] --> Boundary
    AppContext["应用上下文\nrun / trajectory / execution_scope / tool_call"] --> Boundary
    ExternalSignals["外部评估信号\n奖励特征 / 惩罚 / 标签 / 质量"] --> Boundary

    subgraph Boundary["API 与事件接收"]
        Daemon["本地服务 API\n控制与查询"]
        Validation["校验与格式统一\n数据结构 / 身份 / 脱敏"]
        Spool["磁盘缓冲 / 背压 / 保留策略"]
    end

    Daemon --> Validation
    Validation --> Spool
    Spool --> Core

    subgraph Core["执行观测与溯源核心"]
        Intent["意图模型\n契约 / 拒绝 / 协作消息 / 模型调用"]
        Correlation["工具调用作用域关联\nPID / cgroup / 容器 / 时间范围"]
        Timeline["执行时间线\n应用上下文与运行时事件"]
        IntentDiff["意图与实际行为比较\n声明 / 偏差 / 覆盖缺口"]
        Causality["运行时关联图\n进程 / 文件 / 网络 / 事件"]
        Provenance["类 Git 溯源图\nrefs / objects / diff / blame"]
        Derivation["关系推导\n派生关系 / 污点传播 / 来源 / 偏差"]
        Lens["图视图\n意图 / 安全 / 进程 / 文件 / 外发 / 污点"]
        Evidence["证据清单\n内容寻址引用 / 哈希"]
    end

    Core --> Intent
    Intent --> Correlation
    Correlation --> Timeline
    Timeline --> IntentDiff
    IntentDiff --> Causality
    Causality --> Provenance
    Provenance --> Derivation
    Derivation --> Lens
    Lens --> Evidence
    Evidence --> Query["证据查询接口\nobserve / timeline / explain / verify / audit"]
    Evidence --> Security["安全分析\n基线 / 策略 / 风险 / 响应 / 取证"]

使用功能前，先检查运行环境实际提供的能力。 上层功能应根据身份识别、 文件系统、遥测、隔离和恢复能力决定可用范围。例如，只有 Docker 文件系统证据时， 就只提供相应的目录和文件溯源，不能据此声称支持虚拟机内存恢复。

命令记录器、应用上下文、遥测接收器、沙箱适配器和外部评估器结果，均从 API 或事件接收入口进入系统，经过校验、格式统一、身份绑定、脱敏，以及适用的 缓冲、背压和保留处理后，再写入核心证据图。

运行环境与遥测

证据模型与具体运行环境分离。不同来源的数据先转换为 统一遥测格式，再参与关联与图构建。 适配新环境时，应优先让采集器输出已有格式和关联信息，复用核心处理流程。

需要区分三个方面：

• 执行环境：Agent 进程实际运行在哪里。已验证的位置包括本地 Linux、 KVM 虚拟机内部和容器；AgentProvenance 负责观测，不负责创建这些运行环境。
• 任务编排：工作负载由谁调度，例如 Kubernetes、Ray、批处理或云平台。 具体平台能否接入，仍取决于其可提供的身份信息与事件来源。
• 事件来源：内核与行为数据从哪里获取。主要来源是原生 Linux eBPF 传感器 （agentprov sensor stream）；已有 Falco、Tetragon、LoongCollector 或 auditd 的主机，也可通过 telemetry ingest-jsonl / ingest-falco 接收受支持格式的数据， 并保留包含哈希的批次清单。详见Falco 接收器说明。

适配时遵循两项原则：

• 按实际能力报告覆盖范围。 内核和权限满足要求时才启用对应探针； 无法采集的路径和降级原因应明确记录。
• 通过关联标识确定事件归属。 cgroup ID、PID、执行记录或作用域 ID 是重要依据。 在 Linux 上，为每个执行作用域分配独立 cgroup 后，record 可将进程子树的 事件归属到同一次执行，无需原始事件携带 tool_call_id。 缺少精确标识时，只能使用现有证据进行有限关联，并反映相应的置信度或缺口。

这些集成的价值，是把进程、文件和网络行为关联到任务上下文， 为差异比较、来源追溯、污点分析和审计提供依据。

边界

项目范围如下：

• 不实现通用沙箱，也不替代 Kubernetes、Ray、OpenSandbox、Firecracker、 gVisor、Kata 等运行或编排系统。
• 可使用现有事件来源，不要求用原生传感器替换 Falco、Tetragon 或 LoongCollector。
• 不提供模型网关、通用 LLM 调用管理或完整的可观测性平台。
• 第一阶段不提供内存快照、虚拟机瞬时克隆或任意分支的自动合并。
• 不撤销已发生的外部操作。这类动作可以被记录、接受策略检查，或按需关联补偿 Hook。
• 不替 RL 流水线决定奖励、惩罚和轨迹筛选规则，只提供可供评估的行为证据与偏差信号。

产品方向见产品说明，部署方式见 部署模式，与其他系统的职责划分见 项目对比。

仓库结构

cmd/agentprov/          CLI 入口
cmd/agentprov-sensor/   原生 eBPF 传感器（Linux）
internal/cli/           命令解析与输出
internal/launch/        一键启动入口：执行作用域、可视化界面、临时 Hooks 配置、传感器与降级报告

internal/record/        无需 SDK 的命令执行记录
internal/sensor/        Linux amd64/arm64 eBPF 传感器：进程、网络、文件、权限、TLS 与 DNS
internal/producer/      采集模式定义、cgroup 事件归属与 Kubernetes informer
internal/tlsintent/     TLS 分块与 HTTP 消息重组，模型请求和响应解析
internal/telemetry/     统一事件格式、JSONL 接收、TLS/HTTP 元数据与关联输入
internal/correlation/   ToolCallScope 与运行身份的绑定
internal/provenance/    时间线、溯源图、引用与对象、差异比较、来源追溯、校验、回放与视图
internal/evidence/      精简证据记录与外部操作信息
internal/effects/       外部操作与数据外发记录
internal/redact/        写入存储、生成证据对象和导出前的敏感信息脱敏
internal/security/      策略判定、风险信号、基线偏差与响应动作
internal/signals/       关联到图的统一信号模型：行为、成本、质量与安全
internal/signal/        评估上下文、批量导入与外部评估结果
internal/intent/        意图契约与声明、实际行为之间的差异判定
internal/observability/ observe 查询及其完整性信息
internal/compliance/    OWASP Agentic 与 NIST AI 检查项映射、覆盖率与缺口报告
internal/cost/          资源遥测、Docker stats 采样与指定时间范围内的资源记录
internal/baseline/      行为基线学习与偏差记录
internal/attest/        in-toto/DSSE Ed25519 证据签名与验证
internal/forensics/     证据包导出与可选签名
internal/aitools/       AI 工具定义：证据查询、动作预检与上下文写入
internal/hooksbridge/   Hooks 到 Agent 编排图的映射与命令匹配归属；支持 claude/kimi/codex/grok
internal/mcpserver/     基于统一工具定义的 stdio MCP（JSON-RPC 2.0）服务
internal/daemon/        HTTP /v1 服务与客户端，以及用于提示多进程同时写入的锁文件
internal/dashboard/     本地只读可视化界面，前端资源内嵌于程序

internal/substrate/     运行环境信息与兼容适配器
internal/adapter/       运行环境适配器及其能力注册
internal/control/       供兼容功能使用的运行环境作用域处理
internal/computerapi/   供兼容示例使用的文件与工具 API
internal/envtemplate/   任务与运行环境模板的构建和检查
internal/ports/         本地预览代理

internal/store/         SQLite 表结构与数据访问层
internal/ids/           带前缀的标识符生成
examples/               事件、遥测、策略与集成示例
scripts/                示例脚本与验收工具
docs/                   产品、部署、接口、验收与设计文档

核心功能集中在 record、telemetry、correlation、provenance、 evidence、security、signals、cost、baseline、attest 和 forensics。 substrate 包负责表示可供核心使用的运行环境信息。

后续方向

暂不新增功能，重点提升证据与关联的准确性、采集稳定性和使用体验。 后续根据实际使用中发现的问题，完善调查流程和文档，降低使用难度。