OWASP Dependency-Check permite comparar las dependencias directas y transitivas de un proyecto Java con vulnerabilidades publicadas. En esta guía aprenderás a integrarlo en Maven, generar reportes HTML y JSON, revisar los hallazgos sin confundir una coincidencia con explotabilidad y dejar un umbral explícito listo para CI.

El resultado será reproducible: conservarás la versión del plugin, la configuración, el árbol de dependencias, los reportes y un método para comprobar si una actualización eliminó el hallazgo.

Alcance: Dependency-Check detecta vulnerabilidades conocidas asociadas con componentes identificados. No sustituye SAST, DAST ni una revisión manual, y no demuestra por sí solo que una vulnerabilidad sea explotable. También puede producir falsos positivos y falsos negativos.

Requisitos

• Un proyecto Maven con pom.xml.
• Maven 3.8.1 o posterior.
• JDK 11 o posterior.
• Acceso a los repositorios donde Maven resuelve las dependencias.
• Acceso a las fuentes de vulnerabilidades o a un espejo interno.
• Una clave de API del NVD, recomendada para reducir demoras y límites restrictivos.
• jq, únicamente para validar y consultar el reporte JSON desde la terminal.

Al 31 de agosto de 2026, la documentación oficial muestra dependency-check-maven 13.0.0 con Maven 3.8.1 y JDK 11 como requisitos mínimos. Comprueba la versión vigente antes de reutilizar la configuración.

La primera actualización de datos del NVD puede tardar 20 minutos o más. Para integraciones operativas, el proyecto recomienda usar un espejo del NVD y no depender exclusivamente del servicio público. Consulta el uso y los requisitos oficiales.

Qué analiza Dependency-Check

El goal check requiere resolución Maven compile+runtime, reúne evidencias como GAV, PURL o CPE y las correlaciona con entradas CVE.

El plugin omite las dependencias de prueba de forma predeterminada mediante skipTestScope=true; no omite por defecto los scopes provided, runtime o system. Revisa estos valores según lo que realmente forme parte de tu aplicación y entorno.

La secuencia correcta no es “aparece un CVE, entonces la aplicación es vulnerable”. Primero debes confirmar que Dependency-Check identificó el componente y la versión correctos. Después debes comprobar si el CVE aplica a la manera en que la aplicación utiliza ese componente.

Insertar aquí la Imagen 1 mostrada arriba: flujo de análisis SCA.

1. Registra las versiones y el árbol de dependencias

Ejecuta los comandos desde la raíz del proyecto:

java -version
mvn -version
mvn dependency:tree -DoutputFile=target/dependency-tree.txt

Conserva target/dependency-tree.txt. El árbol permite determinar si una biblioteca fue declarada directamente o llegó de forma transitiva.

2. Protege la clave de API del NVD

Solicita una clave en el portal oficial del NVD y guárdala como secreto.

Para cargarla en una sesión local sin escribirla en el historial:

read -rsp "NVD API key: " NVD_API_KEY
printf '\n'
export NVD_API_KEY

No incluyas la clave en pom.xml, en el repositorio ni en la línea de comandos. El plugin recomienda nvdApiKeyEnvironmentVariable para CI; el parámetro directo nvdApiKey puede aparecer cuando Maven se ejecuta con depuración. Consulta los parámetros del goal check.

3. Configura el plugin Maven

Agrega este bloque dentro de <build><plugins> en pom.xml. Si esas etiquetas ya existen, integra únicamente <plugin>.

<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <version>13.0.0</version>

  <configuration>
    <nvdApiKeyEnvironmentVariable>NVD_API_KEY</nvdApiKeyEnvironmentVariable>

    <formats>
      <format>HTML</format>
      <format>JSON</format>
    </formats>

    <outputDirectory>
      ${project.build.directory}/dependency-check
    </outputDirectory>

    <failBuildOnCVSS>
      ${dependency-check.cvss.threshold}
    </failBuildOnCVSS>

    <failOnError>true</failOnError>
  </configuration>

  <executions>
    <execution>
      <id>audit-dependencies</id>
      <phase>verify</phase>
      <goals>
        <goal>check</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Para la primera línea de base, añade esta propiedad dentro de <properties>:

<dependency-check.cvss.threshold>11</dependency-check.cvss.threshold>

