Metadata-Version: 2.4
Name: agentrust-capture-core
Version: 0.1.0
Summary: Shared fingerprinting, comparison and baseline-sealing core for AgenTrust agent-integrity capture engines
Project-URL: Homepage, https://github.com/agentrust-io/integrations
Project-URL: Source, https://github.com/agentrust-io/integrations/tree/main/packages/agentrust-capture-core
Author-email: AgenTrust Contributors <oss@agentrust-io.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,agent-manifest,attestation,drift,integrity,trace
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# agentrust-capture-core

Shared fingerprinting, comparison and baseline-sealing core for AgenTrust
agent-integrity capture engines.

Each engine answers one question about a different coding agent:

> Is this the agent composition I approved, with nothing added and nothing
> subtracted?

What differs between agents is **where to look** and **what to call things**. What
must not differ is how content is fingerprinted, how snapshots are compared, how a
baseline is sealed, and the rules that keep a report honest. This package owns the
second list.

## Why it exists

Those parts lived in three copies, and the cost was not theoretical:

- The same skill-fingerprinting bypass had to be found and fixed **twice**,
  independently, in two shipped engines. A component was digested by its manifest
  alone, so a payload swapped into a sibling `scripts/` directory left the
  fingerprint unchanged and the report said "nothing added, nothing subtracted".
- A reporting defect that rendered **unmeasured** categories as measured zeros was
  fixed in one engine while the other kept shipping it.

A fourth engine would have meant writing both bugs a fourth time.

## What it does not do

No dependencies. The engines are invoked by shell hooks at session start and must
run before anything is installed, so this package is standard library only and a
test asserts it.

No opinion on where an agent keeps its files, what its categories are called, or
how its report is laid out. Baseline scoping in particular is deliberately not
unified: Claude Code keeps one baseline per machine, Codex keeps one per workspace
because a workspace carries its own instructions and skills. Both are correct for
their agent, so an engine supplies its own paths.

## The pieces

| Module | Owns |
|---|---|
| `hashing` | `tree_digest` over a component directory, file and mapping digests, the exclusion denylist, `uuid7`, `now_iso` |
| `seal` | Sealing a baseline with a content digest and checking it: `ok`, `unsealed`, `broken` |
| `compare` | Map, set, scalar and rollup diffs, plus observed-category and measurement-scope gating |
| `state` | Atomic write, load-corrupt-as-absent, sealed baseline write |
| `report` | The honesty vocabulary: unmeasured labelling, partial-coverage qualification, the baseline-integrity block |

## Two rules worth knowing before you use it

**An unmeasured category is not an empty one.** A shell hook cannot see a live tool
roster or the model. Rendering those as `0 tools` states a measurement that was
never taken, and a reader who cannot tell "we did not check" from "we checked and
found nothing" treats an absence as a pass. Use `measured_or` and
`unmeasured_footnote`.

**A partial check is not a clean bill of health.** `clean_verdict(complete=False)`
qualifies the verdict as "in the categories checked".

## On what sealing is worth

`attach_seal` stores a SHA-256 digest of the baseline's own content. It catches
corruption, truncation, and a hand-edit that does not recompute it. **It does not
catch an attacker who owns the state directory**, who can recompute the digest as
easily as this package can.

An earlier design used an HMAC with a locally stored secret. It was removed: the
only adversary an HMAC defeats here is one who can *write* the state directory
without being able to *read* it, which barely exists on a developer machine, and
the stored secret was a credential to leak in exchange.

The control that does survive a real adversary is off-box. Engines print the
baseline digest on approve and on verify, so a human who recorded the first sees a
silent re-baseline even when the attacker resealed it perfectly. There is a test
that makes this limit executable rather than prose.

## License

Apache-2.0.
