matrixscroll
This server provides offline signing, verification, and auditing of provenance records for Git commits, actions, MCP tool surfaces, and agent traces.
Create and verify Ed25519-signed Git commit envelopes (
create_envelope,verify_envelope)Verify commit ranges for PR/merge gates (
verify_pr_range) with local, notes, bundle, or hosted modesPublish envelopes to Git notes (
publish_notes)Sign arbitrary CI/IaC/API action payloads (
sign_action)Export audit bundles in JSON, GUAC, or evidence-pack formats (
audit_export)List hosted organization envelopes (
list_envelopes) — requires SSX360_API_KEYReport local status, hook state, and envelope count (
status)Probe SE050/AP2 hardware signing bridge (
connect_card)Scan, sign, and verify MCP server tool-surface manifests (
scan_mcp_server,sign_mcp_manifest,verify_mcp_manifest)Sign and verify browser-agent JSONL traces (
sign_agent_trace,verify_agent_trace)
Provides tools for signing and verifying commit provenance using Ed25519 signatures, enabling proof of authorship for agent-assisted Git commits.
Integrates with GitHub via a GitHub Action for verifying commit provenance in PRs, and provides browser verification of commit envelopes.
Provides a GitHub Action for verifying commit provenance in CI pipelines, ensuring every commit in a PR range is signed before merge.
Supports hardware-backed signing using the NXP SE050 secure element for enhanced trust, available as a preview upgrade.
Matrix Scroll
Signed machine-action records with offline verification for MCP, Git, and CI.

