DoctorGoz/ghprowl

# ghprowl — GitHub Prowler 一款用于监控凭据和内部引用泄露到**公开** GitHub 的多目标监视工具。 工程师们常常将 token 提交到示例仓库中，将连接字符串粘贴到 gists 中，并推送指向内部主机的 dotfiles。ghprowl 能够同时监控多个项目，在它们刚出现时就发现这些泄露，并通知你 —— 而这一切都无需将机密信息移出你的本地机器。 它是配置驱动的：`lib/` 中包含一个通用引擎，每个目标拥有一个微型的 `config.env` 和标记目录。 引擎代码包含在此 repo 中；**特定目标的数据永远不会被上传**（参见[清理规范](#repo-layout--hygiene)）。 **设计背景：**[*Rare, Not Random*](docs/WRITEUP.md) —— 该方法背后的原理、工程取舍，以及与手动调整基线的 A/B 测试（更高的召回率，仅为三分之一的克隆负载）。 ## 工作原理 主要依靠三个核心理念。 ### 1. 罕见，而非随机 寻找项目泄露的简单方法是直接在 GitHub 上搜索其名称。但这会让你淹没在大量的教程和 fork 中。ghprowl 则会构建一个**标记目录** —— 包含 endpoint、内部主机名、env-var 名称、自定义 header、proto package、SDK 模块名 —— 并根据每个标记的**全局代码搜索频率**对其进行排名，然后优先查询最罕见的标记。 全局计数为 `0–10` 的标记几乎是完美的信号：包含 `internal-gateway.corp.example` 的代码几乎都是不应该被公开的代码。而计数为 `50k`（如 `api_key`、`AUTH_TOKEN` 或供应商的公共 SDK URL）的标记则是干扰项。罕见度*即*精确度。 这也适用于**手动添加的标记** —— “独特”并不等同于“罕见”。公共 SDK repo 的 URL 或 session-cookie 名称对于一个目标来说很独特，但却会出现在每个集成者的构建配置中。对所有内容进行排名；信任罕见的标记。 ### 2. 两级账本 通过克隆来监视每个候选项是无法扩展的。ghprowl 将发现结果分为两级： - **deep** —— 高置信度（罕见标记命中）。在每个周期都会进行克隆和 gitleaks 扫描。 - **light** —— 推测性（名称模式匹配、贡献者、fork）。仅进行追踪；当后续触发标记时（`sweep`），会**自动提升为 deep**。 第三种状态，**置信度 `none`**，会隔离恶意抢注者（squatters）和侦察数据转储，确保它们永远不会浪费克隆资源。其结果是：广撒网的同时，保持一个小巧且高信号的克隆集合。大多数 light 条目就像绊线一样 —— 它们是空白或无关的账户，其价值在于某天它们的主人手滑推送了机密数据。 ### 3. 逃生通道 自动引导（`setup`）从**公开**来源获取标记 —— 项目范围、org-repo README、磁盘侦察结果。这能可靠地重构出目标的*服务清单*。但它无法重构出**非公开的黄金标记**：从流量中提取的 client_id、内部 API-gateway id 或 proto package 名称。这些是信号最强的标记，它们作为 `manual` 标记被手动添加，无论单次运行预算如何，它们**始终**会被查询。逃生通道是必须的，而非可选项 —— 但其中的标记也会像其他所有标记一样被进行罕见度排名。 ## 安装 前置要求：[`gh`](https://cli.github.com/)（已认证）、[`gitleaks`](https://github.com/gitleaks/gitleaks)、`jq`、`curl`。可选：`qrencode`（用于 `topics qr`）、`sqlite3` + HackerOne 范围缓存（用于更丰富的 `setup`）。 ``` git clone https://github.com/DoctorGoz/ghprowl ~/.ghprowl ln -s ~/.ghprowl/bin/ghprowl ~/.local/bin/ghprowl # put it on PATH ghprowl list ``` 克隆*即*安装：`~/.ghprowl` 是工作树，你的特定目标数据位于其中的 `targets//` 下（已被 gitignored）。 ## 快速开始 ``` ghprowl setup acme-corp # onboard: derive scope -> markers -> FIT check -> DRAFT config (stops for review) # # 审查 targets/acme-corp/{config.env,markers.tsv}；添加手动 gold markers ghprowl discover acme-corp # widen the net: rare-marker code-search + pivots, tiered into the ledger ghprowl watch acme-corp # detect: clone+gitleaks the deep set, alert on a LIVE token ghprowl status # dashboard across all targets ``` `setup` 会刻意**暂停以供审查** —— 它生成的是草稿，而非正式配置，并且会报告一个 **FIT 判定**（如果目标在公开 GitHub 上没有实质性的足迹，它会如实告知，而不是盲目运行一个无效的监视器）。这个审查步骤 —— 剪裁嘈杂的标记，粘贴上你的非公开黄金标记 —— 正是精确度的来源。 ## 命令 | 命令 | 功能 | |---|---| | `setup ` | 引导目标：推导范围 → 生成标记 → FIT 检查 → 生成 `config.env` 和目录草稿。暂停等待审查。 | | `rank ` | （重新）按全局罕见度对标记目录进行排名，最罕见的排在最前。 | | `discover ` | 扩大网络：罕见标记代码搜索 + 贡献者/fork 关联分析，分级记录到账本中。 | | `sweep [N]` | 提升阶段：当被追踪的实体触发标记时，从 light 提升至 deep。 | | `watch ` | 检测：克隆/刷新 deep 集合，扫描发生变化的 repo，在 LIVE 命中时发出警报。 | | `status [target]` | 无网络仪表盘：展示各目标的层级、标记、警报和上次运行状态。 | | `topics [target]` | 列出每个目标的 ntfy topic（订阅密钥）+ URL。 | | `topics qr ` | 将订阅 URL 渲染为可在终端扫描的二维码（无需在手机上输入）。 | | `topics test ` | 发送无害的确认 ping，以端到端验证订阅。 | | `list` | 列出已配置的目标。 | `watch`、`discover` 和 `sweep` 接受 `--all` 参数来代替单个目标，从而运行所有已配置的目标 —— 这也是 cron 任务的入口点。 ## 警报机制 命中结果会通过三种方式播报，并且**机密信息永远不会离开宿主机**： - **ntfy 推送** —— 仅作提醒（`"Actionable hit in . Check the local file."`）。消息中绝不包含 token。每个目标都有一个唯一自动生成的 topic；只需订阅一次（`ghprowl topics qr ` → 扫码）。 - **`URGENT-LIVE-TOKEN.txt`** —— 仅限本地的 LIVE 命中记录，包含 repo、commit URL 以及用于离线查看机密的确切 `git show` 命令。 - **`alerts/ALERTS.md`** —— 本地的、仅追加的每次命中日志。 首次扫描（基线扫描）会抑制仓库的历史发现结果，并且仅对**活跃（live）**的 token 发出警报，因此引导目标时不会被海量历史数据淹没。`watch` 在命中时会以非零状态退出，以便于在 cron 端进行处理。 ## 特定目标配置 (`targets//config.env`) | 键 | 用途 | |---|---| | `GP_GH_ORGS` | 作为发现根源并被直接监视的组织。 | | `GP_DOMAINS` | 范围内的域名（主机标记 + issuer 推导）。 | | `GP_ISSUER_SUBSTR` | 标记 token 属于该目标的 JWT `iss` 子字符串（实时检查）。 | | `GP_SOFT_KEYWORDS` | 宽泛的相关性关键词（用于 issuer/代码检测）。 | | `GP_SWEEP_KEYWORDS` | 经过**精心筛选的品牌专有**词汇，用于名称清理 + 兴趣测试。在此处剔除通用词汇。 | | `GP_NAME_PATTERNS` | 用于清理的工作账户登录模式（例如 `*-acme` / `acme-*`）。 | | `GP_FORK_PIVOT` | 默认为 `0`；设为 `1` 则启用有界 fork 枚举 —— 仅适用于小型目标。 | | `GP_NTFY_TOPIC` | 警报 topic（自动生成；绝不传输 token 本身）。 | | `GP_MARKER_BUDGET` | 在每次 `discover` 时，将代码搜索预算消耗在多少个最罕见的标记上。 | | `GP_MAX_REPO_MB` | `watch` 会跳过大于此限制的 repo（默认为 500），确保单个 monorepo 不会卡死整个周期。 | 标记目录（`markers.tsv` → 排名后的 `markers-ranked.tsv`）包含多种类型，如 `endpoint`、`internal-host`、`env-var`、`header`、`proto-pkg` 和 `manual`（你手动添加的黄金标记）。 ## 监视周期的工作原理 对于 deep 集合中的每个 repo（org repos + 标记命中泄露）： 1. **大仓库防护** —— 首先检查 GitHub 报告的大小；如果超过 `GP_MAX_REPO_MB` 则跳过并警告（可以通过 `force-big.txt` 覆盖特定 repo 的限制）。由于无人值守的 cron 无法进行交互提示，因此设计原则是跳过并警告，而非询问。 2. **克隆或拉取**；通过基于 repo 的 commit-set 检查点跳过未更改的 repo。 3. **gitleaks** 全历史扫描 → 一个具备 issuer 感知的后置过滤器只保留与目标相关的机密。 4. **警报**（仅在基线扫描时对活跃命中发出警报）。 每个操作都有一个并发 `flock`，这意味着长时间运行的周期与下一次 cron 触发绝不会发生冲突。 ## 定时任务 (Cron) ``` */30 * * * * ~/.local/bin/ghprowl watch --all >/dev/null 2>&1 # detect 17 5 * * * ~/.local/bin/ghprowl discover --all >/dev/null 2>&1 # widen 37 */6 * * * ~/.local/bin/ghprowl sweep --all >/dev/null 2>&1 # promote ``` ## 范围与道德规范 ghprowl 是一款防御性/授权研究工具，其设计初衷就是在此类界限内运行： - **仅限公开数据。** 它读取公开的 repo 和公开的代码搜索结果。仅此而已。 - **离线验证。** 检测在本地运行；发现的机密仅会被*报告*，绝不会被使用。 - **token 绝不移动。** 推送通知只会提醒“检查宿主机”；机密信息始终保留在磁盘上。 - **登录账号是线索，而非针对个人。** 账号昵称是搜索线索，而不是用于刻画特定个人画像的目标。 请在获得授权测试的项目中使用它，并遵守每个项目的漏洞披露规则。 ## 仓库结构与清理规范 ``` bin/ghprowl # thin dispatcher lib/ # generic engine (target-agnostic) targets/_template/ # the only target dir that ships targets// # YOUR per-target data — gitignored, never committed ``` 所有与操作者相关的特定数据（范围、标记、ntfy topic、账本、克隆、警报）都存放在 `targets//` 下，并且已被 **gitignored**。在提交之前，请确认没有任何内容被意外包含进来： ``` git diff --cached --name-only | grep -v _template # should list only engine/docs files ``` ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：Cutter, GitHub监控, StruQ, 企业安全, 网络资产管理