AgentProvenance

<div align="center"> # AgentProvenance ### 将应用上下文与系统遥测关联成可验证、可签名因果图谱，用于沙盒代理。 将应用侧的代理上下文与系统侧的遥测数据关联，然后将运行时证据、文件差异、工件、风险信号和响应决策转化为可查询、可回放和可审计的因果图谱。证据以内容寻址和哈希验证的方式存储（借鉴自 Git），并且可以签名以防止篡改 —— 但这是一个审计/溯源层，**不是版本控制系统**：没有合并、检出或可变工作树。 [](https://go.dev/) [](https://github.com/ByteYellow/AgentProvenance/actions/workflows/ci.yml) [](https://www.docker.com/) [](https://www.sqlite.org/) [](LICENSE) **[快速开始](#快速开始)** | **[核心模型](#核心模型)** | **[当前能力](#当前能力)** | **[路线图](#路线图)** </div> --- <p align="center"> <img src="docs/assets/agentprovenance-architecture.svg" alt="AgentProvenance 架构：应用上下文和系统遥测进入摄入边界，然后成为可验证的溯源图谱。" width="100%"> </p> <p align="center"> <img src="docs/assets/evidence-dag.svg" alt="AgentProvenance 证据 DAG：LLM 意图、工具调用、进程、运行时事件、策略风险、响应、工件、清单和验证。" width="100%"> </p> AgentProvenance 是一个本地优先的安全和溯源控制平面，适用于自主的、使用工具的代理，特别是沙盒编码代理。它捕获系统遥测数据（来自其自己的 eBPF 传感器或摄入 Falco/Tetragon），将其与应用侧的代理上下文关联成可验证、可签名的因果图谱，并通过 CLI、守护进程 API、AI 工具（包括 MCP 服务器）和本地 Web 仪表盘提供该图谱。 它不是一个通用的沙盒运行时、通用遥测收集器、Kubernetes/Ray 替代品、强化学习训练器、跟踪仪表盘或版本控制系统（它借鉴了 Git 的内容寻址和验证模型，而不是其分支/合并工作流）。它拥有一个更狭窄的原语： ```text 执行上下文 -> 证据摄入 -> 运行时因果图谱 -> 溯源 DAG -> 状态差异 / 责任 / 工件 lineage -> 安全分析 / 风险决策 -> 污染 / 响应动作 -> 回放 / 法医 / 审计清单 ``` 目标是回答普通跟踪无法很好回答的问题： - 哪个快照启动了此执行？ - 哪个尝试生成了此工件？ - 哪个工具调用启动了此进程？ - 哪个子进程导致了此运行时事件？ - 哪个进程更改了此文件？ - 哪个行为对该代理或任务配置文件来说是异常的？ - 哪个执行分支被响应门污染、隔离、中断或阻止？ - 哪些证据支持风险决策？ - 应该触发什么响应动作：审计、拒绝、终止、隔离、污染、导出法医或通过 Feishu/DingTalk 通知人类？ - 应该检查哪些确切的行为证据、偏差信号和风险上下文，以便外部评估者、强化学习管道或人类审查者检查？ - 此执行可以被 diff、责备、验证、回放和审计吗？ <p align="center"> <img src="docs/assets/evidence-flow.svg" alt="AgentProvenance 证据流" width="920"> </p> ## 目录 - [为什么](#为什么) - [安全循环](#安全循环) - [核心模型](#核心模型) - [白盒模式](#白盒模式) - [零 SDK 模式](#零-sdk-模式) - [与现有系统的关系](#与现有系统的关系) - [快速开始](#快速开始) - [部署模式](#部署模式) - [兼容 Falco 的接收器](#兼容-falco-的接收器) - [安全证据命令](#安全证据命令) - [外部评估者协议](#外部评估者协议) - [合规证据，而非认证](#合规证据，而非认证) - [AI 可调用证据工具](#ai-可调用证据工具) - [Web 仪表盘](#web-仪表盘) - [图命令](#图命令) - [当前能力](#当前能力) - [核心演示验收](#核心演示验收) - [架构](#架构) - [基板信号](#基板信号) - [边界](#边界) - [存储库布局](#存储库布局) - [路线图](#路线图) - [开发](#开发) ## 为什么 现代代理执行不是一个提示和一个工具调用。编码代理和自主工作流会分叉尝试、编辑文件、运行测试、创建工件、生成子进程、触摸外部系统并触发运行时遥测。日志、跟踪、指标和沙盒事件各自捕获该故事的片段，但它们很少产生类似 Git 的执行状态的因果记录。 AgentProvenance 将沙盒执行转化为面向安全性的证据图谱： ```text 基准快照 -> 尝试 -> 执行上下文 -> 工具调用 -> 进程 / 子进程 -> 运行时事件 -> 文件差异 / 工件 -> 基线特征 / 风险信号 -> 污染 / 响应动作 -> 回放 / 法医 / 审计清单 ``` 主要路径是记录和解释沙盒代理执行。分支繁重的编码代理脚本只是一个压力演示：它快速创建许多分支、工件、运行时事件和风险案例，以锻炼图谱。AgentProvenance 不会选择奖励赢家。它发出结构化的轨迹证据和期望偏差信号，以便外部评估者或训练管道可以将它们转化为奖励、惩罚、过滤或人工审查决策。 对于强化学习管道，有用的原语不是“最佳”或自动选择获胜者。有用的原语是对每个轨迹的可观察性：代理执行了什么、触摸了哪些子进程和文件、出现了哪些网络/运行时事件、哪个行为违反了安全或任务期望，以及哪些风险/基线信号应该有助于奖励塑造或拒绝。 ## 安全循环 安全模型故意简单和具体： ```text 应用上下文 运行 / 会话 / 尝试 / 工具调用 / 用户 / 任务 / 工作空间 系统遥测 进程 / 文件 / 网络 / 资源 / 沙盒 / eBPF 事件 关联 容器 ID / cgroup ID / PID / PPID / 工作目录 / 时间戳 / 文件差异 安全分析 行为基线 / 可疑事件 / 污染 lineage / 风险决策 响应 审计 / 拒绝 / 终止 / 隔离 / 污染 / 法医 / Feishu 或 DingTalk 通知 ``` 这使得 AgentProvenance 更接近于 AI 时代的 HIDS/控制平面层，而不是纯粹的 LLM 跟踪仪表盘。传统的主机监控询问“这个进程做了什么？”，而 AgentProvenance 添加了代理执行上下文，以便询问“哪个代理/工具/任务导致了它，改变了什么状态，什么证据证明了它，以及应该采取什么响应？” 该项目目前实现了证据图谱、运行时关联、差异/责备、遥测批次清单、策略决策、规范化风险信号、基线偏差记录、响应动作记录、污染、隔离和法医/导出基础。更深入的 eBPF 接收器和 Feishu/DingTalk 响应适配器属于下一个安全控制阶段。 ## 核心模型 AgentProvenance 支持两种上下文模式。 ### 白盒模式 代理托管、SDK、工具路由器或框架显式提供上下文： ```text 运行 ID / 会话 ID / 尝试 ID / 工具调用 ID / 工具名称 / 参数哈希 ``` 这提供了高精度，适用于自定义编码代理系统、Agentix 样式的托管、LangGraph 样式的工作流和内部工具路由器。 ### 零 SDK 模式 用户可以直接运行代理命令： ```sh agentprov record -- <代理命令> ``` 当前的 MVP 在工作目录中记录命令，拍摄执行前的文件状态快照，运行命令，计算执行后的文件更改，并将运行时文件证据发出到 DAG 中。长期零 SDK 路径增加了更深入的进程树和内核遥测捕获。 零 SDK 推理使用运行时事实： ```text 根进程 / 进程树 / 工作目录 / 时间戳 / 容器 ID / cgroup ID / 文件差异 / 工件引用 ``` 原始系统侧遥测不应需要携带 `tool_calls_id`。内核和运行时信号通常知道 PID、cgroup、命名空间、容器 ID、时间戳和进程树。AgentProvenance 将这些基板事实关联回执行上下文。 今天，CLI 暴露了底层绑定原语： ```sh agentprov telemetry bind --run <运行 ID> --session <会话 ID> \ --attempt <尝试 ID> --tool-calls <工具调用 ID> --process <进程 ID> \ --container-id <容器 ID> --cgroup-id <cgroup ID> --pid <PID> ``` 然后可以摄入原始事件而无需 `tool_calls_id`: ```sh agentprov telemetry ingest --raw-event raw-execve-1 --pid <PID> \ --timestamp <事件时间> --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、事件 ID 哈希、接收器摘要和行级映射结果。默认情况下，它还会评估摄入事件的运行时策略，以便元数据-IP、私有 CIDR 和秘密路径行成为 `policy_decisions`、`risk_signals`、`response_actions`、图谱边缘和时间线行。使用 `--no-policy` 时，接收器应仅规范化和存储遥测数据。这为外部 Falco/Tetragon/LoongCollector 证据提供了审计句柄，而不将 AgentProvenance 转变为长期日志存储。 `native` 格式是 AgentProvenance 自身 eBPF 传感器（`cmd/agentprov-sensor`，`source="agentprov_ebpf"`）的接收器，并且自动检测。这弥补了仅消费的差距：传感器的规范化内核事件（execve、网络连接分类为 `metadata_ip`/`private_cidr`、文件写入及其真实绝对主机路径）流经相同的关联、策略、风险和统一信号路径，作为第三方遥测。原始文件遥测现在接受绝对主机路径（例如，写入 `/home/agent/.aws/credentials`），策略路径规则仍然捕获；只有工作区文件节点图保持其相对路径约束。`scripts/accept_native_sensor_risk.sh` 证明了从头到尾的循环（自己的内核遥测到统一的 `security` 信号）。 `ingest-falco` 是兼容 Falco 的接收路径。它从文件或 stdin 流中读取 Falco JSON/stdout，映射识别的 `execve`、`open/openat` 和 `connect` 事件到规范化的运行时事件，将它们与 PID/容器/cgroup/时间证据关联，然后默认评估策略。原始 Falco 行不需要 `tool_calls_id`；当可能时，ToolCallScope 从绑定表中恢复。 ## 与现有系统的关系 AgentProvenance 设计为与系统级可观察性项目、LLM 跟踪系统和沙盒运行时共存。 | 系统类别 | 它拥有 | AgentProvenance 的不同之处 | |---|---|---| | 系统可观察性 | 低侵入性系统侧捕获、eBPF/运行时事件收集、跨进程可见性 | AgentProvenance 将这些事件视为证据输入，然后构建类似 Git 的因果/溯源 DAG、差异/责备、污染 lineage、风险决策、法医和响应控制表面 | | OpenTelemetry / LLM 跟踪平台 | 跨度、日志、指标、LLM/工具跟踪、仪表盘、延迟/成本视图 | AgentProvenance 专注于状态溯源、工件 lineage、沙盒运行时效果、安全决策、回放和审计清单 | | HIDS / EDR / 运行时安全 | 主机/进程/文件/网络检测和强制执行 | AgentProvenance 添加代理上下文：运行/会话/尝试/工具调用、快照 lineage、文件差异、工件溯源、风险信号、基线偏差和响应门 | | 沙盒运行时 | 隔离、进程/容器/VM 执行、文件系统和网络边界 | AgentProvenance 消费沙盒身份和遥测；它不试图取代 Docker、OpenSandbox、gVisor、Firecracker、Kata 或 Kubernetes | 因此，差异不是“另一个零 SDK eBPF 观察者”。狭窄的原语是： ```text 系统侧遥测 + 应用侧代理上下文 -> 证据 DAG -> 安全分析与风险判断 -> 自动响应与审计轨迹 ``` ## 快速开始 先决条件： - Go 1.23+ - Docker Desktop 或兼容的 Docker 守护进程 ```sh git clone https://github.com/ByteYellow/AgentProvenance cd AgentProvenance go build ./cmd/agentprov mkdir -p /tmp/agentprov-record-demo printf 'value = 1\n' > /tmp/agentprov-record-demo/app.py ./agentprov record --run run-record-demo --workdir /tmp/agentprov-record-demo -- \ sh -lc 'printf "value = 2\n" > app.py && echo artifact > artifact.txt' ./agentprov observe summary --run run-record-demo ./agentprov graph explain --run run-record-demo --file app.py ./agentprov adapter list ./agentprov adapter inspect filtered-jsonl --json ./scripts/demo_telemetry_jsonl.sh ./agentprov telemetry batches --run run-telemetry-jsonl-demo ./agentprov timeline --run run-telemetry-jsonl-demo ./agentprov timeline --run run-telemetry-jsonl-demo --view causality ./agentprov timeline --run run-telemetry-jsonl-demo --json ./scripts/accept_phase1.sh ``` 快速路径构建 `agentprov`，记录命令，解释更改的文件，摄入过滤后的基板遥测，并运行第一阶段验收门。`observe summary` 是运行级可观察性入口点：它总结了应用上下文、运行时遥测覆盖、风险、基线、响应和顶级证据引用，然后您可以深入时间线或图查询。 `demo_telemetry_jsonl.sh` 是最小的基板遥测路径。它绑定了一个 ToolCallScope，摄入来自 `examples/telemetry/` 的 Tetragon/Falco/LoongCollector 固定 JSONL，列出规范化事件，并解释一个基板事件如何进入 DAG。 `accept_phase1.sh` 是当前 MVP 的机器可检查门。 `timeline` 是执行时间线表面。它将应用上下文、运行时遥测、证据、策略决策、风险信号、基线偏差、响应动作和外部效果合并为一个时间有序视图。 `--view causality` 将行分组为代理上下文、运行时进程、运行时遥测、证据、风险/策略和外部效果通道，具有相关性状态和钻取命令。JSON 输出旨在提供给未来的 UI。 ## 部署模式 AgentProvenance 有三种部署模式。强化学习（RL）、基准测试和评估用户应从第一种模式开始；企业安全和审计用户可以在需要共享摄入、保留和查询服务时转向后两种模式。 <p align="center"> <img src="docs/assets/deployment-modes.svg" alt="AgentProvenance deployment modes" width="920"> </p> | 模式 | 形态 | 适用场景 | 权衡 | |---|---|---|---| | 库 / 命令行界面（CLI）记录器 | 一个 `agentprov` 二进制文件，可选的 Python 助手，本地 SQLite/对象存储 | 强化学习（RL） rollout，评估任务，基准测试，持续集成（CI），本地红队测试 | 最容易采用；较弱的共享查询和长期摄入 | | 边车 / 本地守护进程 | `agentprov daemon serve` 位于一个工作节点或沙盒主机旁边；CLI/SDK 作为客户端 | 沙盒工作节点，CI 运行器，本地安全测试，适度容量的遥测数据摄入 | 添加本地服务边界、缓冲、反压力和稳定的查询 API | | 中央证据服务 | 共享的摄入/查询服务，带有对象存储、保留、身份验证和 UI/API | 企业安全、审计、SRE、合规性、事件审查 | 运营成本最高；不是默认的 RL 入口点 | 对于 RL 和评估管道，默认契约是轻量级且优先离线的： - 安装：一个 Go 二进制文件和一个可选的薄 Python 包。 - 调用：包装现有命令；SDK/框架集成是可选的。 - 批次：每个轨迹都有稳定的 `run_id` / 证据清单 / 信号上下文输出，查询表面是分页的。 - 开销：默认捕获关注进程/文件/差异/工件/退出/资源证据；更重的 Falco/eBPF 样式遥测是一个可选的基板。 - 所有权：AgentProvenance 发出证据、偏差、风险和轨迹信号。RL 系统拥有奖励、排名、数据集策略和获胜者选择。 - 策略：RL 模式不需要在线拒绝/终止/隔离。那些操作是可选的安全控制；离线评分可以在捕获的 EvalContext JSONL 上运行。 Python 用法保持薄且基于 CLI。对于部署 1，预期的 RL/评估入口点是一个运行本地离线循环端到端的函数： ```python 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) ``` 对于 RL 用户，自定义“规则”是普通的 Python 评估函数。它们在证据上离线运行；Go 保留捕获、关联、清单和查询完整性的所有权。可以将相同的工作流分成更低级别的调用，当管道已经拥有调度或分片时： ```python 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) ``` 稍后，可以按批次、 shard、作业或运行查询相同的本地存储： ```sh ./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 ``` ### Falco 兼容接收器 专用 Falco 接收器在 Falco 已经过滤主机内核或运行时事件时很有用： ```sh ./agentprov telemetry bind --run run-falco-demo --session session-falco-demo \ --attempt attempt-falco-demo --tool-call tool-falco-demo \ --process process-falco-demo --container-id container-falco-demo --pid 4242 \ --started-at 2026-01-01T00:00:00Z ./agentprov telemetry ingest-falco \ --file examples/telemetry/falco-risk-events.jsonl --json ./agentprov telemetry list --run run-falco-demo ./agentprov telemetry list --run run-falco-demo --limit 100 --json ./agentprov telemetry list --run run-falco-demo --limit 100 --cursor <next_cursor> --json ./agentprov timeline --run run-falco-demo ./agentprov security risks --run run-falco-demo --json ./agentprov security responses --run run-falco-demo --json ``` 对于实时流，直接传送 Falco JSON 输出： ```sh sudo falco -o json_output=true -o json_include_output_property=true | \ ./agentprov telemetry ingest-falco --file - ``` 接收器将 Falco 进程、文件和网络行映射为规范化的运行时事件。元数据 IP、私有 CIDR 和秘密路径行被提升为安全证据：`RiskSignal`、`ResponseAction`、策略图边和时间线条目。`graph explain --risk <policy_decision_id> --json` 将风险链接回原始运行时事件，并转发到响应操作。Falco 仍然是基板收集器；AgentProvenance 拥有关联、因果关系、来源和风险/审计链接。 主要的烟雾路径是遥测关联和图解释： ```sh ./scripts/demo_telemetry_jsonl.sh ``` 它绑定一个 ToolCallScope，摄入原始 Falco/Tetragon/LoongCollector 样式的运行时事件，这些事件不携带 `tool_calls_id`，将它们规范化为事件存储，关联回应用程序上下文，并解释生成的因果图。 ## 安全证据命令 ```sh ./agentprov observe summary --run <run_id> ./agentprov observe summary --run <run_id> --json ./agentprov observe coverage --run <run_id> ./agentprov observe coverage --run <run_id> --json ./agentprov observe scopes --run <run_id> ./agentprov observe scopes --run <run_id> --json ./agentprov observe event --run <run_id> --event <event_id> ./agentprov observe event --run <run_id> --event <event_id> --json ./agentprov observe process --run <run_id> --process <process_id> ./agentprov observe process --run <run_id> --process <process_id> --json ./agentprov observe flow --run <run_id> ./agentprov observe flow --run <run_id> --json ./agentprov evidence manifest --run <run_id> ./agentprov evidence manifest --run <run_id> --json ./agentprov evidence manifest --run <run_id> --materialize --json ./agentprov telemetry correlations --run <run_id> ./agentprov telemetry correlations --run <run_id> --json ./agentprov telemetry correlations --event <event_id> --json ./agentprov timeline --run <run_id> ./agentprov timeline --run <run_id> --view causality ./agentprov timeline --run <run_id> --limit 100 --cursor <next_cursor> --json ./agentprov timeline --run <run_id> --tool-calls <tool_calls_id> --json ./agentprov timeline --run <run_id> --process <process_id> --json ./agentprov timeline --run <run_id> --type risk_signal --json ./agentprov security risks --run <run_id> ./agentprov security risks --run <run_id> --json ./agentprov security deviations --run <run_id> ./agentprov security deviations --run <run_id> --json ./agentprov security responses --run <run_id> ./agentprov security responses --run <run_id> --json ./agentprov baseline learn --template <template_name> --run <run_id> ./agentprov baseline check --template <template_name> --run <run_id> ./agentprov signal context --run <run_id> ./agentprov signal batch-context --batch <batch_id> ./agentprov signal batch-context --shard <shard_id> ./agentprov signal batch-context --runs runs.jsonl ./agentprov signal run --run <run_id> ./agentprov signal run --run <run_id> --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 ./agentprov signal import-batch --file signal-reports.jsonl --engine python-sdk --json ./agentprov compliance frameworks ./agentprov compliance map --framework owasp-asi --run <run_id> ./agentprov compliance explain --framework owasp-asi --run <run_id> --item ASI05 ./agentprov compliance gaps --framework owasp-asi --run <run_id> ./agentprov compliance report --framework nist-rfi-2026-00206 --run <run_id> ./agentprov ai tools --provider openai ./agentprov ai tools --provider anthropic ./agentprov ai call evaluate_action --input '{"event_type":"network_connect","dst_ip":"169.254.169.254"}' ./agentprov policy test examples/events/metadata-egress.jsonl ./agentprov policy decisions --run <run_id> ./agentprov forensics export <run_id> ./agentprov forensics export-batch --batch <batch_id> ./agentprov forensics export-batch --latest --include-eval-contexts --json ``` 这些命令现在是主要的安全证据表面的一部分： | 命令 | 目的 | |---|---| | `observe summary` | 显示运行级别的可观察性覆盖范围，涵盖应用程序上下文、运行时遥测、风险、基线、响应和证据引用 | | `observe coverage` | 显示运行时遥测关联质量，并列出缺少会话/工具调用/进程身份的事件 | | `observe scopes` | 显示每个工具调用的可观察性：进程、运行时事件、风险、策略决策、响应和钻取链接 | | `observe event` | 解释一个运行时事件，带有相关联的代理上下文、相关风险/策略/响应证据和钻取链接 | | `observe process` | 解释一个进程及其工具调用上下文、运行时事件、风险/策略/响应证据和钻取链接 | | `observe flow` | 显示从运行时事件到风险信号、策略决策和响应动作的紧凑因果流 | | `evidence manifest` | 发出一个运行级别的证据索引，绑定可观察性摘要、时间线哈希、内容寻址对象引用、风险/响应报告哈希和推荐的钻取查询； `--materialize` 将其写入 `evidence_manifest` 来源对象 | | `telemetry correlations` | 解释为什么运行时遥测事件被附加到 ToolCallScope，包括原始身份、匹配绑定、匹配键、置信度、时间窗口和钻取引用 | | `timeline` | 显示跨应用程序上下文、运行时遥测、证据、风险、基线、响应和外部影响的时间有序执行视图 | | `security risks` | 列出从策略/运行时证据导出的规范化 `RiskSignal` 记录； `--json` 发出模式/哈希元数据和钻取引用到事件/进程/时间线/解释视图 | | `security deviations` | 列出 `BaselineDeviation` 记录，从行为特征检查中； `--json` 发出模式/哈希元数据和钻取引用到时间线和摘要视图 | | `security responses` | 列出记录的 `ResponseAction` 记录，例如审计、拒绝、终止、隔离、标记、导出或通知钩子； `--json` 发出模式/哈希元数据和钻取引用回风险/进程/解释视图 | | `baseline learn/check` | 学习进程/文件/网络/风险/运行时特征向量，并发出偏差记录和基线导出的风险信号 | | `signal context/batch-context/run/import/import-batch` | 导出一个 `EvalContext` 或 JSONL `EvalContext` 流，用于批处理/分片/运行列表，运行内置或外部评估器，并验证导入的 `EvalSignal` 记录或 JSONL `EvalReport` 批次，用于奖励塑造、数据集过滤、质量评分或外部基准测试消费者。AgentProvenance 拥有证据协议，而不是奖励策略 | | `compliance frameworks/map/explain/gaps/report` | 将运行证据映射到 OWASP Agentic Security 和 NIST AI 代理安全评估配置文件，作为项目级自我评估证据和差距列表 | | `ai tools/call` | 暴露只读证据查询表面和内联策略预飞行门，作为提供者工具模式和本地调度器。这不是 LLM 网关：模型可以查询证据并请求受信任的策略判决，但它们不能伪造运行时遥测、签名或来源对象 | | `policy test/decisions` | 评估事件、持久化策略决策，并馈送风险/响应图 | | `forensics export` | 导出运行的可审计证据； `--json` 发出 `agentprovenance.forensics_export/v1`，带有包路径、sha256、大小和状态 | | `forensics export-batch` | 导出批次级别的审计包，用于记录批次； `--json` 发出 `agentprovenance.batch_forensics_export/v1`，带有批次摘要、每个运行的取证引用、可选的 EvalContext 记录、结果/页面哈希和 sha256 验证的包路径 | ## 外部评估器协议 AgentProvenance 向外部评分系统公开证据，而不拥有其奖励、排名或数据集策略。 ```sh ./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` 包含轨迹、文件更改、运行时事件、风险信号和响应动作。 - 外部评估器从标准输入读取 `EvalContext` 并返回 `{ "signals": [...] }`。 - `EvalSignal` 可以表示奖励特征、惩罚、数据集标签或质量信号。 - `python/agentprov_eval` 和 `agentprov` 导入别名提供了一个薄的辅助 SDK，带有 `Registry`、`@rule`、`evaluate_batch`、`reports_jsonl` 和基于 CLI 的捕获/查询帮助程序。它们不编码奖励函数。 - `signal import-batch` 接受 JSONL EvalReport 记录，以便 RL 管道可以导入许多离线信号报告，而无需每个运行一个命令。 这让基准测试框架、RL 管道、红队测试框架或数据过滤作业可以决定证据如何成为分数、拒绝或审查。 在守护进程模式下，相同的协议可通过本地 API 使用： ```text GET /v1/signal/context?run=<run_id> POST /v1/signal/run POST /v1/signal/import ``` 守护进程不公开一个运行任意外部 shell 命令的 HTTP 端点。客户端可以获取 `EvalContext`，在其自己的进程边界执行其评估器，并将生成的信号导入守护进程进行验证。CLI 遵循这种形式，当设置 `--daemon-url` 时。 ## 合规证据，而非认证 AgentProvenance 可以将运行证据映射到安全框架配置文件，例如 OWASP Agentic Security 和 NIST AI 代理安全评估问题： ```sh ./agentprov compliance frameworks ./agentprov compliance frameworks --ruleset examples/compliance/custom-ruleset.yaml ./agentprov compliance validate --ruleset examples/compliance/custom-ruleset.yaml ./agentprov compliance map --framework owasp-asi --run <run_id> ./agentprov compliance map --framework owasp-asi --run <run_id> --only ASI05,ASI10,TRACE ./agentprov compliance explain --framework owasp-asi --run <run_id> --item ASI05 ./agentprov compliance gaps --framework owasp-asi --run <run_id> ./agentprov compliance gaps --framework owasp-asi --run <run_id> --missing-only --json ./agentprov compliance map --framework enterprise-agent-review --ruleset examples/compliance/custom-ruleset.yaml --run <run_id> ./agentprov compliance report --framework nist-rfi-2026-00206 --run <run_id> --json ``` 输出是一个有证据支持的自我评估。它不认证合规性，不提供法律建议，也不取代合格的第三方审计。每个检查项都源自运行中已有的证据：时间线事件、运行时遥测、ToolCallScope 绑定、策略决策、风险信号、基线偏差、响应动作、取证包、内容寻址来源对象和图边。 每个项目报告： ```text covered | partial | missing | not_applicable ``` 具有具体的 `evidence_refs`，当证据不完整时出现空白，并且推荐下一步。这使得代理执行证据可用于安全审查，而无需将 AgentProvenance 变成 GRC 平台。`compliance gaps` 将相同的映射转换为一个可操作的缺少或部分证据项的待办事项清单，用于运行。 自定义规则集可以添加本地框架和规则，而无需替换内置规则。YAML 模型将 `rules`、`frameworks` 和 `mappings` 分开；映射还可以选择内置项目，例如 `ASI05`、`ASI10` 或 `TRACE`，并在企业特定的审查配置文件中重用它们。JSON 保留 `control_id` 以兼容，并发出 `item_id` 以适应当前术语。 ## AI-可调用证据工具 AgentProvenance 可以将其证据查询接口暴露为 AI-可调用工具，供代理、评估器或审查助手使用： ```sh ./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` （stdio JSON-RPC 2.0 服务器，规范 `2025-06-18`）提供，以便 MCP 客户端看到相同的工具集，而无需单独的契约漂移。该目录： | 工具 | 用途 | |---|---| | `verify_run` | 验证运行的哈希、父链接和策略/风险/响应/信号完整性 | | `get_signals` | 返回运行的统一行为/成本/质量/安全信号集 | | `list_risks` | 返回安全风险信号和推荐操作 | | `list_events` | 返回分页的运行时遥测事件，可选地按类型过滤 | | `get_timeline` | 返回合并的应用程序上下文和运行时遥测时间线 | | `evaluate_action` | 在不执行的情况下，通过受信任的策略引擎运行提议的命令、文件操作或网络操作（内联门控，无副作用） | | `bind_scope` | 注册 ToolCallScope 绑定（应用程序断言，强制 `binding_source=ai_asserted`），以便独立系统遥测可以与此工具调用相关联 | | `record_tool_calls` | 锚定应用程序断言的工具调用（`status=asserted`）；**不** 执行任何操作 | 只读工具和 `evaluate_action` 被宣传为只读；`bind_scope` 和 `record_tool_calls` 是上下文写入表面（MCP 上 `readOnlyHint=false`）。 这不是模型网关、提示路由器或工具执行沙箱。模型接收模式，可以查询证据存储，在受信任的策略引擎上预先检查操作，并断言其自己的应用程序侧上下文（`bind_scope` / `record_tool_calls`）。它**永远**不能写入原始系统遥测，制造签名或伪造溯源图事实：上下文写入行被记录为 `ai_asserted` 并且不执行任何操作，判决由受信任的引擎而非模型计算。 ## Web 仪表盘 <p align="center"> <img src="docs/assets/dashboard-causality.png" alt="AgentProvenance 本地证据检查器预览，带有运行选择、验证状态、时间线、进程树、出口、风险信号和因果 DAG。" width="100%"> </p> <p align="center"> <img src="docs/assets/dashboard-timeline-process-egress.png" alt="AgentProvenance 本地证据检查器预览，带有运行选择、验证状态、时间线、进程树、出口、风险信号和因果 DAG。" width="100%"> </p> ```sh ./agentprov dashboard serve # http://127.0.0.1:7396 ./agentprov dashboard serve --data-dir <dir> --addr 127.0.0.1:7396 ``` 一个本地、只读、单页仪表盘，基于可验证图。其 JSON 端点重用与 CLI 和 AI 工具相同的内部函数，因此 UI 永远不会偏离契约；HTML/JS 嵌入在二进制文件中，不加载外部资产（本地优先）。面板： - **因果 DAG** （签名视图）：模型意图 -> 操作 -> 策略 -> 风险 -> 响应，由相同的 `llm_intent_caused` / `llm_call` / 策略->风险->响应边渲染；单击节点以高亮其因果谱系并检查其完整记录。 - **验证 + 签名** 状态，**信号 / 风险** 以及推荐操作，**分页时间线** （带有每个事件的相关类），**进程树** 和 **出口** （目标 IP 和解析的 DNS 主机名）。 - 实时自动刷新；平面事件流加上可验证的签名 DAG，而纯事件查看器无法显示。 ## 图形命令 ```sh ./agentprov graph trace --run run-demo-bugfix ./agentprov graph refs --run run-demo-bugfix ./agentprov graph log --run run-demo-bugfix ./agentprov graph materialize --run run-demo-bugfix ./agentprov graph objects --run run-demo-bugfix ./agentprov graph objects --run run-demo-bugfix --limit 50 --json ./agentprov graph objects --run run-demo-bugfix --limit 50 --cursor <next_cursor> --json ./agentprov graph verify --run run-demo-bugfix ./agentprov graph verify --run run-demo-bugfix --json ./agentprov graph replay --run run-demo-bugfix ./agentprov graph replay --run run-demo-bugfix --json ./agentprov graph trajectories --run run-demo-bugfix --json ./agentprov graph diff --run run-demo-bugfix --file calculator.py ./agentprov graph diff --run run-demo-bugfix --file calculator.py --json ./agentprov graph blame --run run-demo-bugfix --file calculator.py ./agentprov graph blame --run run-demo-bugfix --file calculator.py --json ./agentprov graph explain --run run-demo-bugfix --file calculator.py ./agentprov graph explain --run run-demo-bugfix --file calculator.py --json ./agentprov graph explain --run run-demo-bugfix --file calculator.py --depth 4 --limit 200 --json ./agentprov graph explain --run run-demo-bugfix --file calculator.py --depth 4 --limit 200 --cursor <next_cursor> --json ./agentprov graph explain --tool-calls <tool_calls_id> ./agentprov graph explain --risk <policy_decision_id> --json ``` 这些命令的含义： | 命令 | 用途 | |---|---| | `trace` | 显示执行上下文、运行时因果关系、溯源边、风险和响应门控证据 | | `refs` | 发出尝试、快照、工件和决策的稳定 Git 类引用 | | `log` | 显示时间顺序执行历史 | | `materialize` | 写入内容寻址溯源对象 | | `objects` | 列出内容寻址对象引用、哈希、父哈希、源 ID、路径和大小；支持 `--limit` 和 `--cursor` | | `verify` | 检查图完整性、风险/响应证据链、污染/响应障碍、对象哈希、重放生成、排水水位、遥测批次哈希和孤立生命周期证据 | | `replay` | 发出运行的计划重建 | | `trajectories --json` | 为外部评估器或 RL 奖励/惩罚管道发出每尝试行为证据、风险/偏差上下文、成本、工件和运行时事件 | | `diff` | 比较基准和尝试之间的文件状态 | | `blame` | 将文件状态归因于尝试、工具调用、进程、策略、命令和本地候选状态 | | `explain` | 通过组合跟踪、运行时因果关系、差异/责备、遥测接收器详细信息、遥测批次清单、进程观察、策略、对象引用、风险信号、基线偏差和响应证据来解释目标； `--json` 发出 `agentprovenance.explain/v1` 带有 `upstream` 、 `downstream` 、有界 `causality_path` 、 `query` 、 `evidence` 、 `objects` 、 `risks` 、 `telemetry_batches` 、 `process_observations` 和 `replay_refs`；运行时事件包括接收器/源格式、规范事件类型、身份密钥、模式状态和相关状态；使用 `--depth` 、 `--limit` 和 `--cursor` 来绑定和分页 DAG 遍历 | ## 当前能力 **捕获和摄入** | 能力 | 它做什么 | |---|---| | Zero-SDK 记录 | `record -- <cmd>` 快照工作目录，采样进程树，捕获文件差异 + 运行时证据，无需 SDK | | 批量记录器 | `record batch` 并行记录多个作业，用于 RL/基准测试管道 | | 原生 eBPF 传感器 | `agentprov-sensor` （Linux/arm64）：exec+argv，connect，file write + sensitive **read** → `secret_path`，process_exit，privesc（setuid/setgid/ptrace），tamper（rename/unlink），TLS 明文（哈希 + 元数据），DNS — 内核噪声过滤，实时验证 | **关联和验证** | 能力 | 它做什么 | |---|---| | 执行上下文 | 跨运行/会话/尝试/工具调用/进程/容器/cgroup/pid 的显式 ToolCallScope 绑定 | | 运行时因果关系 | 原生 `runtime_*` 图边（工具调用、进程树、快照、事件、文件） | | 溯源 DAG | `graph trace / refs / log / materialize / objects / verify / replay` 基于内容寻址对象 | | 图验证 | 检查对象哈希、父链接和策略 → 风险 → 响应 → 信号链（白盒和外部遥测运行） | | 相关性解释 | `telemetry correlations` — 原始身份、解析上下文、匹配绑定、置信度和事件的时间窗口 | **查询和观察** | 能力 | 它做什么 | |---|---| | 时间线 | `timeline [--view causality] [--json]` — 合并的应用程序上下文 + 系统遥测，分页带有完整性元数据 | | 可观察性 | `observe summary / coverage / scopes / event / process / flow` — 相关性覆盖范围、间隙、每个范围和事件→响应视图 | | 证据查询 | `graph explain` 基于文件/工件/进程/事件/工具调用/尝试/风险，带有边界、分页的因果路径 | | 差异/责备 | 文件级差异和责备，加入运行时事件和内容寻址对象 | | 证据清单 | `evidence manifest` — 运行级、哈希索引的证据索引（ `--materialize` 到对象） | | Web 仪表盘 | `dashboard serve` — 本地只读 UI：因果 DAG、验证状态、信号、时间线、进程树、出口 | **安全和信号** | 能力 | 它做什么 | |---|---| | 策略/风险/污染 | 策略决策、风险信号、隔离、污染 + 后代检查、响应门控资格 | | 行为基线 | `baseline learn / check` — 进程/文件/网络/资源特征；偏差成为风险信号 | | 统一信号 | 一个图附件的 `signals` 表（行为/成本/质量/安全）；安全 + 质量是实时生产者 | | 合规性 | `compliance` 将证据映射到 OWASP Agentic + NIST AI 配置文件，带有覆盖率和间隙报告 | | 签名证明 | in-toto/DSSE ed25519 签名证据（`forensics export --sign-key`），检测签名后篡改 | | 法医包 | `forensics export[-batch]` — 完整证据集的哈希审计包 | **表面和集成** | 能力 | 它做什么 | |---|---| | CLI / JSON | 每个命令都有稳定的 `--json` 契约，带有结果/页面完整性哈希 | | 守护进程 API | `daemon serve` — 绑定、摄入、查询、验证、记录、法医、信号，支持 HTTP；可选的 bearer-token 认证 | | AI 工具 + MCP | 读取表面、`evaluate_action` 门控和上下文写入（`bind_scope` / `record_tool_calls`）通过 `ai call` 和 stdio MCP（`ai mcp`） | | 评估器/RL | `signal context / import`，轨迹清单和 Python SDK（离线批处理 + 在环评分）— 发出证据，而不是奖励策略 | | 底层 | Docker 运行时（gVisor/Firecracker 桩）；快照 fork/resume/taint；遥测 spool、windows、保留、100k 压力测试 | ## 核心演示验收 主要演示必须证明： - 多个尝试从同一个干净的快照中分叉。 - 原始遥测不需要 `tool_calls_id`。 - 分页的 `graph objects` 和 `graph explain` 响应公开稳定的 `result_set_id` 和每页 `page_hash` 完整性元数据。 - PID、cgroup、容器和时间窗口绑定可以解析执行上下文。 - 原生运行时因果关系记录 `tool_calls -> process -> runtime_event`。 - PID/PPID/TGID 遥测创建进程树因果关系边。 - 运行时观察到的 `file_write` 可以出现在生成文件差异的同一轨迹中。 - 运行时观察到的文件事件创建 `workspace_file/<path>` 图节点，可以与差异/责备一起解释。 - Zero-SDK 进程观察暴露已结束的子进程，并验证孤立生命周期证据和策略决策的存在。 - 时间线 JSON 显示 Zero-SDK `process_observed` 事件，带有 pid、ppid、命令、第一个/最后一个看到的时间戳、`outlived_root` 和范围边界元数据。 - 风险事件可以创建污染和响应记录，但第 1 阶段不做出最终的奖励或获胜者决定。 - `graph diff` 发出统一的差异和 JSON。 - `graph blame` 发出创建/修改/删除/不变的状态归因。 - `graph trajectories --json` 为外部评估器发出结构化的证据包。 运行： ```sh ./scripts/demo_telemetry_jsonl.sh ./scripts/demo_provenance_trace.sh ``` ## 架构 <p align="center"> <img src="docs/assets/architecture-overview.svg" alt="AgentProvenance 架构概述" width="920"> </p> ```mermaid flowchart TD Agent["代理/托管/基准测试/红队/强化学习管道"] --> CLI["agentprov CLI"] Agent --> SDK["可选 SDK/工具路由器"] Agent --> Recorder["Zero-SDK 记录器\nagentprov record -- <cmd>"] CLI --> 边界 SDK --> 边界 Recorder --> 边界 运行时遥测["运行时遥测\nFalco / Tetragon / auditd / 未来 eBPF"] --> 边界 沙箱身份["沙箱身份\n容器/ cgroup / pid / cwd / 时间"] --> 边界 应用程序上下文["应用程序上下文\n运行/会话/尝试/工具调用"] --> 边界 外部信号["外部评估器信号\n奖励特征/惩罚/标签/质量"] --> 边界 subgraph 边界["API/摄入边界"] 守护进程["守护进程 API\n控制 + 查询"] 验证["验证/规范化\n模式/身份/删除"] 队列["队列/背压/保留"] end 守护进程 --> 验证 验证 --> 队列 队列 --> 核心 subgraph 核心["可观察性 + 溯源核心"] 相关性["ToolCallScope 相关性\npid / cgroup / 容器/时间窗口"] 时间线["执行时间线\n应用程序上下文 + 运行时事件"] 因果关系["运行时因果图\n进程/文件/网络/事件"] 溯源["Git 类似溯源 DAG\n引用/对象/差异/责备"] 证据["证据清单\n内容寻址引用/哈希"] end 核心 --> 相关性 相关性 --> 时间线 时间线 --> 因果关系 因果关系 --> 溯源 溯源 --> 证据 证据 --> 查询["证据查询表面\n观察/时间线/解释/验证/审计"] 证据 --> 安全["安全分析\n基线/策略/风险/响应/法医"] ``` 能力门控是一条硬设计规则。上层必须在假设快速分叉、内存快照、恢复、身份或强制语义之前查询运行时、快照、遥测和隔离能力。仅限 Docker 执行会降级为目录/文件系统溯源，而不是假装提供 VM 级的即时克隆。 所有生产者都通过 API/摄入边界进入。Zero-SDK 记录器、SDK/工具路由器、遥测接收器、沙箱适配器和外部评估器信号都是生产者输入；它们不应绕过验证、规范化、身份绑定、删除、队列/背压或保留控制，直接写入核心证据图。 ## 底层信号 底层集成在溯源模型下游： - Docker 是主动本地运行时。 - OpenSandbox、gVisor、Firecracker 和 Kata 是未来的运行时底层。 - Kubernetes、Ray、Batch 和云系统是编排底层。 - Falco、Tetragon、LoongCollector、auditd 和 eBPF 是遥测底层。当前 MVP 通过 `agentprov telemetry ingest-jsonl` 消费已过滤的 Tetragon/Falco/LoongCollector JSONL，通过 `agentprov telemetry ingest-falco` 接收器接收 Falco JSON/stdout 流，记录可哈希的批次清单，不运行内核探针。 - 未来的 `agentprov-sensor` 应该是能力门控的：优先使用现代 eBPF，内核和权限支持时使用，备用路径在适当时使用，操作员明确接受部署模型时使用 kmod 样式的收集器。控制平面必须将传感器能力视为数据，而不是隐藏的假设。 项目价值不在于收集更多日志。价值在于将底层信号与执行上下文相关联，并影响差异、责备、重放和审计能力。 ## 边界 这些边界是有意的： - AgentProvenance 不实施通用沙箱运行时。 - 它不取代 Kubernetes、Ray、OpenSandbox、Firecracker、gVisor、Kata、Falco、Tetragon、LoongCollector 或 eBPF。 - 它不是 LangSmith 克隆、LLM 网关或通用可观察性仪表盘。 - 它不承诺在第 1 阶段提供内存快照或 VM 级的即时克隆。 - 它不执行任意分支自动合并。 - 它不会回滚实际的外部副作用。外部操作会被记录、门控，并可选地链接到补偿钩子。 - 它不会为强化学习管道做出最终的奖励、惩罚或获胜者决定；它会发出行为证据和偏差信号，这些信号可以被那些系统评分。 参见 [docs/product.md](docs/product.md) 获取产品方向，[docs/deployment-modes.md](docs/deployment-modes.md) 获取部署方式。[docs/comparisons.md](docs/comparisons.md) 涵盖了相邻系统的边界。 ## 仓库布局 ```text cmd/agentprov/ 命令行入口 cmd/agentprov-sensor/ 原生 eBPF 传感器（Linux） internal/cli/ 命令解析和输出 internal/record/ 零 SDK 命令记录器 internal/sensor/ 原生 eBPF 传感器（exec/connect/file/privesc/tamper/TLS/DNS）；仅限 Linux，arm64 internal/telemetry/ 规范化运行时事件模式，JSONL 摄入，TLS HTTP 元数据，关联输入 internal/correlation/ ToolCallScope 和运行时身份绑定 internal/provenance/ 时间线，图形跟踪，引用，对象，差异，责备，验证，重放 internal/evidence/ 紧凑证据记录和外部影响 internal/security/ 策略决策，风险信号，基线偏差，响应动作 internal/signals/ 统一的图形附加信号模型（行为/成本/质量/安全） internal/baseline/ 行为基线学习和偏差记录 internal/attest/ in-toto/DSSE ed25519 证据签名（防篡改） internal/forensics/ 证据包导出（可选签名证明） internal/aitools/ AI 可调用工具目录（读取表面 + 内联门 + 上下文写入） internal/mcpserver/ stdio MCP（JSON-RPC 2.0）服务器，位于 aitools 目录之上 internal/dashboard/ 本地只读 Web 仪表盘（嵌入式 UI） internal/substrate/ Docker/运行时/快照适配器，用作执行基板 internal/control/ 本地租约/会话控制，用于基板支持的演示 internal/computerapi/ 文件/工具 API，位于本地沙箱会话之上 internal/ports/ 本地预览代理支持 internal/stressdemo/ 分支繁重的扇出演示，在负载下锻炼 provenance internal/experimental/ 资源窗口，调度器，节点元数据，热池实验 internal/store/ SQLite 模式和仓库 examples/ 任务，事件，策略 scripts/ 可运行的演示 docs/ 产品方向，MVP 细节，比较 ``` 主要产品路径位于 `record`、`telemetry`、`correlation`、`provenance`、`evidence`、`security`、`signals`、`baseline`、`attest` 和 `forensics` 中。`substrate` 包含 AgentProvenance 可以消耗的运行时事实。`stressdemo` 和 `experimental` 被故意分开，以便分支扇出和旧资源实验不会定义项目身份。 ## 路线图 | 阶段 | 目标 | 主要交付成果 | |---|---|---| | 第一阶段 | Provenance Correlation MVP | ToolCallScope、原始遥测关联、运行时因果关系 DAG、差异/责备、风险/偏差记录、响应门证据、重放和轨迹清单 | | 第二阶段 | 证据/因果关系强化 | 执行时间线 JSON、稳定解释 JSON、内容寻址对象、对象父哈希、图形验证、有界遍历、分页、完整性元数据 | | 第三阶段 | 零 SDK 记录器强化 | 进程树捕获、延迟子进程处理、cwd/time/file-diff 推断、孤儿生命周期证据、低侵入性记录模式 | | 第四阶段 | 真实的遥测集成 | Falco/Tetragon/LoongCollector/auditd/eBPF 接收器、cgroup/container/pid 关联、内核侧过滤假设 | | 第五阶段 | 风险/策略/控制 | 可配置的风险信号、行为基线、合规性证据映射、响应适配器、污染传播、隔离、响应阻塞、取证导出、Feishu/DingTalk/webhook 钩子、隔离升级钩子 | | 第六阶段 | 规模/用户界面/产品化 | 异步证据写入器、保留、内容寻址存储、快照 GC、资源窗口、高并发性摄入/查询测试、评估器 SDK 强化、中央证据服务、可用的用户界面/API | 第一至四阶段已构建并通过验收脚本进行机器检查；第五阶段已构建，但通知钩子除外；第六阶段已基本完成（Web 仪表盘、保留、内容寻址存储、并发性、评估器 SDK），但中央证据服务延迟到 v2。 最近完成： - **统一信号模型** (`internal/signals`，`agentprovenance.signals/v1`) - 一种图形附加的行类型，用于行为/成本/质量/安全，取代了每个维度的孤岛；安全性和质量是实时生产者，具有来自旧表的幂等回填。 - **签名证据证明** (`internal/attest`) - in-toto/DSSE ed25519 证据摘要签名，连接到 `forensics export`，提供妥协后防篡改而非完整性哈希重计算。 - **并发性正确性** - SQLite pragmas（包括 `busy_timeout`）通过 DSN 应用于每个连接池的连接，修复了并发写入下的无声 `SQLITE_BUSY`；关联绑定绑定了过时的开放匹配。 - **原生 eBPF 传感器扩展** (`internal/sensor`，在 arm64 虚拟机上实时验证) - 敏感文件读取（-> `secret_path`）、特权更改（setuid/setgid/ptrace）、文件篡改（rename/unlink）、TLS 明文 -> 隐私安全 HTTP 元数据 + `llm_call` 配对、`process_exit` 关闭关联窗口和 DNS（getaddrinfo）。内核噪声过滤在环缓冲区预留之前移除了一个 containerd-teardown 火箭流。特权升级策略规则（ptrace，setuid-to-root -> 隔离）。 - **AI 接口** - MCP 服务器（`ai mcp`，stdio JSON-RPC 2.0）和上下文写入工具（`bind_scope`、`record_tool_calls`）位于同一 `internal/aitools` 目录之上，在信任边界内由应用程序断言。 - **Web 仪表盘** (`internal/dashboard`，`dashboard serve`) - 具有因果关系 DAG 作为签名面板的本地只读视图，以及时间线、进程树、出口、信号和验证/签名状态。 接下来/公开： - **传感器广度** — 通用 DNS（musl / 原始 UDP:53，或 `udp_sendmsg` kprobe；`getaddrinfo` 今日涵盖 glibc）、IPv6/UDP 连接和多架构（x86 `PT_REGS`；今日 arm64-only）。`ptrace` 已捕获但尚未在测试中端到端执行。 - **TLS 深度** — HTTP/2 HPACK 头解码和 SSE 重组（今日 HTTP/1.1 加 h2 检测）。 - **防篡改证据（v2）** — 异地主机/捕获时间签名（KMS / TPM / 透明度日志）。v1 是完整性加上可选的本地签名，而不是针对主机根攻击者的证明。 - **部署 3** — 具有进程级数据平面隔离和 authz/scopes 的中央证据服务。 - **通知** — Feishu / DingTalk / webhook 响应钩子。 ## 开发 ```sh go test ./... ./scripts/accept_phase1.sh ./scripts/accept_zero_sdk_realistic.sh ./scripts/accept_falco_risk_realistic.sh ./scripts/accept_forensics_bundle.sh ./scripts/accept_batch_forensics.sh ./scripts/accept_evidence_query_pagination.sh ./scripts/accept_daemon_evidence_api.sh ./scripts/accept_telemetry_spool_backpressure.sh ./scripts/accept_telemetry_100k_pressure.sh ./scripts/accept_telemetry_event_windows.sh ./scripts/accept_signal_engine.sh ./scripts/accept_python_helper.sh ./scripts/accept_deploy1_batch_pipeline.sh ``` `go test ./...`、`go vet ./...` 和 `gofmt -l` 是每个包的门控。验收脚本是端到端的：每个驱动一个路径 — 零 SDK 记录、Falco/原生传感器风险、取证包、守护进程证据 API、遥测池/压力/窗口、信号引擎、Python 助手、部署 1 批处理管道和查询分页 — 并断言关联的证据、风险/响应记录、图形边缘和干净的 `graph verify`。eBPF 传感器在 Linux 主机上验证（`go generate ./internal/sensor`，然后运行 `agentprov-sensor`）。