OWASP dep-scan 是一个基于已知漏洞、安全公告和项目依赖的许可证限制的下一代安全与风险审计工具。支持本地仓库和容器镜像作为输入，该工具非常适合集成到ASPM/VM平台和CI环境中。
基于完整上下文，详细的数据流可识别应用程序中可达和不可达路径。
dep-scan 通过四个切片器为七种语言生态系统计算可达性。如果一个易受攻击的软件包的代码实际位于执行路径上，则标记为可达，而仅在 BOM 中声明但从未调用的软件包则不是可达。每个切片器都向同一个共享的、以 purl 为键的可达性引擎提供数据，因此行为在不同语言间是一致的。默认情况下可达性处于开启状态（--reachability-analyzer FrameworkReachability）；SemanticReachability 另外会归因于可达的服务、端点以及构建后（二进制/容器）可达性。
关于可达性和优先级排序背后的概念，请阅读可达性模型和优先级排序章节。每种语言的实际示例请参见语言指南。关于合规性（VDR 和 CSAF VEX），请参见VDR 指南和CSAF VEX 指南。
在 --profile research 下，默认启用可达性，这也是 dep-scan 在开启可达性时使用的配置。以下命令足以开始；每种语言指南涵盖了二进制解析、后端和网络安全、恢复要求以及仓库内 fixture 的实际示例。
Rust (rusi). cdxgen 运行 rusi 并持久化其报告，dep-scan 将其转换为共享管道，因此实际上被调用的 crate（例如 time::now() 用于 RUSTSEC-2020-0071）会被标记为可达，而仅存在的则不会。请参见 Rust 可达性指南。```bash
depscan -i ./my-rust-app -o ./reports --profile research
**Go (golem).** dep-scan 直接调用 [golem](https://github.com/cdxgen/cdxgen-plugins-bin) 用于 Go 项目（需要在 `PATH` 中有 `go`），当模块的函数位于追踪路径上时，将其标记为 Reachable。对于具有预热模块缓存的非可信仓库，使用 `--go-analyzer-network offline`。参见 [Go 可达性指南](https://depscan.readthedocs.io/languages/go-reachability)。```bash
depscan -i ./my-go-app -o ./reports -t go
.NET (dosai). cdxgen 运行 dosai，它会为每个包生成明确的可达性判定（PackageReachability 包含 ReachabilityKind 和 Confidence），dep-scan 将其视为权威结果，因此一个实际调用的 NuGet 包（例如，对受控输入调用 JsonConvert.DeserializeObject）即可达。扫描已还原的依赖树以获取带版本号的 purls。请参阅 .NET 可达性指南。```bash
depscan -i ./my-dotnet-app -o ./reports -t dotnet
**JVM、JavaScript/TypeScript、Python 和 PHP（atom）。** 这四种生态系统共享 [atom](https://github.com/AppThreat/atom) 切片器，它构建了一种语言无关的中间表示并执行静态切片。请参阅 [JVM、JS、Python 和 PHP 可达性指南](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability)。```bash
depscan --profile research -t java -i ./my-java-app -o ./reports --explain
要从框架前向可达性扩展到端点、服务及构建后层级，请传递--reachability-analyzer SemanticReachability，并搭配包含生命周期BOM的--bom-dir参数。详见语义可达性指南。
无需阅读描述即可清晰理解CVE信息。
仅关注那些需要你处理的CVE。
通过先进的漏洞与利用预测，始终领先一步。
dep-scan非常适合在持续集成（CI）流程中使用，也可作为本地开发工具。
sudo npm install -g @cyclonedx/cdxgen
pip install owasp-depscan
pip install owasp-depscan[all]
这将会安装两个命令：`cdxgen` 和 `depscan`。
你可以直接使用各种选项调用扫描命令。```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports
完整选项列表如下：```text usage: depscan [-h] [--config CONFIG] [--no-banner] [-i SRC_DIR_IMAGE] [-o REPORTS_DIR] [--csaf] [--profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny}] [--lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...]] [--technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...]] [--bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} | --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer}] [--reachability-analyzer {off,FrameworkReachability,SemanticReachability}] [--no-suggest] [--risk-audit] [--cdxgen-args CDXGEN_ARGS] [--private-ns PRIVATE_NS] [-t PROJECT_TYPE [PROJECT_TYPE ...]] [--bom BOM | --bom-dir BOM_DIR | --purl SEARCH_PURL] [--report-template REPORT_TEMPLATE] [--report-name REPORT_NAME] [--deep] [--fuzzy-search] [--search-order {purl,pcu,cpe,cpu,url}] [--no-universal] [--no-vuln-table] [--server] [--server-host SERVER_HOST] [--server-port SERVER_PORT] [--cdxgen-server CDXGEN_SERVER] [--debug] [-q | --explain] [-v]
Fully open-source security and license audit for application dependencies and container images based on known vulnerabilities and advisories.
options: -h, --help show this help message and exit --config CONFIG Path to the configuration file. Default: $PWD/.config/depscan.toml --no-banner Do not display the logo and donation banner. Please make a donation to OWASP before using this argument. -i, --src SRC_DIR_IMAGE Source directory or container image or binary file -o, --reports-dir REPORTS_DIR Reports directory --csaf Generate a OASIS CSAF VEX document --profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny} Profile to use while generating the BOM. For granular control, use the arguments --bom-engine, --vulnerability-analyzer, or --reachability-analyzer. --lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...] Product lifecycle for the generated BOM. Multiple values allowed. --technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...] Analysis technique to use for BOM generation. Multiple values allowed. --bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} BOM generation engine to use. Defaults to automatic selection based on project type and lifecycle. --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer} Vulnerability analyzer to use. Defaults to automatic selection based on bom_dir argument. --reachability-analyzer {off,FrameworkReachability,SemanticReachability} Reachability analyzer to use. Default FrameworkReachability. --no-suggest Disable suggest mode --risk-audit Perform package risk audit (slow operation). Npm only. --cdxgen-args CDXGEN_ARGS Additional arguments to pass to cdxgen --private-ns PRIVATE_NS Private namespace to use while performing oss risk audit. Private packages should not be available in public registries by default. Comma separated values accepted. -t, --type PROJECT_TYPE [PROJECT_TYPE ...] Override project types if auto-detection is incorrect. Multiple values supported. --bom BOM Examine using the given Software Bill-of-Materials (SBOM) file in CycloneDX format. Use cdxgen command to produce one. --bom-dir BOM_DIR Examine all the Bill-of-Materials (BOM) files in the given directory. --purl SEARCH_PURL Scan a single package url. --custom-data CUSTOM_DATA Path to directory containing custom vulnerability data (JSON/YAML/TOML) to override/augment results. --report-template REPORT_TEMPLATE Jinja template file used for rendering a custom report --report-name REPORT_NAME Filename of the custom report written to the --reports-dir --deep Perform deep scan by passing this --deep argument to cdxgen. Useful while scanning docker images and OS packages. --fuzzy-search Perform fuzzy search by creating variations of package names. Use this when the input SBOM lacks a PURL. --search-order {purl,pcu,cpe,cpu,url} Attributes to use while searching for vulnerabilities. Default: PURL, CPE, URL (pcu). --no-universal Depscan would attempt to perform a single universal scan instead of individual scans per language type. --no-vuln-table Do not print the table with the full list of vulnerabilities. This can help reduce console output. --server Run depscan as a server --server-host SERVER_HOST depscan server host --server-port SERVER_PORT depscan server port --server-allowed-hosts [SERVER_ALLOWED_HOSTS ...] List of allowed hostnames or IPs that can access the server (e.g., 'localhost 192.168.1.10'). If unspecified, no host allowlist is enforced. --server-allowed-paths [SERVER_ALLOWED_PATHS ...] List of allowed filesystem paths that can be scanned by the server. Restricts parameter in /scan requests. --cdxgen-server CDXGEN_SERVER cdxgen server url. Eg: --debug Run depscan in debug mode. -q, --quiet Makes depscan quiet. --explain Makes depscan to explain the various analysis. Useful for creating detailed reports. --explanation-mode {Endpoints,EndpointsAndReachables,NonReachables,LLMPrompts} Style of explanation needed. Defaults to Endpoints and Reachables. --annotate Include the generated text VDR report as an annotation. Defaults to true when explain is enabled; false otherwise. -v, --version Display the version
### 独立二进制文件（无需 Python 或 Node.js）
预构建的单文件可执行文件附加到每个 [GitHub release](https://github.com/owasp-dep-scan/dep-scan/releases)。它们捆绑了匹配的 [cdxgen](https://github.com/cdxgen/cdxgen) SEA 二进制文件，因此 BOM 生成无需安装 Python、Node.js 或 cdxgen 即可开箱即用。
| 平台 | 架构 | 资源 |
| --------------------- | ----------------- | ------------------------------ |
| Linux (glibc) | x86_64 | `depscan-linux-amd64` |
| Linux (glibc) | arm64 | `depscan-linux-arm64` |
| Linux (musl / Alpine) | x86_64 | `depscan-linux-amd64-musl` |
| Linux (musl / Alpine) | arm64 | `depscan-linux-arm64-musl` |
| macOS | Apple silicon | `depscan-darwin-arm64` |
| macOS | Intel | `depscan-darwin-amd64` |
| Windows | x86_64 | `depscan-windows-amd64.exe` |
每个资源都有一个匹配的 `.sha256` 文件用于验证。```bash
# Example: Linux x86_64
curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64
curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64.sha256
sha256sum -c depscan-linux-amd64.sha256
chmod +x depscan-linux-amd64
./depscan-linux-amd64 --src $PWD --reports-dir $PWD/reports
[!NOTE] macOS 二进制文件目前未签名。首次运行时，macOS Gatekeeper 可能会阻止它们；使用
xattr -d com.apple.quarantine ./depscan-darwin-arm64清除隔离属性（或者在系统设置、隐私与安全性中允许该二进制文件）。
[!NOTE] 漏洞数据库仍在首次运行时下载。仅捆绑了 cdxgen，未捆绑漏洞数据库。使用
depscan-vdb命令选择特定的数据库变体，例如depscan-vdb download --scope app获取较小的仅应用数据库。有关完整镜像矩阵，请参阅漏洞数据库指南。
所有独立二进制文件都捆绑了 blint，但不包含其可选的 nyxstone 反汇编后端（该后端没有 wheel 包，也不支持 Windows）。因此，独立二进制文件中无法进行基于深度反汇编的二进制分析；如果需要此功能，请使用 Python 包（pip install owasp-depscan[all]）。
扫描一个 Java 项目。```bash depscan --src -o containertests -t java
扫描容器 `shiftleft/scan-slim` 的 `latest` 标签```bash
depscan --src shiftleft/scan-slim -o containertests -t docker
Include license to the type to perform the license audit.```bash
depscan --src shiftleft/scan-slim -o containertests -t docker license
你也可以使用sha256摘要来指定镜像```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker
你也可以使用docker或podman save命令保存容器镜像，并将归档文件传递给depscan进行扫描。```bash docker save -o /tmp/scanslim.tar shiftleft/scan-slim:latest
depscan --src /tmp/scanslim.tar -o reports -t docker
有关更多示例，请参阅此仓库的 GitHub Actions 工作流下的 Docker 测试。
### 在本地扫描项目（Docker 容器）
可以使用 `ghcr.io/owasp-dep-scan/dep-scan` 容器镜像来执行扫描。
要使用默认设置进行扫描```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports
基于自定义环境变量的配置进行扫描```bash
docker run --rm
-e VDB_HOME=/db
-e GITHUB_TOKEN=
-v /tmp:/db
-v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports
在上面的示例中，`/tmp` 作为 `/db` 挂载到容器中。然后该目录被指定为 `VDB_HOME`，用于缓存漏洞信息。这样，数据库可以被缓存并重用，从而提高性能。
### 服务器模式
dep-scan 和 cdxgen 可以在服务器模式下运行。使用附带的 docker-compose 文件开始。```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up
捆绑的 compose 文件默认将 DEPSCAN_SERVER_API_KEY 设置为开发占位符，以便 dep-scan 服务可以绑定到 0.0.0.0。在将服务暴露到本地实验室之外之前，请覆盖此值。```bash
depscan --server --server-host 127.0.0.1 --server-port 7070
如果你需要将 dep-scan 绑定到非本地地址，请先设置一个 API 密钥：```bash
export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server --server-host 0.0.0.0 --server-port 7070
[!IMPORTANT] dep-scan 拒绝绑定到非本地地址，除非设置了
DEPSCAN_SERVER_API_KEY或通过DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true明确选择退出。
使用 /scan 端点执行扫描。
[!NOTE] 在服务器模式下，
type参数是必需的。当启用 API 密钥认证时，使用X-API-Key或Authorization: Bearer <key>发送密钥。
- 扫描 GitHub 仓库。```bash
curl \
-H 'Authorization: Bearer dev-only-change-me' \
--json '{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}' \
http://127.0.0.1:7070/scan \
-o app.vdr.json
## 本地开发
按照官方 [文档](https://docs.astral.sh/uv/) 设置 uv。```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest
vdb --clean vdb --download-image
### 扫描本地 depscan```shell
uv run depscan --config .config/depscan-dev.toml
这将自动使用本地配置文件 file 中指定的配置。
完整文档位于 depscan.readthedocs.io。关键页面：
MIT 许可证
本项目由 AppThreat Ltd. 于 2023 年 8 月捐赠给 OWASP 基金会。
本项目通过 NGI Zero Core 资助，该基金由 NLnet 设立，并得到欧盟委员会 下一代互联网 计划的财政支持。更多信息请访问 NLnet 项目页面。
| 语言/生态系统 | 可达性引擎 | 默认分析器 |
|---|
| Java / JVM (Groovy, Kotlin, Scala) | atom | FrameworkReachability |
| JavaScript / TypeScript | atom | FrameworkReachability |
| Python | atom | FrameworkReachability |
| PHP | atom | FrameworkReachability |
| Rust | rusi | FrameworkReachability |
| Go | golem | FrameworkReachability |
| .NET (C#, VB, F#, R) | dosai | FrameworkReachability |
path