stephennotw/Hiveguard

# 🐝 HiveGuard **跨平台端点供应链扫描器，具备实时威胁情报功能。** HiveGuard 会对开发者端点上的每一个软件组件进行盘点——npm、PyPI、Go、Composer、RubyGems、Cargo、IDE 扩展、浏览器扩展、MCP server 配置——并在实时将它们与已知的供应链入侵目录进行匹配。 ## 功能 - **零依赖** — 纯 Node.js 18+，无需 `npm install` - **跨平台** — Windows、macOS、Linux，具备特定于操作系统的路径检测功能 - **11 种扫描器** — npm、PyPI、Go、Composer、RubyGems、Cargo、编辑器扩展、浏览器扩展、MCP 配置、npm 全局包、机密信息检测 - **实时威胁情报** — 运行时从 [Bumblebee](https://github.com/perplexityai/bumblebee) 获取暴露目录至内存中，带有内置的基线回退机制 - **自定义威胁情报** — 通过 `--custom-intel` 或 `~/.hiveguard/custom-catalogs/` 添加组织特定的目录 - **已知 CVE 检查** — 针对 20 多种常见漏洞的静态规则（express、lodash、axios、pip、setuptools 等） - **机密信息检测** — 检测包含机密信息的 `.env` 文件、明文 git 凭证、SSH key 审计 - **交互式 HTML 报告** — 可搜索、可过滤，带有威胁警报横幅和 package 详情弹窗 - **机器可读输出** — 适用于 Tanium/Jamf/SIEM 收集的 JSON 格式 - **只读** — 绝不执行 package 管理器，绝不修改文件 ## 安装说明 ``` # Clone the repo（或将该文件夹复制到目标机器） git clone https://github.com/stephennotw/Hiveguard.git cd hiveguard ``` 就这么简单——无需 `npm install`，无需任何依赖。Bootstrap 包装器会处理一切，包括在需要时下载 Node.js。 ## 如何运行 HiveGuard 附带了 Bootstrap 包装器，如果尚未安装，它会**自动下载一个便携版的 Node.js**。无需管理员/root 权限。 ### Windows — 命令提示符 (CMD) 打开 `cmd.exe` 并运行： ``` run.bat run.bat --offline --output C:\results --verbose run.bat --json > results.json ``` ### Windows — PowerShell 打开 PowerShell 并运行： ``` .\run.ps1 .\run.ps1 --offline --output C:\results --verbose .\run.ps1 --json > results.json ``` ### macOS / Linux ``` chmod +x run.sh # first time only ./run.sh ./run.sh --offline --output /tmp/results --verbose ./run.sh --json > results.json ``` ### 直接运行（如果已安装 Node.js 18+） 如果您的系统上已经有 Node.js 18+，则可以完全跳过 Bootstrap 包装器： ``` node bin/hiveguard.js node bin/hiveguard.js --output /path/to/results --verbose node bin/hiveguard.js --json --offline > results.json node bin/hiveguard.js --custom-intel /path/to/custom-catalogs node bin/hiveguard.js --scan-dirs /home/user/projects,/opt/apps ``` 扫描完成后，在任何浏览器中打开生成的 HTML 报告即可交互式地浏览结果。 ### Bootstrap 工作原理 `run.bat` / `run.ps1` (Windows) 和 `run.sh` (macOS/Linux) 包装器使 HiveGuard 真正实现了零前提条件： 1. **检查系统** — 查找现有的版本 >=18 的 `node` 二进制文件 2. **缺失时下载** — 如果未找到 Node.js（或版本太旧），则从 `nodejs.org` 下载便携版 Node.js 二进制文件到代码仓库内的本地 `.node/` 目录中。无需系统级安装，无需管理员/root 权限，无需更改 PATH。 3. **缓存以便重用** — 下载的二进制文件（约 30MB）会保存在 `.node/` 中，以便后续运行时能瞬间启动 4. **透传** — 所有 CLI flags 都将直接转发给 `bin/hiveguard.js` `.node/` 目录已被 gitignored，永远不会被提交到代码仓库中。 | 包装器 | Shell | 何时使用 | |---|---|---| | `run.bat` | CMD（命令提示符） | Windows 默认选项 — 适用于所有环境，无执行策略问题 | | `run.ps1` | PowerShell | 如果您偏好使用 PowerShell 或在 PS 终端中运行 | | `run.sh` | Bash / Zsh | macOS 和 Linux | ## CLI 选项 | Flag | 描述 | 默认值 | |---|---|---| | `--output ` | 结果的输出目录 | `./hiveguard-results` | | `--json` | 输出 JSON 到 stdout（静默模式） | off | | `--offline` | 仅使用内置的基线目录 | off | | `--scan-dirs ` | 逗号分隔的扫描根目录 | 自动检测 | | `--custom-intel ` | 包含自定义威胁情报 JSON 的目录 | 无 | | `--no-report` | 跳过 HTML 报告 | off | | `--no-secrets` | 跳过机密信息检测 | off | | `--max-depth ` | 最大目录遍历深度 | 6 | | `--verbose` / `-v` | 调试日志 | off | ## 退出代码 | 代码 | 含义 | |---|---| | `0` | 干净 — 无威胁，无严重/高危发现 | | `1` | 有发现 — 存在中危/高危 CVE 或安全公告 | | `2` | 严重 — 检测到供应链入侵 | | `3` | 致命错误 | ## 端点部署 HiveGuard 旨在通过任何管理工具（Tanium、Jamf、Intune、Ansible 等）推送到端点。 无需任何前提条件 — 如果需要，Bootstrap 包装器会自动下载 Node.js。 ### 选项 A：ZIP 包（推荐用于 Tanium / 远程部署） 1. **准备** — 将包含 HiveGuard 的文件夹（例如 `Hiveguard/`）压缩为 `Hiveguard.zip` 2. **上传** — 将 `Hiveguard.zip` 作为 package 文件上传 3. **命令** — package 命令解压 ZIP，然后运行 bootstrap： - **Windows (CMD)**: `cmd /c powershell -NoProfile -NonInteractive -Command "$ProgressPreference='SilentlyContinue'; Expand-Archive -Path 'Hiveguard.zip' -DestinationPath '.' -Force" && Hiveguard\run.bat --json` - **Windows (PowerShell)**: `cmd /c powershell -NoProfile -NonInteractive -Command "$ProgressPreference='SilentlyContinue'; Expand-Archive -Path 'Hiveguard.zip' -DestinationPath '.' -Force" && powershell Hiveguard\run.ps1 --json` - **macOS/Linux (Tanium)**: `/bin/bash -c "unzip -qo Hiveguard.zip && cd Hiveguard && chmod +x run.sh && ./run.sh --json"` - **macOS/Linux (shell)**: `unzip -qo Hiveguard.zip && chmod +x Hiveguard/run.sh && Hiveguard/run.sh --json` ### 选项 B：直接复制 1. **部署** — 将整个 `hiveguard/` 目录复制到端点 2. **运行** — 执行 bootstrap 包装器： - **Windows (CMD)**: `cmd /c C:\path\to\hiveguard\run.bat --json` - **Windows (PowerShell)**: `powershell -ExecutionPolicy Bypass -File C:\path\to\hiveguard\run.ps1 --json` - **macOS/Linux**: `/path/to/hiveguard/run.sh --json` ### 收集结果 - **收集** — 从每个端点的 `--output` 目录收集 JSON 输出 - **告警** — 使用退出代码进行自动告警： - `0` = 干净 - `1` = 存在发现（建议审查） - `2` = **严重** — 检测到供应链入侵（立即上报） ### Tanium 7.8 本地部署快速参考 | 步骤 | 位置 | 内容 | |---|---|---| | 创建 package (Win) | Administration → Content → Packages → New Package | 上传 `Hiveguard.zip` | | 设置命令 (Win) | Package → Command field | `cmd /c powershell -NoProfile -NonInteractive -Command "$ProgressPreference='SilentlyContinue'; Expand-Archive -Path 'Hiveguard.zip' -DestinationPath '.' -Force" && Hiveguard\run.bat --json` | | 创建 package (Mac) | Administration → Content → Packages → New Package | 上传 `Hiveguard.zip` | | 设置命令 (Mac) | Package → Command field | `/bin/bash -c "unzip -qo Hiveguard.zip && cd Hiveguard && chmod +x run.sh && ./run.sh --json"` | | 设置超时 | Package → Command Timeout | `600` 秒（解压 + 可能的 Node.js 下载） | | 目标端点 | Interact → Ask question | `Get Computer Name from all machines` | | 部署 | 选择端点 → Deploy Action → 选择 package | 立即运行或计划任务 | | 收集结果 | 创建 sensor 以读取 action 目录中的 `hiveguard-results/*.json` | 通过 Interact 拉取 | 无需管理员/root 权限。默认情况下，结果会写入当前目录的 `./hiveguard-results/` 中。如果端点已经拥有 Node.js 18+，包装器将直接使用它。否则，它会在首次运行时下载便携版二进制文件（约 30MB，已缓存供后续扫描使用）。 ## 输出结构 ``` hiveguard-results/ ├── hiveguard--.json # Full scan results └── hiveguard-report-.html # Interactive HTML report ``` 注意：威胁情报目录会在运行时加载到内存中 — 无需磁盘缓存。 ## 扫描器 | 扫描器 | 查找目标 | Lockfile / 来源 | |---|---|---| | **npm** | 项目及全局依赖 | `package-lock.json` | | **PyPI** | Venv packages, requirements.txt, 全局 | `.dist-info/METADATA` | | **Go** | 模块依赖 | `go.sum` / `go.mod` | | **Composer** | PHP 依赖 | `composer.lock` | | **RubyGems** | Ruby 依赖 | `Gemfile.lock` | | **Cargo** | Rust 依赖 | `Cargo.lock` | | **编辑器扩展** | VS Code, Windsurf, Cursor, VSCodium | 扩展 `package.json` | | **浏览器扩展** | Chrome, Edge, Brave | 扩展 `manifest.json` | | **MCP 配置** | Claude, Cursor, Windsurf MCP servers | 配置 JSON 文件 | | **机密信息检测** | `.env` 文件、git 凭证、SSH key | 文件检测 + 元数据 | ## 威胁情报 HiveGuard 采用**分层回退链**机制，以确保威胁情报始终可用： | 优先级 | 来源 | 描述 | |---|---|---| | **第一级** | 实时获取 | 运行时从 [Bumblebee](https://github.com/perplexityai/bumblebee) GitHub 获取目录至内存中 | | **第二级** | 内置基线 | 随 HiveGuard 一起发布的目录快照（`data/baseline-catalogs/`） | | **第三级** | 自定义目录 | 用户通过 `--custom-intel` 或 `~/.hiveguard/custom-catalogs/` 提供的 JSON 文件 | 自定义目录**始终为追加模式** — 它们会合并到实时/基线之上，并在发生冲突时优先采用。 报告和 JSON 输出始终会指示使用了哪个源层级：`live`、`baseline`、`custom` 或 `live+custom`。 ### 自定义威胁情报格式 要添加您自己的威胁情报（例如内部 SOC 发现），请创建一个 JSON 文件： ``` { "_comment": "Internal SOC findings — 2026-05-27", "_indicators": { "c2_domain": "bad.example.com", "reference": "SOC-2026-0042" }, "entries": [ { "name": "Backdoored internal-utils", "ecosystem": "npm", "package": "internal-utils", "source": "internal-soc", "versions": ["1.0.0", "1.0.1"] } ] } ``` 将其放置在以下任一位置： - **`~/.hiveguard/custom-catalogs/`** — 每台计算机持久保存 - **通过 `--custom-intel ` 传递的任何目录** — 用于 Jamf/Tanium 推送 支持的生态系统：`npm`、`pypi`、`go`、`composer`、`rubygems`、`cargo`、`vscode-extension`、`chrome-extension`。 ### 内置活动 当前基线包括：mini-shai-hulud、antv-mini-shai-hulud、trapdoor-crypto-stealer、node-ipc-credential-stealer、nx-console-vscode、gemstuffer、laravel-lang、shopsprint-decimal-typosquat。 ## 架构 ``` hiveguard/ ├── run.bat # Bootstrap wrapper (Windows CMD) ├── run.ps1 # Bootstrap wrapper (Windows PowerShell) ├── run.sh # Bootstrap wrapper (macOS/Linux) ├── bin/hiveguard.js # CLI entry point + orchestrator ├── src/ │ ├── scanners/ # One module per ecosystem │ ├── platform/ # OS-specific paths (win32, darwin, linux) │ ├── threat-intel/ # Runtime fetch + matcher + baseline fallback │ ├── cve/ # Static known-vulnerability rules │ ├── report/ # HTML report generator │ └── utils/ # Logger, FS helpers, output writers ├── data/ │ └── baseline-catalogs/ # Frozen threat intel snapshot (offline fallback) ├── package.json ├── LICENSE └── README.md ``` ## 系统要求 - **无** — 如果不存在，bootstrap 包装器（`run.bat` / `run.ps1` / `run.sh`）会自动下载 Node.js - **无需 npm install** — 零外部依赖 - **只读文件系统访问** — 扫描用户主目录、项目目录、扩展目录，不写入或执行任何操作 - 如果直接通过 `node bin/hiveguard.js` 运行，需要 Node.js 18+（仅使用内置的 `fs`、`https`、`path`、`os`） ## 安全性 - **只读** — 绝不在输出目录之外写入内容，绝不执行 package 管理器 - **不读取机密值** — 机密信息检测扫描器仅检测文件存在性和 key 名称，绝不读取其值 - **无外部调用**，除了用于获取实时威胁情报的可选 GitHub API（使用 `--offline` 可跳过） ## License MIT

标签：GNU通用公共许可证, Homebrew安装, MITM代理, Node.js, 依赖审计, 域名收集, 多模态安全, 威胁情报, 开发者工具, 文档结构分析, 终端安全, 自定义脚本