Skip to content

About

Kernel-grade antimalware service and memory analysis engine in modern safe Rust (Win32 API, ETW, WFP, YARA-X, Wasmtime).

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

14 Commits

Folders and files

Repository files navigation

🛡️ antimalware-core (v0.8.0)

Motor Antimalware y Cortafuegos Kernel-Assisted para Windows escrito en Rust.
Escaneo estático YARA-X (Wasmtime), Inteligencia Heurística PE (Entropía + Authenticode), Cuarentena Transaccional con DACLs, Telemetría ETW y Firewall Activo WFP.

CI Rust Windows Tests Clippy License: MIT Security: AGENTS.md


📋 Resumen Ejecutivo

antimalware-core es un Servicio Nativo de Windows (NT AUTHORITY\SYSTEM) de huella mínima (< 20 MB RAM en reposo, 0 crates externos no auditados) diseñado bajo una filosofía Zero-Trust Host Security: todo cliente IPC se considera hostil hasta validar su imagen de proceso en el kernel, toda regla de análisis se ejecuta aislada en sandbox WebAssembly, y todo recurso del sistema operativo (handles Win32, sesiones ETW, descriptores criptográficos y memoria del motor BFE) está gobernado por semántica RAII determinista.

✨ Características Principales

Subsistema Tecnología Nativa Capacidades Clave Estado
Servidor IPC Blindado Win32 Named Pipes + Tokio IOCP Handoff Make-Before-Break (refcount: 1 → 2 → 1), DACL restrictiva sin FILE_CREATE_PIPE_INSTANCE para clientes (0x0012_019B), rechazo SMB (PIPE_REJECT_REMOTE_CLIENTS) y validación de PID/ruta (QueryFullProcessImageNameW). ✅ Producción
Motor Estático YARA-X yara-x (Wasmtime Sandbox) + ignore::WalkParallel Recorrido paralelo multi-hilo sin seguir symlinks, límite anti-DoS de 64 MB por archivo, exclusión de directorios críticos del servicio (Rules y Quarantine) y cancelación determinista RAII (Drop en ActiveScan). ✅ Producción
Analizador Heurístico PE Entropía de Shannon + WinVerifyTrust (Win32_Security_WinTrust) Detección de empaquetadores/crypters/ransomware (> 7.20 bits/byte) con defensa contra Entropy Padding (truncado de cola nula + ventanas de 64 KB) y verificación criptográfica Authenticode 100% offline (WTD_UI_NONE + WTD_CACHE_ONLY_URL_RETRIEVAL). ✅ Producción
Bóveda de Cuarentena SetNamedSecurityInfoW + SHA-256 (sha2) Aislamiento atómico intra-volumen o transaccional multi-volumen con verificación SHA-256 post-copia, rollback automático ante fallos y DACL protegida (SE_DACL_PROTECTED: solo SYSTEM y Administrators). ✅ Producción
Firewall Activo WFP Windows Filtering Platform (FwpmFilterAdd0 / FwpmFilterEnum0) Bloqueo real en el motor BFE (FWPM_LAYER_ALE_AUTH_CONNECT_V4 / RECV_ACCEPT_V4) sobre subcapa dinámica propia (ANTIMALWARE_SUBLAYER_GUID, peso 0xFFFF), evaluación en Host Byte Order y desbloqueo por ID o por IP/CIDR. ✅ Producción
Monitor Kernel ETW Event Tracing for Windows (StartTraceW / ProcessTrace) Captura en tiempo real de creación/terminación de procesos y carga de imágenes (Microsoft-Windows-Kernel-Process), ring-buffer de eventos y limpieza CloseTrace + ControlTraceW. ✅ Producción
CLI Unificada (am) Binario nativo tipado (src/bin/am.rs) Comandos directos (scan, status, quarantine, firewall, service) + Centro de Control TUI interactivo. ✅ Producción

🏗️ Arquitectura del Sistema

