entropyvortex/repoguard

# RepoGuard **再多一道防线（或尝试）在 `git clone` 之前。** 2026 年，星标是假的，README 是精心打磨的，恶意软件隐藏在 `postinstall` 脚本中。RepoGuard 在你克隆仓库 **之前** 使用一个 OpenAI 兼容的 LLM（默认是 xAI Grok）分析仓库—— 在几秒钟内给出风险评分、红旗标记和通俗易懂的解释。 **这是一个实验性的“衔尾蛇”。** 它能捕捉恶意仓库……但聪明的攻击者也可以尝试提示注入。 **尚未准备好用于生产。仅作实验。** 不喜欢什么？Fork 它并提交 PR。空洞的批评只是噪音。 ## 哲学 - **一个文件。没有魔法。** 整个工具是一个约 900 行的 Bash 脚本， 你可以在一次阅读中从头到尾看完，再决定是否信任它。 - **没有不寻常的依赖。** 唯一非系统自带的安装是 `curl` 和 `jq`；其余（`awk`、`sed`、`tr`、`mktemp`、`stat`、`grep`、 `getconf`）都是标准 POSIX 工具，任何开发者机器都已具备。 - **透明的信任边界。** 离开你机器的每一字节都在下方有文档说明。 没有遥测，没有分析。 - **CI 友好。** 退出码是一个稳定的约定，因此 `repoguard check ... || exit $?` 会如你所期望地工作。 ## 它实际做什么 给定一个 GitHub 仓库 URL，`repoguard check`： 1. 通过 GitHub API 获取仓库的公开元数据和安全设置、开放 Dependabot PR 以及公开的安全公告。 2. 从 `raw.githubusercontent.com` 获取 `README.md`、`SECURITY.md` 以及常见清单/安装文件 （`package.json`、`setup.py`、`pyproject.toml`、`requirements.txt`、 `install.sh`、`postinstall.js` 以及一些工作流文件）。 3. 将这些文件与一个系统提示一起发送到 OpenAI 兼容的聊天补全端点。 4. 解析模型的 JSON 判决，输出风险评分（0–100）、判定结果（`Safe` / `Warning` / `Danger`）、 红旗标记以及推荐操作。 5. 根据评分退出相应代码，以便 CI 管道和可选的 Git 包装器可以据此拦截克隆。 ### 提供商支持 **目前仅支持 GitHub**。GitLab 和 Bitbucket URL 会被明确拒绝， 而不是静默地生成仅作噪声的分析。提供商兼容性是一个小而受欢迎的 PR。 ## 需求 - `bash` 4+（macOS 自带 3.2 —— 如需要请 `brew install bash`） - `curl` 和 `jq` - 任意 OpenAI 兼容聊天补全端点的 API 密钥。 默认基础 URL 是 xAI 的 `https://api.x.ai/v1`，但你可以在 `repoguard setup` 时指向任何兼容的端点。 - 可选：一个 `GITHUB_TOKEN` 环境变量，用于解除 GitHub 的匿名速率限制（从 60 次/小时到 5000 次/小时）。 一次 `check` 大约会消耗十几个请求，因此未认证使用会迅速达到上限。 ## 安装 ### 推荐：先审计 ``` curl -fsSL https://raw.githubusercontent.com/entropyvortex/repoguard/HEAD/install.sh -o install.sh less install.sh # read it bash install.sh # then run it ``` ### 单行命令（如果你信任来源） ``` curl -fsSL https://raw.githubusercontent.com/entropyvortex/repoguard/HEAD/install.sh | bash ``` 两种方式都会将主脚本 `repoguard` 下载到 `~/.local/bin/repoguard` （权限 `0755`），创建 `~/.config/repoguard`（权限 `0700`），并将 `~/.local/bin` 添加到 PATH（在 `~/.bashrc` 或 `~/.zshrc` 中， 如果尚未存在）。对于 fish，安装器会打印一条手动 `set -gx PATH` 命令， 将其添加到 `~/.config/fish/config.fish`。 安装后，打开一个新 Shell（或运行 `hash -r` / `rehash`），以便命令哈希缓存识别新二进制文件。 ### 配置 ``` repoguard setup ``` 系统会提示你输入基础 URL、模型、API 密钥以及警告/中止的风险阈值。 配置文件将以 `600` 权限写入，这样同一台机器上的其他用户无法读取你的 API 密钥。 ## 用法 ``` repoguard check https://github.com/suspicious/repo ``` 标志： | 标志 | 效果 | |------|------| | `--verbose`, `-v` | 将每一步输出到标准错误 | | `--non-interactive` | 无颜色、无提示 —— 适合 CI | | `--json` | 在标准输出上输出原始模型判决，便于通过 `jq` 管道处理 | ### CI / 流水线 退出码是稳定的约定： | 码值 | 含义 | |------|------| | 0 | 安全（评分低于警告阈值） | | 1 | 警告（评分 ≥ 警告阈值） | | 2 | 中止（评分 ≥ 中止阈值 或 严重错误） | | 64 | 用法错误 | | 78 | 配置错误 | 典型流水线用法： ``` repoguard check --non-interactive --json "$TARGET" || exit $? ``` ### Git 包装器（可选） ``` repoguard enable-git-wrapper ``` 这会在 `~/.local/bin/git` 安装一个约 30 行的 shim，拦截 `git clone `，先运行 `repoguard check`，如果评分超过中止阈值则拒绝克隆。 其他 Git 命令（`git status`、`git commit`、`git push`、……）直接透传给真实的 Git 二进制文件。 在安装时确定真实 Git 的绝对路径并硬编码在包装器中，因此该包装器在 macOS（Apple Silicon / Intel Homebrew）、Linux 和 Nix 上行为一致—— 没有运行时 PATH 戏法，也没有自递归风险。 要移除它： ``` repoguard disable-git-wrapper ``` 检查状态并查看当前使用的是哪个 `git`： ``` repoguard status ``` ## 隐私与信任边界 RepoGuard 是一个安全工具，因此数据流必须明确。 **当运行 `repoguard check` 时离开你机器的内容：** 1. 目标的公开元数据、README、SECURITY.md 以及少量清单/安装文件， 从 GitHub 的公开端点（或设置了 `GITHUB_TOKEN` 时的认证端点）获取。 2. 上述内容加上系统提示，一起发送到你配置在 `setup` 时的 LLM 基础 URL。 **因此你正在检查的仓库 URL 会披露给该 LLM 端点。** 如果启用了 Git 包装器， 你 `git clone` 的每个仓库都会以这种方式披露。 3. 你的 API 密钥，通过 `Authorization: Bearer` 头发送到 LLM 端点。 它不会传输到其他地方。 **保留在你机器上的内容：** - 你的 API 密钥和配置（`~/.config/repoguard/config.json`，权限 `600`）。 - 任何私有仓库的内容——RepoGuard 仅获取 *公开* 的 GitHub 端点。 - LLM 的响应，仅在本地打印，永不持久化或转发。 如果你不想让第三方 LLM 提供商看到你克隆的仓库名称，请 **不要** 启用 Git 包装器—— 而是显式地对选择提交的 URL 使用 `repoguard check`。 ## 已知限制 RepoGuard 的判决是一个 **信号，而非证明**。该工具将攻击者可控的 README 和清单文件 发送给 LLM，并信任其 JSON 响应。一个足够有说服力的恶意 README 可能提示注入模型， 使其返回低风险评分。将该判决作为你决策的一个输入——不要仅凭绿色结果就跳过人工审查。 详见 [SECURITY.md](SECURITY.md) 获取完整威胁模型。 ## 安全报告 若发现破坏上述信任边界或让 RepoGuard 执行攻击者可控内容的漏洞， 请打开一个 [GitHub 安全公告](https://github.com/entropyvortex/repoguard/security/advisories/new) 而非公开问题。详见 [SECURITY.md](SECURITY.md) 了解披露范围、时间线和已知限制列表。 ## 许可证 MIT —— 参见 [LICENSE](LICENSE)。 欢迎贡献：提供程序兼容性（GitLab、Bitbucket、Gitea更好的提示工程、CI 流水线与测试， 这些 PR 都有很高价值。

标签：AI安全分析, CI集成, Dependabot, DLL 劫持, GitHub API, Grok, POSIX, README审计, SEO: AI代码审计, SEO: 仓库安全检查, SEO: 开源供应链安全, 二进制发布, 仓库风险检测, 依赖项扫描, 单文件工具, 后安装脚本, 大语言模型, 安全实验, 安全策略检测, 安全评分, 应用安全, 开源工具, 退出码, 防克隆, 风险判定