Introduction

OWASP dep-scan est un outil de sécurité et d'audit de risque de nouvelle génération basé sur les vulnérabilités connues, les avis de sécurité et les limitations de licence pour les dépendances des projets. Les dépôts locaux et les images conteneurs sont pris en charge en tant qu'entrée, et l'outil est idéal pour l'intégration avec les plateformes ASPM/VM et dans les environnements CI.

Table des matières

• Fonctionnalités
  • Flux de données atteignables précis
  • Matrice d'atteignabilité
  • Atteignabilité Rust (via rusi)
  • Atteignabilité Go (via golem)
  • Atteignabilité .NET (via dosai)
  • Atteignabilité JVM, JavaScript, Python et PHP (via atom)
  • Sources de données de vulnérabilités
  • Distributions Linux
• Démarrage rapide
  • Analyse de projets localement (version Python)
  • Binaires autonomes (aucun Python ou Node.js requis)
  • Analyse de conteneurs localement (version Python)
  • Analyse de projets localement (conteneur Docker)
  • Mode serveur
• Développement local
• Documentation (depscan.readthedocs.io)
• Licence

Fonctionnalités

• Analyser la plupart des codes d'application (dépôts locaux, images conteneurs Linux, manifestes Kubernetes et OS) pour identifier les CVE connues avec priorisation
• Effectuer une analyse avancée d'atteignabilité pour plusieurs langages (voir la matrice d'atteignabilité ci-dessous)
• L'analyse des vulnérabilités des paquets est effectuée localement et est assez rapide. Aucun serveur n'est utilisé
• Générer un Bill-of-Materials logiciel (SBOM) avec des informations de rapport de divulgation de vulnérabilités (VDR)
• Générer un document VEX Common Security Advisory Framework (CSAF) 2.0/2.1 (consultez le CSAF Readme)
• Effectuer un audit de risque approfondi des paquets pour les attaques de confusion de dépendances et les risques de maintenance (voir la doc d'audit de risque)

Flux de données atteignables précis

Flux de données détaillés pour identifier les chemins atteignables et non atteignables dans votre application en fonction du contexte complet.

Matrice d'atteignabilité

dep-scan calcule l'atteignabilité pour sept écosystèmes de langages via quatre trancheurs. Un paquet vulnérable dont le code est effectivement sur un chemin d'exécution est marqué Atteignable, tandis qu'un paquet simplement déclaré dans la nomenclature mais jamais appelé ne l'est pas. Chaque trancheur alimente le même moteur d'atteignabilité partagé, indexé par purl, de sorte que le comportement est uniforme d'un langage à l'autre. L'atteignabilité est activée par défaut (--reachability-analyzer FrameworkReachability) ; SemanticReachability ajoute en plus l'attribution des services, points de terminaison et l'atteignabilité post-construction (binaire/conteneur).

Pour les concepts derrière l'atteignabilité et la priorisation, lisez les chapitres modèle d'atteignabilité et priorisation. Pour des exemples pratiques par langage, consultez les Guides linguistiques. Pour l'aspect conformité (VDR et CSAF VEX), voir le guide VDR et le guide CSAF VEX.

L'atteignabilité est activée par défaut sous --profile research, ce que dep-scan utilise lorsque l'atteignabilité est active. Les commandes ci-dessous suffisent pour commencer ; les guides par langage couvrent la résolution binaire, la sécurité des backends et réseaux, les exigences de restauration, et des exemples pratiques sur les fixtures du dépôt.

Rust (rusi). cdxgen exécute rusi et persiste son rapport, que dep-scan convertit en pipeline partagé, de sorte qu'une crate effectivement appelée (par exemple time::now() pour RUSTSEC-2020-0071) est Atteignable tandis qu'une crate simplement présente ne l'est pas. Voir le guide d'atteignabilité Rust.```bash depscan -i ./my-rust-app -o ./reports --profile research

**Go (golem).** dep-scan invoque directement [golem](https://github.com/cdxgen/cdxgen-plugins-bin) pour les projets Go (nécessite `go` dans le `PATH`), marquant un module comme Accessible lorsque ses fonctions se trouvent sur un chemin tracé. Utilisez `--go-analyzer-network offline` pour les dépôts non fiables avec un cache de modules chaud. Voir le [guide d'accessibilité Go](https://depscan.readthedocs.io/languages/go-reachability).```bash
depscan -i ./my-go-app -o ./reports -t go

.NET (dosai). cdxgen exécute dosai, qui émet un verdict explicite d'atteignabilité par paquet (PackageReachability avec ReachabilityKind et Confidence) que dep-scan considère comme faisant autorité, de sorte qu'un paquet NuGet réellement appelé (par exemple JsonConvert.DeserializeObject sur une entrée contrôlée) est Reachable. Scannez un arbre restauré pour des purls versionnés. Consultez le guide d'atteignabilité .NET.```bash depscan -i ./my-dotnet-app -o ./reports -t dotnet

**JVM, JavaScript/TypeScript, Python et PHP (atom).** Ces quatre écosystèmes partagent le slicer [atom](https://github.com/AppThreat/atom), qui construit une représentation intermédiaire indépendante du langage et effectue un slicing statique. Consultez le [guide d'atteignabilité pour JVM, JS, Python et PHP](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability).```bash
depscan --profile research -t java -i ./my-java-app -o ./reports --explain

Pour dépasser la reachabilité framework-forward vers les niveaux endpoint, service et post-build, passez --reachability-analyzer SemanticReachability avec un --bom-dir de BOMs de cycle de vie. Voir le guide de reachabilité sémantique.

Informations claires sur les CVEs

Comprenez les CVEs clairement sans avoir à lire la description.

Priorisation automatique

Concentrez-vous uniquement sur les CVEs qui nécessitent votre attention.

Restez proactif

Restez toujours une longueur d'avance grâce à la prédiction avancée des vulnérabilités et des exploits.

Sources de données de vulnérabilité

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

Distributions Linux

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

Démarrage rapide

dep-scan est idéal pour une utilisation lors de l'intégration continue (CI) et comme outil de développement local.

Analyse des projets localement (version 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]

Ceci installerait deux commandes appelées `cdxgen` et `depscan`.

Vous pouvez invoquer la commande de scan directement avec les différentes options.```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports

La liste complète des options est ci-dessous :```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

### Binaires autonomes (pas de Python ou Node.js requis)

Des exécutables préconstruits en un seul fichier sont joints à chaque [version GitHub](https://github.com/owasp-dep-scan/dep-scan/releases). Ils regroupent un binaire SEA [cdxgen](https://github.com/cdxgen/cdxgen) correspondant, de sorte que la génération de BOM fonctionne directement sans avoir à installer Python, Node.js ou cdxgen.

| Plateforme            | Architecture  | Fichier                      |
| --------------------- | ------------- | --------------------------- |
| 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` |

Chaque fichier possède un fichier `.sha256` correspondant pour vérification.```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] Les binaires macOS ne sont actuellement pas signés. Lors de la première exécution, macOS Gatekeeper peut les bloquer ; supprimez l'attribut de quarantaine avec xattr -d com.apple.quarantine ./depscan-darwin-arm64 (ou autorisez le binaire dans Réglages Système, Confidentialité et Sécurité).

[!NOTE] La base de données de vulnérabilités est toujours téléchargée lors de la première exécution. Seul cdxgen est inclus, pas la base de données de vulnérabilités. Utilisez la commande depscan-vdb pour sélectionner une variante de base de données spécifique, par exemple depscan-vdb download --scope app pour une base de données plus petite contenant uniquement les applications. Consultez le guide des bases de données de vulnérabilités pour la matrice complète des images.

Tous les binaires autonomes incluent blint, mais pas son backend de désassemblage optionnel nyxstone (qui n'a pas de wheels et ne supporte pas Windows). L'analyse binaire basée sur le désassemblage en profondeur n'est donc pas disponible dans les binaires autonomes ; utilisez le paquet Python (pip install owasp-depscan[all]) si vous en avez besoin.

Scanner des conteneurs localement (version Python)

Scannez un projet Java.```bash depscan --src -o containertests -t java

Analyser le tag `latest` du conteneur `shiftleft/scan-slim````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

Vous pouvez également spécifier l'image en utilisant le sha256 digest```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker

Vous pouvez également sauvegarder des images de conteneurs en utilisant la commande docker ou podman save et passer l'archive à depscan pour analyse.```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

Référez-vous aux tests Docker dans le workflow GitHub Actions de ce dépôt pour plus d'exemples.

### Analyse de projets localement (conteneur Docker)

L'image conteneur `ghcr.io/owasp-dep-scan/dep-scan` peut être utilisée pour effectuer l'analyse.

Pour analyser avec les paramètres par défaut```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

Pour scanner avec une configuration basée sur des variables d'environnement personnalisées```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

Dans l'exemple ci-dessus, `/tmp` est monté comme `/db` dans le conteneur. Ce répertoire est ensuite spécifié comme `VDB_HOME` pour mettre en cache les informations de vulnérabilité. De cette façon, la base de données peut être mise en cache et réutilisée pour améliorer les performances.

### Mode serveur

dep-scan et cdxgen peuvent être exécutés en mode serveur. Utilisez le fichier docker-compose inclus pour commencer.```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up

Le fichier compose fourni définit DEPSCAN_SERVER_API_KEY sur un espace réservé de développement par défaut afin que le service dep-scan puisse se lier à 0.0.0.0. Remplacez cette valeur avant d'exposer le service en dehors d'un laboratoire local.```bash depscan --server --server-host 127.0.0.1 --server-port 7070

Si vous devez lier dep-scan à une adresse non locale, définissez d'abord une clé 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 refuse de se lier à une adresse non locale sans soit DEPSCAN_SERVER_API_KEY, soit une adhésion explicite via DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true.

Utilisez le point de terminaison /scan pour effectuer des analyses.

[!NOTE] Le paramètre type est obligatoire en mode serveur. Lorsque l'authentification par clé API est activée, envoyez la clé en utilisant X-API-Key ou Authorization: Bearer <key>.

• Analyse d'un répertoire local. Analyse d'un fichier SBOM (présent localement).```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

- Analyse d'un dépôt 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

• Téléchargement d'un fichier SBOM et génération des résultats basés sur celui-ci.```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

## Développement local

Configurez uv en suivant la [documentation](https://docs.astral.sh/uv/) officielle.```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest

Configuration VDB locale```shell

vdb --clean vdb --download-image

To scan containers and OS images

vdb --download-full-image

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

Ceci utiliserait automatiquement la configuration spécifiée dans le fichier de configuration local.

Documentation

La documentation complète se trouve sur depscan.readthedocs.io. Pages clés :

• Langages pris en charge et matrice d'accessibilité
• Analyse d'accessibilité (hub)
  • Le modèle d'accessibilité
  • Comment dep-scan priorise
  • SBOM et preuves
  • Guides par langage : Rust, Go, .NET, JVM/JS/Python/PHP
  • Analyseurs : Accessibilité des frameworks, Accessibilité sémantique
• Sortie et conformité : Guide VDR, Guide CSAF VEX
• Personnalisation via les variables d'environnement
• Utilisation avancée : Avis de sécurité GitHub, Mode suggestion, Audit des risques des paquets, Analyse en direct du système, Analyse des licences, Rapports personnalisés

Licence

Licence MIT

Ce projet a été offert à la fondation OWASP en août 2023 par AppThreat Ltd.

Financement

Ce projet est financé par le biais de NGI Zero Core, un fonds établi par NLnet avec le soutien financier du programme Next Generation Internet de la Commission européenne. En savoir plus sur la page du projet NLnet.