Introducción

OWASP dep-scan es una herramienta de auditoría de riesgos y seguridad de próxima generación basada en vulnerabilidades conocidas, avisos y limitaciones de licencia para las dependencias del proyecto. Se admiten tanto repositorios locales como imágenes de contenedores como entrada, y la herramienta es ideal para la integración con plataformas ASPM/VM y en entornos CI.

Contenido

• Características
  • Flujos de datos alcanzables precisos
  • Matriz de alcanzabilidad
  • Alcanzabilidad en Rust (mediante rusi)
  • Alcanzabilidad en Go (mediante golem)
  • Alcanzabilidad en .NET (mediante dosai)
  • Alcanzabilidad en JVM, JavaScript, Python y PHP (mediante atom)
  • Fuentes de datos de vulnerabilidades
  • Distribuciones Linux
• Inicio rápido
  • Escaneo de proyectos localmente (versión Python)
  • Binarios independientes (sin necesidad de Python o Node.js)
  • Escaneo de contenedores localmente (versión Python)
  • Escaneo de proyectos localmente (contenedor Docker)
  • Modo servidor
• Desarrollo local
• Documentación (depscan.readthedocs.io)
• Licencia

Características

• Escanea la mayoría del código de la aplicación (repositorios locales, imágenes de contenedores Linux, manifiestos de Kubernetes y sistema operativo) para identificar CVEs conocidas con priorización.
• Realiza análisis avanzado de alcanzabilidad para múltiples lenguajes (consulte la matriz de alcanzabilidad a continuación).
• El escaneo de vulnerabilidades de paquetes se realiza localmente y es bastante rápido. No se utiliza ningún servidor.
• Genera un Inventario de Componentes de Software (SBOM) con información del Informe de Divulgación de Vulnerabilidades (VDR).
• Genera un documento VEX del Marco Común de Avisos de Seguridad (CSAF) 2.0/2.1 (consulte el Léame de CSAF).
• Realiza una auditoría de riesgos profunda de paquetes para ataques de confusión de dependencias y riesgos de mantenimiento (consulte la documentación de auditoría de riesgos).

Flujos de datos alcanzables precisos

Flujos de datos detallados para identificar rutas alcanzables y no alcanzables en su aplicación basándose en el contexto completo.

Matriz de alcanzabilidad

dep-scan calcula la alcanzabilidad para siete ecosistemas de lenguajes a través de cuatro segmentadores. Un paquete vulnerable cuyo código se encuentra realmente en una ruta ejecutada se marca como Alcanzable, mientras que un paquete que solo se declara en el BOM pero nunca se llama no lo está. Cada segmentador alimenta el mismo motor de alcanzabilidad compartido, indexado por purl, por lo que el comportamiento es uniforme en todos los lenguajes. La alcanzabilidad está activada por defecto (--reachability-analyzer FrameworkReachability); SemanticReachability además atribuye servicios, endpoints y alcanzabilidad post-construcción (binario/contenedor) alcanzados.

Para conocer los conceptos detrás de la alcanzabilidad y la priorización, lea los capítulos sobre modelo de alcanzabilidad y priorización. Para ejemplos prácticos por lenguaje, consulte las Guías de lenguajes. Para el cumplimiento normativo (VDR y CSAF VEX), consulte la guía de VDR y la guía de CSAF VEX.

La alcanzabilidad está activada por defecto con --profile research, que es lo que dep-scan usa cuando la alcanzabilidad está activada. Los comandos a continuación son suficientes para comenzar; las guías por lenguaje cubren la resolución binaria, la seguridad de backend y red, los requisitos de restauración y ejemplos prácticos sobre los fixtures del repositorio.

