cognis-digital/attestport
GitHub: cognis-digital/attestport
一款纯离线运行的软件供应链安全闸门工具，在气隙环境中完成 SBOM 生成、构件来源签名验证及 CI 策略拦截。
Stars: 0 | Forks: 0
# ATTESTPORT — 气隙软件供应链闸门
[](https://pypi.org/project/cognis-attestport/)
[](https://github.com/cognis-digital/attestport/actions)
[](LICENSE)
[](https://github.com/cognis-digital)
**SBOM (CycloneDX 风格) + SLSA/in-toto 风格的来源、签名以及 CI 策略闸门 — 专为气隙 pipeline 打造。**
*开发者与供应链安全 — 了解你交付的内容，并在不进行外部网络通信的情况下予以证明。*
## 用法 — 逐步指南
1. 从源码**安装** (Python 3.9+)：
pip install .
2. 为项目目录**生成** CycloneDX 风格的 SBOM：
attestport sbom ./myproject --out sbom.json
3. **证明** artifact，并绑定 SBOM（SLSA/in-toto 风格的来源）：
attestport attest ./dist --builder ci@example.com --sbom sbom.json --out attestation.json
4. 根据其证明文件对 artifact 进行**验证**：
attestport verify ./dist attestation.json --format json
5. **在 CI 中设置闸门** — 针对项目的策略闸门，按严重程度失败：
attestport gate ./myproject --attestation attestation.json --format sarif --fail-on high --out gate.sarif
签名密钥来源于 `--key`、`ATTESTPORT_KEY` 环境变量或一个演示密钥。此外还支持：`attestport mcp`。
## 为什么
大多数供应链工具都假定存在网络：需要通信的透明度日志、需要获取的密钥服务、需要查询的 registry。但在气隙或高 assurance 的 CI runner 中，你完全不具备这些条件。`attestport` **仅使用 Python 标准库即可在离线状态下完成整个闭环** — 无需 pip install，无需 daemon，无需网络：
1. **盘点**构建所包含的内容（一份 SBOM）。
2. 通过带有签名的 provenance 声明将其**绑定**到已构建的 artifact 上。
3. 稍后在任何地方**验证**该绑定。
4. 根据你控制的策略为 pipeline 设置**闸门**。
它针对的是生态系统已经在使用的公开开放格式 — **CycloneDX**、**in-toto** 和 **SLSA** — 但其实现是原创且自包含的。
## 领域
**主要领域：** AI & ML · **JTF MERIDIAN 部门：** ATHENA-PRIME · SAGE
**主题：** `cognis` `ai` `llm` `machine-learning` `sbom`
**Cognis Neural Suite** 的一部分 — 300 多个源码可用的工具，组织在 JTF MERIDIAN 指挥结构下的 12 个领域中。请参阅 [GitHub 上的 suite](https://github.com/cognis-digital) 和 [jtf-meridian](https://github.com/cognis-digital/jtf-meridian) 以了解各个部分如何协同工作。
## 安装
```
# 无依赖；从 checkout 运行
pip install -e ".[dev]" # only to get pytest for the test suite
# 或者直接：
python -m attestport --help
```
## 快速开始
```
attestport --version
# 1. 生成 CycloneDX 风格的 SBOM（检测 requirements.txt、package-lock.json、go.sum、Cargo.lock）
attestport sbom demos/01-basic/demoproj --out sbom.json
# 2. 生成绑定的 SBOM 的已签名的 SLSA/in-toto 风格的 provenance attestation
attestport attest demos/01-basic/demoproj --sbom sbom.json --out att.json
# 3. 根据 artifact 的 attestation 进行验证（通过；如果其中任何一个被篡改则失败）
attestport verify demos/01-basic/demoproj att.json
# 4. 基于 policy 对 CI pipeline 进行拦截（违规时以非零状态退出）
attestport gate demos/01-basic/demoproj --policy demos/01-basic/policy.json --fail-on high
# 通过 MCP (stdio) 将 engine 暴露给 agents：
attestport mcp
```
## 命令
| 命令 | 作用 |
|---------|--------------|
| `sbom ` | 遍历项目，从 lockfile 检测依赖项，对文件进行哈希处理，生成 CycloneDX 风格的 SBOM。 |
| `attest ` | 构建 in-toto `Statement` + SLSA 风格的 provenance 断言（subject digest、builder、materials、绑定的 SBOM digest）并附加分离式签名。 |
| `verify ` | 重新计算 subject digest，检查签名，可选地强制执行组件策略。任何不匹配均返回非零值。 |
| `gate --policy policy.json` | CI 闸门：遇到被封禁的许可证、已知的恶意组件、未锁定的 deps 或缺失/无效的证明文件时失败。支持 `table` / `json` / `sarif` 输出 + `--fail-on`。 |
| `mcp` | 作为本地 MCP server (stdio JSON-RPC) 运行，暴露 `sbom`、`verify`、`gate`。 |
## 支持的 lockfile
`requirements.txt` (PyPI) · `package-lock.json` (npm, v1/v2/v3) · `go.sum` (Go modules) · `Cargo.lock` (crates.io)。每个组件都会附带一个 [Package-URL](https://github.com/package-url/purl-spec) (`purl`)、一个锁定/未锁定标志，以及 lockfile 中携带的任何完整性哈希值。
## 签名模型（必读）
分离式签名是对规范声明字节的**带密钥 HMAC-SHA256**（`signature.algorithm = "hmac-sha256"`）。这在仅使用共享密钥且除了 `hashlib`/`hmac` 之外无需任何其他依赖的情况下提供了完整性 + 真实性验证，因此它可以在裸机气隙 runner 上运行。
它**不是**公钥加密方案，这是有意为之的。在生产环境中，你应该：
- 通过 `ATTESTPORT_KEY`（或 `--key`）设置真实的密钥，而不是使用内置的演示密钥（当使用演示密钥时，工具会发出强烈的警告），并且
- 理想情况下，在集成边界处替换为非对称签名方案或 HSM。
规范化处理（`sort_keys`，无多余空格，UTF-8）使得 digest 和签名在不同机器之间能够实现逐字节复现。
## 策略文件
```
{
"banned_licenses": ["GPL-3.0", "AGPL-3.0", "SSPL-1.0"],
"banned_components": ["left-pad", "evil-pkg@1.0.0"],
"allowed_components": null,
"require_pinned": true,
"require_attestation": false
}
```
`allowed_components`（设置后）会将闸门转换为允许列表。`banned_components` 条目可匹配纯名称或 `name@version`。
## 可选的 AI 风险摘要
`attestport sbom --ai` 会**仅在**配置了本地 Cognis AI 后端（`COGNIS_AI_BACKEND`）时，向 SBOM 添加自然语言风险摘要。该功能**默认关闭**，绝不是必需的，且不会有任何数据离开本地环境 — 在未配置后端的情况下，生成的 SBOM 与正常运行时在字节上完全一致。
## 内置演示
请参阅 [`demos/01-basic/SCENARIO.md`](demos/01-basic/SCENARIO.md) 获取完整的 sbom → attest → verify → gate 演示流程。
## 输出格式
- **Table**（默认）— 人类可读的终端摘要
- **JSON** — 供 pipeline 使用的机器可读 SBOM / 闸门发现结果
- **SARIF** — 直接输出到 GitHub 代码扫描 / IDE 问题面板
## 原创性 / 净室开发
这是一个 **100% 原创的、净室（clean-room）** 实现。它没有 fork、vendor 或复制任何第三方供应链项目。它特意*针对*公开的开放规范（SPDX/CycloneDX/in-toto/SLSA）— 这些是任何人都可以生成的开放标准 — 但这里的每个解析器、哈希器、签名器和闸门规则都是仅使用 Python 标准库从头编写的。
## 它如何融入 Cognis Neural Suite
`attestport` 是 [Cognis Neural Suite](https://github.com/cognis-digital) 中的一个工具。每个工具都附带一个 MCP server，以便 [Cognis.Studio](https://cognis.studio) agent 能够将它们作为受限作用域的功能进行调用。
**`dev-supply-chain` 中的同级工具：** [`depgraph`](https://github.com/cognis-digital/depgraph)、[`ossaudit`](https://github.com/cognis-digital/ossaudit)、[`secretsweep`](https://github.com/cognis-digital/secretsweep)、[`pipewatch-pro`](https://github.com/cognis-digital/pipewatch-pro)
## 架构与路线图
- 设计文档：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- 计划内工作：[`ROADMAP.md`](ROADMAP.md)
## 互操作性
`attestport` 可与 300 多个工具组成的 Cognis suite 组合使用 — JSON 输入/输出以及共享的
兼容 OpenAI 的 `/v1` 主干网络。请参阅 **[INTEROP.md](INTEROP.md)** 了解
suite 地图、组合模式和参考技术栈。
## 集成
通过
[`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `attestport` 的发现结果转发至 STIX/MISP/Sigma/Splunk/Elastic/Slack/webhook。请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。
## 许可证
在 **Cognis Open Collaboration License (COCL) v1.0** 下源码可见 — 可免费用于个人、内部评估、研究和教育用途；**商业/生产用途需要许可证** (licensing@cognis.digital)。请参阅 [LICENSE](LICENSE)。
## 关于
**[Cognis Digital](https://cognis.digital)** — 美国, 怀俄明州 · *让明天更美好：高级网络安全、AI 创新与区块链专业知识。*
标签：SBOM, 图数据库, 安全合规, 硬件无关, 离线环境, 网络代理, 软件溯源, 逆向工具