跳到主要内容

OSS 取证

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

技能元数据​

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

参考：完整 SKILL.md​

信息

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

OSS 安全取证技能

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

⚠️ 防幻觉护栏​

在执行每个调查步骤之前请阅读这些内容。违反这些规定将使报告无效。

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

示例场景​

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

路径约定：在整个技能中，SKILL_DIR 指的是此技能安装目录的根目录（包含此 SKILL.md 的文件夹）。当技能加载时， 将 SKILL_DIR 解析为实际路径 — 例如 ~/.hermes/skills/security/oss-forensics/ 或等效的 optional-skills/ 路径。所有脚本和模板引用均相对于此路径。

阶段 0：初始化​

  1. 创建调查工作目录： 
    mkdir investigation_$(echo "REPO_NAME" | tr '/' '_')
    cd investigation_$(echo "REPO_NAME" | tr '/' '_')
  2. 初始化证据存储： 
    python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json list
  3. 复制取证报告模板： 
    cp SKILL_DIR/templates/forensic-report.md ./investigation-report.md
  4. 创建一个 iocs.md 文件，以跟踪发现的入侵指标 (Indicators of Compromise)。
  5. 记录调查开始时间、目标仓库和声明的调查目标。

阶段 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 个专业调查员子代理。每个调查员拥有单一数据源，不得混合来源。

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

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

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

操作：

# Clone repository
git clone https://github.com/OWNER/REPO.git target_repo && cd target_repo

# Full commit log with stats
git log --all --full-history --stat --format="%H|%ae|%an|%ai|%s" > ../git_log.txt

# Detect force-push evidence (orphaned/dangling commits)
git fsck --lost-found --unreachable 2>&1 | grep commit > ../dangling_commits.txt

# Check reflog for rewritten history
git reflog --all > ../reflog.txt

# List ALL branches including deleted remote refs
git branch -a -v > ../branches.txt

# Find suspicious large binary additions
git log --all --diff-filter=A --name-only --format="%H %ai" -- "*.so" "*.dll" "*.exe" "*.bin" > ../binary_additions.txt

# Check for GPG signature anomalies
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 命令。

操作：

# Commits (paginated)
curl -s "https://api.github.com/repos/OWNER/REPO/commits?per_page=100" > api_commits.json

# Pull Requests including closed/deleted
curl -s "https://api.github.com/repos/OWNER/REPO/pulls?state=all&per_page=100" > api_prs.json

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

# Contributors and collaborator changes
curl -s "https://api.github.com/repos/OWNER/REPO/contributors" > api_contributors.json

# Repository events (last 300)
curl -s "https://api.github.com/repos/OWNER/REPO/events?per_page=100" > api_events.json

# Check specific suspicious commit SHA details
curl -s "https://api.github.com/repos/OWNER/REPO/git/commits/SHA" > commit_detail.json

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

# Check if a specific commit exists (force-pushed commits may 404 on commits/ but succeed on 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、issues、PR、发布版本、wiki 页面）。

操作：

# Search for archived snapshots of the repo main page
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

# Search for a specific deleted 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

# Search for a specific deleted 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

# Fetch the best snapshot of a page
# Use the Wayback Machine URL: https://web.archive.org/web/TIMESTAMP/ORIGINAL_URL
# Example: https://web.archive.org/web/20240101000000*/github.com/OWNER/REPO

# Advanced: Search for deleted releases/tags
curl -s "https://web.archive.org/cdx/search/cdx?url=github.com/OWNER/REPO/releases/tag/*&output=json" > wayback_tags.json

# Advanced: Search for historical wiki changes
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）。如果不可用，请跳过此调查员并在报告中注明。

成本优化规则（强制）：

  1. 在每次查询前始终运行 --dry_run 以估算成本。
  2. 使用 _TABLE_SUFFIX 按日期范围过滤并最小化扫描的数据。
  3. 仅 SELECT 你需要的列。
  4. 除非进行聚合，否则添加 LIMIT。
# Template: safe BigQuery query for PushEvents to OWNER/REPO
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
"
# If cost is acceptable, re-run without --dry_run

# Detect force-pushes: zero-distinct_size PushEvents mean commits were force-erased
# payload.distinct_size = 0 AND payload.size > 0 → force push indicator

# Check for deleted branch events
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）

阶段 3：证据整合​

在所有调查员完成后：

  1. 运行 python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json list 以查看所有已收集的证据。
  2. 对于每条证据，验证 content_sha256 哈希值是否与原始来源匹配。
  3. 按以下方式对证据进行分组：
    • 时间线：按时间顺序对所有带时间戳的证据进行排序
    • 行为者：按 GitHub 用户名或电子邮件分组
    • IOC（入侵指标）：将证据与其相关的 IOC 关联
  4. 识别差异：即存在于一个来源但缺失于另一个来源的项目（关键删除指示器）。
  5. 将证据标记为 [VERIFIED]（经 2 个或更多独立来源确认）或 [UNVERIFIED]（仅来自单一来源）。

第 4 阶段：假设形成​

假设必须：

  • 陈述一个具体的主张（例如，“行为者 X 于 DATE 强制推送到 BRANCH 以擦除提交 SHA”）
  • 引用至少 2 个支持该假设的证据 ID（EV-XXXX、EV-YYYY）
  • 指出哪些证据可以反驳该假设
  • 在验证之前标记为 [HYPOTHESIS]

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

  • 维护者账户失陷：合法账户在接管后被用于注入恶意代码
  • 依赖混淆：抢注包名以拦截安装
  • CI/CD 注入：恶意更改工作流以在构建期间运行代码
  • typo 抢注（Typosquatting）：使用近乎相同的包名针对拼写错误用户
  • 凭据泄露：令牌/密钥被意外提交，随后通过强制推送擦除

对于每个假设，启动一个 delegate_task 子代理，在确认之前尝试寻找反驳证据。

第 5 阶段：假设验证​

验证子代理必须机械地检查：

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

输出：

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

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

第 6 阶段：最终报告生成​

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

必填部分：

  • 执行摘要：一段话的结论（失陷 / 干净 / 不确定）及置信度级别
  • 时间线：按时间顺序重建所有重大事件并引用证据
  • 已验证的假设：每个假设的状态及支持的证据 ID
  • 证据注册表：所有 EV-XXXX 条目的表格，包含来源、类型和验证状态
  • IOC 列表：所有提取和丰富的入侵指标
  • 监管链：证据如何收集、来自哪些来源、在什么时间戳
  • 建议：如果检测到失陷，立即采取的缓解措施；监控建议

报告规则：

  • 每个事实性主张必须至少有一个 [EV-XXXX] 引用
  • 执行摘要必须声明置信度级别（高 / 中 / 低）
  • 所有秘密/凭据必须脱敏为 [REDACTED]

第 7 阶段：完成​

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

道德使用指南​

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

  • 骚扰或跟踪贡献者或维护者
  • 人肉搜索——出于恶意目的将 GitHub 活动关联到真实身份
  • 竞争情报——未经授权调查专有或内部仓库
  • 虚假指控——发布未经过验证证据的调查结果是（参见反幻觉防护措施）

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

如果调查确认存在真实的安全入侵，请遵循协调漏洞披露流程：

  1. 首先私下通知仓库维护者
  2. 留出合理的修复时间（通常为 90 天）
  3. 如果已发布的包受到影响，请与包注册表（npm、PyPI 等）协调
  4. 如适用，申请 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/天）——务必先执行干跑（dry-run）
  • Wayback Machine CDX API：没有正式的速率限制，但请保持礼貌（最多 1-2 次请求/秒）

如果在调查过程中受到速率限制，请在证据存储中记录部分结果，并在报告中注明该限制。

参考资料​