Einführung

OWASP dep-scan ist ein modernes Sicherheits- und Risikoprüfungstool, das auf bekannten Schwachstellen, Sicherheitshinweisen und Lizenzbeschränkungen für Projektabhängigkeiten basiert. Sowohl lokale Repositorys als auch Container-Images werden als Eingabe unterstützt, und das Tool eignet sich ideal für die Integration mit ASPM/VM-Plattformen sowie in CI-Umgebungen.

Inhaltsverzeichnis

• Funktionen
  • Präzise erreichbare Datenflüsse
  • Erreichbarkeitsmatrix
  • Rust-Erreichbarkeit (via rusi)
  • Go-Erreichbarkeit (via golem)
  • .NET-Erreichbarkeit (via dosai)
  • JVM-, JavaScript-, Python- und PHP-Erreichbarkeit (via atom)
  • Schwachstellen-Datenquellen
  • Linux-Distributionen
• Schnellstart
  • Lokales Scannen von Projekten (Python-Version)
  • Standalone-Binärdateien (kein Python oder Node.js erforderlich)
  • Lokales Scannen von Containern (Python-Version)
  • Lokales Scannen von Projekten (Docker-Container)
  • Server-Modus
• Lokale Entwicklung
• Dokumentation (depscan.readthedocs.io)
• Lizenz

Funktionen

• Scannen der meisten Anwendungscodes (lokale Repos, Linux-Container-Images, Kubernetes-Manifeste und Betriebssysteme) zur Identifizierung bekannter CVEs mit Priorisierung
• Durchführung einer erweiterten Erreichbarkeitsanalyse für mehrere Sprachen (siehe Erreichbarkeitsmatrix unten)
• Paketschwachstellenscanning erfolgt lokal und ist recht schnell. Es wird kein Server verwendet
• Erstellung einer Software-Stückliste (SBOM) mit Vulnerability Disclosure Report (VDR)-Informationen
• Erstellung eines Common Security Advisory Framework (CSAF) 2.0/2.1 VEX-Dokuments (siehe CSAF-Readme)
• Durchführung einer tiefgehenden Paketrisikoprüfung auf Abhängigkeitsverwechslungsangriffe und Wartungsrisiken (siehe Dokumentation zur Risikoprüfung)

Präzise erreichbare Datenflüsse

Detaillierte Datenflüsse zur Identifizierung sowohl erreichbarer als auch nicht erreichbarer Pfade in Ihrer Anwendung basierend auf dem vollständigen Kontext.

Erreichbarkeitsmatrix

dep-scan berechnet die Erreichbarkeit für sieben Sprachökosysteme über vier Slicer. Ein anfälliges Paket, dessen Code tatsächlich auf einem ausgeführten Pfad liegt, wird als Erreichbar markiert, während ein Paket, das lediglich in der BOM deklariert, aber nie aufgerufen wird, nicht als erreichbar gilt. Jeder Slicer speist denselben gemeinsamen, nach PURL geschlüsselten Erreichbarkeitsmechanismus, sodass das Verhalten sprachübergreifend einheitlich ist. Die Erreichbarkeit ist standardmäßig aktiviert (--reachability-analyzer FrameworkReachability); SemanticReachability attributiert zusätzlich erreichte Dienste, Endpunkte und Erreichbarkeit nach dem Build (Binary/Container).

Für die Konzepte hinter Erreichbarkeit und Priorisierung lesen Sie die Kapitel Erreichbarkeitsmodell und Priorisierung. Sprachspezifische Beispiele finden Sie in den Sprachleitfäden. Für die Compliance-Aspekte (VDR und CSAF VEX) siehe den VDR-Leitfaden und den CSAF-VEX-Leitfaden.

Die Erreichbarkeit ist standardmäßig unter --profile research aktiviert, was dep-scan verwendet, wenn die Erreichbarkeit eingeschaltet ist. Die folgenden Befehle reichen für den Einstieg aus; die sprachspezifischen Leitfäden behandeln die Binärauflösung, Backend- und Netzwerksicherheit, Wiederherstellungsanforderungen sowie Beispiele anhand der im Repo enthaltenen Testumgebungen.

Rust (rusi). cdxgen führt rusi aus und speichert dessen Bericht, den dep-scan in die gemeinsame Pipeline umwandelt, sodass eine Crate, die tatsächlich aufgerufen wird (z. B. time::now() für RUSTSEC-2020-0071), als Erreichbar markiert wird, während eine nur vorhandene Crate nicht als erreichbar gilt. Siehe den Rust-Erreichbarkeitsleitfaden.```bash depscan -i ./my-rust-app -o ./reports --profile research

**Go (golem).** dep-scan ruft [golem](https://github.com/cdxgen/cdxgen-plugins-bin) direkt für Go-Projekte auf (benötigt `go` im `PATH`), markiert ein Modul als Reachable, wenn seine Funktionen auf einem verfolgten Pfad liegen. Verwenden Sie `--go-analyzer-network offline` für nicht vertrauenswürdige Repositories mit einem warmen Modul-Cache. Siehe den [Go reachability guide](https://depscan.readthedocs.io/languages/go-reachability).```bash
depscan -i ./my-go-app -o ./reports -t go

