malware-check

Instalação - Uso - Análise Dinâmica - Regras YARA - CI/CD

Documentação: Inglês | Tiếng Việt

Ferramenta de análise estática e dinâmica para detectar código malicioso, binários suspeitos e violações de privacidade. Analisa código-fonte, executáveis compilados (.exe, .dll, .elf), pacotes macOS (.app, .dmg, .pkg), aplicativos móveis (.apk, .ipa) e pacotes de aplicativos com regras YARA, sandbox comportamental Docker, análise móvel MobSF, desofuscação de payloads e geração de relatórios em múltiplos formatos (JSON, HTML, SARIF).

Funcionalidades

Análise Estática

• Scanner de Código-Fonte - Detecta shells reversos, backdoors, web shells, payloads ofuscados, mineradores de criptomoedas, padrões de ransomware, keyloggers, roubo de credenciais, ataques à cadeia de suprimentos e mecanismos de persistência em mais de 15 linguagens
• Analisador de Binários - Análise de PE (Windows), Mach-O (macOS) e ELF (Linux) com detecção de entropia, inspeção de tabela de importações, extração de strings, verificação de assinatura de código e detecção de seções RWX
• Detecção de Tipo de Arquivo por IA - Integração opcional com Magika para detecção baseada em conteúdo de arquivos sem extensão ou disfarçados
• Motor YARA - Varredura baseada em assinaturas com regras incluídas para famílias de malware, empacotadores e padrões suspeitos. Suporta diretórios de regras personalizados
• Analisador de Privacidade - Detecta SDKs de rastreamento, manipulação de campos de PII, permissões invasivas (manifestos Android/iOS), fingerprinting de dispositivo, monitoramento de área de transferência e transmissão não autorizada de dados

Análise Dinâmica (Sandbox Docker)

• Executa binários suspeitos em um contêiner Docker isolado com:
  • rastreamento de chamadas de sistema via strace (chamadas de rede, arquivo, processo)
  • monitoramento de rede via tcpdump (consultas DNS, requisições HTTP, conexões C2)
  • monitoramento do sistema de arquivos (criação, modificação, exclusão de arquivos)
  • monitoramento de processos (criação de processos filhos, tentativas de injeção)
• Isolamento completo: sem rede (padrão), limite de memória, capacidades removidas, sistema de arquivos raiz somente leitura
• Achados comportamentais: detecção de porta C2, modificação em massa de arquivos (ransomware), acesso a arquivos sensíveis, anti-debugging

Geração de Relatórios

• Console - Saída rica no terminal com tabelas coloridas por severidade e achados detalhados
• JSON - Achados legíveis por máquina para pipelines de automação
• HTML - Dashboard profissional com tema escuro, barras de severidade, detalhes de achados e evidências
• SARIF 2.1.0 - Integração direta com GitHub Code Scanning, Azure DevOps e GitLab SAST

Cobertura

Instalação

Pré-requisitos

• Python 3.10+
• pip ou pipx

Instalação Rápida (pip)

pip install malware-check

Instalação Rápida (pipx) - recomendada para uso via CLI

pipx install malware-check

A partir do Código-Fonte

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

Isso instala a CLI principal. Análise de binários via pefile/lief, detecção de arquivos baseada em IA via magika e varredura YARA via yara-python são extras opcionais.

Instalação Completa (todos os analisadores)

# Núcleo + análise de binários + detecção de arquivos por IA + YARA
pip install malware-check[full]

# Ou instale apenas o que precisar
pip install malware-check[binary]
pip install malware-check[detect]
pip install malware-check[yara]

# Ou instale os extras manualmente
pip install pefile lief magika yara-python

Detecção de Tipo de Arquivo por IA (Magika)

pip install malware-check[detect]

Quando instalado, o malware-check usa Magika para melhorar a identificação de arquivos entre plataformas, enriquecer os metadados file_type e direcionar arquivos sem extensão ou disfarçados para o analisador correto com base no conteúdo, em vez do nome do arquivo.

Análise Dinâmica (Sandbox Docker)

# Requer Docker - https://docs.docker.com/get-docker/
# Construir a imagem da sandbox (configuração única)
malware-check build-sandbox

Verificar Instalação

malware-check info

O comando info mostrará se a detecção de arquivos via Magika está disponível.

Claude Code (Skill)

Instale como uma skill do Claude Code para que o Claude possa analisar arquivos por você:

# Instalar a skill do GitHub
npx skills install momenbasel/malware-check --skill malware-check

# Ou manualmente: copie skill/SKILL.md para seu diretório de skills
cp -r skill/ ~/.claude/skills/malware-check/

