Vigía

Control de calidad continuo para los datos de modelos de ciberseguridad.

Vigía revisa los datasets con los que se entrenan los detectores de intrusiones y responde una pregunta incómoda: ¿este 0.99 de F1 es real, o es un artefacto de los datos?

La investigación sobre los datasets más usados del área (CIC-IDS2017, CSE-CIC-IDS2018, UGR'16) documenta duplicados masivos, etiquetas incorrectas, fugas entre entrenamiento y prueba, y columnas que le delatan la respuesta al modelo. El resultado es siempre el mismo: el modelo parece excelente en el laboratorio y falla en una red real.

Estado: v0.2.0 — los tres módulos implementados y validados contra datos reales. El auditor cubre los diez requisitos P0, más los lectores de Zeek, Suricata EVE y PCAP (R13 y R14). El monitor de deriva está medido sobre los cinco días de CIC-IDS2017, y los detectores de envenenamiento sobre ataques inyectados en ese mismo tráfico y sobre el ruido de etiqueta que documentaron Engelen et al. Los números están en benchmarks/RESULTADOS.md, incluidos los casos donde el rendimiento es pobre.

Los tres módulos

24 checks, 8 correcciones automáticas y la comparación de rendimiento antes/después.

Instalación

pip install -e ".[dev]"      # desde el repositorio
vigia --help

Requiere Python 3.11 o superior.

Uso

# Auditar un dataset (las columnas se detectan solas por nombre)
vigia audit data/flows.csv --report out/

# Indicar las columnas explícitamente
vigia audit data/flows.parquet \
  --label-col Label --split-col split --time-col Timestamp \
  --report out/

# Correr solo una categoría de checks
vigia audit data/flows.csv --checks leak,dup

# En CI: salir con código 1 si hay hallazgos críticos
vigia audit data/train.csv --fail-on critical

# Listar los checks disponibles
vigia checks

Desde Python:

import vigia

ctx = vigia.load("data/flows.parquet", label_col="Label", split_col="split")
report = vigia.audit(ctx)

print(report.traffic_light())  # 'rojo' | 'amarillo' | 'verde' | 'gris'
print(report.counts())  # {'critical': 2, 'high': 1, ...}

from vigia.report import write_report

write_report(report, "out/")  # report.html + report.json

Qué revisa hoy

Cada hallazgo trae severidad, métrica, filas afectadas, ejemplos concretos y una recomendación. Un check que no puede correr (falta la columna de split, por ejemplo) no falla en silencio: aparece en la sección "checks no ejecutados" del reporte.

El semáforo

El gris existe porque "no encontré nada" y "está limpio" no son lo mismo. Si la columna de etiqueta o la de split no se detectan, los checks que se saltan son justamente los que buscan fuga y duplicados entre conjuntos: dar verde ahí sería confirmar que el dataset está bien cuando en realidad casi no se lo revisó. Si el semáforo da gris, especificá las columnas a mano con --label-col y --split-col.

Corregir

Los hallazgos nombran su corrección. vigia fix las aplica:

# Ver las disponibles
vigia fixes

# Aplicarlas en cadena; el archivo original nunca se toca
vigia fix data/flows.csv \
  --apply drop_duplicates,drop_constant,drop_identifiers \
  --out data/flows_corregido.parquet

Las filas con etiqueta dudosa nunca se borran: quarantine_noise las deja en un archivo aparte para que una persona las revise.

Medir cuánto del rendimiento era real

from vigia.benchmark import compare

c = compare(ctx, ["drop_identifiers"])
print(c.summary())
print(c.after.per_class_recall)

Entrena el mismo modelo antes y después de corregir. Una caída no significa que las correcciones empeoraron el modelo: significa que el número original estaba inflado. Sobre CIC-IDS2017, cambiar un split aleatorio por uno temporal lleva el recall de DoS Hulk, PortScan y DDoS de ~0,95 a 0,00 — ver benchmarks/RESULTADOS.md.

Formatos de entrada

Archivo suelto o carpeta completa: los datasets CIC vienen partidos en un archivo por día, Vigía los concatena y conserva la procedencia en __source_file. Los PCAP se leen de a uno, porque extraer flujos tarda minutos.

Detalles de cada formato en docs/USO.md.

Desarrollo

pip install -e ".[dev,ml]"

pytest                 # pruebas
ruff check src tests   # lint
ruff format src tests  # formato
mypy src               # tipos

Agregar un check nuevo es una clase con cuatro atributos y un método. El registro es automático al importarse el módulo desde vigia/checks/__init__.py. Los detalles están en docs/ARQUITECTURA.md.

Documentación

Documento de diseño

El diseño completo — los tres módulos (auditor, envenenamiento, deriva), la arquitectura, el plan por fases y las referencias académicas — está en vigia.md.

Licencia

Apache 2.0.