Canari

Canari

Agent 组件验证台账——针对 MCP 服务、Agent 技能和 DSH 插件，提供签名、可离线验证且保留历史记录的证明。

名称源自煤矿中的金丝雀：它是最先察觉异常的。

功能

1. 每周扫描 Agent 组件生态系统（npm、PyPI、MCP Registry、dsh.so）
2. 每个组件都会获得一份签名证明：DSSE/Ed25519 信封，其载荷为 in-toto Statement v1（subject[]，含 digest.sha256、predicateType、predicate），用于绑定：工件哈希 + 主机版本 + 扫描场景。GUAC / cosign / slsa-verifier 无需 Canari 专用代码即可读取。
3. 任何拥有公钥的人都可以离线验证证明
4. 历史记录永不删除——版本变更会形成替代链
5. 提供公开的机器可读数据流，供任何 AI Agent 或主机使用
6. 信任启发式规则：发布节奏（L2.4）、元数据异常（L2.5）、仿冒拼写（L2.6）
7. 提供使用者安装门禁和策略：canari-verify bundle.json --key pub.json --gate --gate-policy paranoid

安装

pip install canari-mcp

也可通过 PyPI 和 GitHub 发布版本 获取（wheel + sdist + SHA256SUMS + Ed25519 签名）。两个渠道提供的工件逐字节相同；请参阅 docs/release-process.md 验证签名发布版本。

canari-gate --store out --list

开放数据集

dataset/ 是依据 CC-BY-4.0 发布的台账快照：包含883 个组件的 3251 份签名证明、规范数据流、漂移报告、架构、两把公钥，以及每个文件都附有 sha256 的 MANIFEST.json。使用 canari-verify 离线验证数据包；使用清单验证整个快照（见 dataset/README.md）。扫描后运行 python scripts/sync_dataset.py 刷新数据集。

质量门禁（在 CI 中强制执行）

门禁	阈值	当前值
测试	在 3.10/3.12/3.13 上全部通过	434 项通过
行覆盖率	>= 85%	90%
变异杀死率	>= 90%（不计等价变异体）	100%（50/50）
实时数据审计	抽样证明可从 npm/PyPI 重新推导	18/18

运行这些门禁：python scripts/quality_gate.py

快速开始

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

策略文件示例

{"name": "my-policy", "block_on_findings": true, "require_native_provenance": false}

使用者侧（主机实际使用的部分）

1. 查找组件并执行门禁

# 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 --list

2. 漂移报告（自上周以来的变化）

canari-drift --store out --write out/drift
# verdict flips / same-version silent changes / findings added / findings removed

每次扫描后，run_weekly.py 都会自动生成此报告。

3. 在任何 MCP 主机中使用（dsh、Codex、Claude 等）

canari-mcp 通过 stdio 使用 MCP 协议（零依赖），并提供三个工具： gate_check、verify_bundle、store_summary。

{
  "mcpServers": {
    "canari": {
      "command": "canari-mcp"
    }
  }
}

无需参数：wheel 内置了每个组件最新的签名证明快照（883 个组件，由 scripts/build_snapshot.py 从 dataset/ 构建），因此 gate_check 开箱即用。需要完整的替代历史记录而非快照时，可将 --store（或 $CANARI_STORE）指向完整台账检出目录。

主机（或 Agent）随后可以询问：“是否允许安装 npm:express？”并获得 ALLOW / BLOCK / REVIEW 结果及原因，且该结果由可签名、可离线验证的证明提供支持。

4. 门控实际安装命令

canari-guard 会包装安装命令，将每个组件与账本进行核对，并在判定结果为阻止时拒绝执行：

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

主机不会被修改——防护程序位于安装命令之前。

对于 DeepSeek Harness（dsh），请将以下内容添加到配置文件的 cordis.patch.yml 中 （已在 dsh 上完成端到端验证：模型调用了 mcp__canari__store_summary，并收到了实时组件数量）：

    - 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: true

多注册表覆盖

注册表	来源	检查内容	继承内容
npm	搜索 API + packument + tarball sha256	是否存在、版本、制品哈希、维护者	-
PyPI	Simple API + JSON API	同上	-
MCP Registry	官方 REST	是否存在身份信息	-
dsh.so	JSON API	引用现有的 L1-L5 结论（不重新扫描）	dsh.so 判定结果

诚实说明局限

• 这是风险信号，而非安全保证
• M0/M1 覆盖元级检查（L1-L2）；行为检查（L3+）属于 M1+
• 扫描覆盖范围仅限注册表公开的信息
• expires_at 为 7 天——证明会过期，需要重新扫描

此方案应对的威胁模型

postmark-mcp（MITRE ATLAS AML.CS0053）：15 个版本均无问题，随后出现一次被投毒的提交，约 300 个组织受到影响。下架后，没有通知任何主机。缺口在于：没有纵向观察、没有跨主机撤销信息源，也没有可移植的判定结果。

Canari 填补了这一缺口。

许可证

Apache-2.0。请参阅 LICENSE 和 SECURITY.md。