FlatScan

---

FlatScan è un motore di analisi statica di malware e di reporting di livello produttivo scritto in Go puro. È progettato per gli analisti che necessitano di triage rapido, estrazione di IOC, rilevamento di capacità sospette, reporting esecutivo e passaggio di regole di hunting — tutto senza eseguire il campione.

FlatScan legge un file, ne calcola l'hash, ne identifica il formato, estrae le stringhe, decodifica i dati codificati sospetti, estrae e classifica gli IOC, ispeziona i metadati di eseguibili/container, assegna un punteggio ai risultati, li arricchisce in un profilo di malware e produce output in formato testo, JSON, PDF, HTML, IOC, YARA, Sigma, STIX 2.1, database dei casi e report-pack.

---

Indice

• Perché esiste FlatScan
• Panoramica dell'architettura
• Pipeline di analisi
• Funzionalità
• Avvio rapido
• Tipi di output
• Interfaccia Web
• Report di esempio
• Modalità di scansione
• Logica di scoring
• Sistema di plugin
• Architettura delle prestazioni
• Mappa dei moduli
• Nota sulla sicurezza
• Limitazioni
• Documentazione
• URL del progetto

---

Perché esiste FlatScan

Il triage del malware ha spesso due destinatari:

Destinatario	Esigenze
Analisti di sicurezza	Evidenze tecniche: hash, stringhe, import, IOC, entropia, sezioni, dati decodificati, TTP, regole di hunting
CISO / Management	Contesto di rischio: cosa probabilmente è, perché è importante, impatto sul business, azioni raccomandate

FlatScan serve entrambi. Esegue l'analisi statica per sicurezza e velocità, poi converte il risultato sia in output leggibile dalla macchina sia in report pronti per il management.

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]

Panoramica dell'architettura

FlatScan è costruito come una pipeline di analisi multi-stadio con esecuzione parallela, un sistema di plugin e nessuna dipendenza esterna — go.mod non richiede nulla, e il motore di disassemblaggio in puro Go è incluso nel repository come internal/x86asm (una copia non modificata di golang.org/x/arch/x86/x86asm, BSD-3-Clause). Nessun cgo, nessuna dipendenza runtime o di sistema, nessuna rete necessaria per la compilazione.

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

Principi di progettazione chiave

Principio	Implementazione
Zero dipendenze esterne	go.mod non richiede nulla e non esiste alcun go.sum. La libreria standard di Go più un unico pacchetto vendored e non modificato — internal/x86asm, una copia di golang.org/x/arch/x86/x86asm (BSD-3-Clause, motore di disassemblaggio) mantenuta in-tree così che la build non richieda download né rete. Nessun cgo, nessuna libreria nativa, nessuna dipendenza a runtime
Solo statico	Non esegue mai il campione — legge byte e metadati
Thread-safe	parallelRun() con risultati protetti da mutex, verificato con il race detector. Le fasi di analisi recuperano individualmente i panic, così un campione malformato non può interrompere un batch
Portabile tra piattaforme	Compila per Linux, macOS, Windows; mmap su Linux con fallback trasparente
Estensibile	Interfaccia plugin + manifest JSON per rilevamenti personalizzati senza ricompilare

Stato della verifica

Controllo	Risultato
go build / go vet / gofmt -l	Pulito
go test ./...	189 test (344 casi inclusi i subtest), tutti superati
go test -race ./...	Pulito
go test -cover ./...	50,6% delle istruzioni
golangci-lint run	0 problemi (errcheck, govet, staticcheck, gosec, errorlint, ineffassign, unused, bodyclose, nilerr, misspell, unconvert, wastedassign)
govulncheck ./...	Nessuna vulnerabilità trovata

Ambiente di test. Verificato su Fedora Linux 44 (x86_64, kernel 7.1.7) con Go 1.26.5. Il minimo di go.mod è Go 1.25. La CI esegue inoltre la stessa suite su ubuntu-latest. Linux è l'unica piattaforma su cui questi risultati sono misurati: macOS e Windows sono target supportati e il codice esegue la cross-compilazione per essi, ma i numeri sopra non sono riprodotti in modo indipendente su tali piattaforme, e mmap_linux.go è solo per Linux per costruzione (le altre piattaforme usano il fallback di lettura bufferizzata).

---

Pipeline di analisi

Il motore elabora i file attraverso 18 fasi con esecuzione parallela per le operazioni indipendenti: