malware-check

Instalación - Uso - Análisis Dinámico - Reglas YARA - CI/CD

Documentación: Inglés | Tiếng Việt

Herramienta de análisis estático y dinámico para detectar código malicioso, binarios sospechosos y violaciones de privacidad. Analiza código fuente, ejecutables compilados (.exe, .dll, .elf), paquetes macOS (.app, .dmg, .pkg), aplicaciones móviles (.apk, .ipa) y paquetes de aplicación con reglas YARA, sandboxing conductual con Docker, análisis móvil MobSF, desofuscación de payloads e informes en múltiples formatos (JSON, HTML, SARIF).

Características

Análisis Estático

• Escáner de Código Fuente - Detecta shells inversos, puertas traseras, webshells, payloads ofuscados, mineros de criptomonedas, patrones de ransomware, keyloggers, robo de credenciales, ataques a la cadena de suministro y mecanismos de persistencia en más de 15 lenguajes
• Analizador de Binarios - Análisis de PE (Windows), Mach-O (macOS) y ELF (Linux) con detección de entropía, inspección de tabla de importaciones, extracción de cadenas, verificación de firma de código y detección de secciones RWX
• Detección de Tipo de Archivo con IA - Integración opcional con Magika para detección basada en contenido de archivos sin extensión o disfrazados
• Motor YARA - Escaneo basado en firmas con reglas incluidas para familias de malware, packers y patrones sospechosos. Soporta directorios de reglas personalizadas
• Analizador de Privacidad - Detecta SDKs de seguimiento, manejo de campos de PII, permisos invasivos (manifiestos Android/iOS), huellas digitales de dispositivo, monitoreo del portapapeles y transmisión no autorizada de datos

Análisis Dinámico (Sandbox Docker)

• Ejecuta binarios sospechosos en un contenedor Docker aislado con:
  • rastreo de syscalls mediante strace (llamadas de red, archivo, proceso)
  • monitoreo de red mediante tcpdump (consultas DNS, solicitudes HTTP, conexiones C2)
  • monitoreo del sistema de archivos (creación, modificación, eliminación de archivos)
  • monitoreo de procesos (creación de procesos hijos, intentos de inyección)
• Aislamiento completo: sin red (por defecto), límite de memoria, capacidades eliminadas, rootfs de solo lectura
• Hallazgos conductuales: detección de puertos C2, modificación masiva de archivos (ransomware), acceso a archivos sensibles, anti-depuración

Informes

• Consola - Salida de terminal enriquecida con tablas codificadas por severidad y hallazgos detallados
• JSON - Hallazgos legibles por máquina para pipelines de automatización
• HTML - Panel profesional con tema oscuro, barras de severidad, detalles de hallazgos y evidencia
• SARIF 2.1.0 - Integración directa con GitHub Code Scanning, Azure DevOps y GitLab SAST

Cobertura

Instalación

Requisitos Previos

• Python 3.10+
• pip o pipx

Instalación Rápida (pip)

pip install malware-check

Instalación Rápida (pipx) - recomendado para uso en CLI

pipx install malware-check

Desde Código Fuente

git clone https://github.com/momenbasel/malware-check.git
cd malware-check
pip install -e ".[dev]"

Esto instala el CLI principal. El análisis de binarios mediante pefile/lief, la detección de archivos con IA mediante magika y el escaneo YARA mediante yara-python son extras opcionales.

Instalación Completa (todos los analizadores)

# Núcleo + análisis de binarios + detección de archivos con IA + YARA
pip install malware-check[full]

# O instalar solo lo necesario
pip install malware-check[binary]
pip install malware-check[detect]
pip install malware-check[yara]

# O instalar extras manualmente
pip install pefile lief magika yara-python

Detección de Tipo de Archivo con IA (Magika)

pip install malware-check[detect]

Cuando está instalado, malware-check utiliza Magika para mejorar la identificación de archivos multiplataforma, enriquecer los metadatos de file_type y dirigir archivos sin extensión o disfrazados al analizador correcto basándose en el contenido en lugar del nombre del archivo.

Análisis Dinámico (Sandbox Docker)

# Requiere Docker - https://docs.docker.com/get-docker/
# Construir la imagen del sandbox (configuración única)
malware-check build-sandbox

Verificar Instalación

malware-check info

El comando info mostrará si la detección de archivos potenciada por Magika está disponible.

Claude Code (Skill)

Instálalo como una skill de Claude Code para que Claude pueda analizar archivos por ti:

# Instalar la skill desde GitHub
npx skills install momenbasel/malware-check --skill malware-check

# O manualmente: copiar skill/SKILL.md a tu directorio de skills
cp -r skill/ ~/.claude/skills/malware-check/

Luego en Claude Code, di: "escanear este archivo en busca de malware" o "¿este binario es seguro?" y Claude usará malware-check automáticamente.

También necesitas la herramienta CLI instalada:

pip install malware-check pefile lief yara-python

Codex CLI