.NET (dosai). cdxgen führt dosai aus, das ein explizites paketweises Erreichbarkeitsurteil (PackageReachability mit ReachabilityKind und Confidence) ausgibt, das dep-scan als autoritativ behandelt, sodass ein NuGet-Paket, das tatsächlich (z. B. JsonConvert.DeserializeObject auf einer kontrollierten Eingabe) aufgerufen wird, als erreichbar gilt. Scannen Sie einen wiederhergestellten Baum nach versionierten purls. Siehe die .NET-Erreichbarkeitsanleitung.```bash depscan -i ./my-dotnet-app -o ./reports -t dotnet

**JVM, JavaScript/TypeScript, Python, and PHP (atom).** Diese vier Ökosysteme teilen sich den [atom](https://github.com/AppThreat/atom) Slicer, der eine sprachunabhängige Zwischendarstellung erstellt und statisches Slicing durchführt. Siehe die [JVM, JS, Python, and PHP reachability guide](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability).```bash
depscan --profile research -t java -i ./my-java-app -o ./reports --explain

Um über die reine Framework-basierte Erreichbarkeit hinaus zu Endpunkt-, Dienst- und Post-Build-Ebenen zu gelangen, übergeben Sie --reachability-analyzer SemanticReachability mit einem --bom-dir mit Lebenszyklus-Stücklisten. Siehe die semantische Erreichbarkeitsanleitung.

Klare Einblicke in CVEs

Verstehen Sie CVEs klar, ohne die Beschreibung durchlesen zu müssen.

Automatische Priorisierung

Konzentrieren Sie sich nur auf CVEs, die Ihre Aufmerksamkeit benötigen.

Bleiben Sie proaktiv

Bleiben Sie mit erweiterten Schwachstellen- und Exploit-Vorhersagen immer einen Schritt voraus.

Datenquellen für Schwachstellen

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

Linux-Distributionen

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

Schnellstart

dep-scan ist ideal für den Einsatz während der kontinuierlichen Integration (CI) und als lokales Entwicklungswerkzeug.

Projekte lokal scannen (Python-Version)```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]

Dies würde zwei Befehle namens `cdxgen` und `depscan` installieren.

Sie können den Scan-Befehl direkt mit den verschiedenen Optionen aufrufen.```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports

Die vollständige Liste der Optionen befindet sich unten:```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

### Standalone-Binärdateien (kein Python oder Node.js erforderlich)

Vorgefertigte Einzeldatei-Executables sind an jede [GitHub-Version](https://github.com/owasp-dep-scan/dep-scan/releases) angehängt. Sie bündeln ein passendes [cdxgen](https://github.com/cdxgen/cdxgen) SEA-Binary, sodass die BOM-Erstellung ohne Installation von Python, Node.js oder cdxgen sofort funktioniert.

| Plattform              | Architektur     | 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` |

Jedes Asset hat eine passende `.sha256`-Datei zur Überprüfung.```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] Die macOS-Binärdateien sind derzeit nicht signiert. Beim ersten Start kann macOS Gatekeeper sie blockieren; entfernen Sie das Quarantäneattribut mit xattr -d com.apple.quarantine ./depscan-darwin-arm64 (oder erlauben Sie die Binärdatei unter Systemeinstellungen, Datenschutz & Sicherheit).

[!NOTE] Die Schwachstellendatenbank wird beim ersten Start immer noch heruntergeladen. Nur cdxgen ist gebündelt, nicht die vuln DB. Verwenden Sie den Befehl depscan-vdb, um eine bestimmte Datenbankvariante auszuwählen, z. B. depscan-vdb download --scope app für eine kleinere, nur auf Apps bezogene Datenbank. Weitere Informationen zur vollständigen Bildmatrix finden Sie im Leitfaden zur Schwachstellendatenbank.

Alle eigenständigen Binärdateien bündeln blint, aber nicht das optionale nyxstone-Disassemblierungs-Backend (das keine Räder und keine Windows-Unterstützung hat). Eine tiefgehende binäre Analyse basierend auf Disassemblierung ist daher in den eigenständigen Binärdateien nicht verfügbar; verwenden Sie das Python-Paket (pip install owasp-depscan[all]), wenn Sie es benötigen.

Scannen von Containern lokal (Python-Version)

Scannen eines Java-Projekts.```bash depscan --src -o containertests -t java

