netapp-suraj/dephunt

# dephunt 一个用于索引和搜索 GitHub 和 Bitbucket Server 仓库依赖项的 CLI 工具。为供应链事件响应而构建——快速查找整个组织中哪些仓库使用了特定包或版本。 ## 功能 - **多源支持**：GitHub（云）和 Bitbucket Server（本地） - **多语言支持**：Node.js 和 Python 生态系统 - **快速搜索**：基于 FTS5 的全文搜索，支持精确匹配、子字符串匹配和模糊匹配 - **全组织同步**：一条命令即可索引所有组织/项目中的仓库 - **并发同步**：可配置工作池的并行同步 - **离线优先**：本地 SQLite 数据库——无需网络即可搜索 - **安全认证**：令牌存储在操作系统凭据存储中（Windows 凭据管理器 / macOS 钥匙串 / Linux 密钥服务） - **导出功能**：CSV 和交互式 HTML 报告 ## 支持的清单文件 | 生态系统 | 清单文件 | 锁文件 | |----------|----------|--------| | **Node.js** | `package.json` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, `npm-shrinkwrap.json` | | **Python** | `pyproject.toml`, `requirements.txt`, `setup.cfg` | `poetry.lock`, `Pipfile.lock`, `uv.lock` | ## 安装 需要 Go 1.22+。 ``` go install github.com/surajg/dephunt@latest ``` 或者从源码构建： ``` git clone https://github.com/surajg/dephunt.git cd dephunt go build -o dephunt . ``` ### 跨平台构建 ``` # Windows (amd64) GOOS=windows GOARCH=amd64 go build -o dephunt.exe . # Windows (arm64) GOOS=windows GOARCH=arm64 go build -o dephunt.exe . # macOS (Apple Silicon) GOOS=darwin GOARCH=arm64 go build -o dephunt . # macOS (Intel) GOOS=darwin GOARCH=amd64 go build -o dephunt . # Linux (amd64) GOOS=linux GOARCH=amd64 go build -o dephunt . # Linux (arm64) GOOS=linux GOARCH=arm64 go build -o dephunt . ``` 或者一次性构建所有平台： ``` # PowerShell foreach ($p in @("windows/amd64","darwin/arm64","darwin/amd64","linux/amd64","linux/arm64")) { $os,$arch = $p -split "/" $ext = if ($os -eq "windows") { ".exe" } else { "" } $env:GOOS=$os; $env:GOARCH=$arch go build -o "dist/dephunt-$os-$arch$ext" . } # Bash for p in windows/amd64 darwin/arm64 darwin/amd64 linux/amd64 linux/arm64; do GOOS=${p%/*} GOARCH=${p#*/} EXT=""; [ "$GOOS" = "windows" ] && EXT=".exe" GOOS=$GOOS GOARCH=$GOARCH go build -o "dist/dephunt-$GOOS-$GOARCH$EXT" . done ``` ## 快速开始 ``` # 1. Store your token securely dephunt auth login --github # 2. Sync a single repo dephunt sync facebook/react # 3. Sync all repos in your GitHub orgs dephunt sync-all # 4. Search for a package dephunt search lodash # 5. Search for a specific vulnerable version dephunt search jsonwebtoken --version 8.5.1 ``` ## 认证 令牌的解析顺序（优先级从高到低）： 1. `--token` / `--bb-token` CLI 参数 2. `GITHUB_TOKEN` / `BITBUCKET_TOKEN` 环境变量 3. OS 凭据存储（通过 `dephunt auth login` 设置） ``` # Store tokens in the OS credential store dephunt auth login # prompts for both GitHub and Bitbucket dephunt auth login --github # GitHub only dephunt auth login --bitbucket # Bitbucket only # Check what's configured dephunt auth status # Remove stored tokens dephunt auth logout ``` ## 命令 ### sync 从单个仓库索引依赖项。 ``` # GitHub (default) dephunt sync owner/repo dephunt sync owner/repo --ref develop # Bitbucket Server dephunt sync PROJECT_KEY/repo-slug --source bb # Force re-sync even if already up to date dephunt sync owner/repo --force ``` ### sync-all 发现并同步所有可访问的组织（GitHub）和项目（Bitbucket Server）中的仓库。 ``` # Both GitHub and Bitbucket (default) dephunt sync-all # GitHub only dephunt sync-all --source gh dephunt sync-all --include-user # also sync your personal repos # Bitbucket Server only dephunt sync-all --source bb # Tuning dephunt sync-all --concurrency 20 # parallel workers (default: 10) ``` ### search 在所有已索引仓库中搜索包。 ``` dephunt search react dephunt search react --version 18.3.1 dephunt search lodash --repo NetApp/my-app dephunt search express --dep-type prod --direct-only dephunt search requests --lang py # Python only dephunt search react --lang js # Node.js only dephunt search jsonwebtoken --exact # exact name match dephunt search reqeusts --fuzzy # typo-tolerant # Export results dephunt search react --output results.csv dephunt search react --output report.html # interactive HTML with filtering/sorting ``` 搜索策略（级联）： 1. **精确匹配**包名 2. **子字符串匹配**（若无精确结果） 3. **模糊匹配**（Levenshtein 距离）作为后备 ### show 显示特定包在所有仓库中的详细信息。 ``` dephunt show --package lodash dephunt show --package lodash --repo NetApp/my-app ``` ### history 显示包首次和最后出现的时间，包括提交 SHA。 ``` dephunt history --package jsonwebtoken dephunt history --package express --repo NetApp/my-app --ref main ``` ### repos 列出所有已索引的仓库。 ``` dephunt repos ``` ### unsync 从索引中移除仓库。 ``` # Remove a single repo dephunt unsync owner/repo # Remove all repos in an org dephunt unsync --org NetApp # Bitbucket Server dephunt unsync PROJECT_KEY/repo-slug --source bb dephunt unsync --org PROJECT_KEY --source bb ``` ## 搜索结果 结果会标注来源，并显示可点击的文件 URL： ``` lodash 4.17.21 prod direct [GH] NetApp/my-app@main -> https://github.com/NetApp/my-app/blob/main/package-lock.json#L5432 lodash 4.17.21 prod transitive [BB] DSS-BB/cvo-ui@master -> https://bitbucket.ngage.netapp.com/projects/DSS-BB/repos/cvo-ui/browse/yarn.lock?at=master#8901 ``` ### 导出格式 **CSV** — 包含所有字段（包括 URL），适用于电子表格和进一步处理。 **HTML** — 深色主题交互式报告，包含： - 可排序的列（点击任意表头） - 实时文本过滤 - 来源、依赖类型、直接/传递依赖的下拉筛选 - 颜色编码标签 - 可点击的源代码文件链接（带行号） ## 数据库 dephunt 使用本地 SQLite 数据库，存储路径为 `~/.dephunt/dephunt.db`。可通过 `--db` 覆盖。 启用 WAL 模式以获得并发读取性能。 ## 全局参数 | 参数 | 环境变量 | 描述 | |------|----------|------| | `--token` | `GITHUB_TOKEN` | GitHub 个人访问令牌 | | `--bb-token` | `BITBUCKET_TOKEN` | Bitbucket Server 个人访问令牌 | | `--bb-url` | — | Bitbucket Server 基础 URL | | `--db` | — | SQLite 数据库路径 | ## GitHub Actions 包含两个用于自动化同步和按需搜索的工作流。 ### 设置 在仓库中添加以下密钥（Settings → Secrets and variables → Actions）： | 密钥 | 是否必需 | 描述 | |------|----------|------| | `DEPHUNT_GITHUB_TOKEN` | 推荐 | 具有 `repo` 和 `read:org` 范围的 GitHub PAT。默认为 `GITHUB_TOKEN` | | `DEPHUNT_BITBUCKET_TOKEN` | 可选 | Bitbucket Server PAT。未设置时跳过 BB 同步 | ### 同步数据库 **工作流**：`.github/workflows/sync.yml` 保持依赖数据库最新。每天 UTC 时间 02:00 运行一次，也可手动触发。 ``` Actions → "Sync Database" → Run workflow ``` | 输入 | 默认值 | 描述 | |------|--------|------| | `source` | `all` | `all`、`gh` 或 `bb` | | `force` | `false` | 即使提交相同也重新同步仓库 | | `concurrency` | `20` | 并行工作数 | | `repo` | — | 仅同步单个仓库（例如 `owner/repo`） | 数据库保存为工作流工件（`dephunt-db`），并在后续运行中恢复以实现增量更新。 ### 依赖项搜索 **工作流**：`.github/workflows/search.yml` 对最新同步的数据库运行按需搜索。 ``` Actions → "Dependency Search" → Run workflow ``` | 输入 | 默认值 | 描述 | |------|--------|------| | `query` | *(必需)* | 要搜索的包名 | | `version` | — | 按精确版本过滤 | | `lang` | — | `js` 或 `py` | | `dep-type` | — | `prod`、`dev`、`peer`、`optional` | | `direct-only` | `false` | 仅显示直接依赖 | | `export-format` | `html` | `html`、`csv` 或 `both` | 结果会在 **作业摘要** 中打印，并导出文件作为可下载的 **工件**。 ### 典型工作流 ``` # 1. Push the repo to GitHub # 2. Add your PAT as a secret # Settings → Secrets → New repository secret → DEPHUNT_GITHUB_TOKEN # 3. Run the Sync workflow to build the initial database # Actions → "Sync Database" → Run workflow → source: all # 4. Search for a vulnerable package # Actions → "Dependency Search" → Run workflow → query: jsonwebtoken, version: 8.5.1 # 5. Download the HTML report from the workflow artifacts ``` ### 限制 - **Bitbucket Server 同步在 GitHub Actions 中不可用**。Bitbucket Server 是本地部署，无法从 GitHub 公共运行器访问。BB 同步在 CI 中会自动跳过。若要启用，需要： - 一个位于公司网络中的 [自托管运行器](https://docs.github.com/en/actions/hosting-your-own-runners) - 或在同步步骤前添加 VPN/隧道（例如 Tailscale、WireGuard） - 在本地运行 dephunt 时，BB 同步正常工作：`dephunt sync-all --source bb`

标签：Bitbucket Server, EVTX分析, GitHub API, Go语言, HTML报告, Linux密钥服务, macOS钥匙串, Node.js依赖, Python依赖, SQLite, Windows凭证存储, 代码搜索, 依赖搜索, 依赖索引, 全文搜索FTS5, 多源索引, 子字符串匹配, 工作线程池, 并发同步, 日志审计, 模糊匹配, 漏洞响应, 离线搜索, 程序破解, 精确匹配, 组织范围索引, 跨平台构建, 软件供应链