ctrlzmydecisions/originfence
GitHub: ctrlzmydecisions/originfence
OriginFence 是一个 GitHub 原生的依赖信任门禁工具，在 PR 合并前对新增或变更的依赖包进行信任评估和策略控制。
Stars: 0 | Forks: 0
# OriginFence
在新的依赖变更合入前对其进行信任评估。
OriginFence 会在 pull request 中审查依赖变更，并在合并前告知您是否应该信任它们。
它仅关注 PR 中新增或变更的包，然后结合仓库策略、豁免规则、来源 (provenance) 检查、恶意软件情报以及上游 registry 信号，决定是 `allow` (允许)、`warn` (警告)、`review` (审查) 还是 `block` (阻断) 这些包。
它专为那些希望在 GitHub 合并时做出信任决策、并将策略和豁免规则保存在仓库中的团队而构建。
状态：
- `alpha`
- 支持的生态系统：`npm`, `PyPI`
- 主要适用场景：`GitHub pull_request` 和 `merge_group` 工作流
## 它的功能
OriginFence 专注于合并边界：
- PR 中新增或变更的包
- 硬性信号，如已知恶意包和上游隔离状态
- 保留在仓库中的策略决策
- 开发者可以直接在 pull request 中阅读的输出结果
## 它能捕捉什么
- 已知恶意包和上游隔离信号
- 策略要求但缺失或无效的来源 (provenance)
- 直接 URL 和 VCS 依赖
- Manifest 和 lockfile 漂移
- 无法精确评估的不受支持的依赖布局
## 在 Pull Request 中
### 恶意包阻断
当包匹配到恶意软件情报时，OriginFence 会采取直接阻断的态度：
### 缺失来源 (Provenance) 审查
当策略要求来源证明时，OriginFence 会直接在 PR 中显示缺失的证据：
### 安全推出
您可以从 `observe` (观察) 模式开始，这样检查将保持绿色（通过），同时让人们看到真实的决策和后续行动：
### 不受支持的布局快速失败
如果 OriginFence 无法精确评估某种依赖布局，它会明确说明，而不是假装已部分覆盖：
## 入门指南
将如下所示的工作流添加到消费者仓库中：
```
name: OriginFence
on:
pull_request:
merge_group:
types:
- checks_requested
permissions:
contents: read
pull-requests: write
issues: write
jobs:
originfence:
runs-on: ubuntu-latest
steps:
- name: Checkout merge candidate
uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Run OriginFence
id: originfence
uses: OWNER/originfence@v0
with:
enforcement-mode: observe
write-job-summary: "true"
pr-comment: "true"
comment-mode: review_and_block
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Upload OriginFence artifacts
if: always()
uses: actions/upload-artifact@v4
with:
name: originfence-report-${{ github.run_id }}-${{ github.job }}
path: |
${{ steps.originfence.outputs.report-path }}
${{ steps.originfence.outputs.summary-path }}
```
参考示例：
- [`examples/repo/.github/workflows/originfence-required-check.yml`](./examples/repo/.github/workflows/originfence-required-check.yml)
- [`.github/workflows/originfence-reusable.yml`](./.github/workflows/originfence-reusable.yml)
## 决策机制
1. 将基础版本与 PR head 进行比较。
2. 仅从支持的 manifest 和 lockfile 中解析变更的依赖主体。
3. 收集 registry 元数据、来源 (provenance) 信号、恶意软件情报以及 OriginFence 漂移历史。
4. 应用基准策略、仓库策略和显式豁免规则。
5. 输出必需检查结果、Job 摘要、可选的置顶 PR 评论以及规范化 JSON 报告。
## 推出流程
推荐的推出路径：
1. 从预设模板添加 `.originfence/policy.yaml` 和 `.originfence/waivers.yaml`。
2. 以 `enforcement-mode: observe` 模式开始。
3. 查看一两周内的 Job 摘要和 PR 评论。
4. 调整策略和豁免规则。
5. 当仓库准备就绪后，切换到 `enforcement-mode: enforce` 模式。
预设入口：
- [`presets/observe.policy.yaml`](./presets/observe.policy.yaml)
- [`presets/balanced.policy.yaml`](./presets/balanced.policy.yaml)
- [`presets/strict.policy.yaml`](./presets/strict.policy.yaml)
- [`presets/waivers.yaml`](./presets/waivers.yaml)
如果您是从本地检出运行 OriginFence，可以直接引导配置文件：
```
npm install
npm run build:test
node dist/src/cli.js init --preset observe
```
## 信号来源
OriginFence 按以下顺序评估恶意包信号：
- 来自 `malicious-packages-file` 的可选本地覆盖条目，用于紧急情况或组织特定的阻断
- 通过 OSV 获取的 OpenSSF malicious-packages
- 作为补充 npm 来源的 GitHub npm 恶意软件公告
PyPI 项目状态作为硬性上游 registry 信号单独处理。
## 输出
OriginFence 始终会写入：
- 一份规范化 JSON 报告
- 一份纯文本摘要
在 GitHub 中，OriginFence 将决策映射为兼容必需检查的状态：
- `success` (成功)：仅包含 `allow` 和 `warn`
- `failure` (失败)：包含任何 `review` 或 `block`
- `neutral` (中立)：未检测到受支持的依赖变更
在 `observe` 模式下，OriginFence 会在报告和人类可读的输出中保留底层决策，但将工作流状态重新映射为 `success`，以便仓库可以调整策略而不干扰合并。
## 限制
- GitHub 是 v1 中唯一的一流交付平台。
- OriginFence 仅支持 `npm` 和 `PyPI`。
- OriginFence 仅评估变更的主体；它不是完整的历史依赖清单扫描器。
- OriginFence 是一个 PR 关卡，而不是透明的包代理。
- 来源 (Provenance) 是有用的证据，而非包安全的证明。
- 仓库以预构建的打包 JavaScript 形式提供 Action；npm 包发布尚未设置。
## 开发
```
npm install
npm run build
npm test
```
公共仓库包含 `npm test` 使用的测试套件和 fixture 语料库，因此贡献者可以在本地验证行为，而不仅仅依赖截图或发布说明。
常用路径：
- [`action.yml`](./action.yml)
- [`schemas/`](./schemas)
- [`fixtures/`](./fixtures)
- [`examples/`](./examples)
- [`presets/`](./presets)
- [`scripts/run-live-canaries.js`](./scripts/run-live-canaries.js)
## 文件
- [`CHANGELOG.md`](./CHANGELOG.md)
- [`LICENSE`](./LICENSE)
标签：CI/CD 安全, Cilium, DevSecOps, GitHub App, GNU通用公共许可证, MITM代理, Node.js, NPM, Pull Request 检查, PyPI, Python, SBOM, Streamlit, 上游代理, 代码安全, 代码审查, 供应链攻击防御, 依赖管理, 安全合规, 安全网关, 恶意包检测, 数据可视化, 数据投毒防御, 文档安全, 无后门, 暗色界面, 源代码完整性, 源码溯源, 漏洞枚举, 硬件无关, 网络代理, 自定义DNS解析器, 自定义脚本, 访问控制, 跌倒检测, 软件开发工具包, 软件物料清单