flowchart LR
    subgraph UserSpace["Espacio de Usuario (Sesión Interactiva)"]
        CLI["CLI Unificada (am.exe)<br/>scan | firewall | status | quarantine"]
    end

    subgraph KernelIPC["Frontera IPC (npfs.sys)"]
        PIPE["Named Pipe: \\.\pipe\antimalware_core_ipc<br/>Make-Before-Break (refcount 1→2→1)<br/>DACL: SYSTEM (Full) + INTERACTIVE (0x0012019B)<br/>PID Whitelist (QueryFullProcessImageNameW)"]
    end

    subgraph Service["Servicio Windows: AntimalwareCoreService (Session 0 — LocalSystem)"]
        SERVER["IpcServer (Tokio Async)<br/>Framing LE 4B + JSON Tipado"]

        subgraph ScannerSub["Subsistema de Análisis Estático y Heurístico"]
            ENGINE["ScanEngine<br/>(ignore::WalkParallel)"]
            YARA["YARA-X Engine<br/>(Wasmtime Sandbox)"]
            HEUR["PE Heuristics<br/>(Shannon Anti-Padding + WinVerifyTrust)"]
            VAULT["QuarantineVault<br/>(SHA-256 + Protected DACL)"]
        end

        subgraph NetworkSub["Subsistema de Red"]
            WFP["WfpManager (BFE)<br/>Subcapa Dinámica (Weight 0xFFFF)<br/>ALE_AUTH_CONNECT_V4 (Host Byte Order)"]
        end

        subgraph TelemetrySub["Subsistema de Telemetría"]
            ETW["EtwMonitor<br/>Microsoft-Windows-Kernel-Process<br/>Ring-Buffer (256 eventos)"]
        end
    end

    CLI <==>|"IpcRequest / IpcResponse"| PIPE
    PIPE <==> SERVER
    SERVER --> ENGINE
    ENGINE --> YARA
    ENGINE --> HEUR
    YARA -->|"Amenaza Confirmada"| VAULT
    HEUR -->|"Entropía > 7.2 + Sin Firma<br/>(--paranoid)"| VAULT
    SERVER --> WFP
    SERVER --> ETW
Loading

Estructura del Repositorio

antimalware-core/
├── src/
│   ├── main.rs                 ← Entry point dual: Servicio SCM Windows y modo --console
│   ├── lib.rs                  ← Exportación modular de la librería
│   ├── bin/
│   │   ├── am.rs               ← CLI oficial unificada (tipado extremo a extremo con protocol.rs)
│   │   └── ipc_client.rs       ← Cliente de diagnóstico e integración IPC
│   ├── common/
│   │   ├── errors.rs           ← Tipo unificado CoreError / CoreResult (cero proc-macros externas)
│   │   └── handles.rs          ← Wrapper RAII SafeHandle para HANDLEs Win32
│   ├── ipc/
│   │   ├── server.rs           ← Servidor asíncrono Named Pipe + streaming de eventos + ActiveScan RAII
│   │   ├── protocol.rs         ← Contrato tipado IpcRequest / IpcResponse / FilterRule
│   │   └── security.rs         ← Construcción de DACL explícita + Make-Before-Break + validación PID
│   ├── scanner/
│   │   ├── engine.rs           ← Orquestador YARA-X + Heurística PE + exclusión de rutas protegidas
│   │   ├── heuristics.rs       ← Entropía de Shannon (Anti-Padding 64 KB) + Authenticode WinVerifyTrust
│   │   ├── quarantine.rs       ← Bóveda transaccional multi-volumen + DACL SE_DACL_PROTECTED
│   │   └── events.rs           ← Stream de eventos ScanEvent (ThreatDetected, HeuristicWarning, etc.)
│   ├── capture/
│   │   └── wfp.rs              ← Firewall WFP nativo (Subcapa dinámica, Host Byte Order, paginación BFE)
│   └── monitor/
│       ├── etw.rs              ← Consumidor ETW en tiempo real + CloseTrace / ControlTraceW
│       └── events.rs           ← Tipos de eventos de proceso y GUIDs del proveedor kernel
├── rules/
│   └── sample.yar              ← Reglas YARA base (EICAR, PowerShell EncodedCommand, mimikatz)
├── scripts/
│   └── install-service.ps1     ← Instalador automatizado del Servicio Windows y registro en PATH
├── docs/
│   ├── AGENTS.md               ← Reglas inquebrantables de arquitectura y seguridad kernel
│   └── BRAIN.md                ← Registro de decisiones arquitectónicas (ADR) e invariantes
├── am.cmd                      ← Launcher rápido local
├── Cargo.toml                  ← Manifiesto con dependencias estrictamente auditadas
└── Cargo.lock                  ← Lockfile reproducible para compilación determinista del binario

🚀 Instalación y Despliegue

1. Requisitos del Sistema

  • Sistema Operativo: Windows 10 (1903+) / Windows 11 / Windows Server 2019+.
  • Toolchain: Rust 1.87+ (edición 2021, toolchain stable-x86_64-pc-windows-msvc).
  • Privilegios: Consola de PowerShell con permisos de Administrador para el registro del servicio (LocalSystem), sesiones ETW de kernel y motor WFP.

2. Compilación Optimizada (--release)

git clone https://github.com/HugoSabater/antimalware-core.git
cd antimalware-core
cargo build --release

3. Despliegue Automatizado como Servicio de Windows (Recomendado)

El script install-service.ps1 detiene instancias previas, aprovisiona la estructura segura en C:\ProgramData\AntimalwareCore\, despliega antimalware-core.exe y am.exe, instala las reglas YARA base, registra el servicio AntimalwareCoreService con inicio automático y añade am al PATH del sistema:

# Ejecutar en PowerShell como Administrador
.\scripts\install-service.ps1

4. Ejecución en Modo Consola (Desarrollo / Depuración)

Si deseas ejecutar el demonio directamente en una terminal sin instalar el servicio SCM:

# Terminal 1 (Administrador)
.\target\release\antimalware-core.exe --console

# Terminal 2
.\target\release\am.exe status

💻 Manual de Comandos de la CLI (am)

Una vez instalado el servicio, el comando am está disponible globalmente desde cualquier terminal:

1. Estado de Salud del Sistema (am status)

Verifica la conectividad del Named Pipe IPC, el estado del consumidor kernel ETW, la sesión dinámica del motor WFP y el tiempo de actividad:

PS C:\> am status

╔═══════════════════════════════════════════════════╗
║       📊 ESTADO DE SALUD DEL ANTIMALWARE          ║
╚═══════════════════════════════════════════════════╝
  Canal IPC:          ✅ Operativo (Named Pipe activo)
  Monitor Kernel ETW: ✅ Activo (Microsoft-Windows-Kernel-Process)
  Filtro Red WFP:     ✅ Activo (Sesión dinámica abierta)
  Tiempo activo:      14m 32s
─────────────────────────────────────────────────────

2. Escaneo Estático YARA-X + Heurística PE (am scan <ruta> [--paranoid])

  • Modo estándar (am scan <ruta>): Aísla inmediatamente en cuarentena cualquier archivo que coincida con una regla YARA. Si un ejecutable PE (.exe, .dll, .sys, .scr) no coincide con YARA pero presenta alta entropía (> 7.20 bits/byte) y carece de firma digital Authenticode válida, emite una alerta HeuristicWarning sin destruir el archivo (previniendo falsos positivos en instaladores comprimidos legítimos).
  • Modo paranoico (am scan <ruta> --paranoid): Eleva las alertas heurísticas PE a aislamiento inmediato en la bóveda de cuarentena.
PS C:\> am scan C:\TempTest --paranoid

╔═══════════════════════════════════════════════════════════════════╗
║ 🔍 ANÁLISIS DE AMENAZAS EN TIEMPO REAL                            ║
╚═══════════════════════════════════════════════════════════════════╝
  Objetivo: \\?\C:\TempTest
  Motor:    YARA-X Sandbox + Heurística PE (Entropía + Authenticode) [MODO PARANOICO]
─────────────────────────────────────────────────────────────────────

[✓] Petición aceptada por el motor. Iniciando análisis...
[*] Reglas YARA activas: 3 firmas compiladas.

[!] 🔎 ALERTA HEURÍSTICA PE:
    Archivo:  \\?\C:\TempTest\packed_payload.exe
    Entropía: 8.00 / 8.00 bits/byte
    Firma:    Ausente o no confiable
    Detalle:  High PE entropy (8.00 bits/byte > 7.20) with untrustedsignature (WinVerifyTrust 0x800B0100) — possible packed, encrypted, or obfuscated binary
    [✓] Bóveda: Archivo aislado y bloqueado con DACLs protegidas (Hash: 9f86d081884c7d65...)

