repo-audit

Repo Audit 是一个用于审计 GitHub 仓库安全设置与卫生状况的工具，能够检测偏差、报告发现的问题，并可选地自动修复。

一、用途 它面向需要批量检查 GitHub 仓库配置是否合规的开发者或团队，帮助发现安全设置缺失、依赖更新配置缺失、工作流写法问题、长期未处理的 PR 与分支，以及第三方 Action 未固定版本等风险。默认审计组织为 skinnyandbald。

二、调用方式 /repo-audit # 审计所有活跃仓库（默认组织：skinnyandbald） /repo-audit <repo> # 审计单个仓库（例如 skinnyandbald/cos-bot） /repo-audit --fix # 审计并自动修复可修复项 /repo-audit <org> # 审计指定组织下所有活跃仓库 /repo-audit <repo> --fix # 审计单个仓库并修复

三、工作流程 Step 0：预检——Token 权限检查。运行任何检查前先验证 token 是否有效（gh api /user），并通过第一个仓库的漏洞警报接口测试 repo 权限（gh api repos/{first-repo}/vulnerability-alerts）。若任一调用失败，则警告用户并跳过安全设置检查（dependabot-alerts、dependabot-autofixes），继续执行只需读权限的检查（dependabot-config、semgrep-syntax、stale-prs、stale-branches、actions-pinned）。警告示例：WARNING: Token permission check failed. Ensure your token has repo scope. Security settings checks will be skipped.

Step 1：构建仓库列表。单仓库模式下直接使用该仓库；组织模式下列出所有活跃仓库。活跃仓库定义为：非归档且最近 180 天内有推送。使用 gh repo list 命令配合 CUTOFF 日期过滤，命令中注明 macOS 使用 date -v-180d，Linux 使用 date -d '-180 days'。执行前先报告仓库数量。

Step 2：运行所有检查。对每个仓库执行以下检查，结果分为 Critical、Warning、Clean 三类。若审计 50 个以上仓库，每个仓库之间加 sleep 1 以规避速率限制。

检查项定义：

1. dependabot-alerts（Critical，可自动修复）：验证仓库级别漏洞警报是否启用。gh api repos/{repo}/vulnerability-alerts，204 表示启用，404 表示禁用。
2. dependabot-autofixes（High，可自动修复）：验证自动安全修复是否启用。gh api repos/{repo}/automated-security-fixes，检查响应 JSON 的 enabled 字段。
3. dependabot-config（High，可自动修复）：验证 .github/dependabot.yml 是否存在。gh api repos/{repo}/contents/.github/dependabot.yml，404 表示缺失。
4. semgrep-syntax（High，可自动修复）：扫描 .github/workflows/ 下所有 *.yml 文件，检查是否有文件在同一行或同一步骤中同时包含 semgrep ci 与 --config auto。
5. stale-prs（Low，仅报告）：查找超过 30 天的开放 PR，报告数量及编号/标题。
6. stale-branches（Low，仅报告）：查找 tip commit 超过 60 天的分支，排除默认分支、dependabot/、renovate/、release/* 前缀，以及存在开放 PR（作为来源或目标）的分支。
7. actions-pinned（High，仅报告）：扫描工作流文件中的第三方 GitHub Actions 是否未按 SHA 固定。当 action owner 不是 actions/* 或 github/*，且 @ 后的 ref 不是 40 位十六进制 SHA 时被标记，可捕获 @main、@master、@v1、@v1.2.3 等非 SHA ref。

Step 3：报告。将结果格式化为 markdown 报告，包含三个部分：Critical Issues、Warnings、All Clear，并给出汇总。严重程度映射：Critical Issues 对应 dependabot-alerts；Warnings 对应 dependabot-autofixes、dependabot-config、semgrep-syntax、actions-pinned（High）以及 stale-prs、stale-branches（Low）；All Clear 为无发现项的仓库。若未传 --fix，提醒用户运行 /repo-audit --fix 以自动修复可修复问题。

Step 4：自动修复（仅在传入 --fix 时）。若未传 --fix 则到此停止，不修改任何内容。可自动修复项分两类： 设置类修复（API PUT，无需 git）：

• dependabot-alerts：gh api repos/{repo}/vulnerability-alerts --method PUT
• dependabot-autofixes：gh api repos/{repo}/automated-security-fixes --method PUT 内容类修复（GitHub Contents API，无需克隆）：
• dependabot-config：使用默认模板创建 .github/dependabot.yml。仅当仓库有 package.json（npm 生态）或 .github/workflows/（actions 生态）时才推送；两者皆无则跳过。新建文件时省略 sha 字段。
• semgrep-syntax：更新每个有问题的 workflow 文件，移除 --config auto。扫描 .github/workflows/ 下所有 *.yml 文件（不只 security.yml），通过 Contents API 推送修复。

默认 Dependabot 模板（version: 2）包含两个 updates：npm 生态（directory 为 /，weekly，open-pull-requests-limit 为 10，cooldown 默认 7 天、semver-major 14 天、semver-minor 7 天、semver-patch 3 天）；github-actions 生态（directory 为 /，weekly，open-pull-requests-limit 为 5，cooldown 默认 3 天）。

修复完成后输出 Fixes Applied 报告表格，列出仓库、检查项与执行的操作。

四、约束

• 绝不修改仓库代码，仅修改仓库设置与 .github/ 下的配置文件。
• 默认只读，仅当传入 --fix 时应用修复。
• 跳过归档仓库（仓库列表查询已过滤）。
• 组织无关，可用于任意 GitHub 组织，未指定时默认 skinnyandbald。
• 速率限制：审计 50 个以上仓库时，仓库间加 sleep 1。
• macOS 使用 date -v-Nd 语法，Linux 使用 date -d '-N days'。
• 无需克隆，所有检查与修复直接使用 GitHub API。
• 修复前确认：传入 --fix 时先展示审计报告，再与用户确认后应用修复，并明确列出将要更改的内容。

五、适用场景 适合需要定期或批量检查多个 GitHub 仓库安全与卫生状况的场景，尤其适合使用 GitHub Actions、npm 依赖较多、需要统一 Dependabot 配置与 Action 版本固定的组织。

六、限制 需要具有 repo 权限的 token，否则安全设置检查会被跳过；该工具依赖 GitHub API，受速率限制影响；仅审计、修复设置与 .github/ 配置文件，不涉及仓库代码；工具未提供收费、价格、平台或其他效果信息。