hamza-ali-shahjahan/ship-guard

# ship-guard **一键式、本地优先的“你是否即将被洗劫？” git 仓库安全检查工具。** 将其安装为 `git pre-push` 钩子，每次 push 都会*在你的本机上*优先进行扫描 — 无需 SaaS，无需账号，无需遥测，**任何数据都不会离开你的电脑**。零依赖 （纯 Node 实现，支持 Node 16+ 和 Bun）。 它能够捕获导致仓库被洗劫的四种方式： | # | 攻击媒介 | 标记内容 | |---|---|---| | 1 | **已提交的机密信息** | Anthropic / OpenAI 密钥，Stripe 和 Clerk 的 `sk_live_`，Resend，带密码的 Neon/Postgres 连接字符串，webhook 和 Sentry token，AWS/Google/Slack 密钥，GitHub token，**私钥区块**，以及 Supabase JWT — 解码后会将 `service_role` 标记为（CRITICAL），将 `anon` 标记为（low）。 | | 2 | **被追踪的机密文件** | 提交到 git 的 `.env` / `.env.*`（排除 `.env.example`）、`*.pem`/`*.key`/`id_rsa`、service-account JSON、`*KEYS_VAULT*`。 | | 3 | **强制 push 影响范围** | 检测自动提交/强制 push 钩子设置，以及自动 push 是否已**就绪**（`.auto-push`）还是受**保护**（`.no-auto-push` / `.no-auto-commit`） — 即泄露的 token 是否会被自动用于抹除历史记录。提醒你设置服务端分支保护。 | | 4 | **高风险的 GitHub Actions** | `pull_request_target`、`permissions: write-all` 或缺失权限块、向 fork PR 暴露机密信息，以及未固定的第三方 action（使用标签/分支而非完整的 commit SHA）。 | ## 快速开始 要求安装 `node` (16+) 或 `bun`。无需安装，无依赖。获取该工具： ``` git clone https://github.com/hamza-ali-shahjahan/ship-guard cd ship-guard ``` 然后，在你想要检查的仓库中运行： ``` # 对任意 repo 进行 ad-hoc scan node /path/to/ship-guard/bin/ship-guard scan . # 将 pre-push hook 安装到你当前所在的 repo 中（一条命令） node /path/to/ship-guard/bin/ship-guard install # …或者从此 clone 运行安装脚本： sh /path/to/ship-guard/install.sh ``` 不想克隆？使用 npx 直接从 GitHub 运行（先读取代码，然后再运行）： ``` npx github:hamza-ali-shahjahan/ship-guard scan . ``` 安装后，每次 `git push` 都会优先运行本地扫描。未通过的扫描会**阻止 push**。 ``` $ git push ship-guard: scanning before push… [CRITICAL] secrets src/config.ts:12 Live secret key (Stripe/Clerk sk_live_) detected ✘ FAIL (1 finding at or above high) ship-guard: push BLOCKED. ``` 临时绕过（仅在你确信安全时使用）： ``` SHIP_GUARD_DISABLE=1 git push # or: git push --no-verify ``` ## 安装原理（独立 / 可直接置入） `install` **会将扫描器的单一副本内置**到 `./.ship-guard/ship-guard`，并 写入 `.git/hooks/pre-push` 来调用它。无需全局安装，无 PATH 依赖，无需 npm。 将 `.ship-guard/` 提交到代码库以与你的团队共享该防护，或者将其加入 `.gitignore` 以使其 保持在本地。`uninstall` 会同时移除两者（并恢复任何已备份的 pre-push 钩子）。 ## 命令与标志 ``` ship-guard scan [path] Scan a repo (default: cwd). Prints PASS/FAIL, sets exit code. ship-guard install [path] Install the pre-push hook. ship-guard uninstall [path] Remove it. ship-guard version | help scan flags: --json Machine-readable output --fail-on= critical | high | medium | low (default: high) --quiet Findings + verdict only --no-secrets --no-env --no-forcepush --no-actions Disable a check ``` 退出代码：`0` 通过 · `1` 发现达到或高于 `--fail-on` 的问题 · `2` 用法/错误。 ## 减少干扰 - ship-guard 会跳过明显的占位符（`your_key_here`、`example`、`<...>` 等）。 - 在一行中添加 `ship-guard:allow` 可跳过该行；在文件任意位置添加 `ship-guard:ignore-file` 可跳过整个文件。 - 可发布的密钥（`pk_live_`/`pk_test_`）和 Supabase `anon` 密钥会被报告为 **low** （在默认的 `high` 阈值下不会阻止 push）。 ## 适用范围说明（诚实的局限性） - 它会扫描仓库中的 **git 追踪内容**（push 安全的检查单元）。扫描 子文件夹仍然会扫描其所属的整个仓库。 - 它只**负责检测和报告** — 不会轮换密钥或重写历史记录。当它发现 已提交的机密信息时，请在其提供商处轮换密钥，并使用 [git-filter-repo](https://github.com/newren/git-filter-repo) / BFG 清除历史记录。 - 无法从磁盘读取服务端分支保护；ship-guard 会提醒你开启它。 - 它**不是**像 gitleaks/trufflehog 那样的全熵引擎 — 它是一个快速、有主见、 零依赖的检查工具，专门针对那些会侵害真实仓库的高风险信号。 ## 测试 ``` node test/run-evals.mjs ``` 在运行时生成带有标签的测试固件，并断言以下标准：在糟糕的仓库固件上 **recall ≥ 0.90**，在干净的仓库固件上 **零 HIGH/CRITICAL 误报**，以及一个可正常工作的**安装往返测试**。 ## 相关项目 - **[guardhooks](https://github.com/hamza-ali-shahjahan/guardhooks)** — 姊妹项目： fail-open 的 PreToolUse 钩子，可在 AI 编码代理采取行动*之前*阻止其执行（触及 机密文件、翻转仓库可见性、强制 push main 分支、批量删除）。同时运行两者： guardhooks 阻止操作，ship-guard 捕获漏网之鱼。 本地优先。无网络。无遥测。MIT。

标签：DevSecOps, Git钩子, GNU通用公共许可证, MITM代理, Node.js, StruQ, 上游代理, 开发安全, 自定义脚本