Instala la herramienta y agrégala a las instrucciones de tu agente Codex:

# 1. Instalar el CLI
pip install malware-check pefile lief yara-python

# 2. Agregar a tus instrucciones de Codex (codex.md o prompt del sistema)
echo 'Usa `malware-check scan <ruta> --verbose` para analizar archivos en busca de malware.' >> AGENTS.md

# 3. O instalar como una skill de Codex
cp -r skill/ .codex/skills/malware-check/

OpenAI Codex / Otros Agentes de IA

Para cualquier agente de codificación de IA que soporte uso de herramientas o instrucciones personalizadas:

# 1. Instalar
pip install malware-check

# 2. Agregar a las instrucciones del agente:
# "Cuando te pidan revisar código/binarios en busca de malware, usa: malware-check scan <objetivo> --verbose"
# "Para informes: malware-check scan <objetivo> --format html -o report.html"
# "Para CI/CD: malware-check scan <objetivo> --format sarif -o report.sarif --exit-code"

Uso

Escanear un archivo

malware-check scan suspicious_file.py

Escanear un archivo sin extensión o renombrado

# Mejores resultados cuando malware-check[detect] está instalado
malware-check scan suspicious_payload --verbose

Escanear un directorio

malware-check scan /path/to/project --verbose

Escanear un binario con análisis dinámico

# Construir sandbox primero (única vez)
malware-check build-sandbox

# Escanear con análisis conductual
malware-check scan malware.exe --dynamic

Escanear un paquete macOS .app

malware-check scan /Applications/SuspiciousApp.app --dynamic --verbose

Generar informes

# Informe JSON
malware-check scan target/ --format json -o report.json

# Panel HTML
malware-check scan target/ --format html -o report.html

# SARIF para CI/CD
malware-check scan target/ --format sarif -o results.sarif

Integración CI/CD

# Salir con código distinto de cero si hay hallazgos (para puertas CI)
malware-check scan . --format sarif -o results.sarif --exit-code

Verificar capacidades

malware-check info

Integración con GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  malware-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install malware-check
        run: pip install malware-check

      - name: Run scan
        run: malware-check scan . --format sarif -o results.sarif --exit-code

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Arquitectura

malware-check/
├── src/malware_check/
│   ├── cli.py                 # Punto de entrada CLI con Click
│   ├── scanner.py             # Orquestador + detección de archivos opcional con Magika
│   ├── models.py              # Modelos de datos: Finding, FileAnalysis, ScanResult
│   ├── analyzers/
│   │   ├── code.py            # Coincidencia de patrones en código fuente (más de 40 reglas)
│   │   ├── binary.py          # Análisis PE/Mach-O/ELF
│   │   ├── privacy.py         # PII, seguimiento, permisos
│   │   ├── yara_engine.py     # Compilación y escaneo de reglas YARA
│   │   └── dynamic.py         # Análisis conductual en sandbox Docker
│   └── reporters/
│       ├── console_reporter.py  # Salida de terminal enriquecida
│       ├── json_reporter.py     # Exportación JSON
│       ├── html_reporter.py     # Panel HTML (Jinja2)
│       └── sarif_reporter.py    # SARIF 2.1.0 para CI/CD
├── rules/yara/                # Reglas YARA incluidas
├── tests/                     # Suite de pruebas pytest
└── pyproject.toml             # Metadatos del proyecto

Reglas YARA Personalizadas

Añade reglas personalizadas a cualquier directorio y pásalas mediante --yara-rules:

malware-check scan target/ --yara-rules /path/to/my/rules/

Las reglas admiten campos de metadatos para severidad, categoría, confianza, CWE y mapeo MITRE ATT&CK:

rule My_Custom_Rule {
    meta:
        description = "Detectar patrón de malware personalizado"
        severity = "critical"
        category = "backdoor"
        confidence = "0.90"
        mitre = "T1059"
        cwe = "CWE-94"
        recommendation = "Eliminar código malicioso"

    strings:
        $pattern = "suspicious_string"

    condition:
        $pattern
}

Detalles del Análisis Dinámico

El sandbox Docker proporciona análisis conductual con aislamiento completo:

Comportamientos monitoreados:

• Syscalls (strace): conexiones de red, operaciones de archivos, creación de procesos
• Red (tcpdump): consultas DNS, conexiones TCP, análisis de protocolos
• Sistema de archivos: nuevos archivos, modificaciones, eliminaciones con detección de tipo de archivo
• Procesos: creación de hijos, cadenas fork/exec

Cobertura MITRE ATT&CK

Contribuir

# Clonar e instalar dependencias de desarrollo
git clone https://github.com/momenbasel/malware-check.git
cd malware-check
pip install -e ".[dev]"

# Opcional: incluir Magika, YARA y extras de binarios durante el desarrollo
pip install -e ".[dev,full]"

# Ejecutar pruebas
pytest

# Lint
ruff check src/ tests/

Licencia

Licencia MIT - consulta LICENSE para más detalles.