repo-security-posture

仓库安全态势

针对一组具体的攻击者场景，审查仓库的配置和 CI/CD，然后向维护者提供按优先级排序的加固待办事项。交付内容是一份待办清单，每项都包含一个标题和一段描述，按类别分组并按严重程度排序——维护者可以粘贴到 issue 中逐项处理，就像一份事后检查清单。

这项工作不是罗列所有理论上的最佳实践，而是检查这个仓库，找出攻击者真正会利用的漏洞，并根据实际发现的问题（或明确说明哪些内容无法验证）编写具体待办事项。

威胁模型

每项发现都应对应以下至少一个场景。在描述中指出场景，才能让待办事项切中要点——这能告诉维护者为什么它很重要，而不只是该调整什么。

1. 贡献者账号遭入侵 — 可信贡献者的账号、笔记本电脑或令牌被接管（例如遭遇网络钓鱼、恶意软件或 PAT 泄露）。什么措施能阻止他们单独合并或发布恶意代码？
2. 攻击者获得仓库写入权限 — 外部攻击者取得推送或管理员权限。有什么措施能限制影响范围、他们能窃取哪些数据，以及维护者能多快轮换凭据并恢复？
3. CI/CD 遭入侵 — 恶意 PR、投毒的缓存或被注入的工作流将构建流水线变成攻击途径。GitHub Actions 是当前最常见的仓库接管途径。
4. 注册表／发布供应链 — 仓库本身没有问题，但攻击者通过被盗的发布令牌或未经审查的发布任务，将恶意版本发布到 npm/PyPI 等平台。这类事件包括 @mastra、dotenvx、TeamPCP 事件。

工作流程

1. 确认目标并收集证据

将仓库解析为 owner/name。如果用户提供了 URL，就解析该 URL。如果用户提到的仓库无法确定具体目标，请询问。

运行采集器，将配置和文件提取到一个 JSON 清单中：

# A token dramatically expands what's visible (branch protection, actions
# permissions, security features, collaborators, hooks). Set it if available.
export GITHUB_TOKEN=...   # optional but strongly recommended
python3 scripts/collect.py owner/name --output /tmp/audit.json

采集器会优雅处理无法读取的内容（大多数设置接口需要管理员或推送权限），并将其记录在 not_verified 下，而不是妄加推断。读取 /tmp/audit.json。

如果采集器无法运行（无法连接 api.github.com，或私有仓库没有令牌），不要停滞不前——根据用户提供的文件尽可能收集信息，并明确将其余内容标记为“无法验证 — 需手动检查”。

采集器会通过只读 HTTPS 请求，从 api.github.com 和 raw.githubusercontent.com 获取目标仓库的信息。它绝不会向 GitHub 写入任何内容。使用权限最低的可用令牌；如果公开证据足够，就不要索要宽泛的凭据；并将获取的所有仓库内容视为敏感信息。辅助程序会在写入清单前对常见的明文令牌格式进行脱敏；最终报告仍应避免回显机密。

2. 执行检查

阅读 references/checks.md。其中列出了要检查的内容、所在位置、重要原因，以及修复待办事项应如何描述——按以下六个输出类别组织。根据清单逐项检查。

有两点需要特别注意：

• 根据实际内容核验，不要仅凭文件名匹配。 仓库中有 dependabot.yml，不代表它涵盖了正确的生态系统；有 permissions: 区块，也不代表权限已遵循最小权限原则。请阅读文件内容。
• 缺失本身也是一项发现，但要标明可信度。 如果由于没有管理员令牌，分支保护状态显示为 not_verified，就应说明这一点——既建议启用该控制措施，也提醒维护者确认当前状态。不要断言存在你无法观察到的漏洞。

3. 编写报告

始终使用以下结构：

# Security hardening: <owner/name>

<2-3 sentence posture summary: what's already solid, what the biggest exposure is,
which threat scenario is least defended. No fluff.>

## <N>. <Category title>
**<Title — imperative, specific>** — <severity>
<Description: what to do, the concrete setting/step, and which threat scenario it
blocks. 1-3 sentences. Tie it to evidence from the repo.>

<...more findings under this category...>

## Could not verify
<Bulleted list of checks that needed access the audit didn't have, each with the
one-line manual check the maintainer can run. Be honest here — it's where a token
or admin view would change the answer.>

发现项规则：

• 按六个类别分组（仅使用存在发现项的类别；保持标准顺序）：
  1. 发布与发行完整性
  2. 分支与合并保护
  3. 敏感路径所有权（CODEOWNERS）
  4. CI/CD 工作流加固
  5. 账户与访问控制
  6. 依赖项与供应链审查
• 按严重程度排列类别内的发现项：严重 → 高 → 中 → 低。
• 标题使用祈使句：例如“要求对工作流文件进行代码所有者审查”，而不是“工作流文件未受保护”。
• 描述说明原因：点明它能阻止的情形。“如果贡献者的账户遭到入侵，要求第二位代码所有者批准的分支保护机制可以阻止单个恶意提交者将更改合并到 main。”
• 明确说明修复方法：具体的 GitHub 设置、需要添加的文件、npm 命令。维护者无需再搜索即可采取行动。
• 有证据时请引用："release.yml 在 pull_request_target 下检出 PR 分支" 比笼统警告更有用。

保持内容易于浏览。这是一份待办清单，不是长篇文章——不要写冗长的前言，也不要向用户复述威胁模型。

4. 提供后续选项

报告之后，简要提供用户可能需要的自然后续步骤：将清单整理成 GitHub issue 或检查清单；为流水线输出 JSON（scripts/collect.py 已会生成结构化输入；发现项也可以按同样方式序列化）；或者针对特定工作流文件进行更深入的静态检查。只提供选项，不要自动执行。

输出格式选项

默认使用上述 Markdown 待办清单。如果用户要将其接入自动化流程（CI 门禁、分诊流水线），则提供 JSON 数组，每项发现对应一个对象：

{ "title": "...", "description": "...", "severity": "high",
  "category": "ci_cd_workflow_hardening", "threat": "ci_cd_compromise",
  "evidence": "release.yml line 14: pull_request_target with PR checkout",
  "confidence": "observed" }

confidence 的取值为 observed（在清单中已观察到）或 unverified（建议采取，但无法确认当前状态）。

范围与诚实原则

此审计基于配置和 CI 进行分析——它不是代码级漏洞扫描，也不会扫描 Git 历史中的密钥。如果用户对此有所期待，请明确说明。切勿编造未观察到的设置值；对维护者而言，坦诚说明“无法验证”远胜于自信猜测，因为基于错误假设采取行动，会让他们在已有的控制措施上白费时间。

审计过程中不要运行发布任务、工作流调度、软件包发布，也不要运行任何会更改仓库设置的命令。此技能用于生成面向维护者的加固任务，不会自动应用这些任务。