depx
恶意包与供应链情报
功能 •
安装 •
用法 •
运行 depx •
JSON •
加入 Discord
**depx** 是一个快速、被动的供应链情报 CLI。它通过匹配 [OpenSSF 恶意包](https://github.com/ossf/malicious-packages)数据（`MAL-*`，OSV 格式）以及从 [X (Grok API)](https://x.com) 整理并每小时刷新的实时情报源，来告诉你某个包是否**已知是恶意的**（劫持发布、凭据窃取程序、安装脚本后门）。
它能在几秒钟内回答四个问题：
1. **最近有什么被入侵了？** 新披露的恶意包实时源。
2. **这个特定的包安装安全吗？** 在添加之前检查任何包。
3. **我的系统上是否已经安装了任何恶意内容？** 审计本地 lockfile 和 SBOM。
4. **我的 GitHub 组织的项目是否发布了任何恶意包？** 扫描整个组织和仓库。
# 功能
- **情报仪表板**：默认视图，显示活动、生态系统、受影响的 namespace 以及披露时间。
- **被入侵的包源**：通过 `depx feed` 按时间排序的卡片（或使用 `--list` 使每个结果占一行）。
- **本地依赖审计**：针对编译好的本地索引扫描 lockfile 和 SBOM。
- **GitHub 组织与仓库审计**：拉取 dependency-graph SBOM 导出并进行大规模审计。
- **适配 CI**：稳定的退出代码、`--require-clean` 门控、SARIF 导出以及带版本的 JSON 信封。
- **即时包判定**：检查任何 `ecosystem:name` 引用、纯名称或通过管道传入的列表。
- **误报控制**：使用 `--exclude-pkg` 文件可从审计结果中剔除已知的良好包。
- **快速且被动**：本地缓存、后台同步；只读，绝不会触碰你的应用程序。
# 安装
```
curl -sfL https://raw.githubusercontent.com/projectdiscovery/depx/main/scripts/install.sh | sh
```
下载适合你的操作系统/架构的最新版本（或使用 `go install` 作为备选进行构建）。该脚本会验证二进制文件，并在需要时更新你的 shell `PATH`。
**从源码构建**（需要 **Go 1.25+**）：
```
git clone https://github.com/projectdiscovery/depx.git
cd depx
make build
./bin/depx --help
```
或者直接使用 Go 进行安装：
```
go install github.com/projectdiscovery/depx/cmd/depx@latest
```
[GitHub releases](https://github.com/projectdiscovery/depx/releases) 页面上也提供了预编译的二进制文件。
# 用法
```
depx --help
```
核心命令和标志：
```
Usage:
depx [flags]
depx [command]
Available Commands:
feed Show recently disclosed malicious packages (cards)
audit Audit dependencies for malicious packages (default: $HOME)
github Audit GitHub repositories via dependency-graph SBOM
search Search known malicious packages by name (local index)
id Lookup advisory by ID
version Show version and check for updates
update Update depx to the latest version
Global flags:
-j, --json Machine-readable JSON output
-V, --version Show version and exit
-e, --ecosystem string Restrict lookup to one ecosystem (npm, PyPI, Go, ...)
-v, --verbose Extra audit/github detail
--silent Suppress banner and version info
--no-color Disable ANSI colors
--config string Config file path
--update Update depx to the latest version
--disable-update-check Disable the update check
Default command (intelligence dashboard):
--since string Feed time window (default "3d")
-n, --limit int Dashboard/feed entry cap on default command
depx feed:
--since string Feed time window (default "3d")
-n, --limit int Result limit
--list One header line per result
depx search:
-n, --limit int Max results shown (default 25)
--list One header line per result
depx audit / depx github:
--require-clean Exit 1 if any malicious package is found
--exclude-pkg string File of ecosystem:package lines to exclude from findings
-o, --output string Write export file(s) to this path or basename
--output-format string Comma-separated export formats: json, csv, txt (default: json)
--sarif-export string Write SARIF 2.1.0 report to this path
--sbom-export string Write audited dependency SBOM (audit only)
--sbom-format string SBOM format: cyclonedx (default) or spdx
depx github:
-n, --limit int Max repos for org/user targets (default 100 with token, 10 without)
depx id:
--raw Raw OSV record only
```
# 运行 depx
### 1. 情报仪表板（默认）
```
depx # dashboard for last 3 days
depx --since 7d # widen the time window
depx -e npm # npm-only dashboard
depx feed # card feed (no dashboard)
depx feed --list # one line per advisory
depx -j # JSON for dashboards / pipelines
```
### 2. 审计你的依赖
针对**本地恶意包索引**扫描 lockfile 和 SBOM，首次运行后即可实现即时查询。如果没有提供路径，depx 将扫描 `$HOME` 以查找项目和全局安装。
```
depx audit # sweep $HOME for projects + global installs
depx audit ./my-app # a single project tree
depx audit ./bom.cdx.json # a CycloneDX / SPDX file
```
支持 npm、PyPI、Go、Cargo、RubyGems、Maven/Gradle lockfile 以及 CycloneDX / SPDX SBOM。
**抑制误报。** 当被标记的包经过你验证是安全的时，可以在（`audit` 或 `github` 中）向 `--exclude-pkg` 传入一个包含以换行符分隔的 `ecosystem:package` 条目的文件，将其从结果中剔除：
```
depx audit ./my-app --exclude-pkg .depxignore
depx github google --exclude-pkg .depxignore
```
```
# .depxignore：从 findings 中排除的 packages
npm:internal-tool
PyPI:requests
*:shared-lib # '*' matches any ecosystem
```
### 3. 审计 GitHub 仓库与组织
使用 GitHub 的 dependency-graph SBOM 导出。对于私有仓库和组织发现，请设置 `GITHUB_TOKEN`。
```
depx github projectdiscovery/depx
depx github google
depx github
```
未经身份验证的 GitHub 访问被限制为每小时约 60 次请求，因此如果没有 token，组织/用户扫描默认为 **10 个仓库**（有 token 时为 **100 个**）。请设置 `GITHUB_TOKEN`、`GH_TOKEN` 或 `DEPX_GITHUB_TOKEN`（或使用 `-n` 显式提高限制）以扫描更多内容。
### 4. 检查单个包或安全公告
```
depx npm:lodash
depx id MAL-2026-4343
depx search redhat
```
### 5. 在 CI 中实施门控
一旦发现恶意包，`--require-clean` 将以非零状态退出。
```
depx audit . --require-clean # fail the build if anything is malicious
depx github google --require-clean -j
```
| 退出代码 | 含义 |
|-----------|---------|
| `0` | 干净 / 成功 |
| `1` | 使用了 `--require-clean` 且发现了恶意包 |
| `2` | 用法错误 |
| `3` | 上游不可用 |
# JSON 输出
每个 `-j` 的响应都使用一个稳定且带有版本号的信封，因此可以安全地在此基础上进行构建。
```
{
"schema_version": "1",
"command": "check",
"depx_version": "v0.1.0",
"data": {
"total": 1,
"results": [
{
"ref": "npm:evil-pkg",
"purl": "pkg:npm/evil-pkg",
"verdict": "malicious",
"confidence": "high",
"ids": ["MAL-2026-4343"],
"package_ecosystem": "npm",
"package_name": "evil-pkg",
"registry_url": "https://www.npmjs.com/package/evil-pkg",
"advisories": [
{
"id": "MAL-2026-4343",
"url": "https://github.com/ossf/malicious-packages/blob/main/osv/npm/MAL-2026-4343.json",
"summary": "Malicious code in evil-pkg (npm)",
"modified_at": "2026-06-01T12:00:00Z",
"published_at": "2026-06-01T10:00:00Z"
}
]
}
]
}
}
```
安全的包会返回 `"verdict": "clean"`。在搜索所有生态系统时，纯名称检查可能会包含 `checked_ecosystems`、`matched_ecosystems` 和 `found_ecosystems`。
schema 位于 [`schema/v1/`](schema/v1/)。
# 许可证
depx 采用 [MIT License](LICENSE) 授权。
加入我们的 Discord • 由 ProjectDiscovery 团队 ❤️ 构建