dobybaxter127/nimbus-vestigeUn motor de reconstrucción forense para la respuesta a incidentes en la nube y de identidad.
Un motor de reconstrucción forense para la respuesta a incidentes en la nube y de identidad.
Dada una telemetría fragmentada de la nube, SaaS e identidad — registros del plano de control, eventos de inicio de sesión, actividad de tokens y consentimiento — NV reconstruye cómo una intrusión se movió más probablemente a través de cuentas y servicios, enumera las otras rutas más probables que podría haber tomado, y reporta cada paso con una confianza calibrada y explicable. Se niega a afirmar lo que la evidencia no puede respaldar.
La detección te dice que algo sucedió. Nimbus Vestige te dice cómo — y qué más.
Las intrusiones modernas no "irrumpen". Inician sesión. La identidad es ahora el principal vehículo de ataque, implicada en la gran mayoría de las investigaciones de respuesta a incidentes en la nube, y la mayoría de las intrusiones abarcan múltiples superficies — identidad más nube más SaaS más endpoint. La telemetría que las registra es fragmentada e inconsistente, lo que ya obliga a los respondedores a reconstruir la historia manualmente a partir de datos incompletos.
Esa reconstrucción manual es lenta y falla de una manera predecible: el respondedor se ancla en la primera narrativa plausible y pierde la real. NV automatiza la reconstrucción y ataca directamente ese modo de fallo al presentar siempre el espacio clasificado de rutas plausibles, no una única historia.
Fundamentalmente, NV hace esto con honestidad como producto. El enemigo declarado del mercado es la confianza de caja negra — una herramienta que afirma una conclusión sin mostrar su trabajo. Cada número que NV produce es rastreable a la evidencia específica que lo generó, y cualquier cosa que no pueda respaldar se omite en lugar de adivinarse.
NV no es un detector, un escáner, un auditor ni un ejecutor de ataques. Esas herramientas te dicen que algo sucedió y lo miden. NV trabaja hacia atrás — reconstrucción abductiva del mecanismo a partir de patrones, a través de un patrimonio de identidad fragmentado.
El equipo azul se regenera; el equipo rojo se mercantiliza. Las herramientas ofensivas encuentran un conjunto finito y parcheable de huecos y se están integrando en pipelines automatizados de seguridad CI/CD. Reconstruir cómo ocurrió una intrusión nunca se resuelve — los atacantes siguen inventando, por lo que la necesidad es permanente y se renueva sola.
El motor es independiente del sustrato. La lógica central — reconstruir el mecanismo a partir de patrones, con confianza calibrada y un tope de seguridad — está comprometida con la nube/identidad primero, pero se traslada a red, endpoint y OT después. El objetivo puede cambiar sin reescribir la tesis.
La reconstrucción permite el endurecimiento. Una vez que sabes cómo entraron — y qué otras puertas estaban abiertas — construyes las defensas. Las rutas no tomadas pero plausibles son un backlog de endurecimiento, a menudo más valioso que la propia reconstrucción, porque la mayoría de las brechas explotan exposición prevenible, no tácticas novedosas.
Se degrada con elegancia ante la intrusión novedosa — el incidente que más importa. Un motor de firmas/reglas se queda ciego ante un día cero; el núcleo abductivo de NV aún produce una ruta más probable, marcada honestamente como de menor confianza.
La honestidad es un foso. La confianza calibrada y basada en casos con alternativas clasificadas es exactamente lo que el mercado dice querer y lo que los competidores de caja negra estructuralmente no pueden ofrecer sin rediseñar.
Registros crudos del proveedor → grafo normalizado de eventos/entidades → motor de reconstrucción → JSON → GUI.``` O365 / Entra audit logs nv_extract_identity_events.py AWS CloudTrail (IAM/STS/S3) nv_extract_cloudtrail_events.py (ingest + normalize) ▼ normalized identity events (JSONL) ← one event model, any substrate │ nv/graph.py (typed per-actor timelines) ▼ reconstruction engine ├─ nv/patterns.py known layer: ATT&CK identity pattern library ├─ nv/providers.py provider packs: per-substrate op→ATT&CK vocab (Entra + AWS) ├─ nv/validation.py Phase 3: provenance + integrity gate on every pattern ├─ nv/feeds.py live ATT&CK STIX / TAXII / Sigma clients + scheduler ├─ nv/confidence.py evidence-corroboration scorer (calibratable weights) ├─ nv/calibration.py fit + measure confidence against labeled ground truth ├─ nv/reconstruct.py most-likely chain + ranked competing paths + trust floor └─ nv/scope.py authorized-scope gate (refuses unauthorized tenants/accounts) │ run_nv.py ▼ reconstruction.json ──► nv_gui.html (embedding canvas + two-column view + trust slider)
La GUI es una **capa de vista pura**: renderiza la salida del motor y permite al analista mover
el umbral de confianza. No contiene lógica de reconstrucción propia.
---
## El modelo de confianza (la credibilidad de todo el producto)
Cada paso lleva una confianza en [0, 1], construida mediante **corroboración de evidencia**:```
confidence = per-technique base rate
+ bonus for each independent corroborating signal
(source IP, device, successful outcome, temporal adjacency, broad-consent flags)
− penalty for missing signals (e.g. no source IP to corroborate origin)
Las puntuaciones de ruta componen sus enlaces mediante media geométrica, por lo que un enlace débil arrastra honestamente una ruta hacia abajo en lugar de promediarse.
Cada peso anterior — las tasas base por técnica, los bonos por señal, las penalizaciones por ausencia — vive en una única tabla PARAMS en nv/confidence.py. Esos son los priors v1 de NV, y son calibrables: nv/calibration.py puede reajustarlos contra verdad fundamental etiquetada y el motor cargará el resultado, recurriendo a los priors v1 cuando no se suministre calibración (ver más abajo).
La regla de retención, integrada en el contrato de salida del motor — no solo en la interfaz. Por debajo del umbral, un paso se retiene. Arrastrar el umbral es el equilibrio honestidad-versus-cobertura hecho físico: hacia arriba para alta confianza/estricto, hacia abajo para permisivo/alta cobertura. El umbral predeterminado es una decisión editorial sobre dónde se sitúa NV antes de que el analista lo toque.
Los pesos v1 son defendibles, pero son priors. nv/calibration.py los ajusta contra verdad fundamental etiquetada — eventos donde sabemos cuáles formaban parte de la intrusión y cuáles eran benignos — y, crucialmente, mide si el ajuste realmente ayudó, de modo que una calibración se adopta solo si reduce el error de calibración en lugar de solo mover números.
La confianza calibrada significa una cosa: la confianza de NV para un paso debe igualar la probabilidad de que el paso realmente estuviera en la ruta de ataque. Así, la confianza de cada evento etiquetado se trata como una probabilidad predicha, y el marco ajusta:
Los umbrales verificado/retenido son política, no calibración, y se dejan intactos.
Informa puntuación de Brier, log-loss, ECE, AUC, una tabla de fiabilidad y un barrido del umbral de confianza (recall de pasos verdaderos vs tasa de falsos positivos benignos en cada umbral), antes y después — para que el equilibrio honestidad-versus-cobertura sea legible en lugar de un solo número.```bash
python3 calibrate.py --labeled run_labeled.jsonl --origin live
--run-label "badzure-2026-07 tenant-x" --out calibration.json
python3 calibrate.py --out calibration.json
python3 run_nv.py events.jsonl out.json --authorize t.onmicrosoft.com
--calibration calibration.json
**Fuente de verdad.** La entrada honesta es telemetría de una ejecución de BadZure / MAAD-AF en un
tenant real, etiquetada al unir el registro de auditoría unificado con el propio registro de
actividad de la herramienta de ataque (cada evento que la herramienta causó está en cadena; todo lo demás es benigno — ver
`LABELED_SCHEMA` en `nv/calibration.py`). Hasta que la apuntes a una ejecución real,
`eval/calibration_cases.py` suministra un corpus **proxy** de forma documentada, y cada
artefacto ajustado a partir de él lleva la marca `source="proxy"` en su procedencia, de modo que un ajuste proxy
nunca pueda confundirse con uno real. `calibration.proxy.json` es ese artefacto proxy incluido.
En el corpus proxy incluido, el ajuste es una clara mejora — Brier 0.398 → 0.045, ECE
0.576 → 0.081, AUC 0.81 → 0.91, y la tasa de falsos positivos benignos en el umbral de 0.60
se desploma de 0.69 a 0.00 (los priors v1 estaban muy sobreconfiados en actividad benigna).
El proxy es deliberadamente conservador; una ejecución en tenant real es lo que produce los pesos que
deberías implementar realmente.
## Integridad de confianza (Fase 3)
Dos controles de primera clase protegen la reconstrucción de entradas malas:
- **Puerta de alcance autorizado** (`nv/scope.py`) — NV se niega a ejecutarse en cualquier infraestructura que no esté en la
lista autorizada. Ejecuta con `--authorize <tenant-domain>` por cada infraestructura que tengas permitido
investigar.
- **Validación de fuente de patrones** (`nv/validation.py`) — ningún patrón entra en la biblioteca
sin pasar: (1) lista blanca de fuentes confiables, (2) checksum de contenido / verificación de manipulación,
(3) buena formación del esquema, (4) id de técnica válido estilo ATT&CK. Cada patrón
admitido mantiene un registro de auditoría; los rechazados se registran con un motivo. Un
feed envenenado o malformado se detiene upstream antes de que pueda fabricar una reconstrucción falsa.
Este es el mismo escepticismo que el motor aplica a la evidencia, trasladado a los propios patrones.
---
## Mantener el conocimiento actualizado (adelantarse a la evolución del atacante)
Un motor de reconstrucción solo está tan actualizado como su biblioteca de patrones más su capacidad para
manejar lo que la biblioteca nunca ha visto. NV aborda la obsolescencia en **dos frentes
independientes**, por diseño:
### 1. La capa conocida se mantiene fresca mediante un pipeline de actualización validado
La biblioteca no está codificada — `nv/patterns.py` carga cada patrón (incluido el
conjunto integrado) a través de `nv/validation.py`, de modo que los feeds externos entran por la misma ruta
confiable. Los clientes de red en vivo que extraen estos feeds según un horario se implementan en
`nv/feeds.py` y se gestionan mediante `update_feeds.py`. Fuentes, en niveles de confianza:
- **MITRE ATT&CK (STIX)** — la taxonomía de técnicas autoritativa. El conector lee
el índice STIX de ATT&CK, extrae la última versión enterprise y actualiza el
nombre de técnica autoritativo y la táctica para cada operación sobre la que NV razona —
descartando cualquier técnica que ATT&CK haya revocado o deprecado desde entonces. NV mantiene
la propiedad del vínculo operación→técnica y el prior de tasa base; ATT&CK posee
la taxonomía.
- **CTI verificado vía TAXII 2.1** — un cliente completo de descubrimiento → api-root → colección → objetos.
Extrae objetos STIX attack-pattern de una colección CTI verificada y actualiza
las técnicas que NV rastrea. Ponderado por debajo de ATT&CK.
- **Conjunto de reglas comunitario Sigma** — extraído como archivo git; cada regla de nube/identidad que
nombre una operación de O365/Entra y lleve una etiqueta `attack.tXXXX` se convierte en un
candidato operación→técnica, con una tasa base derivada del propio `level` de severidad
de la regla y luego reducida por el peso de la fuente comunitaria. Las reglas que no se asignan se
omiten con un motivo, nunca se adivinan.
En una colisión de operaciones, la unión se ordena por confianza ascendente antes del commit, de modo que un
vínculo ATT&CK autoritativo siempre gana sobre uno comunitario; el contenido de nivel inferior aún se
admite y se registra en la auditoría como corroboración. `update_library(candidates)`
re-ingiere todo el conjunto a través de la validación y reconstruye la biblioteca atómicamente, de modo que un
feed envenenado nunca pueda dejar la biblioteca a medio actualizar.
**Dos listas blancas, no una.** La validación ya filtra por la etiqueta de fuente; los conectores
añaden una lista blanca de *hosts* a nivel de red, de modo que un conector solo pueda obtener datos de un host
confiable a través de TLS — el equivalente de transporte de la lista blanca de fuentes, y una protección contra una
URL de feed secuestrada o mal escrita. Cada obtención registra el sha256 del payload bruto, la URL y la hora
como procedencia, de modo que una re-obtención posterior pueda detectar mutaciones upstream.
**Por qué la capa de validación importa más a medida que crecen los feeds:** cuanto más automatices
las actualizaciones, más se convierte un pipeline de auto-actualización en un riesgo de confianza disfrazado — un
feed incorrecto o envenenado inyecta patrones falsos y fabrica reconstrucciones falsas. NV trata
la ingesta como adversarial: lista blanca, checksum, esquema y rastro de auditoría en cada patrón,
cada actualización.
### 2. La capa abductiva cubre lo que ningún feed ha nombrado aún
Los feeds siempre van por detrás de las tácticas más nuevas. El núcleo abductivo es la cobertura: cuando una
operación observada no coincide con **ningún** patrón de la biblioteca, NV no la descarta — reconstruye
la ruta más probable desde primeros principios y la marca `no known match` con confianza
reducida. Esto se valida en el conjunto de evaluación (`eval/ground_truth_cases.py`), donde un
paso de robo de token de identidad gestionada deliberadamente desconocido se detecta, se secuencia correctamente,
y se pondera a la baja honestamente por debajo del umbral de confianza.
Juntos, estos significan que NV nunca queda completamente obsoleto: la capa conocida rastrea la frontera
publicada a través de un pipeline resistente al envenenamiento, y la capa abductiva evita que la herramienta
se quede ciega ante la intrusión que la frontera aún no ha alcanzado.
### Cadencia de actualización sugerida
`nv/feeds.py` lleva una cadencia por feed y `update_feeds.py` solo extrae lo que corresponde,
de modo que puede integrarse directamente en cron o en un temporizador systemd:
- ATT&CK STIX — 90 días (unas pocas versiones oficiales al año).
- CTI/TAXII — 7 días (según publique el feed), siempre a través de validación.
- Sigma — 30 días.```bash
# run whatever is due, keeping state under ./.nv_feeds (cron-friendly)
python3 update_feeds.py
# force all feeds now but only report what would change
python3 update_feeds.py --force --dry-run
# run fully offline against captured fixtures (no network)
python3 update_feeds.py --offline eval/fixtures --force
Después de cualquier cambio en la biblioteca, vuelve a ejecutar eval/run_eval.py para confirmar que las formas de ataque conocidas siguen reconstruyéndose, eval/validation_cases.py para confirmar que la puerta sigue rechazando entradas incorrectas y eval/feeds_offline_test.py para confirmar que la ruta de alimentación está intacta de principio a fin.
La reconstrucción mostrada en nv_gui.html se basa en un conjunto de datos de investigación público
— el corpus de registros de auditoría unificada de Office 365 de invictus-ir — no en el inquilino
en vivo de ninguna empresa. Existe para que el motor pueda demostrarse y probarse internamente de principio a fin sin
la cooperación de nadie. Para usar NV en un entorno real, una organización conecta sus propios datos de auditoría de Entra/M365,
como se describe a continuación. No se incluyen datos propietarios ni de clientes en ningún lugar de
este proyecto.
NV se ejecuta dondequiera que lo ejecutes; tus registros nunca tienen que salir de tu entorno. Cuatro pasos:
1 — Exporta tus registros de auditoría. NV lee el registro de auditoría unificada de Microsoft 365. Obténlo
de Microsoft Purview (Búsqueda de auditoría → exportar CSV), el cmdlet Search-UnifiedAuditLog
de Exchange Online PowerShell, los endpoints auditLogs / signIns
de Microsoft Graph, o una exportación de Sentinel/SIEM de OfficeActivity y SigninLogs.
2 — Normalízalo al modelo de eventos sobre el que NV razona:```bash python3 nv_extract_identity_events.py your_audit_export.csv your_events.jsonl
Esto conserva los inicios de sesión, las concesiones de consentimiento, los cambios de entidades de servicio y de roles, y el acceso al buzón
— incluidas las operaciones de identidad que NV nunca ha nombrado, por lo que aún llegan a la
capa abductiva — y descarta el resto. Lee un CSV que contiene la columna estándar `AuditData`,
o JSON/JSONL donde cada registro es un objeto `AuditData` (la forma en la que se
distribuye el corpus de investigación de invictus-ir).
**3 — Reconstrucción, limitada por ámbito.** El motor se niega a ejecutarse en un inquilino que no hayas
autorizado explícitamente:```bash
python3 run_nv.py your_events.jsonl reconstruction.json \
--authorize yourtenant.onmicrosoft.com
4 — Vista. Abre nv_gui.html y haz clic en ⤒ load reconstruction.json para apuntarlo al
archivo que acaba de generar el motor — la misma pantalla muestra entonces tu incidente, tus
entidades y tus bandas de confianza. Cada punto en el lienzo de incrustación vuelve a ejecutar la
reconstrucción para esa entidad al hacer clic.
El motor es independiente del sustrato — solo el vocabulario de operaciones es específico del proveedor
(nv/providers.py). La ruta de AWS son los mismos tres pasos contra CloudTrail:```bash
python3 nv_extract_cloudtrail_events.py cloudtrail.json aws_events.jsonl
python3 run_nv.py aws_events.jsonl reconstruction.json --authorize aws:123456789012
La ingesta conserva los eventos de IAM/STS/inicio de sesión (incluidas las operaciones IAM novedosas, para que lleguen a la capa abductiva) además de las lecturas de objetos S3, y limita el alcance a la **cuenta** de AWS en lugar de un dominio de inquilino. El mismo núcleo abductivo, modelo de confianza y umbral de confianza se aplican sin cambios.
La GUI también incluye un **banner de datos de demostración** y una guía dentro de la aplicación "Conecta tus propios datos", para que cualquiera que la abra entienda que la reconstrucción son datos de muestra públicos hasta que conecte los suyos.
## Estructura del proyecto```
run_nv.py reconstruction engine entrypoint (scope-gated)
nv_extract_identity_events.py ingest: M365/Entra unified audit log -> event model
nv_extract_cloudtrail_events.py ingest: AWS CloudTrail -> event model [iteration 3]
update_feeds.py pull + validate threat-intel feeds on a cadence [iteration 1]
calibrate.py fit confidence weights from labeled ground truth [iteration 2]
nv/ the engine package
graph.py patterns.py validation.py confidence.py reconstruct.py scope.py
providers.py per-substrate op->ATT&CK vocabulary packs (Entra + AWS) [iteration 3]
feeds.py ATT&CK STIX / TAXII 2.1 / Sigma clients + scheduler [iteration 1]
calibration.py metrics + parameter fit [iteration 2]
eval/ evals + offline fixtures (no network, no tenant)
nv_gui.html pure view layer (loads engine reconstruction.json)
calibration.proxy.json bundled proxy calibration artifact [iteration 2]
Ejecuta todo desde la raíz del proyecto para que el paquete nv sea importable.
python3 nv_extract_identity_events.py auditrecords.csv nv_identity_events.jsonl
python3 run_nv.py nv_identity_events.jsonl reconstruction.json
--trust-floor 0.6 --authorize your-tenant.onmicrosoft.com
Mantén la biblioteca de patrones actualizada y ajusta la confianza:```bash
python3 update_feeds.py # pull + validate feeds that are due
python3 calibrate.py --labeled run.jsonl --origin live --out calibration.json
python3 eval/run_eval.py # attack shapes reconstruct correctly python3 eval/validation_cases.py # poisoned patterns are rejected python3 eval/feeds_offline_test.py # feed connectors + scheduler (offline) python3 eval/providers_aws_test.py # AWS chain reconstructs through the same engine python3 calibrate.py # calibration harness on the bundled proxy corpus
---
## Estado
**Funciona de extremo a extremo con datos reales** (conjunto de datos O365 de invictus-ir), en todo el plan:
| Fase | Elemento | Estado |
|---|---|---|
| 1 | Modelo normalizado de eventos/entidades | hecho |
| 1 | Ingesta + normalización (cabeza de playa Entra/M365) | hecho |
| 2 | Capa conocida (biblioteca de patrones ATT&CK) | hecho |
| 2 | Modelo de confianza por corroboración de evidencia | hecho |
| 2 | Piso de confianza en el contrato de salida | hecho |
| 2 | Núcleo abductivo (capa desconocida) | hecho, probado por evaluación |
| 2 | Hipótesis competidoras clasificadas | hecho |
| 3 | Capa de validación de fuentes de patrones | hecho |
| 3 | Control de alcance autorizado | hecho |
| 3 | Conectores de fuentes en vivo (ATT&CK STIX / TAXII / Sigma) + programador | hecho |
| 4 | Pantalla de dos columnas sobre salida real del motor | hecho |
| 4 | Lienzo de incrustaciones / similitud | hecho |
| 4 | Reconstrucción por entidad impulsada por lienzo (clic re-ejecuta la cadena) | hecho |
| 4 | La GUI carga `reconstruction.json` del motor (apúntala a tu archivo) | hecho |
| 4 | Sustrato multi-proveedor (AWS CloudTrail, probado por evaluación) | hecho |
| 5 | Estética / tematización | hecho |
| 5 | Banco de pruebas de calibración de confianza + integración con el motor | hecho |
### Brechas conocidas honestas (próximas iteraciones)
- **Números de calibración de tenant en vivo.** El *banco de pruebas* de calibración está
completo y la interfaz está probada, pero el `calibration.proxy.json` incluido está
ajustado con datos proxy de forma documentada. Los pesos desplegables requieren ejecutar
el banco de pruebas contra una ejecución real de BadZure / MAAD-AF — un paso operativo
para quien adopte la herramienta.
- **Crecimiento del vocabulario impulsado por fuentes.** Los conectores actualizan la NV
de operaciones sobre la que el motor ya razona; permitir que una fuente *introduzca* una
nueva operación (y la conecte a la clasificación inicial/pivote/colección) es trabajo futuro.
- **Profundidad del segundo proveedor.** AWS está incluido como prueba de independencia del
sustrato (paquete + ingesta + evaluación), pero solo IAM/STS/S3. Ampliar el paquete de AWS,
añadir conectores de fuentes específicos del proveedor y un tercer sustrato (GCP, Okta)
son los siguientes pasos.
---
## Licencia
Nimbus Vestige es **de código disponible** bajo la **Licencia PolyForm No Comercial
1.0.0** (ver [LICENSE](https://gitlab.com/dobybaxter127/nimbus-vestige/-/blob/main/LICENSE)). Toda la herramienta — motor de reconstrucción, ambas
ingestas de proveedores, GUI y banco de pruebas de evaluación — es libre de inspeccionar,
ejecutar y usar para cualquier propósito **no comercial**: proyectos personales,
investigación, educación, organizaciones sin fines de lucro y evaluación. Lee cada línea
antes de decidir.
**El uso comercial requiere una licencia de pago** — usarla en un producto o servicio que
vendas u hospedes, dentro de los sistemas de producción o internos de una empresa con fines
de lucro, o en compromisos de respuesta a incidentes o con clientes remunerados. Ver
[COMMERCIAL-LICENSE.md](https://gitlab.com/dobybaxter127/nimbus-vestige/-/blob/main/COMMERCIAL-LICENSE.md).
---
### Autor
Doby Baxter 2026