fleet-cve-scanner

Un escáner de CVE de código abierto y script único para flotas gestionadas por RMM. PowerShell 7 puro, sin agentes, sin dispositivos, sin tarifas de licencia.

Responde una pregunta por cada pieza de software en cada endpoint que gestionas: ¿la versión instalada se sabe vulnerable y qué tan urgente es? — al unir el inventario de software de tu RMM con fuentes de seguridad autorizadas y gratuitas:

• NIST NVD — CVEs conocidos + rangos de versiones afectadas
• CISA KEV — explotados activamente en la naturaleza (evita el umbral de puntuación)
• EPSS — probabilidad de explotación en los próximos 30 días
• CISA SSVC — decisiones de priorización act / attend / track
• MSRC — prueba de que un parche de Microsoft ya cubre el hallazgo
• endoflife.date — software que nunca volverá a recibir parches

Salidas: un informe CSV por dispositivo, un historial SQLite con relojes de SLA y eventos de cambio semana a semana, un panel HTML autónomo y un informe de exposición opcional en markdown.

Estado

v1.0.0. El motor fue portado en sala limpia desde un escáner que se ejecutaba semanalmente en producción contra una flota Windows (consulta docs/HISTORY.md). Antes de este lanzamiento, ambos se ejecutaron contra la misma flota en vivo y se compararon fila por fila: en decenas de miles de hallazgos donde ambos vieron un (dispositivo, software, versión) idéntico, cada campo calculado — estado, CVSS, severidad, bandera KEV, decisión SSVC, versión de corrección — coincidió exactamente.

Esa comparación cubre la lógica de veredicto. No ejercitó la capa de historial/SLA, y no sustituye la validación de la herramienta en tu propio entorno. Lee docs/known-limitations.md antes de confiar en ella — está escrita para ser honesta, no halagadora.

Inicio rápido

Necesitas PowerShell 7 (pwsh). Dos formas de ejecutarlo:

A. Escaneo en vivo con NinjaOne

cp config.example.json config.json
# edita config.json: completa ninjaone.client_id / client_secret / base_url,
# establece output.report_dir y (recomendado) nvd.api_key
pwsh -File fleet-cve-scan.ps1

B. Sin conexión — cualquier RMM, SCCM o Intune (sin acceso a API)

Exporta tu inventario a un CSV con las columnas hostname, software, version (opcional device_id, os), luego:

cp config.example.json config.json   # aquí solo se necesita output.report_dir
pwsh -File fleet-cve-scan.ps1 -InputCsv inventory.csv

-InputCsv realiza cero llamadas a NinjaOne — sin OAuth, sin API. Aún consulta NVD y las otras fuentes públicas, por lo que igualmente querrás un nvd.api_key en config.json y un output.report_dir válido. Consulta docs/rmm-adapters.md para el contrato de entrada y recetas de exportación por RMM.

Instalación de requisitos previos

• PowerShell 7 — macOS: brew install powershell; Windows: winget install Microsoft.PowerShell; Debian/Ubuntu: instala desde el repositorio de paquetes de Microsoft (packages.microsoft.com).
• sqlite3 (opcional, potencia el historial/tendencia) — macOS: preinstalado o brew install sqlite; Debian/Ubuntu: apt-get install sqlite3; Windows: descarga el paquete "tools" de SQLite desde sqlite.org y coloca sqlite3.exe en PATH o junto al script. Sin él, el escaneo aún se ejecuta; first_seen retrocede a la fecha de ejecución.

Requisitos

• PowerShell 7 (se recomienda 7.4+). El escaneo paralelo requiere 7.0+.
• sqlite3 — opcional; habilita la base de datos de historial, tendencias y seguimiento de first_seen para SLA. Si está ausente, esas funciones se omiten, el escaneo aún se completa.
• Salida de red a NVD, CISA (KEV), epss.empiricalsecurity.com (el host de puntuación masiva de EPSS — FIRST movió el alojamiento de datos de EPSS allí), MSRC, endoflife.date y GitHub raw (cvelistV5 del programa CVE) — más la API de NinjaOne en modo en vivo.
• Credenciales — el modo en vivo necesita id/secreto de cliente OAuth2 de NinjaOne; el modo sin conexión solo necesita un CSV de inventario. Una clave API de NVD es técnicamente opcional pero efectivamente requerida a escala de flota: NVD permite 50 solicitudes/30s con clave y solo 5/30s sin ella. El escáner detecta cuál tienes y limita en consecuencia, por lo que una ejecución sin clave es correcta pero aproximadamente 10 veces más lenta — bien para un puñado de productos, poco práctico para una flota real. Las claves son gratuitas.