Scanne das `latest` Tag des Containers `shiftleft/scan-slim````bash
depscan --src shiftleft/scan-slim -o containertests -t docker

Fügen Sie license zum Typ hinzu, um die Lizenzprüfung durchzuführen.```bash depscan --src shiftleft/scan-slim -o containertests -t docker license

Sie können das Image auch mit dem sha256-Digest angeben.```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker

Sie können Container-Images auch mit dem Befehl docker oder podman save speichern und das Archiv zur Überprüfung an depscan übergeben.```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

Weitere Beispiele finden Sie in den Docker-Tests unter dem GitHub Action Workflow für dieses Repository.

### Projekte lokal scannen (Docker-Container)

`ghcr.io/owasp-dep-scan/dep-scan` Container-Image kann verwendet werden, um den Scan durchzuführen.

Um mit den Standardeinstellungen zu scannen```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

Zum Scannen mit einer auf benutzerdefinierten Umgebungsvariablen basierenden Konfiguration```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

Im obigen Beispiel wird `/tmp` als `/db` in den Container eingehängt. Dieses Verzeichnis wird dann als `VDB_HOME` für das Zwischenspeichern der Schwachstelleninformationen angegeben. Auf diese Weise kann die Datenbank zwischengespeichert und wiederverwendet werden, um die Leistung zu verbessern.

### Servermodus

dep-scan und cdxgen können im Servermodus ausgeführt werden. Verwenden Sie die mitgelieferte docker-compose-Datei, um zu beginnen.```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up

Die mitgelieferte Compose-Datei setzt DEPSCAN_SERVER_API_KEY standardmäßig auf einen Entwicklungs-Platzhalter, damit der dep-scan-Dienst an 0.0.0.0 binden kann. Überschreiben Sie diesen Wert, bevor Sie den Dienst außerhalb eines lokalen Labors verfügbar machen.```bash depscan --server --server-host 127.0.0.1 --server-port 7070

Wenn Sie dep-scan an eine nicht-lokale Adresse binden müssen, setzen Sie zuerst einen API key:```bash
export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server --server-host 0.0.0.0 --server-port 7070

[!IMPORTANT] dep-scan weigert sich, an eine nicht-lokale Adresse zu binden, ohne dass entweder DEPSCAN_SERVER_API_KEY gesetzt ist oder eine explizite Zustimmung über DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true erfolgt ist.

Verwenden Sie den /scan-Endpunkt, um Scans durchzuführen.

[!NOTE] Der Parameter type ist im Server-Modus obligatorisch. Wenn die API-Key-Authentifizierung aktiviert ist, senden Sie den Schlüssel mit X-API-Key oder Authorization: Bearer <key>.

• Scannen eines lokalen Verzeichnisses. Scannen einer SBOM-Datei (lokal vorhanden).```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

- Scannen eines GitHub-Repositorys.```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

• Hochladen einer SBOM-Datei und Generieren von Ergebnissen basierend darauf.```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

## Local development

Richten Sie uv ein, indem Sie der offiziellen [Dokumentation](https://docs.astral.sh/uv/) folgen.```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest

Lokale VDB-Einrichtung```shell

vdb --clean vdb --download-image

To scan containers and OS images

vdb --download-full-image

### Lokalen Depscan scannen```shell
uv run depscan --config .config/depscan-dev.toml

Dies würde automatisch die in der lokalen Konfigurationsdatei Datei festgelegte Konfiguration verwenden.

Dokumentation

Die vollständige Dokumentation finden Sie unter depscan.readthedocs.io. Wichtige Seiten:

• Unterstützte Sprachen und Erreichbarkeitsmatrix
• Erreichbarkeitsanalyse (hub)
  • Das Erreichbarkeitsmodell
  • Wie dep-scan priorisiert
  • SBOM und Nachweise
  • Sprachleitfäden: Rust, Go, .NET, JVM/JS/Python/PHP
  • Analysatoren: Framework-Erreichbarkeit, Semantische Erreichbarkeit
• Ausgabe und Compliance: VDR-Leitfaden, CSAF VEX-Leitfaden
• Anpassung durch Umgebungsvariablen
• Erweiterte Nutzung: GitHub Security Advisory, Suggest-Modus, Paketrisiko-Audit, Live-Betriebssystem-Scan, Lizenz-Scan, Benutzerdefinierte Berichte

Lizenz

MIT-Lizenz

Dieses Projekt wurde im August 2023 von AppThreat Ltd. an die OWASP Foundation gespendet.

Finanzierung

Dieses Projekt wird durch NGI Zero Core finanziert, einen Fonds, der von NLnet mit finanzieller Unterstützung des Programms Next Generation Internet der Europäischen Kommission eingerichtet wurde. Weitere Informationen finden Sie auf der NLnet-Projektseite.