3. Gestión del Firewall Activo WFP (am firewall)

Permite bloquear tráfico saliente hacia direcciones IPv4 o rangos CIDR (y puerto remoto opcional) directamente en la capa FWPM_LAYER_ALE_AUTH_CONNECT_V4 del kernel, listar filtros activos y desbloquear tanto por ID de 64 bits como directamente por dirección IP:

# Bloquear todo el tráfico saliente hacia una IP maliciosa
am firewall block-ip 203.0.113.50

# Bloquear tráfico saliente hacia una IP y puerto específico (ej. C2 en 4444 o HTTPS 443)
am firewall block-ip 1.1.1.1 443

# Bloquear una subred completa en notación CIDR
am firewall block-ip 198.51.100.0/24

# Listar todas las reglas activas en la subcapa AntimalwareCore
am firewall list

# Desbloquear automáticamente buscando por dirección IP o CIDR (sin memorizar IDs de 64 bits)
am firewall unblock-ip 1.1.1.1

# Desbloquear por ID numérico de filtro WFP
am firewall unblock 109601

4. Inspección de Bóveda de Cuarentena y Servicio

# Ver registro forense de amenazas aisladas (regla, ruta original, SHA-256 y fecha UTC)
am quarantine

# Controlar el servicio de Windows
am service status
am service restart

# Abrir el Centro de Control interactivo (TUI)
am

🔒 Arquitectura de Seguridad y Modelo de Amenazas

Cada módulo ha sido diseñado frente a un modelo de amenazas explícito documentado en docs/BRAIN.md y en comentarios // SECURITY: y // SAFETY: dentro del código fuente:

ID Vector de Amenaza Mitigación Implementada Ubicación
T1 Pipe Squatting & TOCTOU entre sesiones La primera instancia exige FILE_FLAG_FIRST_PIPE_INSTANCE. Al rotar sesiones se aplica el patrón Make-Before-Break: create_next_secure_pipe() abre la siguiente instancia antes de desconectar y liberar la anterior (refcount: 1 → 2 → 1, jamás 0), eliminando cualquier ventana temporal de secuestro y limpiando el estado IOCP de Tokio/Mio. src/ipc/security.rs src/ipc/server.rs
T2 Creación No Autorizada de Instancias del Pipe La DACL explícita otorga GENERIC_ALL a SYSTEM, pero restringe a INTERACTIVE a la máscara 0x0012_019B (FILE_GENERIC_READ | FILE_GENERIC_WRITE & !FILE_CREATE_PIPE_INSTANCE), impidiendo a nivel de kernel que un proceso de usuario cree instancias del pipe. src/ipc/security.rs
T3 Acceso Remoto vía SMB PIPE_REJECT_REMOTE_CLIENTS bloquea cualquier intento de conexión desde la red. src/ipc/security.rs
T4 Denegación de Servicio por Payload IPC Gigante Límite estricto de MAX_MESSAGE_SIZE (8 KB) verificado sobre el prefijo de 4 bytes Little-Endian antes de reservar memoria en el heap. src/ipc/server.rs
T5 Suplantación de Cliente IPC Antes de leer un solo byte del pipe, validate_client_process obtiene el PID real desde el kernel (GetNamedPipeClientProcessId), resuelve la ruta completa en disco (QueryFullProcessImageNameW) y la coteja contra la lista blanca inmutable. src/ipc/security.rs
T-R1 Auto-Sabotaje (Escaneo de Reglas o Bóveda) WalkBuilder::filter_entry excluye de raíz C:\ProgramData\AntimalwareCore\Quarantine y C:\ProgramData\AntimalwareCore\Rules, evitando que el motor ponga en cuarentena sus propias firmas .yar o re-escanee payloads ya aislados. src/scanner/engine.rs
T-R3 Hilos Zombie por Desconexión de Cliente ActiveScan implementa Drop activando cancel.store(true, Ordering::Release) de forma inmediata si el cliente cierra la conexión a mitad de un escaneo. src/ipc/server.rs
T-R4 Corrupción en Cuarentena Multi-Volumen Si el archivo amenazado reside en otro disco (ERROR_NOT_SAME_DEVICE), se ejecuta una copia transaccional: se aplica primero la DACL endurecida en destino y se verifica que el SHA-256 coincida bit a bit con el original. Si falla cualquier paso, se ejecuta rollback limpio eliminando el archivo parcial de la bóveda. src/scanner/quarantine.rs
T-H1 Bloqueo en Session 0 o Fuga OCSP en WinVerifyTrust verify_pe_signature invoca WinVerifyTrust con WTD_UI_NONE, WTD_REVOKE_NONE y WTD_CACHE_ONLY_URL_RETRIEVAL (cero ventanas modales en Session 0 y cero conexiones salientes HTTP/OCSP/CRL), cerrando siempre el handle con WTD_STATEACTION_CLOSE. src/scanner/heuristics.rs
T-H2 Evasión por Entropy Padding (Cola de Ceros) Si un binario PE supera los 64 KB o añade bloques 0x00 al final para reducir su entropía media global por debajo de 7.20, compute_effective_pe_entropy evalúa tanto la entropía truncando la cola nula como la entropía máxima en ventanas deslizantes de 64 KB. src/scanner/heuristics.rs
T-W1 Inversión de Byte Order o Auto-Bloqueo en WFP FWP_V4_ADDR_AND_MASK (addr, mask) y FWP_UINT16 (port) se expresan estrictamente en Host Byte Order (u32::from(ipv4) donde 1.2.3.4 = 0x01020304), y se rechazan rangos loopback (127.0.0.0/8), 0.0.0.0 y comodines /0. src/capture/wfp.rs
T-W3 Fuga de Memoria del Motor BFE Todo buffer reservado por WFP (FwpmGetAppIdFromFileName0 y las páginas de FwpmFilterEnum0) se libera determinísticamente mediante FwpmFreeMemory0, y el cursor se destruye con FwpmFilterDestroyEnumHandle0. src/capture/wfp.rs

