repo-sentinel

Repo Sentinel

公共仓库中的所有内容都是永久的攻击面。本技能定义了哪些内容可以放入公共仓库、哪些不可以、如何检测 12 个攻击面上的违规情况、如何在越界时进行修复，以及如何持续执行这些要求。

参考文件

本技能使用随附的参考文件，其中包含详细模式和模板。请按需阅读：

文件	阅读时机
references/attack-surfaces.md	审计任何攻击面时——包含攻击面 0–12 的完整定义
references/scan-patterns.md	运行任何审计（快速路径或完整审计）时——包含所有检测命令
references/pre-release-checklist.md	运行发布前审计（阶段 4）时——§4.1–§4.8 准备情况检查清单
references/templates.md	设置执行机制、生成 .gitignore 或创建 CI 门禁时
references/remediation.md	修复发现的问题或清理历史记录时——包含所有修复流程

---

先决条件

• 已安装并完成身份验证的 gh CLI（gh auth status 必须通过）——GitHub 专属攻击面检查（攻击面 10）所必需
• 处于有效的 git 仓库上下文中——本技能针对 git 对象运行；不适用于非 git 目录
• trufflehog 或 gitleaks——可选，但强烈建议用于通过熵分析检测攻击面 0（git 历史记录）中的机密；如果没有这些工具，则使用 references/scan-patterns.md 中的 git log -p grep 模式
• 对完整 git 对象存储的读取权限——浅克隆（--depth N）会漏掉历史记录中的机密；如果检测到浅克隆，请提醒用户

校准规则

• 公共与私有可见性： 对公共仓库采用更严格的严重性评级——在私有仓库中评为 MEDIUM 的问题（例如注释中的内部 URL），在公共仓库中升级为 HIGH。评分前确认仓库的可见性。
• 按技术栈确定攻击面范围： 根据检测到的技术栈，仅审计相关的攻击面。静态 HTML 仓库没有实质性的攻击面 6（容器）或攻击面 7（锁文件）暴露——将这些攻击面标记为 N/A，而不是扣分。
• N/A 处理： 评为 N/A 的攻击面不予扣分，也不会降低整体风险态势。明确记录 N/A 攻击面，让用户了解跳过了哪些内容。
• 工具可用性： 如果无法使用 trufflehog/gitleaks，请在审计标题中注明，并说明攻击面 0 覆盖范围的置信度较低。
• 严谨处理误报： 只有在有实际暴露证据时才标记问题，不能仅凭模式相似就标记。名为 api_key 且值为占位符的变量属于 LOW，而非 CRITICAL。

基本原则

公开与私有边界是一道单向阀门。 一旦某个字节到达公共远程端——无论是通过推送、PR、议题、Wiki、发布资源还是 GitHub Pages——都应假设它会被永久索引、缓存、镜像和存档。git push --force、删除 PR、编辑议题和移除发布内容都不能保证将其抹除。抓取基础设施（GitHub Archive、GH Torrent、Software Heritage、Google Cache、Wayback Machine 以及数十种专有安全扫描器）会持续运行，延迟不到一小时。

每件产物的决策框架：

问题	如果是 →	如果否 →
这能否帮助没有其他访问权限的攻击者？	排除	继续
这是否泄露了无法从公开信号推断出的内部拓扑？	排除	继续
这是否包含可用于访问任何事物的值？	排除	继续
这是否违反许可义务或带来法律风险？	排除	继续
移除这项内容是否会降低仓库对合法用户的实用性？	纳入（前述各项均为否时）	排除

如有疑问，就排除。漏报（泄露机密）是灾难性的，且无法挽回。误报（过度删减）则很容易纠正。

---

12 个攻击面

攻击面 0 至 12 的完整定义——包括哪些内容属于其中、哪些不属于、泄露原因和检测方法——见 references/attack-surfaces.md。在确定任何审计的范围或评分时，请阅读该文件。各攻击面的扫描命令位于 references/scan-patterns.md；补救流程位于 references/remediation.md。

---

严重性分类

所有发现均按严重性分类。分类决定处理优先级：

严重性	标准	操作
CRITICAL	活跃凭据泄露、私钥、身份验证令牌	阻止推送。立即修复。
HIGH	可助力定向攻击的基础设施／拓扑信息	推送前解决。
MEDIUM	有助于侦察的信息泄露	在下一次提交中修复。
LOW	卫生、风格、冗余问题	方便时修复。

Git 历史中的 CRITICAL 和 HIGH 级问题 → 必须彻底清理完整历史并轮换凭据。

---

操作

快速审计（仅暂存的更改）

推送单个文件或小型更改集时使用。仅扫描暂存的更改，不扫描整个仓库。 请阅读 references/scan-patterns.md § Fast-Path，了解相关命令。

完整仓库审计（20+ 项检查）

在将任何仓库设为公开，或首次推送到公共远程端之前运行。 请阅读 references/scan-patterns.md § Full Audit，了解完整的 20 项检查流程、 快速参考扫描命令块以及审计输出格式。

发布前审计模式（4 阶段 DAG）

准备将仓库开源时，请运行此 4 阶段发布前审计，而不是基于攻击面的审计。每个阶段都会输出 PASS / WARN / FAIL，并提供可执行的补救措施。第 1–3 阶段中的硬性阻断项会停止流水线。第 4 阶段会生成建议性输出。

Stage 1: Sensitive Assets        [HARD BLOCKER] → Surfaces 0–4, 8–9
Stage 2: Legal & Compliance      [HARD BLOCKER] → Surface 11
Stage 3: Public Surface Hygiene  [HARD BLOCKER] → Surfaces 4–7, 9–10
Stage 4: Contribution & Release  [SOFT BLOCKER] → Surface 12 + Pre-Release Checklist

按顺序运行各阶段。最后以结构化审计表的形式报告结果。第 4 阶段的检查清单项（§4.1–§4.8）见 references/pre-release-checklist.md。

持续执行防护设置

左移预防是效益最高的措施。请阅读 references/templates.md，获取可直接使用的 pre-commit 配置、GitHub Actions 工作流和 .gitignore 生成器。

历史泄露修复

当机密信息已提交后。阅读 references/remediation.md，了解完整的分类决策树、git filter-repo 命令、BFG 备选方案、清理后的处理流程以及 .gitignore 生成指南。

---

局限性

• 清理历史记录并不能保证彻底消除泄露。必须强制推送；外部镜像（fork、GitHub Archive、Software Heritage）无论本地如何操作，都会永久保留历史记录。
• 内容移除后，无法验证外部镜像、缓存和搜索引擎索引是否已取消索引。
• 仅适用于单个仓库，不适合未经调整直接用于 monorepo 审计。跨软件包的机密信息传播需要针对每个软件包根目录单独分析。
• GitHub 特定检查（分支保护、机密扫描警报、安全公告）需要通过已认证的 gh CLI。没有它时，Surface 10 的覆盖范围会缩小。
• 机密扫描深度取决于可用工具。trufflehog 和 gitleaks 通过熵分析提供经验证的检测；作为备选方案使用的手动正则表达式模式误报率较高，也会漏掉经过混淆处理的凭据。
• 软件包注册表发布（npm、PyPI、crates）的制品判定有其特定生态规范，与源代码仓库的纳入规则不同；审计已发布制品时，请遵循相应生态规范。