Rust (rusi). cdxgen ejecuta rusi y persiste su informe, que dep-scan convierte en el pipeline compartido, por lo que una crate que realmente se llama (por ejemplo time::now() para RUSTSEC-2020-0071) es Alcanzable mientras que una que solo está presente no lo es. Consulte la guía de alcanzabilidad en Rust.```bash depscan -i ./my-rust-app -o ./reports --profile research

**Go (golem).** dep-scan invoca [golem](https://github.com/cdxgen/cdxgen-plugins-bin) directamente para proyectos Go (necesita `go` en `PATH`), marcando un módulo como Alcanzable cuando sus funciones están en una ruta trazada. Use `--go-analyzer-network offline` para repositorios no confiables con un caché de módulos cálido. Consulte la [guía de alcanzabilidad de Go](https://depscan.readthedocs.io/languages/go-reachability).```bash
depscan -i ./my-go-app -o ./reports -t go

.NET (dosai). cdxgen ejecuta dosai, que emite un veredicto explícito de accesibilidad por paquete (PackageReachability con ReachabilityKind y Confidence) que dep-scan trata como autoritativo, por lo que un paquete NuGet realmente llamado (por ejemplo JsonConvert.DeserializeObject en una entrada controlada) es Accesible. Escanee un árbol restaurado en busca de purls versionados. Consulte la guía de accesibilidad .NET.```bash depscan -i ./my-dotnet-app -o ./reports -t dotnet

**JVM, JavaScript/TypeScript, Python y PHP (atom).** Estos cuatro ecosistemas comparten el slicer [atom](https://github.com/AppThreat/atom), que construye una representación intermedia independiente del lenguaje y realiza slicing estático. Consulte la [guía de alcanzabilidad para JVM, JS, Python y 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 más allá de la accesibilidad centrada en frameworks hacia niveles de endpoint, servicio y post-construcción, pase --reachability-analyzer SemanticReachability con un --bom-dir de BOMs del ciclo de vida. Consulte la guía de accesibilidad semántica.

Información clara sobre CVEs

Comprenda los CVEs claramente sin tener que leer la descripción.

Priorización automática

Concéntrese solo en los CVEs que requieren su atención.

Manténgase proactivo

Siempre esté un paso adelante con predicción avanzada de vulnerabilidades y exploits.

Fuentes de datos de vulnerabilidades

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

Distribuciones de Linux

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

Inicio rápido

dep-scan es ideal para su uso durante la integración continua (CI) y como herramienta de desarrollo local.

Escaneo de proyectos localmente (versión 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]

Esto instalaría dos comandos llamados `cdxgen` y `depscan`.

Puedes invocar el comando de escaneo directamente con las diversas opciones.```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports

La lista completa de opciones está a continuación:```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

### Binarios independientes (no requiere Python o Node.js)

Los ejecutables de un solo archivo precompilados se adjuntan a cada [lanzamiento de GitHub](https://github.com/owasp-dep-scan/dep-scan/releases). Incluyen un binario SEA de [cdxgen](https://github.com/cdxgen/cdxgen) compatible, por lo que la generación de BOM funciona de inmediato sin necesidad de instalar Python, Node.js o cdxgen.

| Plataforma             | Arquitectura | Recurso                     |
| ---------------------- | ------------ | --------------------------- |
| 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 recurso tiene un archivo `.sha256` correspondiente para verificación.```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] Los binarios de macOS actualmente no están firmados. En la primera ejecución, Gatekeeper de macOS puede bloquearlos; elimine el atributo de cuarentena con xattr -d com.apple.quarantine ./depscan-darwin-arm64 (o permita el binario en Configuración del Sistema, Privacidad y Seguridad).

[!NOTE] La base de datos de vulnerabilidades aún se descarga en la primera ejecución. Solo se incluye cdxgen, no la base de datos de vulnerabilidades. Use el comando depscan-vdb para seleccionar una variante de base de datos específica, por ejemplo depscan-vdb download --scope app para una base de datos más pequeña solo de aplicaciones. Consulte la guía de la base de datos de vulnerabilidades para la matriz completa de imágenes.

Todos los binarios independientes incluyen blint, pero no su backend de desensamblado opcional nyxstone (que no tiene wheels ni soporte para Windows). Por lo tanto, el análisis binario basado en desensamblado profundo no está disponible en los binarios independientes; use el paquete de Python (pip install owasp-depscan[all]) si lo necesita.

Escaneo de contenedores localmente (versión de Python)

Escanee un proyecto Java.```bash depscan --src -o containertests -t java

Escanea la etiqueta `latest` del contenedor `shiftleft/scan-slim````bash
depscan --src shiftleft/scan-slim -o containertests -t docker

Incluye license en el tipo para realizar la auditoría de licencias.```bash depscan --src shiftleft/scan-slim -o containertests -t docker license

También puedes especificar la imagen usando el resumen sha256```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker

También puedes guardar imágenes de contenedores usando el comando save de docker o podman y pasar el archivo a depscan para su análisis.```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 las pruebas de Docker en el flujo de trabajo de GitHub Actions de este repositorio para más ejemplos.

### Escaneo de proyectos localmente (contenedor Docker)

La imagen del contenedor `ghcr.io/owasp-dep-scan/dep-scan` se puede utilizar para realizar el escaneo.

Para escanear con la configuración predeterminada```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

Para escanear con configuración basada en variables de entorno 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

En el ejemplo anterior, `/tmp` se monta como `/db` dentro del contenedor. Este directorio se especifica luego como `VDB_HOME` para almacenar en caché la información de vulnerabilidades. De esta manera, la base de datos se puede almacenar en caché y reutilizar para mejorar el rendimiento.

### Modo servidor

dep-scan y cdxgen se pueden ejecutar en modo servidor. Use el archivo docker-compose incluido para comenzar.```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up

El archivo compose incluido establece DEPSCAN_SERVER_API_KEY a un espacio reservado de desarrollo por defecto para que el servicio dep-scan pueda enlazarse a 0.0.0.0. Sobrescribe este valor antes de exponer el servicio fuera de un laboratorio local.```bash depscan --server --server-host 127.0.0.1 --server-port 7070

Si necesita vincular dep-scan a una dirección no local, establezca una API key primero:```bash
export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server --server-host 0.0.0.0 --server-port 7070

[!IMPORTANT] dep-scan se niega a enlazar a una dirección no local sin DEPSCAN_SERVER_API_KEY o una opción explícita mediante DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true.

Use el endpoint /scan para realizar escaneos.

[!NOTE] El parámetro type es obligatorio en modo servidor. Cuando la autenticación con clave API está habilitada, envíe la clave usando X-API-Key o Authorization: Bearer <clave>.

• Escaneo de un directorio local. Escaneo de un archivo 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

- Escaneando un repositorio de 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

• Subiendo un archivo SBOM y generando resultados basados en él.```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

## Desarrollo local

Configura uv siguiendo la [documentación](https://docs.astral.sh/uv/) oficial.```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest

Configuración local de VDB```shell

vdb --clean vdb --download-image

To scan containers and OS images

vdb --download-full-image

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

Esto usaría automáticamente la configuración especificada en el archivo de configuración local .config/depscan.toml.

Documentación

La documentación completa está en depscan.readthedocs.io. Páginas clave:

• Idiomas compatibles y matriz de alcanzabilidad
• Análisis de alcanzabilidad (hub)
  • El modelo de alcanzabilidad
  • Cómo prioriza dep-scan
  • SBOM y evidencia
  • Guías de idiomas: Rust, Go, .NET, JVM/JS/Python/PHP
  • Analizadores: Alcanzabilidad de frameworks, Alcanzabilidad semántica
• Salida y cumplimiento: Guía de VDR, Guía de CSAF VEX
• Personalización mediante variables de entorno
• Uso avanzado: GitHub Security Advisory, Modo sugerencia, Auditoría de riesgo de paquetes, Escaneo en vivo del sistema, Escaneo de licencias, Informes personalizados

Licencia

Licencia MIT

Este proyecto fue donado a la Fundación OWASP en agosto de 2023 por AppThreat Ltd.

Financiación

Este proyecto se financia a través de NGI Zero Core, un fondo establecido por NLnet con el apoyo financiero del programa Next Generation Internet de la Comisión Europea. Obtén más información en la página del proyecto de NLnet.