malware-check

Installation - Verwendung - Dynamische Analyse - YARA-Regeln - CI/CD

Dokumentation: Englisch | Tiếng Việt

Werkzeug zur statischen und dynamischen Analyse zur Erkennung von schädlichem Code, verdächtigen Binärdateien und Datenschutzverletzungen. Analysiert Quellcode, kompilierte ausführbare Dateien (.exe, .dll, .elf), macOS-Bundles (.app, .dmg, .pkg), Mobil-Apps (.apk, .ipa) und Anwendungspakete mit YARA-Regeln, Docker-Verhaltenssandbox, MobSF-Mobilanalyse, Payload-Entschleierung und Mehrformat-Berichterstattung (JSON, HTML, SARIF).

Funktionen

Statische Analyse

• Quellcode-Scanner – Erkennt Reverse Shells, Hintertüren, Web Shells, verschleierte Payloads, Krypto-Miner, Ransomware-Muster, Keylogger, Diebstahl von Anmeldeinformationen, Supply-Chain-Angriffe und Persistenzmechanismen in über 15 Sprachen
• Binäranalysator – PE- (Windows), Mach-O- (macOS) und ELF-Analyse (Linux) mit Entropieerkennung, Importtabellen-Prüfung, String-Extraktion, Code-Signing-Verifikation und Erkennung von RWX-Abschnitten
• KI-Dateityperkennung – Optionale Magika-Integration zur inhaltsbasierten Erkennung von erweiterungslosen oder getarnten Dateien
• YARA-Engine – Signaturbasiertes Scannen mit gebündelten Regeln für Malware-Familien, Packer und verdächtige Muster. Unterstützt benutzerdefinierte Regelverzeichnisse
• Datenschutz-Analysator – Erkennt Tracking-SDKs, PII-Feldverarbeitung, invasive Berechtigungen (Android/iOS-Manifeste), Geräte-Fingerprinting, Zwischenablage-Überwachung und unbefugte Datenübertragung

Dynamische Analyse (Docker-Sandbox)

• Ausführung verdächtiger Binärdateien in einem isolierten Docker-Container mit:
  • Syscall-Tracing mittels strace (Netzwerk-, Datei- und Prozessaufrufe)
  • Netzwerküberwachung mittels tcpdump (DNS-Abfragen, HTTP-Anfragen, C2-Verbindungen)
  • Dateisystemüberwachung (Dateierstellung, -änderung, -löschung)
  • Prozessüberwachung (Kindprozesse, Injection-Versuche)
• Vollständige Isolierung: kein Netzwerk (Standard), Speicherbegrenzung, verworfene Capabilities, read-only rootfs
• Verhaltensbefunde: C2-Porterkennung, massenhafte Dateiänderung (Ransomware), Zugriff auf sensible Dateien, Anti-Debugging

Berichterstattung

• Konsole – Umfangreiche Terminal-Ausgabe mit farblich nach Schweregrad gekennzeichneten Tabellen und detaillierten Befunden
• JSON – Maschinenlesbare Befunde für Automatisierungspipelines
• HTML – Professionelles Dashboard in dunklem Design mit Schweregrad-Balken, Befunddetails und Beweisen
• SARIF 2.1.0 – Direkte Integration mit GitHub Code Scanning, Azure DevOps und GitLab SAST

Abdeckung

Installation

Voraussetzungen

• Python 3.10+
• pip oder pipx

Schnellinstallation (pip)

pip install malware-check

Schnellinstallation (pipx) – für die CLI-Nutzung empfohlen

pipx install malware-check

Aus dem Quellcode

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

Dadurch wird die Kern-CLI installiert. Die Binäranalyse mittels pefile/lief, KI-gestützte Dateierkennung mittels magika und YARA-Scanning mittels yara-python sind optionale Zusätze.

Vollständige Installation (alle Analysatoren)

# Kern + Binäranalyse + KI-Dateierkennung + YARA
pip install malware-check[full]

# Oder nur das Nötigste installieren
pip install malware-check[binary]
pip install malware-check[detect]
pip install malware-check[yara]

# Oder Zusätze manuell installieren
pip install pefile lief magika yara-python

KI-Dateityperkennung (Magika)

pip install malware-check[detect]

Bei Installation verwendet malware-check Magika zur verbesserten plattformübergreifenden Dateiidentifikation, reichert die Metadaten file_type an und leitet erweiterungslose oder getarnte Dateien basierend auf dem Inhalt und nicht nur auf dem Dateinamen an den richtigen Analysator weiter.

Dynamische Analyse (Docker-Sandbox)

# Erfordert Docker - https://docs.docker.com/get-docker/
# Sandbox-Image erstellen (einmaliger Vorgang)
malware-check build-sandbox

Installation überprüfen

malware-check info

Der Befehl info zeigt an, ob die Magika-gestützte Dateierkennung verfügbar ist.

Claude Code (Skill)

Als Claude Code Skill installieren, damit Claude Dateien für Sie analysieren kann:

# Skill von GitHub installieren
npx skills install momenbasel/malware-check --skill malware-check

# Oder manuell: skill/SKILL.md in Ihr Skills-Verzeichnis kopieren
cp -r skill/ ~/.claude/skills/malware-check/

Dann in Claude Code sagen: "scanne diese Datei auf Malware" oder "ist diese Binärdatei sicher?" und Claude verwendet automatisch malware-check.

Sie benötigen auch das installierte CLI-Werkzeug:

pip install malware-check pefile lief yara-python

Codex CLI

Das Werkzeug installieren und zu Ihren Codex-Agentenanweisungen hinzufügen:

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

# 2. Zu Ihren Codex-Anweisungen hinzufügen (codex.md oder System-Prompt)
echo 'Verwende `malware-check scan <pfad> --verbose`, um Dateien auf Malware zu analysieren.' >> AGENTS.md

# 3. Oder als Codex-Skill installieren
cp -r skill/ .codex/skills/malware-check/

OpenAI Codex / Andere KI-Agenten

Für jeden KI-Codierungsagenten, der Werkzeugnutzung oder benutzerdefinierte Anweisungen unterstützt:

# 1. Installieren
pip install malware-check

# 2. Zu den Agentenanweisungen hinzufügen:
# "Wenn du gebeten wirst, Code/Binärdateien auf Malware zu prüfen, verwende: malware-check scan <ziel> --verbose"
# "Für Berichte: malware-check scan <ziel> --format html -o report.html"
# "Für CI/CD: malware-check scan <ziel> --format sarif -o report.sarif --exit-code"

Verwendung

Eine Datei scannen

malware-check scan suspicious_file.py

Eine erweiterungslose oder umbenannte Datei scannen

# Beste Ergebnisse, wenn malware-check[detect] installiert ist
malware-check scan suspicious_payload --verbose

Ein Verzeichnis scannen

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

Eine Binärdatei mit dynamischer Analyse scannen

# Sandbox zuerst erstellen (einmalig)
malware-check build-sandbox

# Mit Verhaltensanalyse scannen
malware-check scan malware.exe --dynamic

Ein macOS .app-Bundle scannen

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

Berichte erstellen

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

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

# SARIF für CI/CD
malware-check scan target/ --format sarif -o results.sarif

CI/CD-Integration

# Mit Exit-Code ungleich Null bei Befunden (für CI-Gates)
malware-check scan . --format sarif -o results.sarif --exit-code

Fähigkeiten prüfen

malware-check info

GitHub-Actions-Integration

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

Architektur

malware-check/
├── src/malware_check/
│   ├── cli.py                 # Click CLI-Einstiegspunkt
│   ├── scanner.py             # Orchestrator + optionale Magika-basierte Dateierkennung
│   ├── models.py              # Datenmodelle für Finding, FileAnalysis, ScanResult
│   ├── analyzers/
│   │   ├── code.py            # Quellcode-Musterabgleich (40+ Regeln)
│   │   ├── binary.py          # PE/Mach-O/ELF-Analyse
│   │   ├── privacy.py         # PII, Tracking, Berechtigungen
│   │   ├── yara_engine.py     # YARA-Regelkompilierung und -Scanning
│   │   └── dynamic.py         # Docker-Sandbox-Verhaltensanalyse
│   └── reporters/
│       ├── console_reporter.py  # Umfangreiche Terminal-Ausgabe
│       ├── json_reporter.py     # JSON-Export
│       ├── html_reporter.py     # HTML-Dashboard (Jinja2)
│       └── sarif_reporter.py    # SARIF 2.1.0 für CI/CD
├── rules/yara/                # Gebündelte YARA-Regeln
├── tests/                     # pytest-Testsuite
└── pyproject.toml             # Projekt-Metadaten

Benutzerdefinierte YARA-Regeln

Fügen Sie benutzerdefinierte Regeln in ein beliebiges Verzeichnis hinzu und übergeben Sie es mit --yara-rules:

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

Regeln unterstützen Metadatenfelder für Schweregrad, Kategorie, Konfidenz, CWE und MITRE-ATT&CK-Zuordnung:

rule My_Custom_Rule {
    meta:
        description = "Eigenes Malware-Muster erkennen"
        severity = "critical"
        category = "backdoor"
        confidence = "0.90"
        mitre = "T1059"
        cwe = "CWE-94"
        recommendation = "Schädlichen Code entfernen"

    strings:
        $pattern = "suspicious_string"

    condition:
        $pattern
}

Details zur dynamischen Analyse

Die Docker-Sandbox bietet Verhaltensanalyse mit vollständiger Isolierung:

Überwachte Verhaltensweisen:

• Syscalls (strace): Netzwerkverbindungen, Dateioperationen, Prozesserstellung
• Netzwerk (tcpdump): DNS-Abfragen, TCP-Verbindungen, Protokollanalyse
• Dateisystem: neue Dateien, Änderungen, Löschungen mit Dateityperkennung
• Prozesse: Kindprozesserzeugung, Fork/Exec-Ketten

MITRE-ATT&CK-Abdeckung

Mitwirken

# Klonen und Entwicklungsabhängigkeiten installieren
git clone https://github.com/momenbasel/malware-check.git
cd malware-check
pip install -e ".[dev]"

# Optional: Magika, YARA und binäre Zusätze während der Entwicklung einschließen
pip install -e ".[dev,full]"

# Tests ausführen
pytest

# Lint
ruff check src/ tests/

Lizenz

MIT-Lizenz – siehe LICENSE für Details.