FlatScan

---

FlatScan is a production-grade static malware analysis and reporting engine written in pure Go. It is designed for analysts who need fast triage, IOC extraction, suspicious capability detection, executive reporting, and hunting-rule handoff — all without executing the sample.

FlatScan reads a file, hashes it, identifies the format, extracts strings, decodes suspicious encoded data, extracts and triages IOCs, inspects executable/container metadata, scores findings, enriches them into a malware profile, and produces text, JSON, PDF, HTML, IOC, YARA, Sigma, STIX 2.1, case database, and report-pack outputs.

---

Table of Contents

• Why FlatScan Exists
• Architecture Overview
• Analysis Pipeline
• Features
• Quick Start
• Output Types
• Web GUI
• Sample Report
• Scan Modes
• Scoring Logic
• Plugin System
• Performance Architecture
• Module Map
• Safety Note
• Limitations
• Documentation
• Project URL

---

Why FlatScan Exists

Malware triage often has two audiences:

Audience	Needs
Security Analysts	Technical evidence: hashes, strings, imports, IOCs, entropy, sections, decoded data, TTPs, hunting rules
CISO / Management	Risk context: what it likely is, why it matters, business impact, recommended actions

FlatScan serves both. It does static analysis for safety and speed, then converts the result into both machine-readable output and management-ready reporting.

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]

---

Architecture Overview

FlatScan is built as a multi-stage analysis pipeline with parallel execution, a plugin system, and no external dependencies — go.mod requires nothing, and the pure-Go disassembly engine is vendored in-tree as internal/x86asm (an unmodified copy of golang.org/x/arch/x86/x86asm, BSD-3-Clause). No cgo, no runtime or system dependencies, no network needed to build.

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

Key Design Principles

Principle	Implementation
Zero external dependencies	go.mod requires nothing and there is no go.sum. The Go standard library plus one vendored, unmodified package — internal/x86asm, a copy of golang.org/x/arch/x86/x86asm (BSD-3-Clause, disassembly engine) held in-tree so the build needs no download and no network. No cgo, no native libraries, no runtime dependencies
Static Only	Never executes the sample — reads bytes and metadata
Thread-Safe	parallelRun() with mutex-protected findings, race-detector verified. Analysis stages recover panics individually, so one malformed sample cannot abort a batch
Platform Portable	Builds for Linux, macOS, Windows; mmap on Linux with transparent fallback
Extensible	Plugin interface + JSON manifests for custom detections without recompiling

Verification status

Check	Result
go build / go vet / gofmt -l	Clean
go test ./...	189 tests (344 cases including subtests), all passing
go test -race ./...	Clean
go test -cover ./...	50.6% of statements
golangci-lint run	0 issues (errcheck, govet, staticcheck, gosec, errorlint, ineffassign, unused, bodyclose, nilerr, misspell, unconvert, wastedassign)
govulncheck ./...	No vulnerabilities found

Test environment. Verified on Fedora Linux 44 (x86_64, kernel 7.1.7) with Go 1.26.5. The go.mod floor is Go 1.25. CI additionally runs the same suite on ubuntu-latest. Linux is the only platform these results are measured on: macOS and Windows are supported targets and the code cross-compiles to them, but the numbers above are not independently reproduced there, and mmap_linux.go is Linux-only by construction (other platforms take the buffered-read fallback).

---

Analysis Pipeline

The engine processes files through 18 stages with parallel execution for independent operations: