Canari
Canari MCP server lets an AI host query, verify, and gate agent components against a signed attestation ledger.
Check install eligibility for npm, PyPI, MCP Registry, and dsh-registry components via
gate_check, returningALLOW,BLOCK, orREVIEWwith reasons and optional policy (default,strict,release-gate,lax,paranoid).Verify a Canari bundle offline with
verify_bundle, checking DSSE/Ed25519 signatures, schema validity, and per-check results.Summarize the local ledger with
store_summary, including coverage and latest drift signals such as verdict flips or silent changes.Support host-side supply-chain decisions by resolving the newest signed attestation for a component and exposing verifiable evidence to agents.
Scans npm packages and components, verifies signed attestations and artifact hashes, and applies policy gates to decide whether npm package installs should be allowed, blocked, or reviewed.
Scans PyPI packages and components, verifies signed attestations and artifact hashes, and applies policy gates to decide whether PyPI package installs should be allowed, blocked, or reviewed.
Canari
Agent component verification ledger - signed, offline-verifiable, history-preserving attestations for MCP servers, agent skills, and DSH plugins.
Named after the canary in the coal mine: the first to detect that something went wrong.
What it does
Weekly scan of agent component ecosystems (npm, PyPI, MCP Registry, dsh.so)
Each component gets a signed attestation: DSSE/Ed25519 envelope whose payload is an in-toto Statement v1 (
subject[]withdigest.sha256,predicateType,predicate) binding: artifact hash + host version + scan scenario. Readable by GUAC / cosign / slsa-verifier without Canari-specific code.Attestations are offline-verifiable by anyone with the public key
History is never deleted - version changes create supersession chains
Public machine-readable feed for any AI agent or host to consume
Trust heuristics: release cadence (L2.4), metadata anomaly (L2.5), typosquatting (L2.6)
Consumer install gate with policies:
canari-verify bundle.json --key pub.json --gate --gate-policy paranoid
Related MCP server: pkg-oracle
Install
pip install canari-mcpAlso on PyPI and as a
GitHub release
(wheel + sdist + SHA256SUMS + Ed25519 signature). Both channels ship byte-identical
artifacts; see docs/release-process.md to verify the signed release.
canari-gate --store out --listOpen dataset
dataset/ is the published snapshot of the ledger under CC-BY-4.0: 5170 signed
attestations over 1417 components, the canonical feed, drift reports, the schema, both
public keys and a MANIFEST.json with a sha256 per file. Verify a bundle offline with
canari-verify; verify the whole snapshot with the manifest (see dataset/README.md).
Refresh it after a scan with python scripts/sync_dataset.py.
Append-only public log (verifiable without trusting us)
Every published verdict bundle and every upstream dataset snapshot is committed
into a signed, append-only Merkle log at
docs/log/. This closes a gap
that a signature alone cannot: a signed attestation proves who said something,
never that an older statement was not quietly deleted or re-issued with a
different verdict.
Latest head:
docs/log/head-latest.json(size, root, Ed25519 signature)Latest offline bundle:
docs/log/bundle-latest.jsonc2sp.org checkpoint:
docs/log/checkpoint.txt-- the same head as a signed note inc2sp.org/tlog-checkpoint+signed-note+tlog-cosignatureform, so an existing transparency-log witness can co-sign it without adopting anything of ours. Pinned against another project's published test vectors (tests/test_checkpoint.py).Format:
docs/spec/append-only-log.md(RFC 9162 hashing, inclusion + consistency proofs, explicit list of what the proof does not claim)Cross-implementation vectors:
docs/spec/merkle-vectors.json(168 cases), checked by two independent verifiers
# no network, no canari install needed for the Node path
node docs/spec/verify_offline.js docs/log/bundle-latest.json --log-id canari-snapshot-log
# "the head I recorded yesterday is still a prefix of today's"
python -m canari.verify_offline docs/log/bundle-latest.json \
--pinned-prefix <root-you-saved-last-week>A new head is appended daily by .github/workflows/append-only-log.yml. The
publish path refuses to sign (LogTruncated / LogRewritten) if the on-disk
log contradicts a head it already published, because a log that re-signs a
rewrite under its own key manufactures false assurance.
Quality gates (enforced in CI)
Gate | Threshold | Current |
tests | green on 3.10/3.12/3.13 | 716 passing (1 env-skip) |
line coverage | >= 85% | 86% line (branch 86%) |
mutation kill rate | >= 90% (equivalent mutants excluded) | 100% (47/47 killed + 2 equivalent, 3 skipped) |
live-data audit | sampled attestations re-derive from npm/PyPI | 18/18 |
Run them yourself: python scripts/quality_gate.py
Quick start
# install
pip install canari-mcp
# run a scan
canari-baseline --limit 50
# verify an attestation offline
canari-verify out/attestations/npm_some-package.bundle.json --key out/public_key.json
# verify + policy gate (exit 0 ALLOW / 5 BLOCK / 6 REVIEW)
canari-verify out/attestations/npm_some-package.bundle.json --key out/public_key.json \\
--gate --gate-policy strict
# custom policy file
canari-verify bundle.json --key out/public_key.json --gate --gate-policy-file my-policy.jsonPolicy file example
{"name": "my-policy", "block_on_findings": true, "require_native_provenance": false}Consumer side (the part a host actually uses)
1. Look up a component and gate it
# resolve the newest signed attestation for a component and run the gate
canari-gate --store out --registry npm --name express
canari-gate --store out --registry dsh-registry --name aegis --policy paranoid --json
# exit codes: 0 ALLOW, 5 BLOCK, 6 REVIEW, 3 not found
canari-gate --store out --list2. Record another scanner's result as a signed, timestamped attestation
Live example: 20 PyPI MCP servers, scanned by bandit, recorded and signed - every record on that page
can be verified with canari-verify using the public key shipped beside it.
Canari does not scan anything itself. What it adds is durability: a scanner tells you what it thinks today, Canari records what it said on each date, signed and offline-verifiable, and keeps the history when the verdict flips.
canari-ingest-sarif reads a SARIF 2.1.0 report from any external scanner
(NVIDIA SkillSpector, Snyk agent-scan, Tencent AI-Infra-Guard, ...) and writes a
normal Canari bundle:
canari-ingest-sarif \
--sarif skillspector.sarif \
--name @modelcontextprotocol/server-filesystem --version 2025.1.0 \
--registry npm \
--artifact-sha256 <sha256 of the scanned artifact> \
--key out/private_key.pem --out out/attestationsRules it enforces, so the ledger cannot become a rubber stamp:
The upstream tool is named, not hidden. Every check records
tool = <scanner>/<version>andchecker.idsays it was ingested by Canari.The artifact digest is required. A scan result without the scanned artifact's sha256 cannot be bound to anything, so the command refuses.
An unusable report is an error, not a pass. No run block, or
executionSuccessful: false, yields verdicterror.Findings move the verdict. Critical/high →
fail; lower severity →pass-with-findings; no findings →pass.
2. Drift report (what changed since last week)
canari-drift --store out --write out/drift
# verdict flips / same-version silent changes / findings added / findings removedrun_weekly.py writes this report automatically after every scan.
3. Use it from any MCP host (dsh, Codex, Claude, ...)
canari-mcp speaks MCP over stdio (zero dependencies) and exposes three tools:
gate_check, verify_bundle, store_summary.
{
"mcpServers": {
"canari": {
"command": "canari-mcp"
}
}
}No arguments needed: the wheel ships a snapshot of the newest signed attestation
per component (1417 components, rebuilt by scripts/build_snapshot.py from
dataset/), so gate_check answers out of the box. Point --store (or
$CANARI_STORE) at a full ledger checkout when you want the complete
supersession history instead of the snapshot.
A host (or agent) can then ask: "is npm:express allowed to install?" and get
ALLOW / BLOCK / REVIEW with reasons, backed by a signed, offline-verifiable
attestation.
4. Gate the actual install command
canari-guard wraps an install command, checks every component against the
ledger, and refuses to execute when the verdict blocks:
canari-guard -- dsh plugin --profile wbpj add dsh-purge
canari-guard -- npm install some-mcp-server
canari-guard -- pip install mcp-server-fetch==0.2.1
# exit 0 allowed+executed | 5 blocked by ledger | 6 review not confirmed
# --dry-run prints what would run; --allow-review accepts pass-with-findingsThe host is never patched - the guard sits in front of the install command.
For DeepSeek Harness (dsh), add this to the profile's cordis.patch.yml
(verified end-to-end on dsh: the model called mcp__canari__store_summary and
received the live component count):
- id: mcp-canari
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: canari
transport: stdio
command: 'E:\Temp\tbdig\_venv_pr_a\Scripts\python.exe'
args: ['-m', 'canari.mcp_server', '--store', 'E:\Temp\tbdig\canari\out',
'--key', 'E:\Temp\tbdig\canari\out\public_key.json']
cwd: 'E:\Temp\tbdig\canari'
failOnStartupError: trueMulti-registry coverage
Registry | Source | What we check | What we inherit |
npm | search API + packument + tarball sha256 | existence, version, artifact hash, maintainers | - |
PyPI | Simple API + JSON API | same | - |
MCP Registry | official REST | identity presence | - |
dsh.so | JSON API | reference existing L1-L5 conclusions (not re-scanned) | dsh.so verdicts |
Honest limitations
This is a risk signal, not a safety guarantee
M0/M1 covers meta-level checks (L1-L2); behavioral checks (L3+) are M1+
Scan coverage is limited to what registries expose publicly
expires_atis 7 days - attestations go stale, re-scan needed
The threat model this addresses
postmark-mcp (MITRE ATLAS AML.CS0053): 15 clean versions, then one poisoned commit, ~300 orgs affected. After takedown, no host was notified. The gap: no longitudinal observation, no cross-host revocation feed, no portable verdict.
Canari fills that gap.
License
Apache-2.0. See LICENSE and SECURITY.md.
Available Tools
3 toolsgate_checkB
Look up a component (registry+name[,version]) in the signed attestation ledger and return the install-gate decision (ALLOW/BLOCK/REVIEW) with reasons.
Inputs: name (required), registry (required), policy, version.
store_summaryC
Coverage summary of the local ledger store plus the latest drift headline (verdict flips / silent changes).
Inputs: no named parameters.
verify_bundleB
Offline verification of one canari bundle: DSSE/Ed25519 signature + schema + per-check breakdown.
Inputs: key_path (required), bundle_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a clearly distinct operation: gate decision lookup, offline bundle verification, and ledger/store summary. The descriptions make the boundaries explicit, so an agent should not confuse them.
All names use lowercase snake_case with two tokens, which is consistent and readable. However, the semantic pattern is not uniformly verb_noun: verify_bundle is clearly verb_object, while gate_check and store_summary read more like noun phrases.
Three tools are appropriate for a focused attestation/verification server. Each tool has a distinct role and earns its place without bloating the surface.
The core read/verification workflows are covered: gate decisions, bundle verification, and ledger coverage/drift summary. Minor gaps remain around inspecting raw attestation entries or detailed component history beyond the decision headline.
Maintenance
Related MCP Connectors
Attestari's verdict on an npm or PyPI package version, asked before an agent installs it.
Read-only lookup of tested agent tools and MCP servers: scores, test evidence, deprecation.
CVEs, affected versions and fix versions for your dependencies, from an affected-version ledger.
Trust-check any dependency for agents: OpenSSF Scorecard, licenses, CVEs, deps. 7 ecosystems.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides verified dependency-audit verdicts for AI agents, checking installed versions against OSV advisories and splitting direct vs transitive dependencies.3MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that verifies npm and PyPI packages before installation, checking for existence, known vulnerabilities, OpenSSF scorecard, and typosquatting, returning an ALLOW/WARN/BLOCK verdict.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to perform read-only pre-install checks for npm, pip, uv, npx, and uvx targets or MCP servers, returning known install traps, tested fixes, warnings, malicious-package denials, or no known issues. It also supports searching tested recipes and reporting leaf packages.MIT
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to check npm packages, GitHub Action refs, and remote scripts before execution, returning deterministic ALLOW/DENY/REVIEW verdicts with evidence and a re-checkable manifest.MIT