# refirmlabs/binwalk architecture

> Architecture diagram of the GitHub repository refirmlabs/binwalk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/refirmlabs/binwalk
- Repository: https://github.com/refirmlabs/binwalk

## Overview

##### Project type and purpose
- This is a command-line firmware analysis tool and Rust library (Binwalk v3).
- It reads binary firmware files, identifies embedded file/data signatures, optionally extracts them, and can perform entropy analysis.
- It also provides a core Rust API for integration and supports fuzzing and Docker-based builds.

##### File structure
- Top-level binaries and scripts:
- Cargo.toml, src/main.rs: primary CLI binary (“binwalk”)
- src/lib.rs: core library exposing scan and extract functions
- scripts/binwalk-ui: optional UI wrapper
- fuzzing/: separate fuzzing harness to test core library
- dependencies/: scripts and manifests to install prerequisites (Python, Ubuntu, pip)
- Dockerfile and build_docker.sh: containerized build/deploy
- Core code modules under src/:
- cliparser.rs: parse CLI args into configuration
- common.rs: shared utilities and types
- .rs, json.rs: output formatting (terminal vs JSON)
- entropy.rs: entropy-analysis routines
- magic.rs, signatures/: signature definitions and detection logic
- extractors/: logic to extract each file/data type
- structures/: parse file-specific internal structures
- binwalk.rs: orchestrator that ties parsing, scanning, extraction, output
- Tests under tests/: unit tests covering signatures and extractors against sample inputs.

##### README for additional insights
- Confirms primary focus (firmware analysis), key features (signature scanning, extraction, entropy graphs).
- Mentions library integration and Docker builds.

##### Detailed breakdown recommendation
- Layer 1 (top): User CLI and UI
- Layer 2 (core):
- Arg Parser → Controller
- Controller branches into Scanner, Parsers, Entropy, Extractors
- Output Formatter
- Side modules:
- Test Suite → calls core API
- Fuzzing Harness → calls core API
- Bottom: Build/Deploy
- Docker build → produces binwalk binary

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User Interface
    subgraph "User Interface Layer"
        direction TB
        CLI["CLI Frontend"]:::code
        UIWrapper["Optional UI Wrapper"]:::external
    end

    %% Layer 2: Core Library
    subgraph "Core Library Layer"
        direction TB
        ArgParser["CLI Argument Parser"]:::code
        CoreEntry["Core Library Entry Point"]:::code
        Controller["Controller / Orchestrator"]:::code
        subgraph "Analysis Components"
            direction TB
            Scanner["Signature Scanner Logic"]:::code
            SigDefs["Signature Definitions"]:::code
            StructLogic["Structure Parsers Logic"]:::code
            StructDefs["Structure Definitions"]:::code
            Entropy["Entropy Analyzer"]:::code
            subgraph "Extraction"
                direction TB
                Dispatcher["Extractors Dispatcher"]:::code
                Extractors["Individual Extractor Modules"]:::code
            end
        end
        subgraph "Output Formatters"
            direction TB
            Display["Display Formatter (terminal)"]:::code
            JSONFmt["JSON Formatter"]:::code
        end
    end

    %% Side Modules
    subgraph "Testing & Fuzzing"
        direction TB
        Tests["Test Suite"]:::dashed
        Fuzz["Fuzzing Harness"]:::dashed
    end

    %% Build & Deployment
    subgraph "Build/Deploy"
        direction TB
        Dependencies["Dependency Installation Scripts"]:::external
        Docker["Docker Container"]:::external
        BuildScript["Docker Build Helper Script"]:::external
        CargoToml["Cargo Manifest"]:::code
    end

    %% Data Storage
    InputFile["Input Firmware File"]:::storage
    Extracted["Extracted Files"]:::storage

    %% Connections
    CLI -->|invokes| ArgParser
    CLI -->|invokes| Controller
    UIWrapper -->|wraps| CLI
    ArgParser -->|produces ScanConfig| Controller
    Controller -->|reads| InputFile
    Controller -->|calls| Scanner
    Scanner -->|uses| SigDefs
    Controller -->|calls| StructLogic
    StructLogic -->|uses| StructDefs
    Controller -->|calls| Entropy
    Controller -->|calls| Dispatcher
    Dispatcher -->|loads| Extractors
    Dispatcher -->|writes to| Extracted
    Controller -->|formats via| Display
    Controller -->|formats via| JSONFmt
    Display -->|outputs result| CLI
    JSONFmt -->|outputs result| CLI
    Tests -->|calls API| CoreEntry
    Fuzz -->|calls API| CoreEntry
    Dependencies -->|provides| CLI
    Docker -->|builds| CLI
    BuildScript -->|runs| Docker
    CargoToml -->|defines build| CLI

    %% Click Events
    click CLI "https://github.com/refirmlabs/binwalk/blob/master/src/main.rs"
    click ArgParser "https://github.com/refirmlabs/binwalk/blob/master/src/cliparser.rs"
    click CoreEntry "https://github.com/refirmlabs/binwalk/blob/master/src/lib.rs"
    click Controller "https://github.com/refirmlabs/binwalk/blob/master/src/binwalk.rs"
    click Scanner "https://github.com/refirmlabs/binwalk/blob/master/src/magic.rs"
    click SigDefs "https://github.com/refirmlabs/binwalk/tree/master/src/signatures/"
    click StructLogic "https://github.com/refirmlabs/binwalk/blob/master/src/structures.rs"
    click StructDefs "https://github.com/refirmlabs/binwalk/tree/master/src/structures/"
    click Dispatcher "https://github.com/refirmlabs/binwalk/blob/master/src/extractors.rs"
    click Extractors "https://github.com/refirmlabs/binwalk/tree/master/src/extractors/"
    click Entropy "https://github.com/refirmlabs/binwalk/blob/master/src/entropy.rs"
    click Display "https://github.com/refirmlabs/binwalk/blob/master/src/display.rs"
    click JSONFmt "https://github.com/refirmlabs/binwalk/blob/master/src/json.rs"
    click CargoToml "https://github.com/refirmlabs/binwalk/blob/master/Cargo.toml"
    click UIWrapper "https://github.com/refirmlabs/binwalk/tree/master/scripts/binwalk-ui"
    click Fuzz "https://github.com/refirmlabs/binwalk/blob/master/fuzzing/src/main.rs"
    click Tests "https://github.com/refirmlabs/binwalk/tree/master/tests/"
    click Dependencies "https://github.com/refirmlabs/binwalk/tree/master/dependencies/"
    click Docker "https://github.com/refirmlabs/binwalk/tree/master/Dockerfile"
    click BuildScript "https://github.com/refirmlabs/binwalk/blob/master/build_docker.sh"

    %% Styles
    classDef code fill:#E8F1FB,stroke:#0366D6,color:#022A61,stroke-width:1.5px;
    classDef external fill:#FFF5E5,stroke:#D97706,color:#92400E,stroke-width:1.5px;
    classDef storage fill:#EEF9EF,stroke:#166534,color:#14532D,stroke-width:1.5px;
    classDef dashed stroke-dasharray: 5 5;
    class CLI,ArgParser,CoreEntry,Controller,Scanner,SigDefs,StructLogic,StructDefs,Entropy,Dispatcher,Extractors,Display,JSONFmt,CargoToml code
    class UIWrapper,Dependencies,Docker,BuildScript external
    class InputFile,Extracted storage
    class Tests,Fuzz dashed
```
