owasp-dep-scan/dep-scanScanner de vulnerabilidades de dependências de próxima geração com análise de alcançabilidade, geração de SBOM, auditoria de licenças e varredura de imagens de contêiner para integração CI/CD.
O OWASP dep-scan é uma ferramenta de auditoria de segurança e risco de última geração baseada em vulnerabilidades conhecidas, avisos e limitações de licença para dependências de projetos. Tanto repositórios locais quanto imagens de contêineres são suportados como entrada, e a ferramenta é ideal para integração com plataformas ASPM/VM e em ambientes CI.
Fluxos de dados detalhados para identificar tanto caminhos alcançáveis quanto não alcançáveis em sua aplicação com base no contexto completo.
O dep-scan calcula a alcançabilidade para sete ecossistemas de linguagem por meio de quatro slicers. Um pacote vulnerável cujo código está realmente em um caminho executado é marcado como Alcançável, enquanto um pacote que é meramente declarado no BOM mas nunca chamado não é. Cada slicer alimenta o mesmo mecanismo de alcançabilidade compartilhado baseado em purl, de modo que o comportamento é uniforme entre as linguagens. A alcançabilidade está ativada por padrão (--reachability-analyzer FrameworkReachability); o SemanticReachability adicionalmente atribui serviços, endpoints e alcançabilidade pós-build (binário/contêiner) alcançados.
Para os conceitos por trás da alcançabilidade e priorização, leia os capítulos modelo de alcançabilidade e priorização. Para exemplos práticos por linguagem, veja os Guias de Linguagem. Para a história de conformidade (VDR e CSAF VEX), veja o guia VDR e o guia CSAF VEX.
A alcançabilidade está ativada por padrão sob --profile research, que é o que o dep-scan usa quando a alcançabilidade está ativa. Os comandos abaixo são suficientes para começar; os guias por linguagem cobrem resolução binária, segurança de backend e rede, requisitos de restauração e exemplos práticos nos fixtures do repositório.
Rust (rusi). O cdxgen executa rusi e persiste seu relatório, que o dep-scan converte no pipeline compartilhado, de modo que uma crate que é realmente chamada (por exemplo time::now() para RUSTSEC-2020-0071) é Alcançável, enquanto uma meramente presente não é. Veja o guia de alcançabilidade Rust.```bash
depscan -i ./my-rust-app -o ./reports --profile research
**Go (golem).** o dep-scan invoca o [golem](https://github.com/cdxgen/cdxgen-plugins-bin) diretamente para projetos Go (precisa de `go` no `PATH`), marcando um módulo como Reachable quando suas funções estão em um caminho rastreado. Use `--go-analyzer-network offline` para repositórios não confiáveis com um cache de módulo aquecido. Consulte o [Guia de alcançabilidade do Go](https://depscan.readthedocs.io/languages/go-reachability).```bash
depscan -i ./my-go-app -o ./reports -t go
.NET (dosai). cdxgen executa o dosai, que emite um veredito explícito de alcançabilidade por pacote (PackageReachability com ReachabilityKind e Confidence) que o dep-scan trata como autoritativo, portanto, um pacote NuGet que realmente chama (por exemplo JsonConvert.DeserializeObject em uma entrada controlada) é Alcançável. Digitalize uma árvore restaurada em busca de purls versionados. Consulte o guia de alcançabilidade .NET.```bash
depscan -i ./my-dotnet-app -o ./reports -t dotnet
**JVM, JavaScript/TypeScript, Python e PHP (atom).** Esses quatro ecossistemas compartilham o fatiador [atom](https://github.com/AppThreat/atom), que constrói uma representação intermediária independente de linguagem e realiza fatiamento estático. Consulte o [guia de alcançabilidade para JVM, JS, Python e PHP](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability).```bash
depscan --profile research -t java -i ./my-java-app -o ./reports --explain
Para ir além da acessibilidade focada em frameworks para os níveis de endpoint, serviço e pós-build, passe --reachability-analyzer SemanticReachability com um --bom-dir dos BOMs do ciclo de vida. Consulte o guia de acessibilidade semântica.
Entenda as CVEs claramente sem ter que ler a descrição.
Concentre-se apenas nas CVEs que precisam da sua atenção.
Esteja sempre um passo à frente com previsão avançada de vulnerabilidades e explorações.
O dep-scan é ideal para uso durante integração contínua (CI) e como ferramenta de desenvolvimento local.
sudo npm install -g @cyclonedx/cdxgen
pip install owasp-depscan
pip install owasp-depscan[all]
Isso instalaria dois comandos chamados `cdxgen` e `depscan`.
Você pode invocar o comando de scan diretamente com as várias opções.```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports
A lista completa de opções está abaixo:```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
### Binários autônomos (sem Python ou Node.js necessários)
Binários pré-construídos de arquivo único estão anexados a cada [lançamento do GitHub](https://github.com/owasp-dep-scan/dep-scan/releases). Eles incluem um binário SEA correspondente do [cdxgen](https://github.com/cdxgen/cdxgen), então a geração de BOM funciona imediatamente sem instalar Python, Node.js ou cdxgen.
| Plataforma | Arquitetura | Artefato |
| --------------------- | --------------- | --------------------------- |
| 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` |
Cada artefato possui um arquivo `.sha256` correspondente para verificação.```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] Os binários do macOS atualmente não estão assinados. Na primeira execução, o Gatekeeper do macOS pode bloqueá-los; remova o atributo de quarentena com
xattr -d com.apple.quarantine ./depscan-darwin-arm64(ou permita o binário em System Settings, Privacy & Security).
[!NOTE] O banco de dados de vulnerabilidades ainda é baixado na primeira execução. Apenas o cdxgen está incluído, não o banco de dados de vulnerabilidades. Use o comando
depscan-vdbpara selecionar uma variante específica do banco de dados, por exemplodepscan-vdb download --scope apppara um banco de dados menor apenas de aplicações. Consulte o guia do banco de dados de vulnerabilidades para ver a matriz completa de imagens.
Todos os binários independentes incluem o blint, mas não seu backend opcional de desmontagem nyxstone (que não tem wheels e não tem suporte para Windows). A análise binária baseada em desmontagem profunda não está disponível nos binários independentes; use o pacote Python (pip install owasp-depscan[all]) se precisar.
Escaneie um projeto Java.```bash depscan --src -o containertests -t java
Digitalizar a tag `latest` do contêiner `shiftleft/scan-slim````bash
depscan --src shiftleft/scan-slim -o containertests -t docker
Inclua license ao tipo para realizar a auditoria de licença.```bash
depscan --src shiftleft/scan-slim -o containertests -t docker license
Você também pode especificar a imagem usando o digest sha256```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker
Você também pode salvar imagens de contêiner usando o comando docker ou podman save e passar o arquivo para o depscan para digitalização.```bash docker save -o /tmp/scanslim.tar shiftleft/scan-slim:latest
depscan --src /tmp/scanslim.tar -o reports -t docker
Consulte os testes Docker no fluxo de trabalho da ação do GitHub para este repositório para mais exemplos.
### Escaneando projetos localmente (contêiner Docker)
`ghcr.io/owasp-dep-scan/dep-scan` a imagem do contêiner pode ser usada para realizar a verificação.
Para escanear com as configurações padrão```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports
Para escanear com configuração baseada em variáveis de ambiente personalizadas```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
No exemplo acima, `/tmp` é montado como `/db` dentro do contêiner. Este diretório é então especificado como `VDB_HOME` para armazenar em cache as informações de vulnerabilidade. Desta forma, o banco de dados pode ser armazenado em cache e reutilizado para melhorar o desempenho.
### Modo servidor
dep-scan e cdxgen podem ser executados em modo servidor. Use o arquivo docker-compose incluído para começar.```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up
The bundled compose file sets DEPSCAN_SERVER_API_KEY to a development placeholder by default so the dep-scan service can bind to 0.0.0.0. Override this value before exposing the service outside a local lab.```bash
depscan --server --server-host 127.0.0.1 --server-port 7070
Se você precisar vincular o dep-scan a um endereço não local, defina uma API key primeiro:```bash
export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server --server-host 0.0.0.0 --server-port 7070
[!IMPORTANT] dep-scan recusa-se a vincular a um endereço não local sem
DEPSCAN_SERVER_API_KEYou uma aceitação explícita através deDEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true.
[!NOTE] O parâmetro
typeé obrigatório no modo servidor. Quando a autenticação por chave de API está ativada, envie a chave usandoX-API-KeyouAuthorization: Bearer <key>.
- Digitalizando um repositório do 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
## Desenvolvimento local
Configure o uv seguindo a [documentação](https://docs.astral.sh/uv/) oficial.```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest
vdb --clean vdb --download-image
### Escaneamento local depscan```shell
uv run depscan --config .config/depscan-dev.toml
Isso usaria automaticamente a configuração especificada no arquivo de config local arquivo.
Documentação completa em depscan.readthedocs.io. Páginas principais:
MIT License
Este projeto foi doado à OWASP Foundation em agosto de 2023 pela AppThreat Ltd.
Este projeto é financiado pelo NGI Zero Core, um fundo estabelecido pela NLnet com suporte financeiro do programa Next Generation Internet da Comissão Europeia. Saiba mais na página do projeto NLnet.
| Linguagem / ecossistema | Mecanismo de alcançabilidade | Analisador padrão |
|---|
| 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