🧪 Suite de Tests y Calidad de Código

El proyecto mantiene una política estricta de cero advertencias de compilación (-D warnings) y cuenta con 22 tests automatizados (19 en la librería principal + 3 en el binario CLI am) que pueden ejecutarse sin requerir privilegios de Administrador:

# Ejecutar toda la suite de tests (unitarios + integración IPC/Scanner)
cargo test

# Verificación estricta de linter en todos los targets
cargo clippy --all-targets -- -D warnings

Cobertura de Tests Automatizados (22 / 22 Passing)

Test Módulo Invariante Verificada
test_wfp_ip_validation_and_host_byte_order capture::wfp Conversión exacta a Host Byte Order (0x01020304), máscaras CIDR y rechazo de loopback/0.0.0.0//0.
test_firewall_ipc_roundtrip ipc::protocol Serialización/deserialización simétrica de AddBlockRule, RemoveRule, ListRules, RuleAdded, RuleRemoved y Rules.
test_start_scan_request_serde ipc::protocol Deserialización de StartScan con valores por defecto (paranoid: false).
test_scan_started_serde ipc::protocol Contrato JSON de IpcResponse::ScanStarted.
test_scan_event_serde ipc::protocol Contrato JSON de IpcResponse::ScanEvent.
test_scan_engine_load_rules ipc::protocol Compilación hermética de las reglas YARA del repositorio (rules/sample.yar).
test_active_scan_drop_sets_cancel_flag ipc::server El Drop de ActiveScan activa inmediatamente cancel = true y limpia is_running.
test_sequential_getstatus_then_startscan ipc::server Handoff Make-Before-Break bajo múltiples clientes consecutivos (GetStatus → StartScan).
test_protected_service_dirs_excluded scanner::engine Exclusión de VAULT_DIR y RULES_DIR (incluyendo rutas con prefijo extendido \\?\).
test_heuristic_warning_and_paranoid_mode scanner::engine Emisión de HeuristicWarning sin cuarentena en modo normal y aislamiento automático en modo --paranoid.
test_shannon_entropy_bounds scanner::heuristics Límites matemáticos de entropía de Shannon (0.00 en buffers uniformes, 8.00 en distribución uniforme de 256 valores).
test_pe_header_detection scanner::heuristics Validación estructural de cabeceras DOS (MZ), offset e_lfanew y firma PE\0\0.
test_entropy_padding_evasion_detected scanner::heuristics Detección de payload PE de alta entropía (8.00) camuflado con 256 KB de relleno nulo (0x00) al final.
test_winverifytrust_signed_system_binary scanner::heuristics Verificación Authenticode real contra binarios firmados del sistema (kernel32.dll) y rechazo de PEs sintéticos sin firma.
test_path_traversal_rejected scanner::quarantine Rechazo de rutas relativas o con secuencias .. antes de operar en la bóveda.
test_sha256_consistent scanner::quarantine Integridad del cálculo SHA-256 por streaming en bloques de 64 KB.
test_cross_volume_relocate_success scanner::quarantine Copia transaccional entre volúmenes, verificación de hash y borrado en origen.
test_cross_volume_rollback_on_acl_failure scanner::quarantine Rollback inmediato del archivo en la bóveda si falla la aplicación de la DACL.
test_cross_volume_rollback_on_hash_mismatch scanner::quarantine Rollback inmediato del archivo en la bóveda si el SHA-256 post-copia no coincide.
test_matching_rule_ids_for_ip bin::am Resolución de IDs de reglas WFP por IP exacta, /32 implícito y subredes CIDR para unblock-ip.
test_format_unix_timestamp bin::am Conversión civil UTC (algoritmo de Howard Hinnant) sin dependencias externas de fechas.
test_format_duration bin::am Formateo legible de tiempo de actividad del servicio.

