Skip to main content
Glama
kogunlowo123

Agent Action Provenance

by kogunlowo123
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Agent Action Provenance

Tamper-evident provenance for every action an AI agent takes. When an agent writes a FHIR task, changes infrastructure or releases a batch record, it (or the gateway in front of it) submits what it decided, the evidence it relied on and the authorization it acted under. The engine turns that into a W3C PROV record, checks it against governance rules, seals it into an append-only Merkle transparency log (RFC 6962 hashing, signed tree heads), writes a signed audit event, and returns an inclusion proof. Auditors export self-verifying evidence bundles and check them offline; independent monitors prove the log was never rewritten.

Decision ─▶ Evidence ─▶ Authorization ─▶ Audit Record
   │            │              │               │
   └── W3C PROV document ──────┴── governance ─┴─▶ Merkle leaf ─▶ signed tree head
                                                     │                 │
                                     inclusion proof ◀┘   consistency proof, WORM archive

Capabilities

Capability

Implementation

Provenance records

W3C PROV-JSON per action: decide / authorize / act activities, evidence and output entities, used, wasGeneratedBy, wasDerivedFrom, wasAssociatedWith (with the policy as prov:Plan), wasAttributedTo, actedOnBehalfOf for the delegation chain, wasInformedBy

PROV validation

Referential integrity, unique generation, acyclic derivation, activity time ordering

Governance checks

Executed without authorization, executed despite deny, approval missing / after execution / self-approval, authorization after execution, evidence after action, high-risk on untrusted or no evidence, classification downgrade

Transparency log

RFC 6962 / RFC 9162 Merkle tree in PostgreSQL; perfect-subtree node store, O(log n) proofs from one query; group commit batches records under one Ed25519 signed tree head

Proofs

Inclusion (audit path) and consistency proofs, verified exactly as RFC 9162 sections 2.1.3.2 and 2.1.4.2 specify; tested against the Certificate Transparency vectors and tamper cases

Signed evidence chain

agentic-core hash-chained, Ed25519-signed audit events for every record, decision, export and archive write

Self-monitoring

Recomputes the signed root from stored nodes, re-hashes the latest batch's records, proves append-only growth since the last check; detects edits, forged heads and rollbacks

Auditor export

Frozen record selection, policy-governed (RESTRICTED data or bulk exports need a second approver), self-verifying bundle

Verification CLI

provenance-verify bundle / consistency / monitor / archive / audit-chain / keygen, all against a pinned public key

WORM storage

S3 Object Lock (COMPLIANCE, conditional create, SHA-256 checksum) or write-once files shipped to immutable blob storage

Agent identity

Agents authorized through agent-identity-fabric (/oauth2/introspect, /v1/authorize); local JWKS verification plus policy when the fabric URL is not configured; never "allow all"

MCP

Six tools over streamable HTTP at /mcp (official mcp SDK), typed schemas, per-tool authorization and audit

A2A

Agent Card at /.well-known/agent-card.json; JSON-RPC message/send at /a2a

Lineage

Which actions, agents and evidence produced an artifact, transitively, by content digest

Shared controls (policy engine, audit chain, logging, telemetry, canonical JSON) come from agentic-core.

Related MCP server: ledger

Quick start (local)

Requires Docker. No API keys or cloud credentials are needed.

docker compose up --build
curl -s localhost:8080/v1/log/tree-head | jq
curl -s localhost:8080/.well-known/agent-card.json | jq .skills[].id

The compose stack runs PostgreSQL, an OIDC provider standing in for both the agent credential issuer and the auditors' IdP, and an OpenTelemetry collector.

Development

uv sync
make check        # ruff, black, mypy --strict, bandit, contracts, tests (coverage >= 90%)
make integration  # PostgreSQL concurrency test (needs PROVENANCE_TEST_DATABASE_URL)
make helm terraform audit-deps

Test suites: tests/unit (Merkle tree against RFC 6962 vectors and a direct transcription of the RFC definitions, PROV, governance, verification, adapters, CLI), tests/security (tampering, forged heads, rollback, credential attacks), tests/chaos (database, sequencer, identity fabric, audit sink and archive failures), tests/performance (proof and group-commit budgets; locustfile.py for load), tests/e2e (REST, MCP and A2A lifecycle, offline bundle verification, property-based OpenAPI contract test), tests/integration (two replicas appending concurrently to PostgreSQL).

API

Endpoint

Caller

Purpose

POST /v1/records

Agent or gateway (agent credential)

Seal an action; returns receipt, signed tree head, inclusion proof

GET /v1/log/tree-head[?tree_size=]

Anyone

Latest (or historical) signed tree head

GET /v1/log/proof/inclusion?leaf_index=&tree_size=

Anyone

RFC 6962 audit path

GET /v1/log/proof/consistency?first=&second=

Anyone

RFC 6962 consistency proof

GET /v1/log/entries?start=&end=

Anyone

Leaf hashes and record IDs

GET /v1/log/public-key

Anyone

Log ID and Ed25519 public key

GET /v1/records, /v1/records/{id}, /v1/records/{id}/verification

Auditor (provenance-auditor)

Search, read, verify

GET /v1/lineage/{sha256:...}

Auditor

Artifact lineage

POST /v1/exports, GET /v1/exports/{id}, POST /v1/exports/{id}/approve, GET /v1/exports/{id}/bundle

Auditor, approver (provenance-approver)

Governed evidence export

POST /mcp

Agents

MCP tools: record_action, get_tree_head, get_inclusion_proof, get_consistency_proof, verify_record, trace_lineage

GET /.well-known/agent-card.json, POST /a2a

Agents

A2A skills: record-action, verify-record, inclusion-proof, consistency-proof

Log reads are unauthenticated by design: they reveal hashes only, and a transparency log is only useful if anyone can check it. Full contract: docs/api/openapi.json; JSON Schemas in schemas/.

Verifying evidence offline

provenance-verify bundle bundle.json --public-key log.pub.pem
provenance-verify monitor --url "$PROVENANCE_URL" \
  --public-key log.pub.pem --state monitor-state.json   # run on a schedule

Deployment

Layer

Location

Container image

Dockerfile (non-root uid 10001, read-only root filesystem compatible)

Helm chart

deployments/helm/agent-action-provenance (StatefulSet, PDB, HPA, NetworkPolicy, ServiceMonitor, Ingress)

Namespace and secret sync

deployments/kubernetes (restricted Pod Security, default-deny, External Secrets)

Cloud infrastructure

deployments/terraform/{aws,azure,gcp}: managed PostgreSQL, KMS, secret store, WORM archive, workload identity. AWS is the reference deployment

See the startup runbook.

Documentation

License

Apache-2.0

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Witness

    MaximilianoColoma
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides evidence-oriented MCP service for cryptographically identified agents, bounded public contracts, privacy-preserving records, and append-only audit.
    Apache 2.0

  • Living Stack Community

    equinoxaifinance-rgb
    A
    license
    A
    quality
    B
    maintenance
    Free seven-tool proof loop for MCP agents: scoped sessions, bounded authorization, typed outcomes, evidence-bound claims, and tamper-evident local closure. Upgrade to Complete Local for durable memory, recovery, signed traces, release verification, and multi-agent workflows.
    7
    Apache 2.0