Matrix Scroll public whitepaper

Agent Attestation for Git Commits

Signed provenance for agent-assisted Git commits - verify offline, one command.

Agentic coding tools can create and push code without a durable, portable record of who acted or which tool produced the change. Matrix Scroll adds a signed commit envelope so teams can verify that provenance offline, in CI, or in a browser without trusting the IDE session that created it.

Scope and audience

Audience: engineers, DevSecOps teams, auditors, and OSS skeptics evaluating agent provenance.

Covers: why Git commits are the first wedge, what ships today, how to try it, and what is still in progress.

Does not cover: IAM replacement, prompt filtering, runtime sandboxing, or broader agent orchestration.

What Matrix Scroll is

Matrix Scroll is signed provenance for agent-assisted Git commits. It records a structured commit envelope with actor metadata and signs it with Ed25519 so the envelope can be checked locally, in CI, or in the browser.

Why start at the Git commit layer

Layer	Question answered	Why it matters
Commit time	Who acted, with which tool, before push?	Reviewers need evidence before build artifacts exist.
Artifact time	What did CI build and sign?	Best served by Sigstore, attestations, and SLSA.
Runtime	What code is executing in production?	Important, but outside Matrix Scroll's current scope.

Regulatory context

Matrix Scroll links its controls to the joint "Careful Adoption of Agentic AI Services" guidance. See the canonical mapping in AGENTIC_AI_SECURITY.md.

Protocol overview

Identity: an Ed25519 keypair plus a derived device identifier.
Commit envelope: canonical JSON with commit data and provenance metadata.
Verification: deterministic canonical bytes, detached signature check, offline verification path.

Canonical references: SPEC.md and commit-envelope.v1.json.

agent / IDE / CI
   |
   v
git commit --> post-commit hook signs envelope
   |
   v
.git/matrixscroll/envelopes/<sha>.json
   |
   v
matrixscroll envelope-verify <sha>

Implementation

1. Install

pip install "matrixscroll==0.6.0"
matrixscroll hook-install
matrixscroll hook-status

2. Agent provenance

export MATRIXSCROLL_ACTOR_TYPE=agent
export MATRIXSCROLL_TOOL=agent-runner
git commit -m "feat: agent-assisted change"
matrixscroll envelope-verify "$(git rev-parse HEAD)"

Hooks default to warn mode. Set "enforce": true in .git/matrixscroll/config.json to block commits when signing fails. Windows support landed in 0.2.1; the public examples on this page pin 0.5.0.

3. CI gate

- uses: SSX360/matrixscroll-verify-action@v1
  with:
    matrixscroll-version: "0.5.0"
    require-mode: emulated
    trusted-keys: trusted-keys.json

Policy flags such as --require-mode and --trusted-keys ship in the current 0.2.x line; public examples pin 0.5.0.

Trust levels

Level	Provider	Status
L1 Emulated	software key in the local Matrix Scroll profile	Shipping
L2 Enclaves	Secure enclaves, SSH-agent, HSMs	In progress
L3 Attested	Remote cryptographic attestation	Roadmap

Honest limits: Shipping now: PyPI 0.6.0, Git hooks, Scroll Gate PR verification, browser verifier. In progress: External Ed25519-capable key backends and transparency-log integrations. Not: IAM, sandbox, prompt filter, or agent runtime.

Next steps

Run the five-minute repo pilot: FIVE_MINUTES.md.
Wire the GitHub Action into a protected branch.
Use the browser verifier to inspect a sample or live envelope.
Compare the commit-time layer to artifact-time tools: matrixscroll.com/compare/.