FlatScan

---

FlatScan ist eine produktionsreife statische Malware-Analyse- und Reporting-Engine, geschrieben in reinem Go. Sie ist für Analysten konzipiert, die schnelle Triage, IOC-Extraktion, Erkennung verdächtiger Fähigkeiten, Management-Reporting und die Übergabe von Hunting-Regeln benötigen — und das alles ohne Ausführung der Probe.

FlatScan liest eine Datei ein, berechnet ihren Hash, identifiziert das Format, extrahiert Strings, dekodiert verdächtige kodierte Daten, extrahiert und triagiert IOCs, inspiziert Metadaten von ausführbaren Dateien und Containern, bewertet die Befunde, reichert sie zu einem Malware-Profil an und erzeugt Ausgaben in Text, JSON, PDF, HTML, IOC, YARA, Sigma, STIX 2.1, als Falldatenbank und als Report-Paket.

---

Inhaltsverzeichnis

• Warum FlatScan existiert
• Architekturübersicht
• Analyse-Pipeline
• Funktionen
• Schnellstart
• Ausgabetypen
• Web-GUI
• Beispielbericht
• Scan-Modi
• Bewertungslogik
• Plugin-System
• Performance-Architektur
• Modulübersicht
• Sicherheitshinweis
• Einschränkungen
• Dokumentation
• Projekt-URL

---

Warum FlatScan existiert

Malware-Triage hat oft zwei Zielgruppen:

Zielgruppe	Bedarf
Sicherheitsanalysten	Technische Beweise: Hashes, Strings, Imports, IOCs, Entropie, Sektionen, dekodierte Daten, TTPs, Hunting-Regeln
CISO / Management	Risikokontext: was es wahrscheinlich ist, warum es relevant ist, geschäftliche Auswirkungen, empfohlene Maßnahmen

FlatScan bedient beide. Es führt statische Analyse für Sicherheit und Geschwindigkeit durch und wandelt das Ergebnis anschließend sowohl in maschinenlesbare Ausgaben als auch in managementtaugliches Reporting um.

graph LR
    A[Malware Sample] --> B[FlatScan Engine]
    B --> C[Analyst Reports]
    B --> D[Executive Reports]
    B --> E[Machine-Readable]
    B --> F[Hunting Rules]
    
    C -->|HTML, Full Text| G[SOC Team]
    D -->|PDF, Executive MD| H[CISO / Board]
    E -->|JSON, STIX 2.1| I[SIEM / SOAR]
    F -->|YARA, Sigma| J[EDR / Hunt Team]

Architekturübersicht

FlatScan ist als mehrstufige Analyse-Pipeline mit paralleler Ausführung, einem Plugin-System und ohne externe Abhängigkeiten aufgebaut — go.mod benötigt nichts, und die reine Go-Disassemblierungs-Engine ist als internal/x86asm im Baum mitgeliefert (eine unveränderte Kopie von golang.org/x/arch/x86/x86asm, BSD-3-Clause). Kein cgo, keine Laufzeit- oder Systemabhängigkeiten, kein Netzwerk zum Bauen erforderlich.

graph TB
    subgraph "Input Layer"
        CLI[CLI Parser] --> CFG[Config]
        INT[Interactive Mode] --> CFG
        SHL[Shell Mode] --> CFG
        WCH[Watch Mode] --> CFG
    end
    
    subgraph "I/O Layer"
        CFG --> MMP{File > 100MB?}
        MMP -->|Yes| MMAP[Memory-Mapped I/O]
        MMP -->|No| BUF[Buffered Read]
        MMAP --> DATA[Raw Bytes + Hashes]
        BUF --> DATA
    end
    
    subgraph "Analysis Pipeline"
        DATA --> DET[File Type Detection]
        DET --> ENT[Entropy Analysis]
        ENT --> STR[String Extraction]
        STR --> IOC[IOC Extraction]
        IOC --> DEC[Decoder Pass]
        DEC --> CRP[Corpus Build]
        CRP --> PAT[Pattern Matching]
        
        PAT --> PG["Parallel Group"]
        
        subgraph PG["⚡ Parallel Stages"]
            FMT[Format Analysis]
            CRV[Safe Carving]
            CRY[Crypto/Config]
            SIM[Similarity Hash]
        end
        
        PG --> SEQ[Sequential Stages]
        SEQ --> PLG[Plugin Engine]
        PLG --> SCR[Risk Scoring]
    end
    
    subgraph "Output Layer"
        SCR --> TXT[Text Report]
        SCR --> JSN[JSON]
        SCR --> PDF[PDF Report]
        SCR --> HTM[HTML Report]
        SCR --> YAR[YARA Rule]
        SCR --> SIG[Sigma Rule]
        SCR --> STX[STIX 2.1]
        SCR --> RPK[Report Pack]
    end
    
    style PG fill:#1a1a2e,stroke:#e94560,stroke-width:2px
    style SCR fill:#0f3460,stroke:#e94560,stroke-width:2px

Zentrale Designprinzipien

Prinzip	Umsetzung
Keine externen Abhängigkeiten	go.mod benötigt nichts und es gibt keine go.sum. Die Go-Standardbibliothek plus ein vendortes, unverändertes Paket — internal/x86asm, eine Kopie von golang.org/x/arch/x86/x86asm (BSD-3-Clause, Disassemblierungs-Engine) — im Baum gehalten, damit der Build keinen Download und kein Netzwerk benötigt. Kein cgo, keine nativen Bibliotheken, keine Laufzeitabhängigkeiten
Nur statisch	Führt die Probe niemals aus — liest Bytes und Metadaten
Thread-sicher	parallelRun() mit mutex-geschützten Findings, vom Race-Detector verifiziert. Analysephasen fangen Panics einzeln ab, sodass eine fehlerhafte Probe einen Batch nicht abbrechen kann
Plattformportabel	Baut für Linux, macOS, Windows; mmap unter Linux mit transparentem Fallback
Erweiterbar	Plugin-Schnittstelle + JSON-Manifeste für benutzerdefinierte Erkennungen ohne Neukompilierung

Verifikationsstatus

Prüfung	Ergebnis
go build / go vet / gofmt -l	Sauber
go test ./...	189 Tests (344 Fälle inklusive Subtests), alle bestanden
go test -race ./...	Sauber
go test -cover ./...	50,6 % der Anweisungen
golangci-lint run	0 Probleme (errcheck, govet, staticcheck, gosec, errorlint, ineffassign, unused, bodyclose, nilerr, misspell, unconvert, wastedassign)
govulncheck ./...	Keine Schwachstellen gefunden

Testumgebung. Verifiziert auf Fedora Linux 44 (x86_64, Kernel 7.1.7) mit Go 1.26.5. Die go.mod-Mindestversion ist Go 1.25. Die CI führt dieselbe Suite zusätzlich auf ubuntu-latest aus. Linux ist die einzige Plattform, auf der diese Ergebnisse gemessen werden: macOS und Windows sind unterstützte Ziele und der Code cross-kompiliert dorthin, aber die obigen Zahlen werden dort nicht unabhängig reproduziert, und mmap_linux.go ist konstruktionsbedingt nur für Linux (andere Plattformen verwenden den Fallback auf gepufferte Lesevorgänge).

---

Analyse-Pipeline

Die Engine verarbeitet Dateien durch 18 Phasen mit paralleler Ausführung für unabhängige Operationen: