malware-check

Installation - Utilisation - Analyse dynamique - Règles YARA - CI/CD

Docs : Anglais | Tiếng Việt

Outil d'analyse statique et dynamique pour détecter les codes malveillants, les binaires suspects et les violations de la vie privée. Analyse le code source, les exécutables compilés (.exe, .dll, .elf), les bundles macOS (.app, .dmg, .pkg), les applications mobiles (.apk, .ipa) et les paquets applicatifs avec des règles YARA, un bac à sable comportemental Docker, l'analyse mobile MobSF, la désobfuscation de payloads et des rapports multi-formats (JSON, HTML, SARIF).

Fonctionnalités

Analyse statique

• Scanner de code source - Détecte les reverse shells, les backdoors, les web shells, les payloads obfusqués, les mineurs de crypto-monnaies, les patterns de ransomware, les keyloggers, le vol d'identifiants, les attaques sur la chaîne d'approvisionnement et les mécanismes de persistance dans plus de 15 langages
• Analyseur binaire - Analyse PE (Windows), Mach-O (macOS) et ELF (Linux) avec détection d'entropie, inspection de la table d'importations, extraction de chaînes, vérification de la signature de code et détection des sections RWX
• Détection de type de fichier par IA - Intégration facultative de Magika pour la détection basée sur le contenu de fichiers sans extension ou déguisés
• Moteur YARA - Analyse par signatures avec des règles intégrées pour les familles de logiciels malveillants, les packers et les patterns suspects. Prend en charge les répertoires de règles personnalisés
• Analyseur de vie privée - Détecte les SDK de suivi, le traitement des champs de données personnelles (PII), les autorisations invasives (manifestes Android/iOS), l'empreinte numérique de l'appareil, la surveillance du presse-papiers et les transmissions de données non autorisées

Analyse dynamique (bac à sable Docker)

• Exécute des binaires suspects dans un conteneur Docker isolé avec :
  • Suivi des appels système via strace (appels réseau, fichier, processus)
  • Surveillance réseau via tcpdump (requêtes DNS, requêtes HTTP, connexions C2)
  • Surveillance du système de fichiers (création, modification, suppression de fichiers)
  • Surveillance des processus (création de processus fils, tentatives d'injection)
• Isolation complète : pas de réseau (par défaut), limites de mémoire, capacités supprimées, système de fichiers racine en lecture seule
• Résultats comportementaux : détection de port C2, modification massive de fichiers (ransomware), accès à des fichiers sensibles, anti-débogage

Rapports

• Console - Sortie terminal enrichie avec des tableaux colorés par sévérité et des résultats détaillés
• JSON - Résultats lisibles par machine pour les pipelines d'automatisation
• HTML - Tableau de bord professionnel sur fond sombre avec barres de sévérité, détails des résultats et preuves
• SARIF 2.1.0 - Intégration directe avec GitHub Code Scanning, Azure DevOps et GitLab SAST

Couverture

Installation

Prérequis

• Python 3.10+
• pip ou pipx

Installation rapide (pip)

pip install malware-check

Installation rapide (pipx) - recommandée pour une utilisation en CLI

pipx install malware-check

Depuis les sources

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

Ceci installe la CLI de base. L'analyse binaire via pefile/lief, la détection de fichiers par IA via magika et l'analyse YARA via yara-python sont des options supplémentaires facultatives.

Installation complète (tous les analyseurs)

# Noyau + analyse binaire + détection de fichiers par IA + YARA
pip install malware-check[full]

# Ou installer uniquement ce dont vous avez besoin
pip install malware-check[binary]
pip install malware-check[detect]
pip install malware-check[yara]

# Ou installer les extras manuellement
pip install pefile lief magika yara-python

Détection de type de fichier par IA (Magika)

pip install malware-check[detect]

Une fois installé, malware-check utilise Magika pour améliorer l'identification des fichiers multiplateformes, enrichir les métadonnées file_type et orienter les fichiers sans extension ou déguisés vers le bon analyseur en fonction du contenu plutôt que du nom de fichier.

Analyse dynamique (bac à sable Docker)

# Nécessite Docker - https://docs.docker.com/get-docker/
# Construire l'image du bac à sable (une seule fois)
malware-check build-sandbox

Vérifier l'installation

malware-check info

La commande info indiquera si la détection de fichiers par Magika est disponible.

Claude Code (Skill)

Installer en tant que skill Claude Code pour que Claude puisse analyser des fichiers pour vous :

# Installer le skill depuis GitHub
npx skills install momenbasel/malware-check --skill malware-check

# Ou manuellement : copier skill/SKILL.md dans votre répertoire de skills
cp -r skill/ ~/.claude/skills/malware-check/

Ensuite, dans Claude Code, dites : "scan this file for malware" ou "is this binary safe?" et Claude utilisera malware-check automatiquement.

Vous avez également besoin de l'outil CLI installé :

pip install malware-check pefile lief yara-python

Codex CLI

Installer l'outil et l'ajouter à vos instructions d'agent Codex :

# 1. Installer la CLI
pip install malware-check pefile lief yara-python

# 2. Ajouter à vos instructions Codex (codex.md ou prompt système)
echo 'Utilisez `malware-check scan <path> --verbose` pour analyser les fichiers à la recherche de malwares.' >> AGENTS.md

# 3. Ou installer en tant que skill Codex
cp -r skill/ .codex/skills/malware-check/

OpenAI Codex / Autres agents IA

Pour tout agent de codage IA prenant en charge l'utilisation d'outils ou des instructions personnalisées :

# 1. Installer
pip install malware-check

# 2. Ajouter aux instructions de l'agent :
# "Lorsqu'on vous demande de vérifier du code/des binaires pour des malwares, utilisez : malware-check scan <cible> --verbose"
# "Pour les rapports : malware-check scan <cible> --format html -o rapport.html"
# "Pour CI/CD : malware-check scan <cible> --format sarif -o resultats.sarif --exit-code"

Utilisation

Analyser un fichier

malware-check scan suspicious_file.py

Analyser un fichier sans extension ou renommé

# Meilleurs résultats lorsque malware-check[detect] est installé
malware-check scan suspicious_payload --verbose

Analyser un répertoire

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

Analyser un binaire avec analyse dynamique

# Construire le bac à sable d'abord (une seule fois)
malware-check build-sandbox

# Analyser avec analyse comportementale
malware-check scan malware.exe --dynamic

Analyser un bundle macOS .app

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

Générer des rapports

# Rapport JSON
malware-check scan target/ --format json -o rapport.json

# Tableau de bord HTML
malware-check scan target/ --format html -o rapport.html

# SARIF pour CI/CD
malware-check scan target/ --format sarif -o resultats.sarif

Intégration CI/CD

# Sortir avec un code non nul en cas de résultats (pour les barrières CI)
malware-check scan . --format sarif -o resultats.sarif --exit-code

Vérifier les capacités

malware-check info

Intégration 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

Architecture

malware-check/
├── src/malware_check/
│   ├── cli.py                 # Point d'entrée CLI Click
│   ├── scanner.py             # Orchestrateur + détection de fichiers facultative basée sur Magika
│   ├── models.py              # Modèles de données Finding, FileAnalysis, ScanResult
│   ├── analyzers/
│   │   ├── code.py            # Correspondance de motifs dans le code source (40+ règles)
│   │   ├── binary.py          # Analyse PE/Mach-O/ELF
│   │   ├── privacy.py         # PII, suivi, autorisations
│   │   ├── yara_engine.py     # Compilation et analyse des règles YARA
│   │   └── dynamic.py         # Analyse comportementale dans le bac à sable Docker
│   └── reporters/
│       ├── console_reporter.py  # Sortie terminal enrichie
│       ├── json_reporter.py     # Export JSON
│       ├── html_reporter.py     # Tableau de bord HTML (Jinja2)
│       └── sarif_reporter.py    # SARIF 2.1.0 pour CI/CD
├── rules/yara/                # Règles YARA incluses
├── tests/                     # Suite de tests pytest
└── pyproject.toml             # Métadonnées du projet

Règles YARA personnalisées

Ajoutez des règles personnalisées dans n'importe quel répertoire et transmettez-les via --yara-rules :

malware-check scan cible/ --yara-rules /chemin/vers/mes/regles/

Les règles prennent en charge les champs de métadonnées pour la sévérité, la catégorie, la confiance, CWE et le mapping MITRE ATT&CK :

rule Ma_Regle_Personnalisee {
    meta:
        description = "Détecter un motif de malware personnalisé"
        severity = "critical"
        category = "backdoor"
        confidence = "0.90"
        mitre = "T1059"
        cwe = "CWE-94"
        recommendation = "Supprimer le code malveillant"

    strings:
        $pattern = "chaine_suspecte"

    condition:
        $pattern
}

Détails de l'analyse dynamique

Le bac à sable Docker fournit une analyse comportementale avec isolation complète :

Comportements surveillés :

• Appels système (strace) : connexions réseau, opérations sur les fichiers, création de processus
• Réseau (tcpdump) : requêtes DNS, connexions TCP, analyse de protocole
• Système de fichiers : nouveaux fichiers, modifications, suppressions avec détection de type de fichier
• Processus : création de processus fils, chaînes fork/exec

Couverture MITRE ATT&CK

Contribuer

# Cloner et installer les dépendances de développement
git clone https://github.com/momenbasel/malware-check.git
cd malware-check
pip install -e ".[dev]"

# Optionnel : inclure les extras Magika, YARA et binaires pendant le développement
pip install -e ".[dev,full]"

# Exécuter les tests
pytest

# Linting
ruff check src/ tests/

Licence

Licence MIT - voir LICENSE pour les détails.