FlatScan

---

O FlatScan é um mecanismo de análise estática de malware e geração de relatórios de nível de produção, escrito em Go puro. Ele foi projetado para analistas que precisam de triagem rápida, extração de IOCs, detecção de capacidades suspeitas, relatórios executivos e entrega de regras de hunting — tudo isso sem executar a amostra.

O FlatScan lê um arquivo, calcula seu hash, identifica o formato, extrai strings, decodifica dados codificados suspeitos, extrai e faz a triagem de IOCs, inspeciona metadados de executáveis/contêineres, pontua os achados, enriquece-os em um perfil de malware e produz saídas em texto, JSON, PDF, HTML, IOC, YARA, Sigma, STIX 2.1, banco de dados de casos e pacotes de relatórios.

---

Índice

• Por que o FlatScan Existe
• Visão Geral da Arquitetura
• Pipeline de Análise
• Recursos
• Início Rápido
• Tipos de Saída
• Interface Web (GUI)
• Relatório de Exemplo
• Modos de Varredura
• Lógica de Pontuação
• Sistema de Plugins
• Arquitetura de Desempenho
• Mapa de Módulos
• Nota de Segurança
• Limitações
• Documentação
• URL do Projeto

---

Por que o FlatScan Existe

A triagem de malware frequentemente tem dois públicos:

Público	Necessidades
Analistas de Segurança	Evidências técnicas: hashes, strings, imports, IOCs, entropia, seções, dados decodificados, TTPs, regras de hunting
CISO / Gestão	Contexto de risco: o que provavelmente é, por que importa, impacto nos negócios, ações recomendadas

O FlatScan atende a ambos. Ele realiza análise estática por segurança e velocidade, e então converte o resultado tanto em saída legível por máquina quanto em relatórios prontos para a gestão.

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]

Visão Geral da Arquitetura

O FlatScan é construído como um pipeline de análise multi-estágio com execução paralela, um sistema de plugins e nenhuma dependência externa — o go.mod não requer nada, e o motor de desmontagem em Go puro está embutido no próprio repositório como internal/x86asm (uma cópia não modificada de golang.org/x/arch/x86/x86asm, BSD-3-Clause). Sem cgo, sem dependências de runtime ou de sistema, sem necessidade de rede para compilar.

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

Princípios de Design Fundamentais

Princípio	Implementação
Zero dependências externas	go.mod não requer nada e não há go.sum. A biblioteca padrão do Go mais um pacote vendorizado e não modificado — internal/x86asm, uma cópia de golang.org/x/arch/x86/x86asm (BSD-3-Clause, motor de desassemblagem) mantida na árvore para que a compilação não precise de download nem de rede. Sem cgo, sem bibliotecas nativas, sem dependências de runtime
Apenas Estático	Nunca executa a amostra — lê bytes e metadados
Thread-Safe	parallelRun() com descobertas protegidas por mutex, verificado com race-detector. As etapas de análise recuperam panics individualmente, de modo que uma amostra malformada não pode abortar um lote
Portátil entre Plataformas	Compila para Linux, macOS, Windows; mmap no Linux com fallback transparente
Extensível	Interface de plugins + manifestos JSON para detecções personalizadas sem recompilar

Estado de verificação

Verificação	Resultado
go build / go vet / gofmt -l	Limpo
go test ./...	189 testes (344 casos incluindo subtestes), todos passando
go test -race ./...	Limpo
go test -cover ./...	50,6% das instruções
golangci-lint run	0 problemas (errcheck, govet, staticcheck, gosec, errorlint, ineffassign, unused, bodyclose, nilerr, misspell, unconvert, wastedassign)
govulncheck ./...	Nenhuma vulnerabilidade encontrada

Ambiente de teste. Verificado em Fedora Linux 44 (x86_64, kernel 7.1.7) com Go 1.26.5. O piso do go.mod é Go 1.25. A CI também executa a mesma suíte em ubuntu-latest. Linux é a única plataforma onde estes resultados são medidos: macOS e Windows são alvos suportados e o código compila de forma cruzada para eles, mas os números acima não são reproduzidos de forma independente lá, e mmap_linux.go é exclusivo do Linux por construção (outras plataformas usam o fallback de leitura em buffer).

---

Pipeline de Análise

O motor processa arquivos através de 18 etapas com execução paralela para operações independentes: