Oss Forensics

供应链调查、证据恢复与 GitHub 仓库取证分析。涵盖已删除提交恢复、强制推送检测、IOC 提取、多源证据收集、假设形成/验证以及结构化取证报告。灵感来源于 RAPTOR 的 1800+ 行 OSS Forensics 系统。

技能元数据


来源	可选 — 使用 `hermes skills install official/security/oss-forensics` 安装
路径	`optional-skills/security/oss-forensics`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是 Agent 在技能激活时看到的指令。

OSS 安全取证技能

一个用于研究开源供应链攻击的 7 阶段多 Agent 调查框架。改编自 RAPTOR 的取证系统。涵盖 GitHub Archive、Wayback Machine、GitHub API、本地 git 分析、IOC 提取、基于证据的假设形成与验证，以及最终取证报告生成。

⚠️ 反幻觉护栏

在每次调查步骤前阅读。违反这些规则将使报告无效。

证据优先规则：任何报告、假设或摘要中的每个声明都必须引用至少一个证据 ID（EV-XXXX）。禁止无引用的断言。
各司其职：每个子 Agent（调查员）只有一个数据源。不要混合来源。GH Archive 调查员不查询 GitHub API，反之亦然。角色边界是硬性的。
事实与假设分离：所有未经验证的推论必须标记为 [HYPOTHESIS]。只有经过原始来源验证的陈述才能作为事实陈述。
禁止捏造证据：假设验证器必须在接受假设之前机械地检查每个引用的证据 ID 是否确实存在于证据存储中。
需要证据的反驳：没有具体的、有证据支持的反驳论点，就不能驳回假设。“未找到证据”不足以反驳——它只会使假设变得不确定。
SHA/URL 双重验证：任何作为证据引用的提交 SHA、URL 或外部标识符，在标记为已验证之前，必须至少从两个来源独立确认。
可疑代码规则：切勿在本地运行在被调查仓库中找到的代码。仅进行静态分析，或使用 execute_code 在沙盒环境中运行。
机密信息编辑：调查过程中发现的任何 API 密钥、令牌或凭据必须在最终报告中编辑。仅在内部记录。

示例场景

场景 A：依赖混淆：一个恶意包 internal-lib-v2 以比内部版本更高的版本上传到 NPM。调查员必须追踪该包首次出现的时间，以及目标仓库中是否有任何 PushEvent 将 package.json 更新为此版本。
场景 B：维护者接管：一个长期贡献者的账户被用来推送带有后门的 .github/workflows/build.yml。调查员会查找该用户在长时间不活动后或从新 IP/位置（如果可通过 BigQuery 检测到）发出的 PushEvent。
场景 C：强制推送隐藏：开发者意外提交了生产机密，然后强制推送以“修复”它。调查员使用 git fsck 和 GH Archive 恢复原始提交 SHA 并验证泄露了什么。

阶段 1：提示解析与 IOC 提取

目标：从用户请求中提取所有结构化的调查目标。

操作：

解析用户提示并提取：
- 目标仓库（owner/repo）
- 目标参与者（GitHub 用户名、电子邮件地址）
- 关注的时间窗口（提交日期范围、PR 时间戳）
- 提供的入侵指标：提交 SHA、文件路径、包名、IP 地址、域名、API 密钥/令牌、恶意 URL
- 任何关联的供应商安全报告或博客文章

工具：仅使用推理，或使用 execute_code 从大文本块中进行正则表达式提取。

输出：将提取的 IOC 填入 iocs.md。每个 IOC 必须包含：

类型（来自：COMMIT_SHA、FILE_PATH、API_KEY、SECRET、IP_ADDRESS、DOMAIN、PACKAGE_NAME、ACTOR_USERNAME、MALICIOUS_URL、OTHER）
值
来源（用户提供、推断）

参考：参见 evidence-types.md 了解 IOC 分类。

阶段 2：并行证据收集

使用 delegate_task（批处理模式，最多 3 个并发）生成最多 5 个专业调查子 Agent。每个调查者拥有单一数据源，且不得混合来源。

编排者注意：在委托任务的 context 字段中传递阶段 1 的 IOC 列表和调查时间窗口。

调查者 1：本地 Git 调查者

角色边界：你仅查询本地 Git 仓库。不要调用任何外部 API。

操作：

# 克隆仓库
git clone https://github.com/OWNER/REPO.git target_repo && cd target_repo

# 完整提交日志（含统计信息）
git log --all --full-history --stat --format="%H|%ae|%an|%ai|%s" > ../git_log.txt

# 检测强制推送证据（孤立/悬空提交）
git fsck --lost-found --unreachable 2>&1 | grep commit > ../dangling_commits.txt

# 检查 reflog 以发现重写的历史
git reflog --all > ../reflog.txt

# 列出所有分支（包括已删除的远程引用）
git branch -a -v > ../branches.txt

# 查找可疑的大二进制文件添加
git log --all --diff-filter=A --name-only --format="%H %ai" -- "*.so" "*.dll" "*.exe" "*.bin" > ../binary_additions.txt

# 检查 GPG 签名异常
git log --show-signature --format="%H %ai %aN" > ../signature_check.txt 2>&1

需收集的证据（通过 python3 SKILL_DIR/scripts/evidence-store.py add 添加）：

每个悬空的提交 SHA → 类型：git
强制推送证据（显示历史重写的 reflog） → 类型：git
已验证贡献者的未签名提交 → 类型：git
可疑的二进制文件添加 → 类型：git

参考：详见 recovery-techniques.md，了解如何获取强制推送的提交。

调查员 2：GitHub API 调查员

角色边界：你仅查询 GITHUB REST API。不要在本地运行 git 命令。

操作：

# 提交（分页）
curl -s "https://api.github.com/repos/OWNER/REPO/commits?per_page=100" > api_commits.json

# 拉取请求（包括已关闭/已删除）
curl -s "https://api.github.com/repos/OWNER/REPO/pulls?state=all&per_page=100" > api_prs.json

# Issue
curl -s "https://api.github.com/repos/OWNER/REPO/issues?state=all&per_page=100" > api_issues.json

# 贡献者和协作者变更
curl -s "https://api.github.com/repos/OWNER/REPO/contributors" > api_contributors.json

# 仓库事件（最近 300 条）
curl -s "https://api.github.com/repos/OWNER/REPO/events?per_page=100" > api_events.json

# 检查特定可疑提交 SHA 的详细信息
curl -s "https://api.github.com/repos/OWNER/REPO/git/commits/SHA" > commit_detail.json

# 发布版本
curl -s "https://api.github.com/repos/OWNER/REPO/releases?per_page=100" > api_releases.json

# 检查某个具体提交是否存在（强制推送的提交可能在 commits/ 返回 404，但在 git/commits/ 返回成功）
curl -s "https://api.github.com/repos/OWNER/REPO/commits/SHA" | jq .sha

交叉验证目标（将不一致之处标记为证据）：

PR 在归档中存在但 API 中缺失 → 删除证据
贡献者在归档事件中出现但不在贡献者列表中 → 权限撤销证据
提交在归档的 PushEvents 中出现但不在 API 提交列表中 → 强制推送/删除证据

参考：详见 evidence-types.md，了解 GH 事件类型。

调查员 3：Wayback Machine 调查员

角色边界：你仅查询 WAYBACK MACHINE CDX API。不要使用 GitHub API。

目标：恢复已删除的 GitHub 页面（README、Issue、PR、发布版本、Wiki 页面）。

操作：

# 搜索仓库主页的归档快照
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO&output=json&limit=100&from=YYYYMMDD&to=YYYYMMDD" > wayback_main.json

# 搜索某个已删除的 Issue
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/issues/NUM&output=json&limit=50" > wayback_issue_NUM.json

# 搜索某个已删除的 PR
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/pull/NUM&output=json&limit=50" > wayback_pr_NUM.json

# 获取某个页面的最佳快照
# 使用 Wayback Machine 的 URL：https://web.archive.org/web/TIMESTAMP/ORIGINAL_URL
# 示例：https://web.archive.org/web/20240101000000*/github.com/OWNER/REPO

# 高级：搜索已删除的发布版本/标签
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/releases/tag/*&output=json" > wayback_tags.json

# 高级：搜索历史 Wiki 变更
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/wiki/*&output=json" > wayback_wiki.json

需要收集的证据：

已删除的 issue/PR 及其内容的存档快照
显示变更历史的 README 历史版本
存档中存在但当前 GitHub 状态中缺失的内容证据

参考：参见 github-archive-guide.md 了解 CDX API 参数。

调查员 4：GH Archive / BigQuery 调查员

角色边界：你仅通过 BIGQUERY 查询 GITHUB ARCHIVE。这是所有公开 GitHub 事件的防篡改记录。

前置条件：需要具有 BigQuery 访问权限的 Google Cloud 凭据（gcloud auth application-default login）。如果不可用，请跳过此调查员并在报告中注明。

成本优化规则（强制）：

每次查询前务必先运行 --dry_run 以估算成本。
使用 _TABLE_SUFFIX 按日期范围过滤，最小化扫描数据量。
只 SELECT 你需要的列。
除非是聚合查询，否则添加 LIMIT。

# 模板：针对 OWNER/REPO 的 PushEvents 的安全 BigQuery 查询
bq query --use_legacy_sql=false --dry_run "
SELECT created_at, actor.login, payload.commits, payload.before, payload.head,
       payload.size, payload.distinct_size
FROM \`githubarchive.month.*\`
WHERE _TABLE_SUFFIX BETWEEN 'YYYYMM' AND 'YYYYMM'
  AND type = 'PushEvent'
  AND repo.name = 'OWNER/REPO'
LIMIT 1000
"
# 如果成本可接受，去掉 --dry_run 重新运行

# 检测强制推送：distinct_size 为零的 PushEvents 表示提交被强制擦除
# payload.distinct_size = 0 AND payload.size > 0 → 强制推送指示器

# 检查已删除的分支事件
bq query --use_legacy_sql=false "
SELECT created_at, actor.login, payload.ref, payload.ref_type
FROM \`githubarchive.month.*\`
WHERE _TABLE_SUFFIX BETWEEN 'YYYYMM' AND 'YYYYMM'
  AND type = 'DeleteEvent'
  AND repo.name = 'OWNER/REPO'
LIMIT 200
"

需要收集的证据：

强制推送事件（payload.size > 0, payload.distinct_size = 0）
针对分支/标签的 DeleteEvents
可疑 CI/CD 自动化的 WorkflowRunEvents
在 git 日志“缺口”之前的 PushEvents（重写证据）

参考：参见 github-archive-guide.md 了解所有 12 种事件类型和查询模式。

调查员 5：IOC 丰富调查员

角色边界：你仅使用被动公开来源丰富阶段 1 中已有的 IOC。不要执行目标仓库中的任何代码。

操作：

对于每个提交 SHA：尝试通过直接 GitHub URL 恢复（github.com/OWNER/REPO/commit/SHA.patch）
对于每个域名/IP：检查被动 DNS、WHOIS 记录（通过公共 WHOIS 服务的 web_extract）
对于每个包名：检查 npm/PyPI 上匹配的恶意包报告
对于每个参与者用户名：检查 GitHub 个人资料、贡献历史、账户年龄
使用 3 种方法恢复强制推送的提交（参见 recovery-techniques.md）

阶段 4：假设形成

一个假设必须：

陈述一个具体主张（例如：“行为者 X 在 DATE 对 BRANCH 进行了 force-push 以擦除 commit SHA”）
引用至少 2 个支持它的证据 ID（EV-XXXX、EV-YYYY）
指出哪些证据可以反驳它
在验证前标记为 [HYPOTHESIS]

常见假设模板（参见 investigation-templates.md）：

维护者账户失陷：合法账户在接管后被用于注入恶意代码
依赖混淆：通过包名抢注拦截安装
CI/CD 注入：恶意修改工作流以在构建过程中运行代码
拼写劫持：使用几乎相同的包名针对拼写错误者
凭据泄露：令牌/密钥被意外提交后通过 force-push 擦除

对于每个假设，生成一个 delegate_task 子 Agent，尝试在确认前找到反证证据。

阶段 5：假设验证

验证子 Agent 必须机械地检查：

对于每个假设，提取所有引用的证据 ID。
验证每个 ID 存在于 evidence.json 中（如果任何 ID 缺失则硬失败 → 假设被拒绝，视为可能伪造）。
验证每条 [VERIFIED] 证据已从 2 个以上来源确认。
检查逻辑一致性：证据所描述的时间线是否支持该假设？
检查替代解释：相同的证据模式是否可能由良性原因引起？

输出：

VALIDATED：所有证据被引用、已验证、逻辑一致，且没有合理的替代解释。
INCONCLUSIVE：证据支持假设，但存在替代解释或证据不足。
REJECTED：缺失证据 ID、将未验证的证据当作事实引用、检测到逻辑不一致。

被拒绝的假设反馈回阶段 4 进行优化（最多 3 次迭代）。

阶段 6：最终报告生成

使用 forensic-report.md 中的模板填充 investigation-report.md。

必填章节：

执行摘要：一段话的结论（已失陷 / 干净 / 不确定）及置信度
时间线：所有重要事件的时间顺序重建，附证据引用
已验证的假设：每个假设的状态及支持证据 ID
证据登记表：所有 EV-XXXX 条目的表格，包含来源、类型和验证状态
IOC 列表：所有提取并富集的入侵指标
监管链：证据如何收集、来自哪些来源、在什么时间戳
建议：如果检测到失陷，立即采取的缓解措施；监控建议 报告规则：
每个事实性主张必须至少有一个 [EV-XXXX] 引用
执行摘要必须说明置信度（高/中/低）
所有机密/凭证必须编辑为 [REDACTED]

阶段 7：完成

运行最终证据计数：python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json list
归档整个调查目录。
如果确认存在入侵：
- 列出即时缓解措施（轮换凭证、固定依赖哈希、通知受影响的用户）
- 识别受影响的版本/包
- 注明披露义务（如果是公共包：与包注册中心协调）
向用户呈现最终的 investigation-report.md。

道德使用指南

此技能专为防御性安全调查而设计——保护开源软件免受供应链攻击。不得用于：

骚扰或跟踪贡献者或维护者
人肉搜索——将 GitHub 活动与真实身份关联以用于恶意目的
商业情报——未经授权调查专有或内部仓库
虚假指控——在无有效证据的情况下发布调查结果（参见反幻觉护栏）

调查应遵循最小侵入原则：仅收集验证或反驳假设所需的证据。发布结果时，遵循负责任的披露实践，并在公开披露前与受影响的维护者协调。

如果调查发现真正的入侵，请遵循协调漏洞披露流程：

首先私下通知仓库维护者
留出合理的修复时间（通常为 90 天）
如果发布的包受到影响，与包注册中心（npm、PyPI 等）协调
如果合适，提交 CVE

API 速率限制

GitHub REST API 强制执行速率限制，如果管理不当，会中断大型调查。

已认证请求：5,000/小时（需要 GITHUB_TOKEN 环境变量或 gh CLI 认证） 未认证请求：60/小时（无法用于调查）

最佳实践：

始终进行认证：export GITHUB_TOKEN=ghp_... 或使用 gh CLI（自动认证）
使用条件请求（If-None-Match / If-Modified-Since 标头）以避免在未更改数据上消耗配额
对于分页端点，按顺序获取所有页面——不要对同一端点进行并行请求
检查 X-RateLimit-Remaining 标头；如果低于 100，则暂停直到 X-RateLimit-Reset 时间戳
BigQuery 有自己的配额（免费层 10 TiB/天）——始终先进行试运行
Wayback Machine CDX API：没有正式速率限制，但请保持礼貌（最多 1-2 请求/秒）

如果在调查中途遇到速率限制，将部分结果记录在证据存储中，并在报告中注明限制。

参考资料

github-archive-guide.md — BigQuery 查询、CDX API、12 种事件类型
evidence-types.md — IOC 分类、证据来源类型、观察类型
recovery-techniques.md — 恢复已删除的提交、PR、问题
investigation-templates.md — 每种攻击类型的预构建假设模板
evidence-store.py — 用于管理证据 JSON 存储的 CLI 工具
forensic-report.md — 结构化报告模板

技能元数据​

参考：完整 SKILL.md​

OSS 安全取证技能

⚠️ 反幻觉护栏​

示例场景​

阶段 1：提示解析与 IOC 提取​

阶段 2：并行证据收集​

调查者 1：本地 Git 调查者​

调查员 2：GitHub API 调查员​

调查员 3：Wayback Machine 调查员​

调查员 4：GH Archive / BigQuery 调查员​

调查员 5：IOC 丰富调查员​

阶段 4：假设形成​

阶段 5：假设验证​

阶段 6：最终报告生成​

阶段 7：完成​

道德使用指南​

API 速率限制​

参考资料​