{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Oss Forensics

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

Skill 元数据


来源	可选 — 通过 `hermes skills install official/security/oss-forensics` 安装
路径	`optional-skills/security/oss-forensics`
平台	linux, macos, windows

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。

OSS 安全取证 Skill

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

⚠️ 反幻觉（Anti-Hallucination）防护规则

在每个调查步骤前必须阅读这些规则。违反这些规则将使报告失效。

证据优先原则：任何报告、假设或摘要中的每一项声明都必须引用至少一个证据 ID（EV-XXXX）。禁止无引用的断言。

职责边界：每个子 agent（调查员）只有一个数据源，不得混用。GH Archive 调查员不查询 GitHub API，反之亦然。职责边界是硬性规定。

事实与假设分离：所有未经验证的推断必须标注 [HYPOTHESIS]。只有经原始来源验证的陈述才可作为事实表述。

禁止捏造证据：假设验证器必须机械地检查每个被引用的证据 ID 在证据库中确实存在，然后才能接受假设。

反驳需有证据：驳斥一个假设必须提供具体的、有证据支撑的反驳论点。"未找到证据"不足以推翻假设——这只能使假设变为不确定状态。

SHA/URL 双重验证：任何作为证据引用的提交 SHA、URL 或外部标识符，必须在被标记为已验证之前从至少两个来源独立确认。

可疑代码规则：绝不在本地运行被调查仓库中发现的代码。仅进行静态分析，或在沙箱环境中使用 execute_code。

密钥脱敏：调查过程中发现的任何 API 密钥、token 或凭据必须在最终报告中脱敏处理，仅在内部日志中记录。

示例场景

场景 A：依赖混淆：恶意包 internal-lib-v2 以更高版本号上传至 NPM，高于内部版本。调查员需追踪该包首次出现的时间，以及目标仓库中是否有 PushEvent 将 package.json 更新为该版本。

场景 B：维护者账户接管：一名长期贡献者的账户被用于推送带有后门的 .github/workflows/build.yml。调查员在该用户长期不活跃或来自新 IP/位置（如可通过 BigQuery 检测）之后，查找其 PushEvent。

场景 C：强制推送隐藏：开发者意外提交了生产环境密钥，随后强制推送以"修复"。调查员使用 git fsck 和 GH Archive 恢复原始提交 SHA，并验证泄露内容。

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

阶段 0：初始化

创建调查工作目录：

初始化证据库：

复制取证报告模板：

创建 iocs.md 文件，用于追踪发现的入侵指标（Indicators of Compromise，IOC）。

记录调查开始时间、目标仓库及调查目标说明。

阶段 1：Prompt 解析与 IOC 提取

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

操作：

解析用户 prompt（提示词），提取：

目标仓库（owner/repo）

目标参与者（GitHub 用户名、电子邮件地址）

关注的时间窗口（提交日期范围、PR 时间戳）

提供的入侵指标：提交 SHA、文件路径、包名、IP 地址、域名、API 密钥/token、恶意 URL

任何关联的供应商安全报告或博客文章

工具：仅推理，或对大段文本使用 execute_code 进行正则提取。

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

类型（从以下选择：COMMIT_SHA、FILE_PATH、API_KEY、SECRET、IP_ADDRESS、DOMAIN、PACKAGE_NAME、ACTOR_USERNAME、MALICIOUS_URL、OTHER）

值

来源（用户提供、推断得出）

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

阶段 2：并行证据收集

使用 delegate_task（批量模式，最多 3 个并发）派生最多 5 个专业调查员子 agent。每个调查员只有一个数据源，不得混用。

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

调查员 1：本地 Git 调查员

职责边界：仅查询本地 Git 仓库，不调用任何外部 API。

操作：

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

每个悬空提交 SHA → 类型：git

强制推送证据（reflog 显示历史重写）→ 类型：git

已验证贡献者的未签名提交 → 类型：git

可疑二进制文件添加 → 类型：git

参考：访问强制推送提交的方法见 recovery-techniques.md。

调查员 2：GitHub API 调查员

职责边界：仅查询 GitHub REST API，不在本地运行 git 命令。

操作：

交叉比对目标（将差异标记为证据）：

PR 存在于归档中但 API 中缺失 → 删除证据

贡献者出现在归档事件中但不在贡献者列表中 → 权限撤销证据

提交出现在归档 PushEvent 中但不在 API 提交列表中 → 强制推送/删除证据

参考：GH 事件类型见 evidence-types.md。

调查员 3：Wayback Machine 调查员

职责边界：仅查询 Wayback Machine CDX API，不使用 GitHub API。

目标：恢复已删除的 GitHub 页面（README、issues、PR、releases、wiki 页面）。

操作：

需收集的证据：

已删除 issue/PR 的归档快照及其内容

显示变更的历史 README 版本

存在于归档中但在当前 GitHub 状态中缺失的内容证据

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

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

职责边界：仅通过 BigQuery 查询 GitHub Archive。这是所有公开 GitHub 事件的防篡改记录。

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

成本优化规则（强制执行）：

每次查询前必须先运行 --dry_run 以估算成本。

使用 _TABLE_SUFFIX 按日期范围过滤，最小化扫描数据量。

只 SELECT 所需列。

除非进行聚合，否则添加 LIMIT。

需收集的证据：

强制推送事件（payload.size > 0，payload.distinct_size = 0）

分支/标签的 DeleteEvent

可疑 CI/CD 自动化的 WorkflowRunEvent

在 git 日志出现"空白"之前的 PushEvent（历史重写证据）

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

调查员 5：IOC 富化调查员

职责边界：仅使用被动公开来源对阶段 1 中的现有 IOC 进行富化。不执行目标仓库中的任何代码。

操作：

对每个提交 SHA：尝试通过直接 GitHub URL（github.com/OWNER/REPO/commit/SHA.patch）恢复

对每个域名/IP：检查被动 DNS、WHOIS 记录（通过 web_extract 访问公开 WHOIS 服务）

对每个包名：检查 npm/PyPI 中是否有匹配的恶意包报告

对每个 actor 用户名：检查 GitHub 个人资料、贡献历史、账户注册时间

使用 3 种方法恢复强制推送的提交（见 recovery-techniques.md）

阶段 3：证据整合

所有调查员完成后：

运行 python3 SKILL_DIR/scripts/evidence-store.py --store evidence.json list 查看所有已收集证据。

对每条证据，验证 content_sha256 哈希值与原始来源一致。

按以下维度对证据分组：

时间线：将所有带时间戳的证据按时间顺序排列

参与者：按 GitHub 用户名或电子邮件分组

IOC：将证据与其关联的 IOC 链接

识别差异：存在于一个来源但在另一个来源中缺失的条目（关键删除指标）。

将证据标记为 [VERIFIED]（已从 2 个以上独立来源确认）或 [UNVERIFIED]（仅单一来源）。

阶段 4：假设形成

一个假设必须：

陈述具体声明（例如："参与者 X 于某日期对 BRANCH 进行强制推送以擦除提交 SHA"）

引用至少 2 个支持它的证据 ID（EV-XXXX、EV-YYYY）

指明哪些证据可以推翻它

在验证之前标注 [HYPOTHESIS]

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

维护者账户被攻陷：合法账户在被接管后用于注入恶意代码

依赖混淆：包名抢注以拦截安装

CI/CD 注入：恶意 workflow 变更以在构建期间运行代码

仿冒命名（Typosquatting）：针对拼写错误者的高度相似包名

凭据泄露：token/密钥意外提交后强制推送以擦除

对每个假设，派生一个 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。

道德使用准则

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

骚扰或跟踪贡献者或维护者

人肉搜索（Doxing）——将 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）——始终先进行 dry-run

Wayback Machine CDX API：无正式速率限制，但请保持礼貌（最多 1-2 次请求/秒）

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

参考资料

github-archive-guide.md — BigQuery 查询、CDX API、12 种事件类型

evidence-types.md — IOC 分类法、证据来源类型、观察类型

recovery-techniques.md — 恢复已删除的提交、PR、issues

investigation-templates.md — 按攻击类型预置的假设模板

evidence-store.py — 用于管理证据 JSON 库的 CLI 工具

forensic-report.md — 结构化报告模板

"Oss Forensics — GitHub 仓库的供应链调查、证据恢复与取证分析"

Oss Forensics#

Skill 元数据#

参考：完整 SKILL.md#

OSS 安全取证 Skill#

⚠️ 反幻觉（Anti-Hallucination）防护规则#

示例场景#

阶段 0：初始化#

阶段 1：Prompt 解析与 IOC 提取#

阶段 2：并行证据收集#

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

调查员 2：GitHub API 调查员#

调查员 3：Wayback Machine 调查员#

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

调查员 5：IOC 富化调查员#

阶段 3：证据整合#

阶段 4：假设形成#

阶段 5：假设验证#

阶段 6：最终报告生成#

阶段 7：完成#

道德使用准则#

API 速率限制#

参考资料#

Oss Forensics

Skill 元数据

参考：完整 SKILL.md

OSS 安全取证 Skill

⚠️ 反幻觉（Anti-Hallucination）防护规则

示例场景

阶段 0：初始化

阶段 1：Prompt 解析与 IOC 提取

阶段 2：并行证据收集

调查员 1：本地 Git 调查员

调查员 2：GitHub API 调查员

调查员 3：Wayback Machine 调查员

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

调查员 5：IOC 富化调查员

阶段 3：证据整合

阶段 4：假设形成

阶段 5：假设验证

阶段 6：最终报告生成

阶段 7：完成

道德使用准则

API 速率限制

参考资料