Referencia de configuración

La configuración es un archivo JSON (por defecto config.json junto al script; se puede anular con -ConfigPath). Comienza desde config.example.json. Cada clave que el escáner lee, su valor predeterminado cuando se omite y qué hace:

ninjaone (modo en vivo)

nvd

Escaneo y puntuación

Almacenamiento en caché y límite de velocidad

nvd_min_spacing_ms, nvd_rate_limit y parallel_throttle son leídos por el escáner pero no están presentes en config.example.json — agrégalos solo si necesitas ajustarlos. Consulta docs/rate-limiting.md.

Enriquecimiento y SLA

output

Salidas

Todo lo siguiente se ubica en output.report_dir.

• vuln-report-YYYY-MM-DD.csv — el informe por hallazgo. 28 columnas (esquema a continuación).
• vuln-history.db — historial SQLite (requiere sqlite3): runs (agregados por ejecución), findings (historial de hallazgos abiertos por (dispositivo, software, cve) con first_seen / last_seen / resolved_date / epss_score), y changes (eventos semana a semana tipificados).
• cve-dashboard.html — panel HTML autónomo (biblioteca de gráficos incrustada, sin solicitudes externas). Opcionalmente copiado a output.dashboard_share.

Esquema del CSV (28 columnas)

El conjunto de columnas es fijo y se aplica mediante compuerta. En orden:

Programación

Run-WeeklyScan.ps1 es un envoltorio para ejecuciones programadas: ejecuta el escáner desde su propio directorio, captura todas las secuencias de salida en un registro fechado bajo <directorio del script>/logs/ (anular con -LogDir), y propaga el código de salida del escáner para que el programador vea los fallos.

Programador de tareas de Windows:

schtasks /Create /TN "CVE-Scan-Weekly" ^
  /TR "pwsh -NoProfile -File C:\ruta\a\Run-WeeklyScan.ps1" ^
  /SC WEEKLY /D SUN /ST 22:00 /RU SYSTEM

cron (Linux/macOS):

0 22 * * 0  pwsh -File /ruta/a/Run-WeeklyScan.ps1

Alojamiento del panel

cve-dashboard.html es completamente autónomo: ábrelo directamente, colócalo en cualquier host estático o recurso compartido, o cópialo automáticamente en cada ejecución mediante output.dashboard_share. Para alojamiento con control de acceso, el directorio dashboard-auth/ incluye un host ASP.NET mínimo con autenticación de Microsoft Entra (Azure AD); consulta su README y RUNBOOK.

Limitaciones honestas (léalas antes de confiar en él)

• La coincidencia de CPE es difusa por naturaleza. Entre el 40 y el 60 % del inventario típico no tiene ninguna entrada en NVD y se omite (se registra, nunca en silencio). La selección de CPE basada en nombres puede elegir el producto incorrecto; existe un flujo de trabajo de supresión porque es necesario. Este es el techo del enfoque gratuito de NVD: un escáner de pago con un catálogo de detección curado será más preciso. El valor de esta herramienta es ser gratuita, transparente y auditable.
• UNKNOWN es un veredicto de primera clase. Cuando el escáner no puede probar vulnerable o parcheado, lo dice en lugar de adivinar.
• Verificado solo con NinjaOne. El motor de escaneo es independiente del RMM (la entrada es solo dispositivo + software + versión); el modo -InputCsv permite que cualquier exportación de RMM/SCCM/Intune lo alimente, pero solo el adaptador de NinjaOne se ha ejecutado en producción.

La lista completa y sin concesiones — la tasa de omisión de CPE, el enmascaramiento de claves de deduplicación, totalResults de la página 1, las brechas de supercesión de MSRC y más — está en docs/known-limitations.md.

Notas de diseño

Algunas opciones estructurales que parecen poco convencionales son deliberadas:

• Un solo archivo, no un módulo. La ruta crítica del escaneo se ejecuta dentro de ForEach-Object -Parallel, y esos espacios de ejecución no pueden ver las funciones del ámbito externo, razón por la cual un puñado de ayudantes se duplican intencionalmente dentro del bloque paralelo. Un diseño de módulo con una función por archivo no eliminaría esa duplicación (el cuerpo paralelo aún necesitaría la fuente inyectada por espacio de ejecución); solo agregaría un paso de compilación y rompería el modelo de implementación de copiar un archivo. Si el proyecto alguna vez supera el archivo único, el empaquetado es el cambio con forma de v2, no un parche.
• Registros [PSCustomObject], no clases. Los registros de hallazgos se producen dentro de espacios de ejecución paralelos y se devuelven al espacio de ejecución principal. Las instancias de clases de PowerShell no sobreviven de manera confiable ese límite; [PSCustomObject] sí lo hace, y el contrato de columnas CSV se aplica mediante la compuerta de lanzamiento en lugar de un sistema de tipos.
• Scripts de prueba PS7 simples, no Pester. Los conjuntos en tests/ son scripts sin dependencias con aserciones de código de salida, ejecutables en cualquier lugar donde exista pwsh — incluido el servidor de escaneo — sin nada que instalar. CI los ejecuta todos en Windows y Ubuntu.

Documentación

• docs/how-it-works.md — el pipeline de escaneo etapa por etapa, lógica de veredicto, disciplina de caché y el contrato de fallo suave.
• docs/known-limitations.md — todas las formas conocidas en que el escáner puede equivocarse y por qué.
• docs/rate-limiting.md — las lecciones de límite de velocidad de NVD como guía del operador y tabla de ajuste.
• docs/rmm-adapters.md — el contrato de entrada, las dos rutas de inventario integradas y cómo agregar un adaptador nativo.
• docs/HISTORY.md — historial de versiones condensado y desinfectado y las lecciones de ingeniería detrás de cada lanzamiento.

Contribuciones

Se aceptan PRs — sobre todo adaptadores de RMM. Consulta CONTRIBUTING.md para las reglas básicas y el requisito de dirección segura (la lógica de estado solo puede errar hacia más visibilidad, nunca en silencio hacia PATCHED).

Fuentes de datos y atribución

Esta herramienta solo es tan útil como las fuentes gratuitas y autorizadas con las que se une. Cada una de las siguientes se consulta en el momento del escaneo; respeta sus términos si construyes sobre esto.

• NIST National Vulnerability Database (NVD) — registros CVE y rangos de versiones afectadas, a través de la API de NVD. Este producto utiliza la API de NVD pero no está respaldado ni certificado por la NVD. https://nvd.nist.gov/
• CISA Known Exploited Vulnerabilities (KEV) Catalog — la lista autorizada de CVEs que se sabe que se explotan en la naturaleza. https://www.cisa.gov/known-exploited-vulnerabilities-catalog
• CVE Program — cvelistV5 — registros CVE más los datos SSVC / vulnrichment aportados por el ADP de CISA. CVE® es una marca registrada de The MITRE Corporation. https://github.com/CVEProject/cvelistV5
• SSVC (Stakeholder-Specific Vulnerability Categorization) — la lógica de decisión act / attend / track en esta herramienta se deriva de CERT/CC SSVC (Software Engineering Institute de la Universidad Carnegie Mellon) y el árbol de decisiones del Coordinador SSVC de CISA, versión 2.0.3. Se requiere atribución a CERT/CC y CISA. https://www.cisa.gov/ssvc · https://github.com/CERTCC/SSVC
• FIRST.org EPSS (Exploit Prediction Scoring System) — probabilidad de explotación en los próximos 30 días. Los datos de EPSS son proporcionados por FIRST. Ver Jay Jacobs, Sasha Romanosky, Benjamin Edwards, Michael Roytman, Idris Adjerid (2021), Exploit Prediction Scoring System, Digital Threats: Research and Practice, 2(3). https://www.first.org/epss/
• Microsoft Security Response Center (MSRC) — la API CVRF, utilizada para confirmar cuándo una actualización de seguridad de Microsoft ya cubre un hallazgo. © Microsoft Corporation. https://api.msrc.microsoft.com/ · https://msrc.microsoft.com/
• endoflife.date — fechas de fin de vida útil y fin de soporte para software que nunca volverá a recibir parches. Datos cortesía del proyecto endoflife.date. https://endoflife.date/

Licencia

Apache-2.0 — consulta LICENSE.