Skip to main content
Glama

Matrix Scroll

Signed machine-action records with offline verification for MCP, Git, and CI.

ci-unit PyPI Python License

SSX360 Matrix Scroll: Trust must be checkable. Open verifier matrixscroll 0.10.0; signed sources Ed25519 plus ML-DSA; ledger available.

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 (0), INCONSISTENT (2), or INDETERMINATE (1). No silent pass on missing evidence

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-mcp

After 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

status

Reports local identity, hook state, and envelope count

Read-only and local

create_envelope

Creates an Ed25519-signed Git commit envelope

Writes a local envelope by default

verify_envelope

Verifies one signed envelope and its policy fields

Read-only and local

sign_action

Signs provenance for CI, infrastructure changes, migrations, API calls, or other actions

Writes only when save_path is set

verify_pr_range

Checks every commit in a Git range

Local for local, notes, or bundle. Hosted mode requires an API key

publish_notes

Publishes local envelopes to refs/notes/matrixscroll

Writes local Git notes

audit_export

Exports evidence for review

Writes a local bundle or uses the hosted API when configured

list_envelopes

Lists organization envelopes

Requires SSX360_API_KEY and the hosted API

scan_mcp_server

Fingerprints MCP tool names, descriptions, and input schemas

Read-only when tools are supplied

sign_mcp_manifest

Signs an MCP tool-surface manifest

Writes only when save_path is set

verify_mcp_manifest

Verifies a manifest and compares it with a signed baseline

Read-only and local

sign_agent_trace

Signs a browser-agent JSONL trace

Writes a signed envelope

verify_agent_trace

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 \
  --pretty

The 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 --pretty

Device-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.json

matrixscroll 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.0 installs 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_envelopes and the hosted modes of verify_pr_range and audit_export require SSX360_API_KEY and 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). Release 0.10.0 defaults new software keys to ml-dsa-87 for CNSA 2.0 signature-parameter alignment (0.7.0 and earlier default to ml-dsa-65; pass --algorithm or MATRIXSCROLL_PQC to 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.kem provides ML-KEM-1024 primitives (ACVP-checked). Sealed evidence packs in matrixscroll.sealed use hybrid X25519 + ML-KEM-1024 with Ed25519 + ML-DSA-87. Same boundary as the signature overlay: evidence mapping against NIST vectors, not a validation. See docs/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_type can 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/provenance

The 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).

  1. Does it run in one command, offline? matrixscroll verify vectors/valid_simple.json prints "ok": true and exits 0; matrixscroll verify vectors/tampered_field.json prints "ok": false and exits 2. Neither command opens a network connection. Exit codes are fixed in docs/reference/exit-codes.md.

  2. 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.py enforces that in CI on every change.

  3. Are the vectors committed? vectors/valid_*.json, tampered_*.json and unsigned_*.json are the conformance set (CC0 1.0); vectors/acvp-sigver-fips204-fips205.json and vectors/acvp-mlkem-fips203.json are NIST ACVP sample vectors with source URLs and SHA-256 digests. python -m pytest tests/test_vectors.py tests/test_independent_verifier.py -q runs the conformance set; python -m pytest tests/test_acvp_sigver.py tests/test_acvp_mlkem.py -q runs the NIST vectors through liboqs.

  4. 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.

  5. 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.yml runs 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)

docs/explanation/gold-standard.md

Release evidence (digests, provenance, PQC boundary)

docs/EVIDENCE.md

Tombstone / schemas

matrixscroll.com

Documentation

GitHub docs

Where Matrix Scroll fits (dated comparison)

docs/COMPARISON.md

Cryptographic roadmap (Ed25519, ML-DSA-87 overlay, policy dates)

docs/CRYPTO_ROADMAP.md

Offline verification

CLI guide

Protocol specification

SPEC.md

Source repository

github.com/SSX360/matrixscroll

SSX360 contact

Contact SSX360

Available Tools

13 tools
audit_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_envelopesA
Read-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_serverA
Read-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

statusA
Read-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_traceA
Read-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_envelopeA
Read-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_manifestA
Read-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

    A4.4/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      An 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.
      2
      500
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local-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
    • A
      license
      B
      quality
      D
      maintenance
      A 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.
      27
      MIT