depproof/depproof-action
GitHub: depproof/depproof-action
一款在 CI 环境中本地运行的依赖漏洞与许可证审计工具，支持生成 CycloneDX SBOM 并在 PR 中拦截不合规依赖。
Stars: 0 | Forks: 0
# depproof — 针对 Maven、Gradle 和 npm 的依赖漏洞与许可证审计工具
在您的 pull request 中捕获存在漏洞和不合规的依赖项——扫描完全在您的 CI runner 内部运行，**您的源代码和清单文件绝不会离开本地**。
depproof 会扫描您的 Maven、Gradle 和 npm/pnpm/yarn 依赖清单，并与 [OSV.dev](https://osv.dev)（漏洞）以及完整的 [SPDX 许可证库](https://spdx.org/licenses/) + [ClearlyDefined.io](https://clearlydefined.io)（许可证）进行比对，生成 CycloneDX 1.6 SBOM，并设置用于拦截 PR 的通过/失败退出代码。
## 为什么选择 depproof
- **隐私优先。** 扫描在您的 GitHub Actions runner 内部运行。您的 `pom.xml` / `build.gradle.kts` / `package-lock.json` 绝不会离开本地——仅会针对公共注册表以及漏洞/许可证数据库检查单个包的坐标。不上传源代码，无需账户，无遥测。
- **适配 Monorepo。** 默认自动发现仓库中的所有清单文件（Maven、Gradle 和 npm/pnpm/yarn，位于任何子目录中）。正确处理多模块 Maven 项目，确保子模块基于其父模块构建。
- **精准的传递依赖解析。** 解析完整的传递依赖树，使其与您构建实际发布的内容一致（包含 Spring Boot / Kotlin / Quarkus 托管版本），从而避免因您已修补的版本而出现误报的 CVE。
- **对小型企业免费。** 年收入低于 100 万美元的组织可免费使用——无需注册，无需 API key，无配额限制。（大型组织：需商业许可——请联系 licensing@depproof.com。）
## 快速开始
在您的仓库中添加单个工作流文件：
```
# .github/workflows/audit.yml
name: Dependency Audit
on:
push:
branches: [main]
pull_request:
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: depproof/depproof-action@v1
- uses: actions/upload-artifact@v4
if: always()
with:
name: depproof-reports
path: |
depproof-*.json
depproof-report*.html
```
就这样。在每次 PR 以及推送到 main 分支时，depproof 都会扫描您的仓库，如果存在任何 CRITICAL（严重）级别的漏洞，则会导致构建失败。
## 配置
所有输入均为可选。默认配置已适用于大多数仓库。
```
- uses: depproof/depproof-action@v1
with:
# Single file mode (skip auto-discovery)
file: backend/pom.xml
# OR multiple explicit files (newline or comma-separated)
files: |
backend/pom.xml
services/api/pom.xml
# Auto-discover manifests under root (default: true). Set false to require file/files.
discover: true
# Severity threshold for failure: critical (default) | high | medium | low | none
fail-on: critical
# Discovery root. Default: $GITHUB_WORKSPACE
root: backend
# Extra glob patterns to exclude (on top of default node_modules / target / build / etc.)
exclude: 'fixtures/**,examples/**'
# Where to write SBOM artifacts. Default: $GITHUB_WORKSPACE
output-dir: reports
# Also emit a human-readable HTML report (depproof-report.html). Default: true
html: true
```
## 默认扫描内容
自动发现功能会在您的仓库中的任何位置查找以下清单文件：
- `pom.xml` (Maven)
- `build.gradle`、`build.gradle.kts`、`gradle.lockfile`、`libs.versions.toml`、`dependencies.txt` (Gradle)
- `package-lock.json` (npm)、`pnpm-lock.yaml` (pnpm)、`yarn.lock` (yarn) —— 直接根据 lockfile 解析，无需安装
并**跳过**以下目录（构建输出和第三方代管代码——此处无需审计）：
- `node_modules/`、`target/`、`build/`、`.gradle/`、`.git/`、`dist/`、`out/`、`vendor/`、`test-fixtures/`、`__fixtures__/`
使用 `exclude` 可在默认设置基础上添加自定义 glob 模式。
## 输出
运行成功后，depproof 会将结果写入工作区（或写入 `output-dir` 如果已设置）：
| 文件 | 内容 |
|---|---|
| `depproof-summary.json` | 汇总结果：各清单统计、漏洞/许可证总数、每个清单的通过/失败状态 |
| `depproof-sbom-.json` | 每个扫描清单对应的 CycloneDX 1.6 SBOM。路径中的斜杠会被替换为 `--`。 |
| `depproof-report.html` | 人类可读的报告（漏洞 + 依赖项 + 许可证策略）。独立生成——可离线打开，无需网络或 JS。在多清单扫描中，这将是一个索引页面，为每个清单链接一个 `depproof-report-.html`。设置 `html: false` 可跳过此步骤。 |
`depproof-summary.json` 的 schema 在 v1 版本中是稳定的——可安全地在后续步骤中使用：
```
{
"schemaVersion": 1,
"depproofVersion": "0.1.4",
"scannedAt": "2026-06-12T14:53:25Z",
"rootDir": "/github/workspace",
"manifests": [
{
"path": "backend/pom.xml",
"ecosystem": "Maven",
"components": 132,
"direct": 29,
"transitive": 103,
"vulns": { "critical": 0, "high": 4, "medium": 5, "low": 4 },
"licenses": { "forbidden": 0, "review": 15, "allowed": 117, "unknown": 0 },
"sbomFile": "depproof-sbom-backend--pom.xml.json",
"fail": false,
"isParentPom": false,
"unresolvedCount": 0
}
],
"totals": { "critical": 0, "high": 4, "medium": 5, "low": 4 },
"fail": false
}
```
## 退出代码
- `0` — 扫描无异常（或没有超过 `fail-on` 阈值的发现）
- `1` — 发现结果超过 `fail-on` 阈值（一个或多个清单失败）
- `2` — 扫描错误（参数错误或不支持的文件）
## 示例
### Monorepo / 多模块项目
```
- uses: depproof/depproof-action@v1
# Discovery default — scans every Maven/Gradle manifest under repo root.
# Multi-module Maven projects: parent + child POMs are auto-detected and bundled,
# so child modules build on their parent locally (no Maven Central round-trip).
```
### 仅扫描一个特定的清单
```
- uses: depproof/depproof-action@v1
with:
file: services/api/pom.xml
```
### 遇到 HIGH 或更高级别时失败（不仅是 CRITICAL）
```
- uses: depproof/depproof-action@v1
with:
fail-on: high
```
### 以非阻塞咨询模式使用 depproof
```
- uses: depproof/depproof-action@v1
with:
fail-on: none # never fails on findings (scan errors still exit 2); results still in artifacts
```
## 许可证
depproof 是专有软件，对于年收入低于 100 万美元的组织**免费**使用。大型组织需要商业许可（请联系 licensing@depproof.com）。请参阅 [LICENSE](LICENSE)。
## 隐私
depproof 仅会向以下公共服务发起外部网络请求：
- `repo.maven.apache.org` — Maven Central，用于传递依赖解析
- `api.osv.dev` — OSV.dev 漏洞数据库
- `api.clearlydefined.io` — ClearlyDefined.io 许可证元数据（当 SPDX 库不匹配时的后备选项）
无遥测。无数据回传。无 API key。
depproof 作为独立的 Docker 镜像（`ghcr.io/depproof/depproof`）运行——您的 runner 上无需安装本地 Java、Maven 或 Gradle。请参阅 [action.yml](./action.yml) 了解具体的调用方式。
📖 许可证详解、SBOM 及 SCA 指南，以及完整文档 → **[depproof.com](https://depproof.com)**
标签：DevSecOps, SBOM, Syscall 审计, 上游代理, 依赖审计, 后台面板检测, 开源合规, 暗色界面, 硬件无关, 请求拦截