# AgentProvenance > Security-oriented execution observability and Git-like provenance for sandboxed AI agents: verifiable evidence graphs for risk, replay, forensics, and audit. - **Type:** MCP server - **Install:** `agentstack add mcp-byteyellow-agentprovenance` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ByteYellow](https://agentstack.voostack.com/s/byteyellow) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [ByteYellow](https://github.com/ByteYellow) - **Source:** https://github.com/ByteYellow/AgentProvenance ## Install ```sh agentstack add mcp-byteyellow-agentprovenance ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. [](https://github.com/ByteYellow/AgentProvenance/releases/latest) [](https://go.dev/) [](https://github.com/ByteYellow/AgentProvenance/actions/workflows/ci.yml) [](https://www.docker.com/) [](https://www.sqlite.org/) [](LICENSE) **[Quickstart](#quickstart)** | **[Core Model](#core-model)** | **[Current Capability](#current-capability)** | **[Demo walkthrough](docs/interview-demo.md)** | **[Roadmap](#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: ```text 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](#why) - [Security Loop](#security-loop) - [Core Model](#core-model) - [White-box mode](#white-box-mode) - [Zero-SDK mode](#zero-sdk-mode) - [Relationship To Existing Systems](#relationship-to-existing-systems) - [Quickstart](#quickstart) - [Deployment Modes](#deployment-modes) - [Falco-compatible Receiver](#falco-compatible-receiver) - [Security Evidence Commands](#security-evidence-commands) - [External Evaluator Protocol](#external-evaluator-protocol) - [Compliance Evidence, Not Certification](#compliance-evidence-not-certification) - [AI-Callable Evidence Tools](#ai-callable-evidence-tools) - [Web Dashboard](#web-dashboard) - [Graph Commands](#graph-commands) - [Current Capability](#current-capability) - [Core Demo Acceptance](#core-demo-acceptance) - [Architecture](#architecture) - [Substrate Signals](#substrate-signals) - [Boundaries](#boundaries) - [Repository Layout](#repository-layout) - [Roadmap](#roadmap) - [Development](#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: ```text 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: ```text 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, and forensics/export foundations. Deeper eBPF receivers and Feishu/DingTalk response adapters belong to the next security-control phases. ## Core Model AgentProvenance supports two context modes. ### White-box mode An agent harness, SDK, tool router, or framework explicitly provides context: ```text run_id / session_id / attempt_id / tool_call_id / tool_name / args_hash ``` This gives high precision and fits custom coding-agent systems, Agentix-style harnesses, LangGraph-like workflows, and internal tool routers. ### Zero-SDK mode The user can run an agent command directly: ```sh agentprov record -- ``` The current MVP records a command in a working directory, snapshots the pre-execution file state, runs the command, computes post-execution file changes, and emits runtime file evidence into the DAG. The long-term zero-SDK path adds deeper process-tree and kernel telemetry capture. Zero-SDK inference uses runtime facts: ```text 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: ```sh agentprov telemetry bind --run --session \ --attempt --tool-call --process \ --container-id --cgroup-id --pid ``` Then raw events can be ingested without `tool_call_id`: ```sh agentprov telemetry ingest --raw-event raw-execve-1 --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` 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 Falco-compatible receiver path. It reads Falco JSON/stdout from a file or stdin stream, maps recognized `execve`, `open/openat`, and `connect` events into normalized runtime events, correlates them by PID/container/cgroup/time evidence, and then evaluates policy by default. Raw Falco rows do not need `tool_call_id`; ToolCallScope is recovered from the binding table when possible. ## 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 audit trail ``` ## Quickstart Prerequisites: - Go 1.23+ - Docker Desktop or a compatible Docker daemon ```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 ``` The quick path builds `agentprov`, records a command, explains the changed file, ingests filtered substrate telemetry, and runs the Phase 1 acceptance gate. `observe summary` is the run-level observability entry point: it summarizes application context, runtime telemetry coverage, risk, baseline, response, and top evidence refs before you drill into timeline or graph queries. `demo_telemetry_jsonl.sh` is the minimal substrate telemetry path. It binds a ToolCallScope, ingests Tetragon/Falco/LoongCollector fixture JSONL from `examples/telemetry/`, lists normalized events, and explains how one substrate event entered the DAG. `accept_phase1.sh` is the machine-checkable gate for the current MVP. `timeline` is the execution timeline surface. It merges application context, runtime telemetry, evidence, policy decisions, risk signals, baseline deviations, response actions, and external effects into one time-ordered view. `--view causality` groups rows into agent context, runtime process, runtime telemetry, evidence, risk/policy, and external-effect lanes, with correlation status and drill-down commands. The JSON output is designed to feed a future UI. ## Deployment Modes AgentProvenance is intentionally usable in three deployment shapes. RL, benchmark, and evaluator users should start with the first shape; enterprise security and audit users can move toward the later shapes when they need shared ingest, retention, and query services. | Mode | Shape | Best for | Tradeoff | |---|---|---|---| | Library / CLI-only recorder | one `agentprov` binary, optional Python helper, local SQLite/object store | RL rollout, evaluator jobs, benchmarks, CI, local red-team harnesses | easiest to adopt; weaker shared query and long-running ingest | | Sidecar / local daemon | `agentprov daemon serve` beside one worker or sandbox host; CLI/SDK acts as client | sandbox worker, CI runner, local security harness, medium-volume telemetry ingest | adds a local service boundary, spool, backpressure, and stable query API | | Central evidence service | shared ingest/query service with object storage, retention, auth, and UI/API | enterprise security, audit, SRE, compliance, incident review | highest operational cost; not the default RL entry point | For RL and evaluator pipelines, the default contract is lightweight and offline-first: - Install: one Go binary plus an optional thin Python package. - Call: wrap an existing command first; SDK/framework integration is optional. - Batch: every trajectory gets stable `run_id` / evidence manifest / signal context output, and query surfaces are paged. - Overhead: default capture focuses on process/file/diff/artifact/exit/resource evidence; heavier Falco/eBPF-style telemetry is an opt-in substrate. - Ownership: AgentProvenance emits evidence, deviation, risk, and trajectory signals. The RL system owns reward, ranking, dataset policy, and winner selection. - Policy: RL mode does not require online deny/kill/quarantine. Those actions are opt-in security controls; offline scoring can run later over captured EvalContext JSONL. Python usage stays thin and CLI-backed. For Deploy 1, the intended RL/evaluator entry point is one function … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [ByteYellow](https://github.com/ByteYellow) - **Source:** [ByteYellow/AgentProvenance](https://github.com/ByteYellow/AgentProvenance) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-byteyellow-agentprovenance - Seller: https://agentstack.voostack.com/s/byteyellow - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.