package-health-analyzer: El informe de dependencias que tu equipo de compliance necesita antes de cerrar la due diligence

Estás en una ronda de financiación. El fondo de inversión hace due diligence técnica y su equipo de compliance envía un cuestionario. Pregunta 47: “Liste todas las dependencias de software de terceros, sus licencias, y confirme que ninguna tiene términos copyleft que obliguen a liberar el código fuente”. Abres el package.json. Tienes 47 dependencias directas. Ejecutas npm ls y descubres que en total son 847 paquetes contando las transitivas.

Ahora tienes que averiguar la licencia de cada uno. Algunas son MIT, otras Apache 2.0, otras ISC. Pero en algún lugar del árbol hay un paquete con GPL-3.0 que nadie recuerda haber instalado. Si tu producto es SaaS, quizás no sea problema. Si es software distribuido, puede bloquear la operación.

El equipo de compliance también quiere saber si alguna dependencia tiene vulnerabilidades conocidas. Y si alguna está abandonada, sin actualizaciones en años. Y si alguna está deprecada. Y necesitan todo esto documentado en un formato que puedan adjuntar al informe de due diligence.

Hacer esto manualmente lleva días. Por cada paquete tienes que ir a npm, buscar la licencia, verificar el repositorio en GitHub, comprobar si hay CVEs, revisar cuándo fue la última actualización. Con 847 paquetes, es inviable.

La solución: análisis automatizado en 5 segundos

package-health-analyzer es una herramienta CLI que analiza todas las dependencias de un proyecto Node.js y genera informes completos en segundos. No necesitas configurar nada. Instalas, ejecutas, y tienes el informe.

npm install -g package-health-analyzer
cd tu-proyecto
pha scan

En menos de 5 segundos tienes un análisis completo: licencias de todos los paquetes, vulnerabilidades conocidas, antigüedad, estado de mantenimiento, popularidad, y una puntuación de salud de 0 a 100 para cada dependencia.

Los 7 formatos de salida

La herramienta genera informes en el formato que necesites:

1. Tabla en terminal (por defecto)

pha scan

Muestra una tabla con colores que indica el estado de cada dependencia. Verde para paquetes saludables, amarillo para advertencias, rojo para problemas críticos. Útil para revisión rápida durante desarrollo.

2. JSON estructurado

pha scan --format json --output informe.json

Datos completos de cada dependencia en formato JSON. Incluye toda la metadata: nombre, versión, licencia, repositorio, última actualización, vulnerabilidades, puntuación de salud, y más. Ideal para procesamiento programático o integración con otras herramientas.

{
  "package": "express",
  "version": "5.2.1",
  "license": {
    "spdx": "MIT",
    "type": "permissive",
    "blueOakRating": "Gold",
    "commercialUse": true
  },
  "health": {
    "score": 95,
    "age": { "score": 100, "lastUpdate": "3 days ago" },
    "deprecation": { "score": 100, "deprecated": false },
    "repository": { "score": 80, "stars": 65000, "issues": 120 }
  },
  "vulnerabilities": []
}

3. CSV para Excel

pha scan --format csv --output informe.csv

Exporta los datos a CSV que puedes abrir en Excel o Google Sheets. Perfecto para equipos de compliance que prefieren trabajar con hojas de cálculo. Pueden filtrar, ordenar, y generar sus propios informes.

4. Markdown para documentación

pha scan --format markdown --output DEPENDENCIES.md

Genera un documento Markdown con tablas formateadas. Puedes incluirlo directamente en la documentación del proyecto o en el repositorio de GitHub. Ejemplo de salida:

# Package Health Report

**Project:** mi-proyecto@1.0.0
**Generated:** 2026-01-08
**Total packages:** 47
**Average health:** 94/100
**Risk level:** Medium

| Package | Version | License | Health | Last Update | Issues |
|---------|---------|---------|--------|-------------|--------|
| express | 5.2.1 | MIT | 95/100 | 3 days ago | None |
| lodash | 4.17.21 | MIT | 88/100 | 1 year ago | None |
| moment | 2.30.1 | MIT | 72/100 | 2 years ago | ⚠️ Maintenance |

5. SBOM en formato SPDX 2.3

pha scan --format sbom --output sbom.json

Genera un Software Bill of Materials (SBOM) en formato SPDX 2.3, el estándar de la industria. Este formato es requerido por regulaciones como la orden ejecutiva de ciberseguridad de EE.UU. y está alineado con CISA SBOM 2025.

El SBOM incluye:

• Identificadores únicos para cada componente
• Relaciones de dependencia
• Información de licencias en formato SPDX
• Checksums para verificación de integridad
• Metadata del proveedor

{
  "spdxVersion": "SPDX-2.3",
  "SPDXID": "SPDXRef-DOCUMENT",
  "name": "mi-proyecto-sbom",
  "packages": [
    {
      "SPDXID": "SPDXRef-Package-express-5.2.1",
      "name": "express",
      "versionInfo": "5.2.1",
      "licenseConcluded": "MIT",
      "downloadLocation": "https://registry.npmjs.org/express/-/express-5.2.1.tgz"
    }
  ],
  "relationships": [
    {
      "spdxElementId": "SPDXRef-DOCUMENT",
      "relationshipType": "DESCRIBES",
      "relatedSpdxElement": "SPDXRef-Package-mi-proyecto-1.0.0"
    }
  ]
}

6. SARIF para GitHub Code Scanning

pha scan --format sarif --output results.sarif

Genera un archivo SARIF 2.1.0 compatible con GitHub Code Scanning. Puedes subirlo a GitHub y ver los problemas de dependencias directamente en la pestaña Security del repositorio, junto con otros análisis de seguridad.

7. NOTICE.txt para cumplimiento Apache

pha generate-notice --output NOTICE.txt

Genera un archivo NOTICE.txt siguiendo el formato de la Apache Software Foundation. Este archivo es requerido cuando distribuyes software que incluye componentes con licencia Apache 2.0. Lista todas las dependencias con sus atribuciones de copyright y notas de patentes.

NOTICE

This product includes software developed by third parties.

===========================================================
express - Fast, unopinionated, minimalist web framework
Version: 5.2.1
License: MIT
Copyright (c) 2009-2025 TJ Holowaychuk <tj@vision-media.ca>
Copyright (c) 2013-2025 Roman Shtylman <shtylman+expressjs@gmail.com>
Copyright (c) 2014-2025 Douglas Christopher Wilson <doug@somethingdoug.com>
===========================================================

[... continúa para cada dependencia ...]

Verificar un paquete antes de instalarlo

Antes de añadir una nueva dependencia, puedes verificar su salud:

pha check express

La salida muestra información detallada del paquete:

📦 Package: express@5.2.1
📅 Published: 3 days ago
📊 Status: Active

📜 License Analysis
   SPDX: MIT
   Type: permissive
   Blue Oak Rating: Gold
   Commercial Use: ✓ Allowed

🏥 Health Score: 95/100
   ├─ Age: 100/100
   ├─ Deprecation: 100/100
   ├─ License: 100/100
   └─ Repository: 80/100

✅ Result: OK - No issues detected

Esto te permite tomar decisiones informadas antes de añadir dependencias al proyecto. Si el paquete tiene licencia problemática o está abandonado, lo sabes antes de instalarlo.

Configuración por tipo de proyecto

Diferentes tipos de proyecto tienen diferentes requisitos de licencias. Una startup que vende SaaS puede usar AGPL sin problemas. Una empresa que distribuye software on-premise no puede. Un proyecto open source puede usar GPL. Un proyecto comercial propietario no.

La herramienta incluye 8 perfiles predefinidos:

pha init

El asistente interactivo te pregunta qué tipo de proyecto tienes:

• commercial: Bloquea GPL, AGPL, SSPL. Solo permite licencias permisivas.
• saas: Advierte sobre AGPL (copyleft de red) pero no bloquea.
• open-source: Permite cualquier licencia compatible con open source.
• library: Configuración para librerías que serán distribuidas.
• government: Requisitos estrictos para contratos gubernamentales.
• startup: Balance entre flexibilidad y protección.
• educational: Permisivo para proyectos académicos.
• personal: Sin restricciones.

Cada perfil ajusta automáticamente qué licencias son aceptables, cuáles generan advertencias, y cuáles bloquean el análisis.

Detección de licencias problemáticas

La herramienta clasifica licencias usando la base de datos SPDX (221 licencias) y el rating de Blue Oak Council:

Licencias permisivas (Gold/Silver): MIT, Apache 2.0, BSD, ISC. Puedes usar el código en proyectos comerciales sin restricciones significativas.

Licencias copyleft débil (Bronze): LGPL, MPL. Puedes usar el código pero con ciertas obligaciones de atribución o liberación de modificaciones.

Licencias copyleft fuerte (Lead): GPL, AGPL. Si usas este código, puede que tengas que liberar tu código fuente. AGPL además aplica a software accedido por red.

Licencias restrictivas: SSPL, Commons Clause. Restricciones adicionales que pueden impedir uso comercial.

Para proyectos comerciales, la herramienta marca en rojo cualquier dependencia con GPL, AGPL, o SSPL, y genera un código de salida de error para integraciones CI/CD:

pha scan --fail-on=warning
echo $?  # 2 si hay problemas críticos

Análisis de vulnerabilidades

Con un token de GitHub, la herramienta consulta la GitHub Advisory Database para detectar vulnerabilidades conocidas:

export GITHUB_TOKEN=tu_token
pha scan

El informe incluye CVEs asociados a cada paquete vulnerable:

{
  "package": "lodash",
  "version": "4.17.15",
  "vulnerabilities": [
    {
      "id": "CVE-2021-23337",
      "severity": "high",
      "title": "Command Injection in lodash",
      "fixedIn": "4.17.21"
    }
  ]
}

El token se almacena cifrado con AES-256-GCM y se limpia de memoria después de cada uso. Nunca aparece en logs ni en la salida del comando.

