Bind AI and research artifacts to the exact source bytes that produced them.
ProvBind is a small, local-first provenance verifier for AI agents, research pipelines, coding agents, and automated reports. It creates a closed JSON manifest that binds an artifact to one or more source files using SHA-256 digests and an independently recomputable binding_id.
pip install provbind0.2.0 is the current PyPI and GitHub release. It defaults new seals to
provbind-manifest-v2while continuing to verify frozen v1 manifests.
Already tried it? File an Integration report for an actual success or failed attempt. Still deciding where it fits? Join the workflow feedback. Want a focused first contribution? Windows path conformance coverage is unassigned and labeled good first issue / help wanted.
If an agent says “this output was based on these sources,” ProvBind turns that claim into something another process can verify later.
ProvBind proves byte identity and binding. It does not prove that a source is true, that an agent reasoned correctly, that a person authored a file, or that a timestamp is externally trusted.
Create one source and one derived artifact:
printf 'source bytes\n' > source.txt
printf 'derived output\n' > report.mdSeal the exact bytes and verify them:
provbind seal report.md --source source.txt -o provbind.json
provbind verify provbind.jsonExpected result:
PASS artifact:report.md — artifact bytes match
PASS local_file:source.txt — source bytes match
VERIFIED
Now change the artifact:
printf '\ntampered\n' >> report.md
provbind verify provbind.jsonProvBind fails closed with NOT VERIFIED and exit code 2.
The agent produces the artifact; ProvBind independently binds the result to the inputs that actually exist afterward:
Codex / another agent
│
│ produces artifact
▼
exact artifact bytes ─────┐
│
exact source bytes ───────┼──> ProvBind manifest
│
▼
independent verify
A complete Codex example is in examples/codex, including:
- a constrained prompt;
- a credential-free checked-in provenance fixture;
- a workflow using the official
openai/codex-action@v1interface; - a CI-enforced intentional tamper failure.
The core verifier has no model-vendor dependency. The same seal and verify flow works for outputs produced by people, scripts, Codex, or other agents.
Agent workflows increasingly read files, Git repositories, documents, and research inputs before producing code or reports. A normal output file does not preserve enough evidence to answer basic questions later:
- Was this the exact source file the agent used?
- Did a GitHub source come from a fixed commit, or from a branch that later moved?
- Did the source change after the output was produced?
- Did someone edit the provenance record itself?
- Can CI fail closed when the evidence shape is unknown?
ProvBind turns those questions into deterministic checks.
GitHub sources must use an exact 40-hex commit SHA. Branches, tags, and abbreviated SHAs are rejected.
provbind seal report.md \
--github-source openai/openai-python@0123456789abcdef0123456789abcdef01234567:README.md \
-o provbind.jsonFor private repositories, set GITHUB_TOKEN in the environment.
In v0.2, a v2 GitHub source records and verifies both portable byte identity and Git-native repository membership:
- exact commit SHA;
- root tree SHA;
- path resolved through tree objects;
- final Git blob SHA and regular-file mode;
- Git blob SHA-1 recomputed from the returned blob bytes;
- SHA-256 and byte size over those same bytes.
The release-gate fixture in examples/github-v2 exercises this path against the real public GitHub API using the immutable v0.1.0 release commit, and CI requires the independently observed blob identity to match before verification succeeds.
This is intentional:
main -> rejected
v1.2.3 -> rejected
abc1234 -> rejected
40-hex commit SHA -> accepted
A provenance record should bind immutable source identity, not a mutable name.
Create a new manifest. In v0.2, v2 is the default; use --schema v1 only when you explicitly need the frozen legacy output shape.
provbind seal ARTIFACT \
--source LOCAL_SOURCE \
--github-source OWNER/REPO@COMMIT:PATH \
--root . \
-o provbind.json
provbind seal ARTIFACT --source LOCAL_SOURCE --schema v1 -o provbind-v1.jsonBoth --source and --github-source are repeatable. At least one source is required.
Recompute artifact and source evidence and compare it with the sealed claims. Verification is schema-driven, so existing v1 manifests remain supported while v2 GitHub sources use the stronger Git object chain.
provbind verify provbind.json --root .
provbind verify provbind.json --root . --jsonExit codes:
0: verified2: invalid manifest, unavailable evidence, repository-membership mismatch, or byte mismatch
Inspect a manifest without fetching or re-reading its sources.
provbind inspect provbind.jsonFor v2 GitHub sources, inspection includes the sealed tree SHA, blob SHA, and Git file mode.
Compare two valid manifests.
provbind diff old.json new.jsonThe diff reports artifact changes and source additions, removals, or changes.
ProvBind supports two closed schema versions:
provbind-manifest-v1— frozen v0.1 byte-binding contract;provbind-manifest-v2— v0.2 contract with Git-native identity for GitHub sources.
A v1 manifest looks like this:
{
"schema_version": "provbind-manifest-v1",
"binding_id": "...",
"created_at": "2026-08-08T01:00:00Z",
"artifact": {
"path": "report.md",
"sha256": "...",
"size": 15
},
"sources": [
{
"kind": "local_file",
"path": "source.txt",
"sha256": "...",
"size": 13
}
],
"producer": "provbind/0.1.0"
}A v2 github_file source additionally seals git_tree_sha, git_blob_sha, and git_mode alongside the exact commit/path and SHA-256/size.
binding_id is the SHA-256 of ProvBind's canonical JSON encoding of:
schema_version + artifact claim + ordered source claims
created_at is intentionally excluded from binding_id, so the same artifact/source claim has the same binding identity even if the manifest is regenerated at a different time.
The schemas are published at schemas/provbind-manifest-v1.schema.json and schemas/provbind-manifest-v2.schema.json. Runtime validation is implemented without third-party dependencies and is stricter than simply parsing JSON.
ProvBind intentionally accepts a small closed evidence model:
local_filegithub_file
Unknown top-level fields are rejected. Unknown fields inside artifact/source objects are rejected. Unknown source kinds are rejected. Duplicate source identities are rejected. Parent-directory traversal in local paths is rejected. GitHub mutable refs are rejected. In v2, symlink/submodule/tree final objects are also rejected until they have an explicit reviewed contract.
New source types should be introduced through a new reviewed schema/version rather than silently accepted by old verifiers.
The v0.2.0 composite Action is addressed by its release tag:
- uses: yunying24/provbind@v0.2.0
with:
manifest: provbind.json
root: .The existing v0.1.0 tag remains available for workflows intentionally pinned to the v0.1 implementation.
The action installs ProvBind from the checked-out action source and runs verification. A failing binding fails the workflow.
You can also install the CLI directly in any CI system:
- run: pip install provbind
- run: provbind verify provbind.json --root .ProvBind is designed to detect:
- source bytes changing after a manifest was created;
- artifact bytes changing after a manifest was created;
- provenance claim edits that are not accompanied by a recomputed binding;
- use of mutable GitHub refs in a byte-binding claim;
- malformed or unexpectedly widened manifest shapes;
- in v2, mismatch between exact commit/tree/path/blob membership and the sealed GitHub claim.
ProvBind does not currently defend against an attacker who can replace the artifact, every source, and the manifest together. That requires an external trust anchor such as a signed release, transparency log, trusted CI attestation, or another independent publication channel. Those are roadmap items, not current claims.
- Exact bytes over labels. A source name is not evidence of source identity.
- Immutable refs over mutable refs. GitHub bindings use exact commit SHAs.
- Closed schemas over permissive parsing. Unknown evidence shapes fail closed.
- Separate verification from correctness. Matching bytes do not make content true.
- Local-first verification. Local-file verification requires no service or account.
- Small trusted core. ProvBind has zero runtime Python dependencies.
- bind an AI-generated research memo to its input corpus;
- bind a coding-agent patch/report to exact repository files;
- preserve source identity for automated market or technical reports;
- fail CI when evidence or generated outputs drift;
- attach a portable provenance manifest to releases or audit artifacts.
examples/basic— minimal local-file example.examples/codex— agent generation + independent provenance verification.examples/github-v2— real public exact-commit Git tree/blob membership verification.
provbind verify examples/basic/provbind.json --root examples/basic
provbind verify examples/codex/provbind.json --root examples/codexProvBind is alpha. Version 0.2.0 is the current PyPI and GitHub release. It shipped after completing the v2 Git identity gate: 72 compatibility/adversarial tests, package smoke testing, the Codex positive/tamper contract, a real public exact-commit GitHub v2 fixture, CodeQL, and post-publication verification of PyPI distribution hashes and the tagged Action.
See ROADMAP.md for planned work, including signed attestations, HTTP content-addressed sources, reusable policy profiles, and integrations for coding/research agents.
Issues, test cases, source adapters, security review, and integration examples are welcome. See CONTRIBUTING.md.
Please report security-sensitive findings privately as described in SECURITY.md.
MIT. See LICENSE.