FlatScan

---

FlatScanは、純粋なGoで書かれた実運用グレードの静的マルウェア解析・レポートエンジンです。サンプルを実行することなく、迅速なトリアージ、IOC抽出、疑わしい機能の検出、エグゼクティブ向けレポート、ハンティングルールの引き継ぎを必要とするアナリスト向けに設計されています。

FlatScanはファイルを読み込み、ハッシュを計算し、フォーマットを識別し、文字列を抽出し、疑わしいエンコードデータをデコードし、IOCを抽出・トリアージし、実行ファイル/コンテナのメタデータを検査し、検出結果をスコアリングし、それらをマルウェアプロファイルへと強化し、テキスト、JSON、PDF、HTML、IOC、YARA、Sigma、STIX 2.1、ケースデータベース、レポートパックの各出力を生成します。

---

目次

• FlatScanが存在する理由
• アーキテクチャ概要
• 解析パイプライン
• 機能
• クイックスタート
• 出力タイプ
• Web GUI
• サンプルレポート
• スキャンモード
• スコアリングロジック
• プラグインシステム
• パフォーマンスアーキテクチャ
• モジュールマップ
• 安全性に関する注意
• 制限事項
• ドキュメント
• プロジェクトURL

---

FlatScanが存在する理由

マルウェアのトリアージには、しばしば2つの対象者が存在します:

対象者	必要なもの
セキュリティアナリスト	技術的証拠: ハッシュ、文字列、インポート、IOC、エントロピー、セクション、デコードされたデータ、TTP、ハンティングルール
CISO / 経営層	リスクの文脈: それが何である可能性が高いか、なぜ重要か、ビジネスへの影響、推奨される対応

FlatScanは両方に応えます。安全性と速度のために静的解析を行い、その結果を機械可読な出力と経営層向けのレポートの両方に変換します。

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]

アーキテクチャ概要

FlatScanは、並列実行、プラグインシステム、そして外部依存関係ゼロを特徴とする多段階の解析パイプラインとして構築されています。go.modは何も要求せず、純粋なGo製の逆アセンブリエンジンはinternal/x86asmとしてツリー内にベンダリングされています（golang.org/x/arch/x86/x86asmの未改変コピー、BSD-3-Clause）。cgoもなく、ランタイムやシステム依存関係もなく、ビルドにネットワークも不要です。

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

主要な設計原則

原則	実装
外部依存ゼロ	go.mod は何も要求せず、go.sum も存在しない。Go 標準ライブラリに加え、ベンダー化された未改変のパッケージが1つ — internal/x86asm は golang.org/x/arch/x86/x86asm（BSD-3-Clause、逆アセンブリエンジン）のコピーをツリー内に保持しており、ビルドにダウンロードもネットワークも不要。cgo なし、ネイティブライブラリなし、ランタイム依存なし
静的解析のみ	サンプルを実行することは一切なく、バイト列とメタデータを読み取るのみ
スレッドセーフ	parallelRun() はミューテックスで保護された検出結果を持ち、レース検出器で検証済み。解析ステージは個別にパニックを回復するため、1つの不正なサンプルがバッチ全体を中断させることはない
プラットフォーム移植性	Linux、macOS、Windows 向けにビルド可能。Linux では mmap を使用し、透過的なフォールバックを備える
拡張可能	プラグインインターフェース + JSON マニフェストにより、再コンパイルなしでカスタム検出を追加可能

検証状況

チェック	結果
go build / go vet / gofmt -l	クリーン
go test ./...	189 テスト（サブテストを含め 344 ケース）、すべて成功
go test -race ./...	クリーン
go test -cover ./...	ステートメントの 50.6%
golangci-lint run	問題 0 件（errcheck、govet、staticcheck、gosec、errorlint、ineffassign、unused、bodyclose、nilerr、misspell、unconvert、wastedassign）
govulncheck ./...	脆弱性は見つからず

テスト環境。 Fedora Linux 44（x86_64、カーネル 7.1.7） と Go 1.26.5 で検証済み。 go.mod の下限は Go 1.25。CI では同じスイートを ubuntu-latest 上でも実行している。 これらの結果が測定されているのは Linux のみである。macOS と Windows は サポート対象でありコードはそれらへクロスコンパイルできるが、上記の数値は そこで独立に再現されたものではなく、mmap_linux.go は構造上 Linux 専用である （他のプラットフォームではバッファ付き読み取りのフォールバックを使用する）。

---

解析パイプライン

エンジンはファイルを 18 のステージで処理し、独立した操作については並列実行する：

sequenceDiagram
    participant CLI as CLI/Interactive
    participant IO as I/O Layer
    participant Engine as Analysis Engine
    participant Parallel as Parallel Group
    participant Score as Scoring
    participant Output as Output Renderers
    
    CLI->>IO: Config + File Path
    IO->>IO: mmap or buffered read
    IO->>IO: Compute MD5/SHA1/SHA256/SHA512
    IO->>Engine: Raw bytes + Hashes
    
    Engine->>Engine: 1. File type detection
    Engine->>Engine: 2. Entropy analysis (incremental)
    Engine->>Engine: 3. String extraction (zero-alloc)
    Engine->>Engine: 4. IOC extraction + triage
    Engine->>Engine: 5. Decoder pass (base64/hex/URL)
    Engine->>Engine: 6. Corpus build (shared, single alloc)
    Engine->>Engine: 7. Pattern matching
    
    Engine->>Parallel: Launch independent stages
    
    par Format Analysis
        Parallel->>Parallel: PE/ELF/Mach-O/APK/MSIX
    and Safe Carving
        Parallel->>Parallel: Embedded artifacts
    and Crypto/Config
        Parallel->>Parallel: C2, tokens, mutex, wallets
    and Similarity
        Parallel->>Parallel: FlatHash, import hash, section hash
    end
    
    Parallel->>Engine: Merged results
    Engine->>Engine: 8. Rules + Plugins
    Engine->>Engine: 9. Family classification
    Engine->>Score: Findings
    Score->>Score: Deduplicate + Score + Verdict
    Score->>Output: Enriched ScanResult
    
    par Output Generation
        Output->>Output: Text/JSON/PDF/HTML/YARA/Sigma/STIX
    end

パイプラインステージの詳細