vuln-scanner

用途

vuln-scanner 是漏洞披露循环中的“写入/行动”环节，一个技能覆盖负责任披露的完整生命周期：扫描、重提交、披露。其设计出发点是：把未修补漏洞直接倾倒进公开 PR 的扫描器等于零日发布器，而非助手。因此该技能遵循行业实践——代码缺陷走私有漏洞报告（PVR），只有已经公开的依赖 CVE 才提公开 PR。

主要能力

技能通过一个动作选择器 ${var} 分派到不同分支，格式为 [<action>][:<owner/repo>]：

• 扫描（scan）：空值或裸 owner/repo 触发。审计指定仓库，或从趋势仓库中自动选取。
• 重提交（resubmit / watchlist / pvr）：探测安全观察列表，对刚启用 PVR 的仓库重新提交排队中的公告。
• 披露（disclose / email）：将已武装的带外邮件披露草稿排队发送。
• PoC 冒烟（poc-smoke / verify-gate）：针对一个良性的真实 Base 分叉演练 PoC 门禁，不进行审计或披露。
• Riva 研究内核（riva / research）：以 Riva 研究内核扫描，仅影子/提案模式。
• 影子对比（shadow / compare）：生成私有对比产物。

各分支可独立执行，共享同一 GitHub token 和 memory/ 状态（vuln-scanned.json、security-watchlist.md、pending-disclosures/、email-log.json），状态即分支间的交接方式。冒烟分支不读写该状态。

使用方式

扫描分支（Arm A）

1. 选取目标：若指定 $TARGET 则直接使用；否则优先读取 output/.chains/github-trending.md 链式输出，解析 owner/repo 目标。若该输出缺失或不可解析，则通过 gh api 搜索近 14 天创建、按星数排序的仓库。

   选取标准：语言可推理（JS/TS、Python、Go、Rust、Solidity）；≥50 星、非分叉、近 6 个月活跃；处理不可信输入（认证、加密、网络、文件 I/O、模板）；近 30 天未扫描；跳过故意易受攻击的教学仓库（DVWA、juice-shop、webgoat、vulnerable-*、-ctf、hackme-）；跳过既无 SECURITY.md 又未启用 PVR 的仓库（仍可做依赖扫描）。

2. 分叉并克隆：影子内核直接 git clone，否则 gh repo fork --clone。

3. 运行专用扫描器：在运行中把扫描器暂存到 /tmp/bin，仅使用允许列表内的命令（python3 -m pip、curl -o、chmod、npm/npx、node）。

   • Semgrep OSS（SAST）：使用 p/security-audit、p/owasp-top-ten、p/secrets 规则集，排除测试、示例、vendor、node_modules 等目录。
   • TruffleHog（密钥）：--only-verified 仅报告真正能认证的密钥，分别扫描文件系统和完整 git 历史，均以 timeout 300 限时。
   • osv-scanner（依赖）：跨生态统一 CVE 数据库，优先 v2 scan source 子命令，失败回退 v1；--no-ignore 必需，以读取被 gitignore 但已提交的锁文件。退出码 128 表示无包源，记为 N/A 而非失败。
   • Slither（智能合约）：存在 Solidity 时运行。
   • 每个工具缺失时记录 VULN_SCANNER_SKIPPED 并继续，绝不因单个工具中止整轮。

4. 动态测试（A3.5）：若仓库自带 cargo fuzz 测试框架，则运行模糊测试。此步骤仅限 Rust + cargo fuzz，会编译并运行目标代码，信任边界高于静态扫描，仅在仓库主动提供测试框架时激活。

重提交分支（Arm B）

当扫描在无 PVR、无 SECURITY.md、无可用联系方式的仓库中发现 HIGH/CRITICAL 问题时，记录为 "channel": "skipped" 并加入观察列表。重提交分支定期探测这些仓库，对刚启用 PVR 的仓库重新提交排队公告，避免发现静默过期直至披露窗口关闭。

披露分支（Arm C）

当唯一负责任路径是向维护者发送私有邮件时，草稿存于 memory/pending-disclosures/，状态为 pending-operator-send，等待人工。披露分支查找明确武装为自动发送的草稿，撰写邮件并在运行中通过 Resend（经 ./secretcurl）发送，受一组失败关闭上限约束，发送是该分支的最终动作。

适用场景

• 对趋势开源仓库进行安全审计并负责任披露。
• 跟踪无安全渠道的漏洞发现，等待披露渠道出现。
• 对已公开的依赖 CVE 提交依赖升级 PR。
• 在需要时通过私有邮件向维护者披露。

限制

• 影子运行按设计无 GitHub 凭据，裸影子选择器必须失败关闭，需改用 shadow:owner/repo。
• 单次 workflow_dispatch 运行是一次性的，无法恢复；扫描超时记为失败，不写“仍在运行、稍后继续”的占位说明。
• 动态模糊测试当前仅支持 Rust + cargo fuzz。
• 各扫描器需在运行中成功暂存，否则跳过并记录。
• 披露发送受失败关闭上限约束，且发送为分支最终动作。

其他

技能启动时要求读取 memory/MEMORY.md 及最近 30 天的 memory/logs/。Riva 内核仍在评估中，legacy 为安全默认值；shadow 生成私有对比产物，仅显式 riva 选择器或经审查的环境覆盖才会为扫描选用。两种模式均不改变披露权限，也不绕过 A4/A4.5。