Introdução

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.

Conteúdo

• Recursos
  • Fluxos de dados alcançáveis precisos
  • Matriz de alcançabilidade
  • Alcançabilidade Rust (via rusi)
  • Alcançabilidade Go (via golem)
  • Alcançabilidade .NET (via dosai)
  • Alcançabilidade JVM, JavaScript, Python e PHP (via atom)
  • Fontes de dados de vulnerabilidade
  • Distribuições Linux
• Início Rápido
  • Escaneando projetos localmente (versão Python)
  • Binários independentes (sem necessidade de Python ou Node.js)
  • Escaneando contêineres localmente (versão Python)
  • Escaneando projetos localmente (contêiner Docker)
  • Modo servidor
• Desenvolvimento local
• Documentação (depscan.readthedocs.io)
• Licença

Recursos

• Escaneie a maioria dos códigos de aplicativos (repos locais, imagens de contêineres Linux, manifestos Kubernetes e SO) para identificar CVEs conhecidas com priorização
• Realize análise avançada de alcançabilidade para múltiplas linguagens (veja a matriz de alcançabilidade abaixo)
• A verificação de vulnerabilidades de pacotes é realizada localmente e é bastante rápida. Nenhum servidor é utilizado
• Gere um Software Bill-of-Materials (SBOM) com informações de Relatório de Divulgação de Vulnerabilidades (VDR)
• Gere um documento VEX Common Security Advisory Framework (CSAF) 2.0/2.1 (confira o Readme do CSAF)
• Realize uma auditoria profunda de risco de pacotes para ataques de confusão de dependência e riscos de manutenção (veja a documentação de auditoria de risco)

Fluxos de dados alcançáveis precisos

Fluxos de dados detalhados para identificar tanto caminhos alcançáveis quanto não alcançáveis em sua aplicação com base no contexto completo.

Matriz de alcançabilidade

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.

Informações claras sobre CVEs

Entenda as CVEs claramente sem ter que ler a descrição.

Priorização automática

Concentre-se apenas nas CVEs que precisam da sua atenção.

Mantenha-se proativo

Esteja sempre um passo à frente com previsão avançada de vulnerabilidades e explorações.

Fontes de dados de vulnerabilidade

• OSV
• NVD
• GitHub
• NPM
• Linux vuln-list

Distribuições Linux

• AlmaLinux
• Debian
• Alpine
• Amazon Linux
• Arch Linux
• RHEL/CentOS
• Rocky Linux
• Ubuntu
• OpenSUSE/SLES
• Photon
• Chainguard
• Wolfi OS

Início Rápido

O dep-scan é ideal para uso durante integração contínua (CI) e como ferramenta de desenvolvimento local.

Escaneando projetos localmente (versão Python)```bash

sudo npm install -g @cyclonedx/cdxgen

Normal version recommended for most users (MIT)

pip install owasp-depscan

For a full version with all extensions and server mode (Multiple Licenses)

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 path parameter in /scan requests. --cdxgen-server CDXGEN_SERVER cdxgen server url. Eg: http://cdxgen:9090 --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-vdb para selecionar uma variante específica do banco de dados, por exemplo depscan-vdb download --scope app para 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.

Escaneando contêineres localmente (versão Python)

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

podman save --format oci-archive -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_KEY ou uma aceitação explícita através de DEPSCAN_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 usando X-API-Key ou Authorization: Bearer <key>.

• Varrendo um diretório local. Varrendo um arquivo SBOM (presente localmente).```bash curl
  -H 'X-API-Key: dev-only-change-me'
  --json '{"path": "/tmp/vulnerable-aws-koa-app/sbom_file.json", "type": "js"}'
  http://127.0.0.1:7070/scan

- 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

• Carregar um arquivo SBOM e gerar resultados com base nele.```bash curl -X POST
  -H 'X-API-Key: dev-only-change-me'
  -H 'Content-Type: multipart/form-data'
  -F 'file=@/tmp/app/sbom_file.json'
  http://127.0.0.1:7070/scan?type=js

## 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

Configuração local da VDB```shell

vdb --clean vdb --download-image

To scan containers and OS images

vdb --download-full-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

Documentação completa em depscan.readthedocs.io. Páginas principais:

• Linguagens suportadas e matriz de alcançabilidade
• Análise de alcançabilidade (hub)
  • O modelo de alcançabilidade
  • Como o dep-scan prioriza
  • SBOM e evidências
  • Guias de linguagem: Rust, Go, .NET, JVM/JS/Python/PHP
  • Analisadores: Alcançabilidade de framework, Alcançabilidade semântica
• Saída e conformidade: Guia VDR, Guia CSAF VEX
• Personalização através de variáveis de ambiente
• Uso avançado: GitHub Security Advisory, Modo sugerir, Auditoria de risco de pacote, Escaneamento de SO ao vivo, Escaneamento de licença, Relatórios personalizados

Licença

MIT License

Este projeto foi doado à OWASP Foundation em agosto de 2023 pela AppThreat Ltd.

Financiamento

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.