AgentProvenance

Correlate application context with system telemetry into a verifiable, signable causality graph for sandboxed agents.

Correlate application-side agent context with system-side telemetry, then turn runtime evidence, file diffs, artifacts, risk signals, and response decisions into a queryable, replayable, and auditable causality graph. Evidence is stored content-addressed and hash-verified (a model borrowed from Git) and can be signed for tamper-evidence -- but this is an audit/provenance layer, not a version-control system: there is no merge, checkout, or mutable working tree.

Quickstart | Core Model | Current Capability | Demos | Roadmap

---

AgentProvenance is a local-first security and provenance control plane for autonomous, tool-using agents, especially sandboxed coding agents. It captures system telemetry from its own eBPF sensor (or ingests Falco/Tetragon), correlates it with app-side agent context into a verifiable, signable causality graph, and serves that graph over the CLI, a daemon API, AI tools (including an MCP server), and a local web dashboard.

It is not a generic sandbox runtime, generic telemetry collector, Kubernetes/Ray replacement, RL trainer, trace dashboard, or version-control system (it borrows Git's content-addressing and verification model, not its branch/merge workflow). It owns a narrower primitive:

Execution Context
  -> Evidence Ingest
  -> Runtime Causality Graph
  -> Provenance DAG
  -> State Diff / Blame / Artifact Lineage
  -> Security Analysis / Risk Decision
  -> Taint / Response Action
  -> Replay / Forensics / Audit Manifest

The goal is to answer questions ordinary traces do not answer well:

• Which snapshot did this execution start from?
• Which attempt produced this artifact?
• Which tool call started this process?
• Which child process caused this runtime event?
• Which process changed this file?
• Which behavior is anomalous for this agent or task profile?
• Which execution branch was tainted, quarantined, interrupted, or blocked by a response gate?
• Which evidence supports a risk decision?
• What response action should be triggered: audit, deny, kill, quarantine, taint, export forensics, or notify a human through Feishu/DingTalk?
• What exact behavior evidence, deviation signal, and risk context should an external evaluator, RL pipeline, or human reviewer inspect?
• Can this execution be diffed, blamed, verified, replayed, and audited later?

Contents

• Why
• Security Loop
• Core Model
• Evidence layers
• Runtime facts and correlation
• Relationship To Existing Systems
• Quickstart
• Deployment Modes
• Security Evidence Commands
• External Evaluator Protocol
• Compliance Evidence, Not Certification
• AI-Callable Evidence Tools
• Web Dashboard
• Graph Commands
• Current Capability
• Core Demo Acceptance
• Architecture
• Substrate Signals
• Boundaries
• Repository Layout
• Roadmap
• Development

Why

Modern agent execution is not one prompt and one tool call. Coding agents and autonomous workflows fork attempts, edit files, run tests, create artifacts, spawn subprocesses, touch external systems, and trigger runtime telemetry. Logs, traces, metrics, and sandbox events each capture pieces of that story, but they rarely produce a Git-like causal record of execution state.

AgentProvenance turns sandboxed execution into a security-oriented evidence graph:

base snapshot
  -> attempt
  -> execution context
  -> tool_call
  -> process / child process
  -> runtime_event
  -> file_diff / artifact
  -> baseline feature / risk signal
  -> taint / response action
  -> replay / forensics / audit manifest

The primary path is recording and explaining sandboxed agent execution. The branch-heavy coding-agent script is only a stress demo: it creates many branches, artifacts, runtime events, and risk cases quickly enough to exercise the graph. AgentProvenance does not choose the reward winner. It emits structured trajectory evidence and expectation-deviation signals so an external evaluator or training pipeline can turn them into reward, penalty, filtering, or human-review decisions.

For RL pipelines, the useful primitive is not "best-of-one" or automatic winner selection. The useful primitive is observability over each trajectory: what the agent did, which subprocesses and files were touched, which network/runtime events appeared, which behavior violated safety or task expectations, and which risk/baseline signals should contribute to reward shaping or rejection.

Security Loop

The security model is intentionally simple and concrete:

application context
  run / session / attempt / 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 / Feishu or DingTalk notification

This makes AgentProvenance closer to an AI-era HIDS/control-plane layer than a pure LLM trace dashboard. Traditional host monitoring asks "what did this process do?" AgentProvenance adds the agent execution context needed to ask "which agent/tool/task caused it, what state did it change, what evidence proves it, and what response should happen?"

The project currently implements the evidence graph, runtime correlation, diff/blame, telemetry batch manifests, policy decisions, normalized risk signals, baseline deviation records, response action records, taint, quarantine, forensics/export foundations, and a native eBPF sensor. Feishu/DingTalk response adapters belong to the next security-control phases; third-party receivers (Falco/Tetragon) are maintained for compatibility, not extended.

Core Model

AgentProvenance is not "pick an integration mode." It is layered evidence with one entry point: wrap the command you already run.

agentprov record -- <agent command>

record snapshots the pre-execution file state, runs the command, samples the process tree, computes post-execution file changes, and emits runtime evidence into the DAG — no integration code required. Everything else stacks on top of that base automatically.

Evidence layers

Layer	Source	Trust semantics
Kernel / runtime facts (foundation)	record process tree + file diffs, native eBPF sensor, Falco/Tetragon/LoongCollector receivers	hard facts keyed by pid / cgroup / container / time; the agent cannot fabricate them
Application context (enrichment)	harness hooks (hooks bridge), MCP context-write (bind_scope / record_tool_call), explicit run_id / session_id / attempt_id / tool_call_id / tool_name / args_hash	semantics the kernel can never infer — agent identity, delegation and peer messages, refused intents; app-asserted claims carry binding_source=ai_asserted and a <=0.5 confidence cap, and never override kernel facts

The kernel layer answers "what actually happened on this host." The application-context layer answers "which agent, which tool call, which intent" — including things no syscall stream can express, such as an orchestrator's agent_spawn/agent_message edges or an attempt the LLM refused to execute. Application context is not a separate deployment or a required SDK: when a harness emits hooks or calls the MCP context-write tools, the enrichment layer attaches to the same run; when it doesn't, the kernel layer still stands on its own.

Runtime facts and correlation

Correlation back to execution context uses runtime facts:

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

Raw system-side telemetry should not be required to carry tool_call_id. Kernel and runtime signals usually know PID, cgroup, namespace, container ID, timestamp, and process tree. AgentProvenance correlates those substrate facts back to execution context.

Today, the CLI exposes the underlying binding primitive:

agentprov telemetry bind --run <run_id> --session <session_id> \
  --attempt <attempt_id> --tool-call <tool_call_id> --process <process_id> \
  --container-id <container_id> --cgroup-id <cgroup_id> --pid <pid>

Then raw events can be ingested without 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 records a telemetry batch manifest with the input file hash, mapped event IDs, event ID hash, receiver summary, and row-level mapping results. By default it also evaluates runtime policy for ingested events, so metadata-IP, private-CIDR, and secret-path rows become policy_decisions, risk_signals, response_actions, graph edges, and timeline rows. Use --no-policy when the receiver should only normalize and store telemetry. This gives the DAG an audit handle for external Falco/Tetragon/LoongCollector evidence without turning AgentProvenance into a long-term log store.

The native format is the receiver for AgentProvenance's own eBPF sensor (cmd/agentprov-sensor, source="agentprov_ebpf"), and is auto-detected. This closes the consume-only gap: the sensor's normalized kernel events (execve, network connect classified into metadata_ip/private_cidr, file writes with their real absolute host paths) flow through the identical correlation, policy, risk, and unified-signal path as third-party telemetry. Raw file telemetry now accepts absolute host paths (e.g. a write to /home/agent/.aws/credentials), which the policy path rules still catch; only the workspace file-node graph keeps its relative-path constraint. scripts/accept_native_sensor_risk.sh proves the loop end to end (own kernel telemetry to a unified security signal).

ingest-falco is the compatibility receiver for hosts that already run Falco (or where the native sensor cannot run); it folds Falco JSON/stdout streams into the same correlation/policy path. Details: docs/falco-receiver.md.

Relationship To Existing Systems

AgentProvenance is designed to coexist with system-level observability projects, LLM tracing systems, and sandbox runtimes.

System category	What it owns	How AgentProvenance differs
system observability	low-intrusion system-side capture, eBPF/runtime event collection, cross-process visibility	AgentProvenance treats those events as evidence input, then builds a Git-like causality/provenance DAG, diff/blame, taint lineage, risk decision, forensics, and response-control surface
OpenTelemetry / LLM trace platforms	spans, logs, metrics, LLM/tool traces, dashboards, latency/cost views	AgentProvenance focuses on state provenance, artifact lineage, sandbox runtime effects, security decisions, replay, and audit manifests
HIDS / EDR / runtime security	host/process/file/network detection and enforcement	AgentProvenance adds agent context: run/session/attempt/tool_call, snapshot lineage, file diffs, artifact provenance, risk signals, baseline deviations, and response gates
Sandbox runtimes	isolation, process/container/VM execution, filesystem and network boundaries	AgentProvenance consumes sandbox identity and telemetry; it does not try to replace Docker, OpenSandbox, gVisor, Firecracker, Kata, or Kubernetes

So the differentiation is not "another zero-SDK eBPF observer." The narrow primitive is:

```text system-side telemetry + application-side agent context -> evidence DAG -> security analysis and risk judgment -> automated response and audi