El valor 11 permite generar la línea de base sin bloquear el build, porque CVSS utiliza una escala de 0 a 10.

Este también es el valor predeterminado del plugin. Por lo tanto, Dependency-Check no bloquea el build por vulnerabilidades mientras no configures un umbral real. La documentación oficial explica este comportamiento.

Antes de ejecutar, inspecciona el cambio y genera el POM efectivo:

git diff -- pom.xml
mvn help:effective-pom -Doutput=target/effective-pom.xml

En target/effective-pom.xml deberían aparecer:

• dependency-check-maven;
• la versión fijada;
• NVD_API_KEY como nombre de la variable;
• los formatos HTML y JSON;
• el directorio de salida;
• el umbral configurado.

Proyecto multimódulo: este ejemplo corresponde a un proyecto de un módulo. En un reactor Maven, decide si necesitas ejecutar check por módulo o aggregate en el proyecto padre para obtener un reporte conjunto. Consulta los goals disponibles.

4. Ejecuta la línea de base

mvn verify

La primera ejecución descarga y procesa los datos de vulnerabilidades. No la interrumpas únicamente porque permanece varios minutos actualizando el NVD.

Al finalizar, comprueba que los reportes existan:

test -s target/dependency-check/dependency-check-report.html
test -s target/dependency-check/dependency-check-report.json

Valida la estructura del JSON:

jq -e '.dependencies | type == "array"' \
  target/dependency-check/dependency-check-report.json

Para contar las dependencias que contienen al menos una vulnerabilidad registrada:

jq \
  '[.dependencies[]
    | select((.vulnerabilities // []) | length > 0)]
    | length' \
  target/dependency-check/dependency-check-report.json

Un resultado 0 significa que el análisis no correlacionó vulnerabilidades conocidas con las dependencias examinadas y los datos disponibles. No demuestra que la aplicación esté libre de vulnerabilidades.

Conserva la línea de base

Antes de ejecutar mvn clean o corregir una dependencia, copia la evidencia fuera de target:

evidence_dir="../dependency-check-evidence/$(basename "$PWD")-$(date -u +%Y%m%dT%H%M%SZ)"

mkdir -p "$evidence_dir"

cp target/dependency-tree.txt "$evidence_dir/"
cp target/dependency-check/dependency-check-report.html "$evidence_dir/"
cp target/dependency-check/dependency-check-report.json "$evidence_dir/"

Maven elimina target durante la fase clean. Sin esta copia perderías el reporte que necesitas para comparar el estado anterior y posterior.

5. Interpreta cada hallazgo antes de actuar

Abre target/dependency-check/dependency-check-report.html y revisa cada dependencia en este orden:

1. Identidad: comprueba el archivo, GAV, PURL, versión y CPE. Una CPE incorrecta suele explicar un falso positivo.
2. Origen: localiza la dependencia en dependency-tree.txt.
3. Vulnerabilidad: abre la referencia CVE y revisa las versiones afectadas, la configuración necesaria y el vector de ataque.
4. Aplicabilidad: determina si la aplicación utiliza la función vulnerable y si existen controles que cambien el riesgo.
5. Decisión: prioriza actualizar, sustituir o excluir la dependencia. Suprime únicamente una coincidencia que hayas comprobado que no aplica.

CVSS ayuda a ordenar la severidad técnica, pero no incorpora por sí solo la exposición, la criticidad del activo ni el contexto de negocio.

Si el reporte indica que una vulnerabilidad está en el catálogo CISA Known Exploited Vulnerabilities, úsalo como una señal adicional de priorización.

Insertar aquí la Imagen 2 mostrada arriba: interpretación de un hallazgo.

6. Corrige dependencias directas y transitivas

Si la dependencia está declarada en pom.xml, cambia su versión por una corregida que sea compatible con la aplicación.

No elijas una versión solamente porque es la más reciente. Revisa las notas del proveedor, los cambios incompatibles y las pruebas del proyecto.

Para localizar una dependencia transitiva:

mvn dependency:tree -Dincludes=grupo:artefacto

Reemplaza grupo:artefacto por las coordenadas reales. Después puedes:

• actualizar la dependencia padre que la incorpora;
• fijar una versión corregida mediante <dependencyManagement>;
• excluirla si no es necesaria y las pruebas confirman que la aplicación sigue funcionando.

Vuelve a ejecutar las pruebas y el análisis:

mvn clean verify
mvn dependency:tree -DoutputFile=target/dependency-tree.txt

Comprueba que:

• la dependencia corregida aparece con la versión esperada;
• las pruebas del proyecto finalizan correctamente;
• el hallazgo desapareció o cambió de estado;
• no surgieron nuevas dependencias vulnerables;
• el reporte nuevo puede compararse con la línea de base archivada.

7. Suprime solo falsos positivos comprobados

No uses una supresión para ocultar una vulnerabilidad pendiente. Primero confirma que el GAV, PURL o CPE es incorrecto, o que el CVE no aplica al componente identificado.

El reporte HTML contiene un botón para generar la regla XML correspondiente. Para el primer archivo, utiliza la opción que produce el documento XML completo.

Cada supresión debería contener:

• selector específico;
• evidencia de la revisión;
• responsable;
• referencia al ticket o decisión;
• fecha until para forzar una nueva evaluación;
• ausencia de datos sensibles.

Dependency-Check admite selectores por SHA-1, PURL, GAV, ruta, CPE y CVE. Consulta la guía oficial de supresiones.

Guarda el archivo como dependency-check-suppressions.xml y añade dentro de <configuration>:

<suppressionFiles>
  <suppressionFile>
    ${project.basedir}/dependency-check-suppressions.xml
  </suppressionFile>
</suppressionFiles>

<failBuildOnUnusedSuppressionRule>
  true
</failBuildOnUnusedSuppressionRule>

failBuildOnUnusedSuppressionRule permite detectar reglas que ya no coinciden con hallazgos. Revisa además los vencimientos y elimina las supresiones que dejaron de ser necesarias.

8. Activa una política de severidad

Después de revisar la línea de base, reemplaza 11 por el umbral aprobado por tu organización. Por ejemplo:

<dependency-check.cvss.threshold>7.0</dependency-check.cvss.threshold>

Con este ejemplo, Maven falla si Dependency-Check identifica una vulnerabilidad con CVSS igual o superior a 7.0.

El valor es ilustrativo. La organización debe definirlo según su riesgo, los plazos de remediación y el proceso de excepciones.

Prueba el umbral

Antes de publicarlo en CI, realiza una prueba en un proyecto aislado:

1. Ejecuta el análisis con umbral 11 y confirma que no bloquea por CVSS.
2. Selecciona un fixture que contenga un hallazgo conocido.
3. Configura un umbral igual o inferior al CVSS de ese hallazgo.
4. Ejecuta nuevamente mvn verify.
5. Confirma que Maven falla por la política y que los reportes se generan.
6. Conserva ambos logs y reportes.

No introduzcas deliberadamente una dependencia vulnerable en un proyecto productivo.

9. Integra el análisis en CI

El pipeline debe:

1. Inyectar NVD_API_KEY desde su almacén de secretos.
2. Reutilizar el directorio de datos de Dependency-Check.
3. Ejecutar mvn verify.
4. Publicar los reportes HTML y JSON incluso cuando el build falle.
5. Diferenciar un bloqueo CVSS de un error técnico.
6. Conservar el commit, la versión del plugin, el umbral y los reportes.

El directorio de datos predeterminado se encuentra bajo:

~/.m2/repository/org/owasp/dependency-check-data/

Incluye la versión mayor del plugin en la clave del caché. Evita que varios jobs escriban simultáneamente sobre una misma base H2.

Para runners concurrentes, utiliza cachés independientes, un espejo NVD o una base central preparada para ese patrón. Consulta la documentación sobre fuentes y caché.

No configures failOnError=false para mantener el pipeline verde. Un análisis que no pudo actualizarse o completarse no equivale a un análisis sin hallazgos.

Cloud Serversby Donweb

Todo el poder de la nube a tus proyectos y aplicaciones.
Alojamiento ultra rápido, escalable y con alta disponibilidad.

• Performance que te sorprenderá
• Rápida escalabilidad y sin limitaciones
• Arquitectura de alta disponibilidad
• Soporte experto y ejecutivos de cuenta
• Pagos en tu moneda y facturación local

Descubre la mejor solución de Cloud Hosting