Em seguida, no Claude Code, diga: "scan this file for malware" ou "is this binary safe?" e o Claude usará o malware-check automaticamente.

Você também precisa ter a ferramenta CLI instalada:

pip install malware-check pefile lief yara-python

Codex CLI

Instale a ferramenta e adicione às instruções do seu agente Codex:

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

# 2. Adicionar às suas instruções Codex (codex.md ou prompt do sistema)
echo 'Use `malware-check scan <caminho> --verbose` para analisar arquivos em busca de malware.' >> AGENTS.md

# 3. Ou instalar como uma skill do Codex
cp -r skill/ .codex/skills/malware-check/

OpenAI Codex / Outros Agentes de IA

Para qualquer agente de codificação de IA que suporte uso de ferramentas ou instruções personalizadas:

# 1. Instalar
pip install malware-check

# 2. Adicionar às instruções do agente:
# "Quando solicitado a verificar código/binários em busca de malware, use: malware-check scan <alvo> --verbose"
# "Para relatórios: malware-check scan <alvo> --format html -o report.html"
# "Para CI/CD: malware-check scan <alvo> --format sarif -o report.sarif --exit-code"

Uso

Escanear um arquivo

malware-check scan arquivo_suspeito.py

Escanear um arquivo sem extensão ou renomeado

# Melhores resultados quando malware-check[detect] está instalado
malware-check scan payload_suspeito --verbose

Escanear um diretório

malware-check scan /caminho/para/projeto --verbose

Escanear um binário com análise dinâmica

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

# Escanear com análise comportamental
malware-check scan malware.exe --dynamic

Escanear um pacote macOS .app

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

Gerar relatórios

# Relatório JSON
malware-check scan target/ --format json -o report.json

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

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

Integração com CI/CD

# Sair com código diferente de zero em caso de achados (para gates de CI)
malware-check scan . --format sarif -o results.sarif --exit-code

Verificar capacidades

malware-check info

Integração com GitHub Actions

name: Varredura de Segurança
on: [push, pull_request]

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

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

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

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

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

Arquitetura

malware-check/
├── src/malware_check/
│   ├── cli.py                 # Ponto de entrada da CLI (Click)
│   ├── scanner.py             # Orquestrador + detecção opcional de arquivos via Magika
│   ├── models.py              # Modelos de dados: Finding, FileAnalysis, ScanResult
│   ├── analyzers/
│   │   ├── code.py            # Correspondência de padrões em código-fonte (40+ regras)
│   │   ├── binary.py          # Análise PE/Mach-O/ELF
│   │   ├── privacy.py         # PII, rastreamento, permissões
│   │   ├── yara_engine.py     # Compilação e varredura de regras YARA
│   │   └── dynamic.py         # Análise comportamental com sandbox Docker
│   └── reporters/
│       ├── console_reporter.py  # Saída rica no terminal
│       ├── json_reporter.py     # Exportação JSON
│       ├── html_reporter.py     # Dashboard HTML (Jinja2)
│       └── sarif_reporter.py    # SARIF 2.1.0 para CI/CD
├── rules/yara/                # Regras YARA incluídas
├── tests/                     # Suíte de testes pytest
└── pyproject.toml             # Metadados do projeto

Regras YARA Personalizadas

Adicione regras personalizadas em qualquer diretório e passe via --yara-rules:

malware-check scan alvo/ --yara-rules /caminho/para/minhas/regras/

As regras suportam campos de metadados para severidade, categoria, confiança, CWE e mapeamento MITRE ATT&CK:

rule Minha_Regra_Personalizada {
    meta:
        description = "Detecta padrão de malware personalizado"
        severity = "critical"
        category = "backdoor"
        confidence = "0.90"
        mitre = "T1059"
        cwe = "CWE-94"
        recommendation = "Remover código malicioso"

    strings:
        $pattern = "string_suspeita"

    condition:
        $pattern
}

Detalhes da Análise Dinâmica

A sandbox Docker fornece análise comportamental com isolamento completo:

Comportamentos monitorados:

• Chamadas de sistema (strace): conexões de rede, operações de arquivo, criação de processos
• Rede (tcpdump): consultas DNS, conexões TCP, análise de protocolo
• Sistema de arquivos: novos arquivos, modificações, exclusões com detecção de tipo de arquivo
• Processos: criação de filhos, cadeias fork/exec

Cobertura MITRE ATT&CK

Contribuindo

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

# Opcional: incluir extras Magika, YARA e binários durante o desenvolvimento
pip install -e ".[dev,full]"

# Executar testes
pytest

# Lint
ruff check src/ tests/

Licença

Licença MIT - consulte LICENSE para detalhes.