llody9977/artifactgate
GitHub: llody9977/artifactgate
一个基于证据的第三方容器镜像准入控制参考实现，通过 digest 锁定、多维安全扫描和策略门控实现供应链风险管理。
Stars: 0 | Forks: 0
# ArtifactGate：针对第三方容器的基于证据的准入控制
[](https://github.com/llody9977/artifactgate/actions/workflows/ci.yml)
[](https://github.com/llody9977/artifactgate/actions/workflows/image-promotion.yml)
[](https://github.com/llody9977/artifactgate/actions/workflows/rescan.yml)
我构建 ArtifactGate 的初衷是为了解决一个实际问题：拉取第三方容器很容易，但同时接受供应商带来的风险也很容易。
一个熟悉的镜像名称或一次显示无风险的漏洞扫描虽然有用，但这两者都不能证明该镜像是通过预期路径进来的、只包含可接受的组件，或者是后续部署时的那一组相同字节。标签是可以变动的。SBOM 可能是不完整的。发布后可能会出现新的 CVE。Sidecar 也可能带来与主应用程序不同的独立供应链风险。
ArtifactGate 是一个**基于证据的准入和提升门控**的个人参考实现。它将供应商镜像视为不受信任的输入，解析出确切的应用程序和 runner digest，收集安全证据，应用已记录的决策策略，并仅将通过校验的一对组合提升到受控的 registry 命名空间中。随后，部署阶段会验证提升证明，并使用这些相同的不可变 digest。
示例工作负载是 `n8nio/n8n`，但该模式的意义更广泛：在您能解释评估了什么、接受了什么以及实际将运行什么之前，不要将第三方软件转化为内部受信任的 artifact。
## ArtifactGate 产生的决策
ArtifactGate 旨在部署前回答六个问题：
| 问题 | 证据或控制 |
| :--- | :--- |
| **来源** — 这是否来自允许的上游？ | 来源允许列表和版本引入策略 |
| **身份** — 评估了哪些确切的字节？ | OCI digest 解析和 digest 锁定 |
| **构成** — 声明了哪些内部内容？ | SPDX SBOM 生成和证明 |
| **风险** — 目前已知哪些安全信号？ | 漏洞、恶意软件、密钥、许可证、KEV、EPSS、年龄和受限 runtime 检查 |
| **决策** — 为什么它被提升？ | 策略门控，或明确的、限定范围且带有有效期的豁免 |
| **连续性** — 我们部署和监控的是同一个 artifact 吗？ | 无密钥提升证明、部署前验证以及计划内重新扫描 |
这些是互补的控制措施。来源证明不是 SBOM，SBOM 不是漏洞判定，扫描也不是不可利用的证明，而签名也不能使不安全的内容变得安全。
## 此代码库的作用
- 将上游源镜像加入允许列表，并强制执行 semver 风格的版本引入
- 解析并扫描不可变的应用程序和 runner digest
- 使用 `KEV`、`EPSS`、CVE 年龄和 runtime 可达性上下文来丰富发现结果
- 将批准的应用程序和 runner 组合提升至 GHCR
- 为提升后的 artifact 提供来源和 SBOM 数据的证明
- 按计划重新扫描最新提升的发布版本
- 为 n8n 提供经过强化的 Docker Compose 部署方案
## 基于标准的框架
ArtifactGate 使用以下出版物作为设计参考。这是一种工程映射，并非认证或声称符合 NIST 或 SLSA。
| 参考 | 它如何为 ArtifactGate 提供参考 |
| :--- | :--- |
| [NIST SP 800-161 Rev. 1](https://csrc.nist.gov/pubs/sp/800/161/r1/upd1/final) | 将第三方软件构建为一种网络安全供应链风险，需要尽职调查、评估、缓解和持续监督。 |
| [NIST SP 800-190](https://csrc.nist.gov/pubs/sp/800/190/final) | 为受信任的镜像处理、漏洞管理、registry 控制以及强化的容器 runtime 配置提供参考。 |
| [NIST SP 800-218 (SSDF)](https://csrc.nist.gov/pubs/sp/800/218/final) | 为第三方组件验证，以及发布来源和完整性证据的收集与保护提供参考。 |
| [NIST SP 800-204D](https://csrc.nist.gov/pubs/sp/800/204/d/final) | 为将来源证明、证明、SBOM 和供应链控制集成到 CI/CD 中提供了最贴切的架构框架。 |
| [SLSA v1.2](https://slsa.dev/spec/v1.2/) | 提供了关于来源和验证预期的实用模型。ArtifactGate 并不为其未构建的上游镜像声明 SLSA 级别。 |
NIST 将 SBOM 描述为一种提高透明度、来源和漏洞识别速度的方法。因此，ArtifactGate 将 SBOM 与提升的 digest 绑定，并将清单输入到持续的风险审查中。它不将 SBOM 的存在视为清单完整或 artifact 安全的证明。
## 信任与规则的设定位置
规则保存在代码库中，因此任何更改都是可审查的，并会留下源代码历史记录。策略文件声明意图；工作流和增强脚本执行决策。
| 控制点 | 当前规则 | 事实来源 |
| :--- | :--- | :--- |
| 受信任的上游引入 | 仅限 `n8nio/n8n` 和 `n8nio/runners`；严格的 `x.y.z` 版本，在使用前解析 `latest` | [`policy/image-ingestion-policy.yml`](policy/image-ingestion-policy.yml) |
| 上游签名处理 | 仅警告，因为目前无法获取供应商签名；已记录接受的差距和审查日期 | [`policy/image-ingestion-policy.yml`](policy/image-ingestion-policy.yml) |
| 漏洞门控 | 严重/高危发现需要针对 KEV、年龄 ≥30 天、EPSS ≥2% 或未知必要证据进行审查 | [`policy/vulnerability-gate-policy.yml`](policy/vulnerability-gate-policy.yml) 和 [`enrich_findings.py`](.github/scripts/enrich_findings.py) |
| 手动例外 | `trusted-promotion` 环境批准，加上所有受门控的 CVE、有意义的理由、补偿控制措施和未来的过期时间 | [`image-promotion.yml`](.github/workflows/image-promotion.yml) |
| 受信任的输出 | 为应用程序和 runner 提供独立的 ArtifactGate GHCR 代码库和证明 | [`signing-and-attestation.md`](docs/signing-and-attestation.md) |
| 部署准入 | 针对所有者 `llody9977` 验证两个主体，然后通过不可变 digest 部署两者 | [`install.sh`](iac/n8n/install.sh) |
| 持续审查 | 每周对最新提升的发布版本进行重新扫描，并在风险超出当前门控时提出安全问题 | [`rescan.yml`](.github/workflows/rescan.yml) |
将该模式调整到其他供应商时，请首先通过拉取请求更改引入允许列表，确认供应商自身的签名或来源机制，定义适合您环境的风险阈值，并为受保护的提升环境配置独立的审查人员。
## 流水线流程
```
flowchart TD
A["Promotion request or weekly version check"] --> B["Allowlist and semver policy"]
B --> C["Resolve immutable digest"]
C --> D["Trivy, ClamAV, Tracee, and ZAP checks"]
D --> E["KEV, EPSS, age, and reachability enrichment"]
E --> F{"Approval gate"}
F -->|Lower-risk| G["Auto-promote to GHCR"]
F -->|Higher-risk| H["Manual approval"]
G --> I["Attest promotion provenance and SBOM"]
H --> I
I --> J["Create trusted release"]
J --> K["Scheduled re-scan of latest promoted release"]
```
## 保障边界
成功的提升并不意味着镜像是无漏洞的、合规的或适用于所有环境的。它仅表示该确切的镜像对通过了本项目已记录的检查，或者已识别的例外在被明确接受时附带了范围、理由和有效期。
GitHub OIDC 证明证明了 ArtifactGate 的提升工作流处理了特定的 digest。除非存在经过独立验证的上游来源，否则它**并不**证明上游供应商最初是如何构建该 digest 的。同样，Tracee 观测结果仅涵盖已执行的冒烟测试路径；未观测到的文件并不能证明是不可达的。
## 快速开始
要将最新提升的镜像部署到主机：
```
git clone https://github.com/llody9977/artifactgate.git
cd artifactgate/iac/n8n
chmod +x install.sh
./install.sh
```
安装流程：
- 解析要部署的代码库和发布版本
- 使用 GitHub CLI 要求并验证两个镜像的来源
- 写入部署 `.env`
- 使用外部 task runner 启动 n8n
- 支持回滚和可选的自动升级
安全默认设置将 n8n 绑定到 localhost，并期望在配置的 `PUBLIC_BASE_URL` 处进行 TLS 终止。仅在隔离的测试环境中使用 `--insecure-lab-mode`；它会禁用证明验证。
要手动运行镜像提升：
1. 打开 `Actions`
2. 选择 `Image Promotion (Trusted Source)`
3. 输入一个版本，例如 `2.14.2`，或保留 `latest`
## 文档
- [架构和信任模型](docs/architecture-and-trust.md)
- [批准门控策略](docs/gate-policy.md)
- [部署和操作](docs/deployment-and-operations.md)
## 代码库结构
```
.
├── .github/workflows/
├── .github/scripts/
├── docs/
├── iac/n8n/
└── policy/
```
## 关键路径
- [image-promotion.yml](https://github.com/llody9977/artifactgate/blob/main/.github/workflows/image-promotion.yml)
- [rescan.yml](https://github.com/llody9977/artifactgate/blob/main/.github/workflows/rescan.yml)
- [docker-compose.yml](https://github.com/llody9977/artifactgate/blob/main/iac/n8n/docker-compose.yml)
- [install.sh](https://github.com/llody9977/artifactgate/blob/main/iac/n8n/install.sh)
- [upgrade.sh](https://github.com/llody9977/artifactgate/blob/main/iac/n8n/upgrade.sh)
## 参考资料
- [OWASP Top 10 CI/CD 安全风险](https://owasp.org/www-project-top-10-ci-cd-security-risks/)
- [NIST SP 800-161 Rev. 1](https://csrc.nist.gov/pubs/sp/800/161/r1/upd1/final)
- [NIST SP 800-190](https://csrc.nist.gov/pubs/sp/800/190/final)
- [NIST SP 800-218](https://csrc.nist.gov/pubs/sp/800/218/final)
- [NIST SP 800-204D](https://csrc.nist.gov/pubs/sp/800/204/d/final)
- [NIST 软件供应链 SBOM 指南](https://www.nist.gov/itl/executive-order-14028-improving-nations-cybersecurity/software-supply-chain-security-guidance-20)
- [SLSA v1.2 规范](https://slsa.dev/spec/v1.2/)
- [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
- [FIRST EPSS](https://www.first.org/epss/)
- [CIS Docker 基准测试](https://www.cisecurity.org/benchmark/docker)
## 免责声明
ArtifactGate 是一个个人的、实验性的参考实现，提供用于一般信息和学习。它不是安全、法律、合规或风险管理建议，也不证明镜像、部署或上游发布者是安全的。
扫描和丰富的结果可能不完整、有延迟、被修改或不正确。Runtime 观测仅涵盖已执行的测试路径。已提升的镜像可能仍然包含可利用的漏洞，或者稍后变得容易受到攻击。请根据您自己的环境审查源代码、策略、扫描证据、例外情况和部署配置。本项目按“原样”提供，不提供任何保证。使用风险由您自行承担。
n8n 及其他产品名称和商标归其各自所有者所有。本项目不隶属于、不受认可或经 n8n、CIS、CISA、NIST、OWASP、Sigstore、Aqua Security 或 GitHub 认证。
## 许可证、归属和签名
ArtifactGate 基于 [Apache License 2.0](LICENSE) 发布。再分发必须保留适用的声明，包括 [NOTICE](NOTICE)。有关作者身份和 AI 辅助披露，请参见 [AUTHORS.md](AUTHORS.md)。
维护者的提交和标签使用为 VulnSignal 配置的相同本地 SSH 签名身份。已发布的容器证据使用 GitHub 基于 OIDC 的无密钥 artifact 证明；个人 SSH 私钥永远不会被复制到 GitHub Actions 中。这些身份服务于不同的信任目的，并会进行单独验证。
标签：DevSecOps, Web截图, 上游代理, 容器安全, 应用安全, 开源框架, 持续集成, 版权保护, 自定义DNS解析器, 逆向工具