cowenpa/github-repo-scanner

# GitHub 仓库安全扫描器 v2.1 在下载或安装任何 GitHub 仓库之前，扫描其中的恶意代码、密钥、漏洞和信任信号。 ## v2.1 新增功能 - **通俗易懂的解释** — 每个检测结果都会提供“为什么重要”或“意味着什么”的说明，专为非技术人员撰写。没有术语，只有清晰的行动理由（或不行动的理由） - **Semgrep 误报过滤器** — 在评分前移除 `skills/`、`prompts/`、`templates/`、`workflows/`、`.yaml`、`.yml` 和 `.md` 路径中的内容。技能/提示类仓库不再因误报触发“禁止安装”判定 ## v2 新增功能 - **代码质量阶段** — 10 个信号：CI/CD、测试套件、README 深度、SECURITY.md、CHANGELOG、TypeScript 严格模式、锁定文件、依赖面、可疑 CI 流水线 - **成熟度评分**（0-10） alongside 安全评分 — 判断仓库是否既安全又维护良好 - **Gitleaks 误报过滤器** — 在报告前移除测试固件、占位符值和环境变量引用（灵感来自 [Kem 的 kem-sec 研究](https://campfire.aura-intel.net/blog/deterministic-skills)） - **状态持久化** — 使用 `--resume` 可从最后完成的阶段恢复中断的扫描 - **结构化类型契约** — 每个阶段输出经过验证的模式 - **项目类型检测** — 自动跳过与 npm 库、Python 包、CLI、Go、Rust 或 Web 应用无关的检查 ## 工作原理 ``` Phase 1 — Remote (parallel, no clone) OpenSSF Scorecard · TruffleHog · GitHub API ↓ Phase 2 — Shallow clone + security SAST (parallel) GuardDog · Semgrep · Gitleaks (FP-filtered) · OSV-Scanner · Grype ↓ Phase 3 — Code quality signals (10 checks) CI/CD · Tests · README · SECURITY.md · CHANGELOG TypeScript strict · Lock files · Dep surface · Workflow safety ↓ Phase 4 — Aggregate + Verdict Security Score (0-10) Maturity Score (0-10) SAFE / REVIEW NEEDED / DO NOT INSTALL ``` ## 快速开始 ### macOS ``` ./mac/install.sh ``` ### Windows 右键 `windows\install.bat` → 以管理员身份运行 ## 使用方法（安装后） ``` # 完整扫描 — 所有 4 个阶段（推荐） repo-scan https://github.com/owner/repo # 快速扫描 — 仅第 1 阶段远程，不克隆 (~15s) repo-scan https://github.com/owner/repo --quick # 恢复中断的扫描 repo-scan https://github.com/owner/repo --resume # 强制全新扫描（忽略保存状态） repo-scan https://github.com/owner/repo --fresh # 输出为 JSON repo-scan https://github.com/owner/repo --json ``` ## 检查内容 | 阶段 | 工具 | 检测内容 | |-------|------|--------------| | 1 | OpenSSF Scorecard | 18 分信任评分 — 分支保护、代码审查、CI、签名发布 | | 1 | TruffleHog | 仓库历史中的实时/已验证密钥与凭证 | | 1 | GitHub API | 星标、Forks、许可证、活动、项目类型检测 | | 2 | GuardDog | 恶意安装脚本、数据外传、挖矿程序、拼写劫持 | | 2 | Semgrep | 代码漏洞（1,000+ SAST 规则） | | 2 | Gitleaks | 源码中的硬编码密钥（已过滤误报） | | 2 | OSV-Scanner | 依赖项中的已知 CVE（基于 OSV 数据库） | | 2 | Grype | 带严重性评级的依赖漏洞扫描 | | 3 | 质量信号 | CI、测试、文档、锁定文件、TypeScript 严格模式、工作流安全性 | ## 判定结果 每次扫描最终会给出以下三种判定之一： | 判定 | 含义 | |-------|------| | **SAFE** | Scorecard 评分 > 6.0，无关键问题，依赖图谱清晰 | | **REVIEW NEEDED** | 发现中等问题 — 安装前请阅读警告 | | **DO NOT INSTALL** | 检测到实时密钥、恶意代码或关键 CVE | ## 系统要求 - macOS：Homebrew（缺失时自动安装） - Windows：Windows 10/11，支持 winget 或 Scoop - GitHub CLI（`gh`）已认证 — 安装后运行一次 `gh auth login` ## 扫描历史 结果以 JSON 格式保存到 `~/.repo-scanner/scans/`。中断扫描的状态保存在 `~/.repo-scanner/state/`。 ## 安装说明 macOS 安装器使用 `curl | bash` 安装 Homebrew 和 Bun — 与官方文档推荐方式相同。如需手动安装这些工具，脚本会自动跳过。 ## 致谢 - 安全工具：详见 [CREDITS.md](CREDITS.md) - v2 架构灵感来自 [Kem](https://campfire.aura-intel.net) — 其 [kem-sec](https://github.com/aura-intel/kem-sec) 工具以及在确定性 Claude Code 技能方面的研究 [研究链接](https://campfire.aura-intel.net/blog/deterministic-skills) 为误报过滤器、状态持久化和结构化阶段契约提供了基础

标签：Angular, CI/CD 安全, CLI 工具, GitHub 安全扫描, Gitleaks, Grype, Mac 安全扫描, npm 库, OpenSSF Scorecard, OSV-Scanner, Python 包, SAST, Semgrep, SLSA, SSDF, TruffleHog, TypeScript 严格模式, Web 应用, Windows 安全扫描, WordPress安全扫描, 仓库安全检测, 代码质量评估, 依赖扫描, 依赖表面分析, 信任信号评估, 学术论文, 密钥泄露检测, 应用安全, 恶意代码扫描, 成熟度评分, 数据投毒防御, 日志审计, 模型提供商, 流水线安全, 状态恢复, 盲注攻击, 结构化输出, 自动化攻击, 误报过滤, 防御框架, 静态应用安全测试, 项目类型检测, 预安装安全检查