📦 Dependencias Auditadas

Siguiendo docs/AGENTS.md §2.1, está prohibido introducir crates externos no auditados. Todas las operaciones del sistema operativo se realizan mediante el crate oficial windows de Microsoft:

Crate Versión Propósito Mantenedor Licencia
windows 0.61 Bindings oficiales Win32 (Pipes, Security, WinTrust, WFP, ETW, Services) Microsoft MIT / Apache-2.0
tokio 1.52 Runtime asíncrono para el servidor IPC y canales de eventos Tokio Team MIT
serde / serde_json 1.0 Serialización tipada del protocolo IPC David Tolnay MIT / Apache-2.0
yara-x 1.0 Motor YARA en Rust puro con sandbox WebAssembly (Wasmtime) VirusTotal / Google BSD-2-Clause
ignore 0.4 Recorrido paralelo de directorios (WalkParallel) BurntSushi MIT / Unlicense
sha2 0.10 Hash criptográfico SHA-256 para la bóveda de cuarentena RustCrypto MIT / Apache-2.0
hex 0.4 Codificación hexadecimal de hashes SHA-256 David Tolnay MIT / Apache-2.0

🗺️ Roadmap del Proyecto

  • Fase 1–4: Servidor IPC Named Pipe con DACL restrictiva, consumidor ETW y sesión WFP.
  • Fase 5: Motor de escaneo estático paralelo YARA-X y Bóveda de Cuarentena con DACL protegida.
  • Fase 6: CLI unificada am con menú interactivo TUI y script de despliegue install-service.ps1.
  • Fase 7: Handoff IPC Make-Before-Break (cero TOCTOU), cuarentena transaccional multi-volumen con rollback y cancelación RAII ActiveScan.
  • Fase 8 (v0.8.0): Inteligencia Estática PE (Entropía de Shannon anti-padding + Authenticode WinVerifyTrust offline) y Firewall Activo WFP en Host Byte Order.
  • Fase 9 (Próximo Hito): Auditoría de Recursos Robados e Inspector de Red por PID (resource_guard.rs).
  • Fase 10: Interfaz Gráfica de Escritorio (Centro de Control Visual).

📄 Licencia

Distribuido bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

Desarrollado en Rust · Blindado con APIs nativas Win32 · Cero código externo no auditado

About

Kernel-grade antimalware service and memory analysis engine in modern safe Rust (Win32 API, ETW, WFP, YARA-X, Wasmtime).

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages