SSX360/matrixscroll
GitHub: SSX360/matrixscroll
Matrix Scroll 是一个为 agent 辅助 Git 提供 Ed25519 签名的 commit 来源证明协议，支持在 CLI、浏览器和 CI 中进行离线验证，解决「谁签名了每次 commit」的可追溯性问题。
Stars: 4 | Forks: 0
# Matrix 滚动
**关于是谁——或者说是哪个程序——编写了每一次 commit 的签名证明。** Matrix Scroll 是一个开放的 Ed25519 commit 来源协议，专为 agent 辅助的 Git 设计——支持在 CLI、浏览器和 CI 中进行离线验证。硬件 (SE050) 是可选的预览信任升级；模拟模式现已发布。
**托管控制平面：** 身份验证、计费和设备激活位于 [ssx360.com](https://ssx360.com/)。Digital Rain 是本地漏斗；Matrix Scroll 是长矛。
## 合规性证据映射
Matrix Scroll **映射到** 并 **生成以下证据**（绝非“被要求”）：
- **Five Eyes · Agentic AI (2026年4月)** —— 证明 agent 运行的是预期的、未修改的代码的加密认证。
- **EU AI Act · 高风险可追溯性** —— 可验证的 commit 时审计产物。
- **美国联邦 SSDF · 自我证明** —— 用于供应链审查的证据包。
完整矩阵：[`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json)
## 采用信号
在推出期间跟踪出站和注册表的吸引力：
| 信号 | 计数器 |
|--------|---------|
| PyPI `matrixscroll` | [](https://pypi.org/project/matrixscroll/) |
| PyPI `[mcp]` extra | [](https://pypi.org/project/matrixscroll/) |
| GitHub stars | [](https://github.com/SSX360/matrixscroll/stargazers) |
| Scroll Gate Action | [](https://github.com/SSX360/matrixscroll-verify-action) |
| Glama MCP registry | [matrixscroll on Glama](https://glama.ai/mcp/servers/SSX360/matrixscroll) |
## 核心演示 (MCP 合并后)
在 [`docs/HERO_DEMO.md`](docs/HERO_DEMO.md) 中记录 60-90 秒的来源流程 —— 仅包含 Scroll Gate + 浏览器验证器 + MCP 动词。
## 安装 —— MCP server (核心路径)
Agent 通过 **仅限来源** 的 MCP server 在循环内对 commit 进行签名：
```
{
"mcpServers": {
"matrixscroll-mcp": {
"command": "matrixscroll-mcp",
"args": []
}
}
}
```
```
pip install "matrixscroll[mcp]==0.2.6"
matrixscroll-mcp # stdio — register in Cursor / Claude Desktop / VS Code
```
**MCP 工具 (仅限来源动词)：** `create_envelope`、`verify_envelope`、`verify_pr_range` (Scroll Gate)、`publish_notes`、`status`、`audit_export`。
工作区智能（分析、头脑风暴、雷达）位于 [Digital Rain](https://ssx360.com/) 中 —— 而不在此 MCP server 中。
## 也可用 —— CLI & hooks
```
pip install "matrixscroll==0.2.6"
matrixscroll hook-install
export MATRIXSCROLL_ACTOR_TYPE=agent
export MATRIXSCROLL_TOOL=agent-runner
git commit -m "feat: agent-assisted change"
matrixscroll envelope-verify "$(git rev-parse HEAD)"
```
请参阅 [`docs/quickstart-git.md`](docs/quickstart-git.md) 和
[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh)。
本仓库是该产品的标准 SDK、验证器契约、测试固件集和发布窗口。
Matrix Scroll 是 Git 的加密证据层。当 agent、CI 工作流或人类操作者生成 commit 时，一个已签名的 commit 信封可以记录执行者、工具和可选的受限范围。任何人都可以在本地、CI 或浏览器中验证该信封，而无需信任生成它的编辑器会话。
保留 GitHub Advanced Security、Semgrep、Snyk、分支保护和构建产物认证。Matrix Scroll 在合并前添加了签名的 commit 时作者身份证明，并在 CLI、浏览器、CI 和 SE050 预览路径中保持相同的离线验证契约。
参考 SDK 目前提供基于标准 manifest 字节的纯 Ed25519。SSX360 / NXP SE050 路径是兼容的下一信任层，在设备验收完成之前仍作为预览路径。
## 客观的局限
- 现已发布：PyPI `matrixscroll==0.2.6`、Git post-commit hooks、`matrixscroll envelope-verify`、Scroll Gate PR 验证、浏览器验证器、GitHub Action 以及用于 SE050 推广路径的 USB CDC 主机传输预览。模拟模式是默认的评估路径。
- 开发中：RP2350 + SE050 固件验证、外部支持 Ed25519 的硬件密钥后端，以及透明度日志集成。
- 不包含：IAM、沙箱、prompt 过滤或 agent runtime。
## 适用场景
- 扫描器和分支保护能发现代码和策略问题；Matrix Scroll 记录在 push 之前是谁或什么签名了该更改。
- 硬件密钥和构建认证仍然是互补的信任根和下游证明；Matrix Scroll 负责处理 commit 时的来源记录。
- 公共契约保持基于标准 manifest 字节的纯 Ed25519，无论今天的签名者是模拟的还是未来由硬件支持的。
## 常见问题
### 什么是 Matrix Scroll，它如何保护 Git 的安全？
Matrix Scroll 是 agent 辅助 Git 的签名 commit 时来源记录。它通过将 Ed25519 签名的 commit 信封附加到 commit 上来保护 Git，记录执行者、工具和可选的受限范围，然后让审查者在 CLI、浏览器或 CI 中在合并前离线验证该证明。
### Matrix Scroll 中硬件和模拟模式有何不同？
模拟模式今天即可使用，它将签名密钥以仅限所有者的权限保留在磁盘上，以便团队现在就可以评估整个工作流程。硬件模式保持相同的验证器契约和 commit 信封 schema，但将私钥移入 SE050 安全元件中，因此主机无法将其导出；该路径在设备验收完成之前将仅作为预览提供。
### 如何将 Matrix Scroll 集成到 CI/CD 工作流中？
在你的仓库中安装 SDK 和 hooks，在 PR 审查之前将 commit 信封发布到 `refs/notes/matrixscroll`，并使用 `SSX360/matrixscroll-verify-action@v1` 在 GitHub Actions 中验证完整的 PR commit 范围。受保护的分支随后可以与现有的扫描器、分支保护和构建认证一起，要求提供 Matrix Scroll 证明。
## 快速开始 (CLI)
```
pip install "matrixscroll==0.2.6"
matrixscroll hook-install
matrixscroll hook-status
export MATRIXSCROLL_ACTOR_TYPE=agent
export MATRIXSCROLL_TOOL=agent-runner
git commit -m "feat: agent-assisted change"
matrixscroll envelope-verify "$(git rev-parse HEAD)"
```
请参阅 [`docs/quickstart-git.md`](docs/quickstart-git.md) 并运行
[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh)。
## CI 验证
### 针对 PR commit 范围的 Scroll Gate
```
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: SSX360/matrixscroll-verify-action@v1
with:
head-ref: ${{ github.event.pull_request.head.sha }}
base-ref: ${{ github.event.pull_request.base.sha }}
source: notes
matrixscroll-version: "0.2.6"
require-mode: emulated
```
在审查前将信封发布到 git notes：
```
matrixscroll envelope-publish-notes --base origin/main --head HEAD
git push origin refs/notes/matrixscroll
```
```
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: SSX360/matrixscroll-verify-action@v1
with:
head-ref: ${{ github.event.pull_request.head.sha }}
base-ref: ${{ github.event.pull_request.base.sha }}
source: notes
matrixscroll-version: "0.2.6"
summary-output: provenance-summary.json
```
请参阅 [`docs/quickstart-git.md`](docs/quickstart-git.md) 和
[`examples/ci/protected-branch.yml`](examples/ci/protected-branch.yml)。
`--require-mode`、`--trusted-keys` 以及执行者或委托策略检查可在 `0.2.x` 系列中使用；本 README 中的示例固定为 `0.2.6`。
## 为什么它与 Sigstore 不同
Sigstore、GitHub 构建产物认证和 SLSA 回答的是“CI 中构建了什么？” Matrix Scroll 回答的是“在 push 之前是谁签名的这个 commit？” 这些系统是互补的：Matrix Scroll 在 commit 时对 commit 信封进行签名，而构建产物认证系统稍后在交付链中对构建输出进行签名。
Matrix Scroll 不会在通用认证密钥的主场与之竞争。现有的硬件信任根只有在保留相同的纯 Ed25519 字节契约时，才能成为 Matrix Scroll 的签名后端。
## 公开证明链接
- 浏览器验证器：
- Agentic AI 控制项：[`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
- 网站：
- 参考设备路径：[SSX360](https://matrixscroll.com/device)
## Python API
```
pip install "matrixscroll==0.2.6"
```
```
import matrixscroll
print(matrixscroll.status())
# {'schema': 'matrixscroll.identity.v1', 'available': True,
# 'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
assert matrixscroll.verify_manifest(signed)
```
## CLI
```
$ matrixscroll status
{
"available": true,
"device_id": "MS-A3F2-9C81",
"mode": "emulated",
"public_key": "...",
"schema": "matrixscroll.identity.v1"
}
$ matrixscroll sign release.json > release.signed.json
$ matrixscroll verify release.signed.json
{"device_id": "MS-A3F2-9C81", "mode": "emulated", "ok": true, "signed_at": "..."}
```
`matrixscroll verify` 在签名有效时退出代码为 `0`，在失败时（如 manifest 被篡改、缺少签名块、schema 或算法错误、设备 ID 不匹配、公钥格式错误、文件不可读）退出代码为 `2`。
## 工作原理
```
your IDE / agent / CI
|
| commit envelope, release manifest, evidence pack, SBOM
v
matrixscroll.sign_manifest(...) / post-commit hook
|
| canonical JSON (sorted keys, ASCII-escaped, no NaN,
| signature block excluded from input)
v
IdentityProvider --> Ed25519 signature
(L1 emulated today,
SSX360 / SE050 roadmap)
|
v
signed document --> matrixscroll.verify_manifest(...)
(anyone, anywhere, offline)
```
使用 `MATRIXSCROLL_MODE` 切换 provider。硬件模式包含一个 USB CDC 主机传输预览和一个用于 CI 的 mock 路径；真实的 SE050 签名仍然取决于设备固件验证。外部密钥后端在能够使用 Ed25519 对相同的标准字节进行签名之前，不会进入主线。
关于推广顺序，建议从 `MATRIXSCROLL_MODE=emulated` 开始进行评估，仅在外部支持 Ed25519 的签名者保持与验证器兼容时才引入它们，并将 `hardware` 视为 SE050 预览路径，直到设备验收完成。
## 合规级别
| 级别 | Provider | 支持方式 | 状态 |
| ----- | -------- | --------- | ------ |
| **L1** 模拟 | `EmulatedProvider` | 软件密钥，文件备份 (0600) | 已发布 |
| **L2** 硬件 | `HardwareProvider` | NXP SE050 安全元件 (SSX360) | 开发中 |
| **L3** 认证 | 未来计划 | L2 + 远程认证 | 规划中 |
`status()` 通过 `mode` 和 `available` 字段公开当前的活动级别。
## 存储和信任边界
- 模拟密钥存储：`~/.matrixscroll/device.json`
（使用 `MATRIXSCROLL_HOME` 覆盖）。
- 创建目录时的权限为 `0700`；打开种子文件时的权限为 `0600` 并带有 `O_CREAT|O_EXCL`，因此私有种子绝不会出现短暂的全球可读状态。
- 损坏或截断的存储会明确报错（`IdentityError`），而不是静默生成新身份。
- 计划中的硬件路径不会在磁盘上保存任何私有内容；种子密封在安全元件中。
## 参考实现，并非唯一实现
Matrix Scroll 是一个协议。这个 Python 包是参考实现。我们欢迎使用 Rust、Go、TypeScript 和嵌入式 C 进行实现。针对 [`vectors/`](vectors/) 运行它们以进行自我认证。请参阅 `CONTRIBUTING.md`。
## Agentic AI 指导证明
该仓库包含位于 [`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json) 的机器可读控制矩阵，位于 [`examples/agentic_ai_evidence_manifest.json`](examples/agentic_ai_evidence_manifest.json) 的示例受限 agent 证据 manifest，以及 `tests/test_agentic_guidance.py` 中的可执行检查。
## Model Context Protocol (MCP) 服务器
MCP server **仅公开来源动词**：`create_envelope`、`verify_envelope`、`verify_pr_range`、`publish_notes`、`status` 和 `audit_export`。工作区智能和仓库扫描位于 [Digital Rain](https://ssx360.com/) 中 —— 而不在此 MCP server 中。
在 Cursor / Claude Desktop / VS Code 中安装并注册：
```
pip install "matrixscroll[mcp]==0.2.6"
matrixscroll-mcp # stdio
```
请参阅上面的 [安装 —— MCP server](#install--mcp-server-headline-path) 部分获取推荐的 `mcp.json` 代码片段。
## License
- 代码：**Apache-2.0** (`LICENSE`)。
- 规范文本（`SPEC.md`、`vectors/`）：**CC0 1.0** - 公共领域。
## 安全性
请参阅 [`SECURITY.md`](SECURITY.md)。将漏洞私下报告给
**security@matrixscroll.com** 或通过 GitHub Security Advisory 提交。
**协议：** https://matrixscroll.com · **验证：** https://matrixscroll.com/verify/
**控制平面：** https://ssx360.com · **试点：** sales@ssx360.com
标签：AI代理, Git工具, 代码溯源, 密码学, 手动系统调用, 网络安全研究, 逆向工具