Métricas de salud

Cada dependencia recibe una puntuación de 0 a 100 basada en siete dimensiones:

Antigüedad (Age): Cuánto tiempo desde la última actualización. Un paquete actualizado hace una semana puntúa 100. Uno sin actualizaciones en 3 años puntúa bajo.

Deprecación: Si el paquete está marcado como deprecado en npm. Deprecado = 0 puntos en esta dimensión.

Licencia: Tipo de licencia según el perfil del proyecto. MIT en proyecto comercial = 100. GPL en proyecto comercial = 0.

Vulnerabilidades: CVEs conocidos. Sin vulnerabilidades = 100. Vulnerabilidad crítica = 0.

Popularidad: Descargas semanales en npm. Indica adopción y probabilidad de mantenimiento continuo.

Repositorio: Estrellas en GitHub, issues abiertos vs cerrados, frecuencia de commits. Indica salud del proyecto upstream.

Frecuencia de actualizaciones: Cadencia de releases. Releases regulares indican mantenimiento activo.

La puntuación final es una media ponderada configurable. Por defecto, vulnerabilidades y licencia tienen más peso que popularidad.

Integración en CI/CD

Puedes integrar el análisis en tu pipeline de CI para bloquear merges que introduzcan dependencias problemáticas:

# GitHub Actions
- name: Analyze dependencies
  run: |
    npm install -g package-health-analyzer
    pha scan --fail-on=warning --format json --output health-report.json

- name: Upload SBOM
  uses: actions/upload-artifact@v3
  with:
    name: sbom
    path: health-report.json

El código de salida indica el resultado:

• 0: Sin problemas
• 1: Advertencias (con --fail-on=warning)
• 2: Problemas críticos
• 3: Error de ejecución

Rendimiento

El análisis completo de un proyecto típico (50-100 dependencias) tarda menos de 5 segundos:

1. Descubrimiento y metadata (1-2 segundos): Lee package.json y package-lock.json, obtiene metadata de npm.
2. Análisis multidimensional (1-2 segundos): Evalúa licencias, busca vulnerabilidades, calcula puntuaciones.
3. Árbol de dependencias (1 segundo): Construye el grafo de dependencias, detecta duplicados y ciclos.
4. Puntuación y recomendaciones (<1 segundo): Calcula puntuaciones finales y genera recomendaciones.
5. Formateo de salida (<1 segundo): Genera el informe en el formato solicitado.

Los resultados se cachean en memoria. Escaneos subsecuentes del mismo proyecto tardan menos de 1 segundo mientras los datos estén frescos.

Casos de uso reales

Due diligence de inversión

El equipo de compliance del fondo de inversión necesita un inventario de dependencias con licencias. Generas el SBOM en formato SPDX y el informe en CSV. Ellos pueden verificar que no hay licencias copyleft que comprometan la propiedad intelectual.

pha scan --format sbom --output sbom-due-diligence.json
pha scan --format csv --output dependencias-licencias.csv

Auditoría de seguridad

El equipo de seguridad necesita saber qué vulnerabilidades conocidas tienen las dependencias. Generas el informe SARIF y lo subes a GitHub Code Scanning.

pha scan --format sarif --output security-audit.sarif
gh api repos/{owner}/{repo}/code-scanning/sarifs -f sarif=@security-audit.sarif

Cumplimiento de licencias para distribución

Vas a distribuir software que incluye dependencias Apache 2.0. Necesitas generar el NOTICE.txt requerido por la licencia.

pha generate-notice --output NOTICE.txt

Verificación antes de añadir dependencias

Antes de instalar un paquete nuevo, verificas que no tenga problemas de licencia o seguridad.

pha check nombre-del-paquete

Monitorización continua

Integras el análisis en CI para que cada PR verifique que las nuevas dependencias cumplen las políticas del proyecto.

pha scan --project-type commercial --fail-on=warning

Seguridad de la herramienta

La herramienta implementa múltiples capas de seguridad:

• Cifrado de tokens: Los tokens de GitHub se cifran con AES-256-GCM antes de almacenarse.
• Limpieza de memoria: Los secretos se limpian de memoria después de cada uso.
• Enmascaramiento en logs: Los tokens nunca aparecen en la salida del comando.
• Validación de permisos: Verifica permisos de archivos de configuración.
• Prevención de path traversal: Valida rutas de entrada y salida.
• Protección SSRF: Valida URLs antes de realizar peticiones.

Instalación y requisitos

npm install -g package-health-analyzer

Requisitos:

• Node.js 18+
• npm o yarn
• Token de GitHub (opcional, para vulnerabilidades)

El código está en GitHub

El paquete está publicado en NPM como package-health-analyzer. El código fuente está en github.com/686f6c61/package-health-analyzer.

En el repositorio encontrarás ejemplos de salida en examples/express-project-outputs con todos los formatos generados para un proyecto Express real.

La licencia es MIT. Si encuentras bugs o tienes sugerencias para nuevas métricas o formatos de salida, abre un issue en GitHub.