Introduzione

OWASP dep-scan è uno strumento di audit di sicurezza e rischio di nuova generazione basato su vulnerabilità note, avvisi e limitazioni di licenza per le dipendenze dei progetti. Supporta repository locali e immagini container come input ed è ideale per l'integrazione con piattaforme ASPM/VM e in ambienti CI.

Contenuti

• Caratteristiche
  • Flussi di dati precisi raggiungibili
  • Matrice di raggiungibilità
  • Reachability Rust (tramite rusi)
  • Reachability Go (tramite golem)
  • Reachability .NET (tramite dosai)
  • Reachability JVM, JavaScript, Python e PHP (tramite atom)
  • Fonti dati sulle vulnerabilità
  • Distribuzioni Linux
• Avvio rapido
  • Scansione di progetti in locale (versione Python)
  • Binari autonomi (non richiede Python o Node.js)
  • Scansione di container in locale (versione Python)
  • Scansione di progetti in locale (contenitore Docker)
  • Modalità server
• Sviluppo locale
• Documentazione (depscan.readthedocs.io)
• Licenza

Caratteristiche

• Scansiona la maggior parte del codice applicativo (repo locali, immagini container Linux, manifest Kubernetes e sistema operativo) per identificare CVE note con priorità
• Esegue un'analisi avanzata di raggiungibilità per più linguaggi (vedi la matrice di raggiungibilità sotto)
• La scansione delle vulnerabilità dei pacchetti viene eseguita localmente ed è piuttosto veloce. Non viene utilizzato alcun server
• Genera un Software Bill-of-Materials (SBOM) con informazioni nel Vulnerability Disclosure Report (VDR)
• Genera un documento VEX (Common Security Advisory Framework) CSAF 2.0/2.1 (vedi il Readme CSAF)
• Esegue un audit approfondito del rischio dei pacchetti per attacchi di confusione delle dipendenze e rischi di manutenzione (vedi la documentazione sull'audit del rischio)

Flussi di dati precisi raggiungibili

Flussi di dati dettagliati per identificare percorsi sia raggiungibili che non raggiungibili nella tua applicazione basati sul contesto completo.

Matrice di raggiungibilità

dep-scan calcola la raggiungibilità per sette ecosistemi linguistici attraverso quattro slicer. Un pacchetto vulnerabile il cui codice è effettivamente su un percorso eseguito viene contrassegnato come Raggiungibile, mentre un pacchetto solo dichiarato nel BOM ma mai chiamato non lo è. Ogni slicer alimenta lo stesso motore di raggiungibilità condiviso basato su chiave purl, quindi il comportamento è uniforme tra i linguaggi. La raggiungibilità è attiva per impostazione predefinita (--reachability-analyzer FrameworkReachability); SemanticReachability attribuisce inoltre servizi, endpoint e raggiungibilità post-build (binary/container) raggiunti.

Per i concetti alla base della raggiungibilità e della priorità, leggi i capitoli modello di raggiungibilità e priorità. Per esempi pratici per linguaggio, vedi le Guide per linguaggio. Per la conformità (VDR e CSAF VEX), vedi la guida VDR e la guida CSAF VEX.

La raggiungibilità è attiva per impostazione predefinita con --profile research, che è ciò che dep-scan utilizza quando la raggiungibilità è attiva. I comandi seguenti sono sufficienti per iniziare; le guide per linguaggio coprono la risoluzione binaria, la sicurezza del backend e della rete, i requisiti di ripristino e gli esempi pratici sui fixture all'interno del repository.

Rust (rusi). cdxgen esegue rusi e persiste il suo report, che dep-scan converte nella pipeline condivisa, quindi una crate effettivamente chiamata (ad esempio time::now() per RUSTSEC-2020-0071) è Raggiungibile mentre una solo presente non lo è. Vedi la guida alla raggiungibilità Rust.```bash depscan -i ./my-rust-app -o ./reports --profile research

**Go (golem).** dep-scan invoca [golem](https://github.com/cdxgen/cdxgen-plugins-bin) direttamente per i progetti Go (necessita `go` in `PATH`), contrassegnando un modulo come Raggiungibile quando le sue funzioni si trovano su un percorso tracciato. Usa `--go-analyzer-network offline` per repository non fidati con una cache dei moduli calda. Vedi la [guida sulla raggiungibilità di Go](https://depscan.readthedocs.io/languages/go-reachability).```bash
depscan -i ./my-go-app -o ./reports -t go

.NET (dosai). cdxgen esegue dosai, che emette un verdetto esplicito di raggiungibilità per pacchetto (PackageReachability con ReachabilityKind e Confidence) che dep-scan considera autorevole, quindi un pacchetto NuGet effettivamente chiamato (ad esempio JsonConvert.DeserializeObject su un input controllato) è Reachable. Scansiona un albero ripristinato per purl versionati. Vedi la guida sulla raggiungibilità .NET.```bash depscan -i ./my-dotnet-app -o ./reports -t dotnet

**JVM, JavaScript/TypeScript, Python e PHP (atom).** Questi quattro ecosistemi condividono lo slicer [atom](https://github.com/AppThreat/atom), che costruisce una rappresentazione intermedia agnostica rispetto al linguaggio ed esegue lo slicing statico. Vedi la [guida alla raggiungibilità per 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

Per andare oltre la raggiungibilità in avanti del framework verso gli endpoint, i servizi e i livelli post-build, passa --reachability-analyzer SemanticReachability con un --bom-dir dei BOM del ciclo di vita. Vedi la guida alla raggiungibilità semantica.

Informazioni chiare sulle CVE

Comprendi le CVE chiaramente senza dover leggere la descrizione.

Prioritizzazione automatica

Concentrati solo sulle CVE che richiedono la tua attenzione.

Resta proattivo

Rimani sempre un passo avanti con la previsione avanzata di vulnerabilità e exploit.

Fonti dei dati sulle vulnerabilità

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

Distribuzioni Linux

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

Avvio rapido

dep-scan è ideale per l'uso durante l'integrazione continua (CI) e come strumento di sviluppo locale.

Scansione di progetti localmente (versione 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]

Questo installerà due comandi chiamati `cdxgen` e `depscan`. Puoi invocare il comando di scansione direttamente con le varie opzioni.```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports

L'elenco completo delle opzioni è di seguito:```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

### Binari autonomi (nessun requisito di Python o Node.js)

Eseguibili precompilati in un unico file sono allegati a ogni [rilascio GitHub](https://github.com/owasp-dep-scan/dep-scan/releases). Includono un binario SEA [cdxgen](https://github.com/cdxgen/cdxgen) corrispondente, quindi la generazione del BOM funziona immediatamente senza dover installare Python, Node.js o cdxgen.

| Platform              | Architecture  | Asset                       |
| --------------------- | ------------- | --------------------------- |
| 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` |

Ogni asset ha un corrispondente file `.sha256` per verifica.```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] I binari macOS attualmente non sono firmati. Al primo avvio, Gatekeeper di macOS potrebbe bloccarli; rimuovi l'attributo di quarantena con xattr -d com.apple.quarantine ./depscan-darwin-arm64 (o consenti il binario in Impostazioni di Sistema, Privacy e Sicurezza).

[!NOTE] Il database delle vulnerabilità viene ancora scaricato al primo avvio. Solo cdxgen è incluso, non il database delle vulnerabilità. Usa il comando depscan-vdb per selezionare una variante specifica del database, ad esempio depscan-vdb download --scope app per un database più piccolo limitato alle applicazioni. Consulta la guida al database delle vulnerabilità per la matrice completa delle immagini.

Tutti i binari standalone includono blint, ma non il backend di disassemblaggio opzionale nyxstone (che non ha wheel e non supporta Windows). L'analisi binaria basata su disassemblaggio approfondito non è quindi disponibile nei binari standalone; utilizza il pacchetto Python (pip install owasp-depscan[all]) se ne hai bisogno.

Scansione dei contenitori localmente (versione Python)

Esegui la scansione di un progetto Java.```bash depscan --src -o containertests -t java

Scansiona il tag `latest` del contenitore `shiftleft/scan-slim````bash
depscan --src shiftleft/scan-slim -o containertests -t docker

Includi license al type per eseguire il controllo delle licenze.```bash depscan --src shiftleft/scan-slim -o containertests -t docker license

Puoi anche specificare l'immagine usando il digest sha256```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker

Puoi anche salvare le immagini dei container utilizzando il comando docker o podman save e passare l'archivio a depscan per la scansione.```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

Fai riferimento ai test docker nel workflow di GitHub Action di questo repository per ulteriori esempi.

### Scansione di progetti in locale (contenitore Docker)

L'immagine del contenitore `ghcr.io/owasp-dep-scan/dep-scan` può essere utilizzata per eseguire la scansione.

Per eseguire la scansione con le impostazioni predefinite```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

Per eseguire la scansione con una configurazione basata su variabili d'ambiente personalizzate```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

Nell'esempio sopra, `/tmp` è montato come `/db` nel container. Questa directory viene poi specificata come `VDB_HOME` per la memorizzazione nella cache delle informazioni sulle vulnerabilità. In questo modo, il database può essere memorizzato nella cache e riutilizzato per migliorare le prestazioni.

### Modalità server

dep-scan e cdxgen possono essere eseguiti in modalità server. Utilizza il file docker-compose incluso per iniziare.```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up

Il file compose incluso imposta DEPSCAN_SERVER_API_KEY su un segnaposto di sviluppo per impostazione predefinita, in modo che il servizio dep-scan possa associarsi a 0.0.0.0. Sovrascrivi questo valore prima di esporre il servizio al di fuori di un laboratorio locale.```bash depscan --server --server-host 127.0.0.1 --server-port 7070

Se hai bisogno di associare dep-scan a un indirizzo non locale, imposta prima una chiave 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 rifiuta di associarsi a un indirizzo non locale senza DEPSCAN_SERVER_API_KEY o un'esplicita accettazione tramite DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true.

Usa l'endpoint /scan per eseguire scansioni.

[!NOTE] Il parametro type è obbligatorio in modalità server. Quando l'autenticazione tramite chiave API è abilitata, invia la chiave usando X-API-Key o Authorization: Bearer <key>.

• Scansione di una directory locale. Scansione di un file 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

- Scansione di un repository 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

• Caricare un file SBOM e generare risultati basati su di esso.```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

## Sviluppo locale

Configura uv seguendo la [documentazione](https://docs.astral.sh/uv/) ufficiale.```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest

Configurazione VDB locale```shell

vdb --clean vdb --download-image

To scan containers and OS images

vdb --download-full-image

### Scansiona local depscan```shell
uv run depscan --config .config/depscan-dev.toml

Ciò userebbe automaticamente la configurazione specificata nel file di configurazione locale.

Documentazione

La documentazione completa è su depscan.readthedocs.io. Pagine chiave:

• Linguaggi supportati e matrice di raggiungibilità
• Analisi della raggiungibilità (hub)
  • Il modello di raggiungibilità
  • Come dep-scan dà priorità
  • SBOM e prove
  • Guide per linguaggio: Rust, Go, .NET, JVM/JS/Python/PHP
  • Analizzatori: Raggiungibilità dei framework, Raggiungibilità semantica
• Output e conformità: Guida VDR, Guida CSAF VEX
• Personalizzazione tramite variabili d'ambiente
• Utilizzo avanzato: GitHub Security Advisory, Modalità Suggerisci, Audit del rischio dei pacchetti, Scansione live del sistema operativo, Scansione delle licenze, Report personalizzati

Licenza

Licenza MIT

Questo progetto è stato donato alla OWASP Foundation nell'agosto 2023 da AppThreat Ltd.

Finanziamenti

Questo progetto è finanziato tramite NGI Zero Core, un fondo istituito da NLnet con il supporto finanziario del programma Next Generation Internet della Commissione Europea. Per maggiori informazioni, visita la pagina del progetto NLnet.