Shipping / Bar. Shipping: raw event → domain-separated hash (matrixscroll.ledger) → time-epoch checkpoints → Ed25519 signature with optional FIPS 204 ML-DSA overlay. Bar: ML-DSA-only primary mode as default, Lean 4 / F* extracted verifier. Reviewers verify offline. Results are CONSISTENT, INCONSISTENT, or INDETERMINATE. AI never enters the verified core and never decides a technical conclusion. Full mapping: docs/explanation/gold-standard.md.
An MCP server can change its tool descriptions or input schemas after installation. A Git commit can also declare an actor or tool without carrying a signed authorization record. Matrix Scroll records both surfaces as Ed25519-signed evidence that reviewers can verify offline, with an optional ML-DSA-87 post-quantum overlay and ML-KEM-1024 sealed evidence packs on the CNSA 2.0 Category 5 track.
The matrixscroll-mcp stdio server exposes 13 tools for commit envelopes, action records, pull-request checks, Git notes, MCP surface manifests, and agent traces. Custody is device-agnostic: the default is a file-backed software provider, and any device or HSM plugs in through the IdentityProvider seam. Local signing and verification need no cloud account.
Matrix Scroll is an open protocol. The Python SDK is Apache-2.0 software, and the specification and vectors are CC0 1.0.
Contents
Related MCP server: FlowCheck MCP Server
Gold standard
Three pillars and one refusal rule govern the protocol:
Pillar | Requirement |
Post-quantum proofs | FIPS 204 ML-DSA and FIPS 205 SLH-DSA overlays so attestation survives the quantum computers the programme monitors (parameter readiness through liboqs; not FIPS CMVP or CNSA certification) |
Offline verification | An auditor reconstructs events from raw records offline. Shipping: independent verifier + TLC. Bar: Lean 4 / F* extracted executable |
Fail-closed architecture | Every result is CONSISTENT ( |
Rule of Refusal. We refuse to accept AI-generated or AI-altered data into the verified core. The provenance of every artifact is digest-pinned. No AI system is a decision authority for any technical conclusion.
See docs/explanation/gold-standard.md and docs/DOCTRINE.md.
Install the MCP server
Install the current release from PyPI:
pip install "matrixscroll[mcp]==0.10.0"Register the stdio server in your MCP client:
{
"mcpServers": {
"matrixscroll": {
"command": "matrixscroll-mcp",
"args": []
}
}
}On Windows, use the full path to matrixscroll-mcp.exe inside the active virtual environment if the command is not on PATH.
Start the executable directly when you want to inspect the server over stdio:
matrixscroll-mcpAfter your client connects, call status. The server reports the local identity, hook state, and envelope count.
MCP tools
The 0.10.0 server exposes these tools:
Tool | What it does | Network or write behavior |
| Reports local identity, hook state, and envelope count | Read-only and local |
| Creates an Ed25519-signed Git commit envelope | Writes a local envelope by default |
| Verifies one signed envelope and its policy fields | Read-only and local |
| Signs provenance for CI, infrastructure changes, migrations, API calls, or other actions | Writes only when |
| Checks every commit in a Git range | Local for |
| Publishes local envelopes to | Writes local Git notes |
| Exports evidence for review | Writes a local bundle or uses the hosted API when configured |
| Lists organization envelopes | Requires |
| Fingerprints MCP tool names, descriptions, and input schemas | Read-only when tools are supplied |
| Signs an MCP tool-surface manifest | Writes only when |
| Verifies a manifest and compares it with a signed baseline | Read-only and local |
| Signs a browser-agent JSONL trace | Writes a signed envelope |
| Verifies a signed trace and optionally checks the source bytes | Read-only and local |
An API key is optional. Local signing, offline verification, and MCP manifest checks do not require one. Hosted organization history and hosted range verification use SSX360_API_KEY.
Detect MCP tool-surface changes
Matrix Scroll records an MCP server's tool names, descriptions, and input schemas in a signed manifest. Re-scan the server after an update and compare it with the install-time baseline.
pip install "matrixscroll[mcp]==0.10.0"
matrixscroll mcp scan \
--connect stdio \
--server-command "npx -y some-mcp-server" \
--output manifest.json \
--pretty
matrixscroll mcp sign manifest.json \
--output baseline.signed.json
matrixscroll mcp scan \
--connect stdio \
--server-command "npx -y some-mcp-server" \
--output current.json
matrixscroll mcp sign current.json \
--output current.signed.json
matrixscroll mcp verify current.signed.json \
--baseline baseline.signed.json \
--prettyThe verify command exits with code 2 when the signature is invalid or the current tool surface differs from the signed baseline. You can also scan an exported tools/list response without starting a server:
matrixscroll mcp scan --tools tools.json --output manifest.json --prettyDevice-agnostic custody
Signing goes through an IdentityProvider (public_key_bytes, sign, mode). The default emulated provider stores an Ed25519 key under ~/.matrixscroll. To adapt Matrix Scroll to any device or HSM, implement that interface and select it with MATRIXSCROLL_MODE (or pass a provider instance to the library APIs). Experimental tpm and yubikey previews remain available; they are not the Category 5 story and do not claim hardware ML-DSA.
Historical envelopes with signature.mode equal to "hardware" still verify. The USB/SE050 signing path was removed in 0.10.0; MATRIXSCROLL_MODE=hardware raises instead of opening a serial port.
Sealed evidence packs (matrixscroll.sealed) encrypt a payload to a recipient's ML-KEM-1024 key with a hybrid X25519 + ML-KEM-1024 agreement, AES-256-GCM for the body, and Ed25519 plus ML-DSA-87 signatures over the pack. Install matrixscroll[pqc]. This is parameter-set readiness through liboqs, not a CNSA certification or FIPS validation.
Sign and verify from the CLI
The Python package includes a CLI and Git hooks for workflows that do not use MCP.
pip install "matrixscroll==0.10.0"
matrixscroll hook-install
export MATRIXSCROLL_ACTOR_TYPE=ci
export MATRIXSCROLL_TOOL=release-runner
git commit -m "feat: automate release"
matrixscroll envelope-verify "$(git rev-parse HEAD)"Sign a JSON manifest directly:
matrixscroll sign release.json > release.signed.json
matrixscroll verify release.signed.jsonmatrixscroll verify exits with code 0 for a valid signature and code 2 for invalid input, a failed signature, a mismatched device identity, or an unsupported schema or algorithm.
Verification boundaries
Release: PyPI
matrixscroll==0.10.0installs the 13-tool stdio MCP server and Git hooks, the MCP Trust Scanner, offline verification, sealed evidence packs, and device-agnostic custody.Hosted tools:
list_envelopesand the hosted modes ofverify_pr_rangeandaudit_exportrequireSSX360_API_KEYand a deployed SSX360 API. Local signing and verification remain available without a key.Post-quantum evaluation path: the optional
matrixscroll[pqc]extra provides ML-DSA and SLH-DSA through liboqs, including Category 5 sets (ml-dsa-87,slh-dsa-sha2-256s/256f). Release0.10.0defaults new software keys toml-dsa-87for CNSA 2.0 signature-parameter alignment (0.7.0and earlier default toml-dsa-65; pass--algorithmorMATRIXSCROLL_PQCto choose a set explicitly). That is parameter-set readiness, not CNSA certification, FIPS CMVP validation, or NSA approval. This module has no CMVP validation. liboqs states that applications should not rely on it to protect sensitive data in production.CNSA 2.0 full-suite track:
matrixscroll.kemprovides ML-KEM-1024 primitives (ACVP-checked). Sealed evidence packs inmatrixscroll.sealeduse hybrid X25519 + ML-KEM-1024 with Ed25519 + ML-DSA-87. Same boundary as the signature overlay: evidence mapping against NIST vectors, not a validation. Seedocs/CRYPTO_ROADMAP.md.Verification scope: an Ed25519 signature proves that the signed bytes match and correspond to the included public key. A trusted-key and authorization policy establishes whether the declared
actor_typecan perform the action.Adjacent controls: identity and access management, sandboxing, prompt filtering, and agent runtime policy remain separate controls.
Verify the release
GitHub Actions publishes each Matrix Scroll release through PyPI Trusted Publishing. PyPI records a PEP 740 attestation for the wheel and source distribution.
Ask PyPI for the 0.10.0 wheel provenance:
curl -H "Accept: application/vnd.pypi.integrity.v1+json" \
https://pypi.org/integrity/matrixscroll/0.10.0/matrixscroll-0.10.0-py3-none-any.whl/provenanceThe response names the GitHub publisher:
{
"kind": "GitHub",
"repository": "SSX360/matrixscroll",
"workflow": "publish.yml",
"environment": "pypi"
}Compare the attested subject[].digest.sha256 value with the SHA-256 digest of the file you downloaded. Stop if the repository, workflow, or digest differs.
Ten-minute check for reviewers
Five questions a programme manager or auditor asks first, each with the command that answers it. Everything below runs offline from a clone of this repository with pip install "matrixscroll[pqc]==0.10.0" (the pqc extra is needed only for the last two lines of question 3).
Does it run in one command, offline?
matrixscroll verify vectors/valid_simple.jsonprints"ok": trueand exits0;matrixscroll verify vectors/tampered_field.jsonprints"ok": falseand exits2. Neither command opens a network connection. Exit codes are fixed in docs/reference/exit-codes.md.Is there a second implementation of the verifier?
python tools/independent_verify.py vectors/re-implements SPEC.md sections 3 to 6 from the text, with its own canonical serializer and a pure-Python RFC 8032 Ed25519, and imports nothing from the SDK. It must reach the same verdict as the SDK on every committed vector and on 500 randomly generated documents;tests/test_independent_verifier.pyenforces that in CI on every change.Are the vectors committed?
vectors/valid_*.json,tampered_*.jsonandunsigned_*.jsonare the conformance set (CC0 1.0);vectors/acvp-sigver-fips204-fips205.jsonandvectors/acvp-mlkem-fips203.jsonare NIST ACVP sample vectors with source URLs and SHA-256 digests.python -m pytest tests/test_vectors.py tests/test_independent_verifier.py -qruns the conformance set;python -m pytest tests/test_acvp_sigver.py tests/test_acvp_mlkem.py -qruns the NIST vectors through liboqs.Is the boundary stated? Verification boundaries above, docs/CRYPTO_ROADMAP.md (Shipping now / In progress / Not, with policy dates) and docs/COMPARISON.md (a dated landscape and the claims Matrix Scroll does not make). Compliance language everywhere is evidence mapping, not a certification claim.
Are the design rules checked by a model checker?
formal/tla/holds TLA+ models of the canonical bytes, the dual signature and the Scroll Gate range rules;.github/workflows/formal-verify.ymlruns TLC on all seven configurations on every change to them. The models check the design, not the Python implementation; the tests above check the implementation. docs/WHITEPAPER.md is the written account of the protocol.
Security and license
Read the security policy and security properties. Report vulnerabilities privately to security@matrixscroll.com or through a GitHub Security Advisory.
Matrix Scroll code is licensed under Apache-2.0. SPEC.md and vectors/ are released under CC0 1.0.
Resource | Link |
Gold standard (formal mathematics of accountability) | |
Release evidence (digests, provenance, PQC boundary) | |
Tombstone / schemas | |
Documentation | |
Where Matrix Scroll fits (dated comparison) | |
Cryptographic roadmap (Ed25519, ML-DSA-87 overlay, policy dates) | |
Offline verification | |
Protocol specification | |
Source repository | |
SSX360 contact |
Available Tools
13 toolsaudit_exportA
Export a compliance or procurement audit bundle with optional verification proofs.
Use when auditors need envelope bundles (JSON, GUAC JSONL, or evidence-pack).
Prefer ``verify_pr_range`` for merge-gate pass/fail on a commit range.
Prefer ``list_envelopes`` to browse hosted metadata without exporting files.
Hosted mode requires SSX360_API_KEY and calls ssx360.com/api/v1/audit/export.
Local fallback: exports from git notes or on-disk envelopes when no API key.
Side effects: writes files under ``output_dir`` locally; hosted mode returns
download metadata. Returns ``{ok, bundle?, download_url?, error?}``.
Parameters:
start_date / end_date: ISO 8601 UTC bounds (hosted filter).
signer_id: Filter by device_id or public-key fingerprint.
format: json, guac, or evidence-pack serialization.
include_verification: Attach per-envelope verification replay data.
workspace / base / head / output_dir: Local fallback range and output path.
Inputs: base, head, format, end_date, +5 more. Returns: object
create_envelopeA
Create a signed Git commit envelope with Ed25519 provenance metadata.
Use after staging changes and before or after ``git commit`` when you need
commit-time actor/tool proof. Prefer ``sign_action`` for non-Git evidence
(CI steps, IaC, migrations). Do not use for verification — call
``verify_envelope`` or ``verify_pr_range`` instead.
Side effects: may write ``.matrixscroll/envelopes/<sha>.json`` when ``save``
is true. Requires a Git repo and Matrix Scroll identity store. No network.
Returns ``{ok, sha, envelope, path, error?}``.
Parameters:
workspace: Git repo root (defaults to detected repo).
commit_sha: Existing commit to envelope (defaults to staged/next commit).
actor_type: Provenance actor, e.g. agent, human, ci.
tool: Producing tool name, e.g. cursor, claude-code.
agent_scope: Optional bounded scope path/glob for agent commits.
sign: Ed25519-sign the envelope (default True).
save: Persist under .matrixscroll/envelopes (default True).
Inputs: save, sign, tool, workspace, +3 more. Returns: object
list_envelopesARead-onlyIdempotent
List commit envelopes stored on ssx360.com for the authenticated organization.
Use for paginated org triage and agent memory. Requires SSX360_API_KEY.
Do not use for offline Git repos — call ``status`` and ``verify_envelope``.
Do not use for bulk export — call ``audit_export`` instead.
Read-only: no local Git writes. Returns ``{ok, envelopes, total?, error?}``.
Parameters:
limit: Maximum envelopes per page (1–200, default 50).
offset: Pagination skip index (zero-based).
signer_filter: Optional device_id or public-key prefix.
Inputs: limit, offset, signer_filter. Returns: object
publish_notesA
Publish local signed envelopes to git notes for CI Scroll Gate verification.
Use after ``create_envelope`` when CI reads ``refs/notes/matrixscroll``.
Do not use for offline single-commit checks — call ``verify_envelope``.
Do not use for hosted org audit — call ``audit_export`` with SSX360_API_KEY.
Side effects: updates the local git notes ref only; push
``refs/notes/matrixscroll`` to remote separately. Returns
``{ok, published, notes_ref, error?}``.
Parameters:
workspace: Git repo root (defaults to detected repo).
base: Range start ref (exclusive) for envelopes to publish.
head: Range end ref (inclusive) for envelopes to publish.
notes_ref: Git notes ref to write (default refs/notes/matrixscroll).
Inputs: base, head, notes_ref, workspace. Returns: object
scan_mcp_serverARead-onlyIdempotent
Fingerprint an MCP server's tool surface into an unsigned ssx360.mcp-manifest.v1.
Use before ``sign_mcp_manifest`` to capture install-time tool names, descriptions,
and input schema hashes. Re-scan later and pass results to ``verify_mcp_manifest``
with a baseline to detect rug-pull drift. Read-only; no network required when
``tools`` is supplied directly.
Returns ``{ok, tool_count, surface_hash, manifest}``.
Inputs: tools (required), package, server_url, server_name, +1 more. Returns: object
sign_actionA
Sign a universal provenance action envelope with the active Ed25519 identity.
Use for CI steps, IaC changes, DB migrations, API calls, contract deploys,
or agent delegation grants. Prefer ``create_envelope`` for Git commits.
Do not use for verification — call ``verify_envelope`` on exported JSON.
Side effects: writes ``save_path`` when set; uses local identity store.
No network unless you later upload the signed artifact yourself.
Returns ``{ok, signed, device_id, mode, path?, error?}``.
Parameters:
action_type: Provenance label (git_commit, ci_step, iac_change, etc.).
payload: JSON object to sign (no top-level signature block).
key_path: Optional MATRIXSCROLL_HOME override for CI ephemeral keys.
save_path: Optional file path to write the signed document.
Inputs: payload (required), action_type (required), key_path, save_path. Returns: object
sign_agent_traceA
Sign a browser-agent JSONL trace with the active Ed25519 identity.
Use when a WEB_WIZARD or Steel run completes. Hashes the full trace bytes,
records step count and run_id, and writes an offline-verifiable envelope.
Side effects: writes envelope file; uses local identity store. No network.
Returns ``{ok, signed, path?, error?}``.
Inputs: trace_path (required), save_path. Returns: object
sign_mcp_manifestA
Ed25519-sign an MCP tool-surface manifest for offline install verification.
Use after ``scan_mcp_server``. Prefer ``verify_mcp_manifest`` for checks.
Side effects: may write ``save_path``; uses local identity store. No network.
Returns ``{ok, signed, device_id, path?, error?}``.
Inputs: manifest (required), save_path. Returns: object
statusARead-onlyIdempotent
Report hook install state, local envelope count, and Matrix Scroll config.
Call first in a new repo before any verify/sign tool. Read-only: no Git or
filesystem writes, no network. Do not use for signature checks — call
``verify_envelope`` or ``verify_pr_range`` instead.
Returns ``{ok, config, hook_installed, envelope_count, mode?, device_id?}``.
Parameters:
workspace: Git repo root (defaults to detected repo).
Inputs: workspace. Returns: object
verify_agent_traceARead-onlyIdempotent
Verify a signed agent trace envelope offline; optional trace byte check.
Use in CI or auditor handoff. Read-only; no network.
Returns ``{ok, run_id?, step_count?, error?}``.
Inputs: envelope_path (required), trace_path. Returns: object
verify_envelopeARead-onlyIdempotent
Verify one signed commit envelope offline against RFC 8032 Ed25519 rules.
Use for a single commit SHA or explicit envelope JSON file. Prefer
``verify_pr_range`` for PR/branch ranges and ``audit_export`` for procurement
bundles spanning many commits. Do not use when you only need hook status —
call ``status`` instead.
Read-only: no network or SSX360_API_KEY required. Does not modify Git state.
Returns ``{ok, sha, actor_type, mode, error?, envelope?}``; ``ok`` is false
on signature, policy, expiry, or missing-envelope errors.
Parameters:
workspace: Git repo root (defaults to detected repo).
commit_sha: Commit SHA to verify (uses local envelope file).
envelope / envelope_path: Optional explicit path to envelope JSON.
require_mode: Policy filter, e.g. emulated or hardware (empty skips).
trusted_keys / trusted_keys_file: JSON file listing trusted public keys.
check_expiry: Reject envelopes with expired delegation timestamps.
require_actor_types / deny_actor_types: Actor policy allow/deny lists.
Inputs: envelope, workspace, commit_sha, check_expiry, +6 more. Returns: object
verify_mcp_manifestARead-onlyIdempotent
Verify a signed MCP manifest and optionally diff against an install-time baseline.
Use in CI or before trusting an MCP server after upgrade. Read-only; no network.
Returns ``{ok, surface_hash, tool_count, drift?, error?}``; ``ok`` is false on
bad signature or surface drift vs baseline.
Inputs: manifest (required), baseline. Returns: object
verify_pr_rangeA
Scroll Gate: verify signed/unsigned commits across a PR commit range.
Use for merge gates and PR review (many commits). Prefer ``verify_envelope``
for one commit offline. Prefer ``audit_export`` when auditors need bundles,
not pass/fail on a range.
Hosted mode (default): calls ssx360.com; requires SSX360_API_KEY.
Set ``source=local|notes|bundle`` to verify offline without an API key.
Read-only for Git refs; hosted mode emits usage to ssx360.com.
Returns ``{ok, verified_count, unsigned_shas?, failures?, error?}``.
Parameters:
workspace: Git repo root (defaults to detected repo).
base: Range start ref (exclusive), e.g. origin/main.
head: Range end ref (inclusive), e.g. HEAD or PR head SHA.
source: Envelope transport — hosted, local, notes, or bundle.
notes_ref: Git notes ref when source=notes.
bundle_dir: Bundle directory when source=bundle.
require_mode: Policy require_mode filter.
trusted_keys_file: Trusted keys JSON for signed/untrusted actor checks.
require_actor_types / deny_actor_types: Actor policy lists.
allow_empty: Accept a labelled empty range. Defaults to false.
Inputs: base, head, source, notes_ref, +7 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct artifact type (PR range, commit envelope, action, MCP manifest, agent trace), and the descriptions include helpful cross-references like 'prefer verify_envelope' and 'prefer audit_export.' However, the multiple sign/verify/create tools share similar shapes and require careful reading of the object noun to avoid misselection.
Most tool names follow a clear verb_noun snake_case pattern, with consistent sign_/verify_ pairs across mcp_manifest and agent_trace. The pattern is weakened slightly by 'status' (a bare noun) and 'audit_export' (noun_noun), though these are still readable and do not cause much confusion.
Thirteen tools is within a reasonable range and each tool maps to a distinct workflow step. The count feels slightly heavy because the server covers several domains at once—Git commit provenance, action signing, MCP manifest security, agent trace verification, and hosted audit export—rather than focusing on one narrow purpose.
The core lifecycle is well covered: create/verify/publish for Git envelopes, sign/verify for actions, manifests, and traces, plus status, listing, and audit export. Minor gaps exist around identity/key management and there is no explicit revocation or deletion workflow, but these are not critical for the primary signing and verification use cases.
Maintenance
Related MCP Connectors
Deep security scans of repos you own from your editor: dependency CVEs, SAST, git-history secrets.
Audit GitHub repos for malicious and supply-chain code before you depend on them.
Security reviews, threat models over a repo or website, and remediation tracking, in your editor.
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
Related MCP Servers
- AlicenseCqualityBmaintenanceAn MCP server providing 1,112 tools for the GitHub REST API across all 44 API categories. It enables comprehensive GitHub operations through Claude with typed validation and category filtering.25001MIT
- AlicenseAqualityDmaintenanceActs as a production-grade safety layer for AI-assisted coding, monitoring Git hygiene, scanning for security issues (PII, secrets, injection), and enabling semantic history search.9MIT
- AlicenseNot gradedqualityDmaintenanceLocal-first security check for AI coding agents — finds hardcoded secrets, exposed .env files, git-history leaks and vulnerable dependencies (OSV), entirely on your machine. Ask your agent "is this safe to ship?" and get a Launch Readiness score with a fix for every finding.MIT
- AlicenseBqualityDmaintenanceA security-first MCP gateway that enables AI assistants to safely inspect and interact with GitHub repositories through a controlled, auditable tool layer with policy enforcement and human approval for mutations.27MIT