# samudragupto/firmware-detector architecture

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

- Interactive diagram: https://gitdiagram.com/samudragupto/firmware-detector
- Repository: https://github.com/samudragupto/firmware-detector

## Overview

##### What this project is (type + purpose)
This is a **bootable bare-metal x86 security/forensics tool** implemented entirely in **NASM assembly**, designed to run **before any OS**. Architecturally, it’s not a “service-based system”; it’s a **boot chain + kernel** that alternates between CPU modes and directly inspects firmware/physical memory.

- **Boot medium layout and boot sequence (Stage 1 → Stage 2)**
- **CPU execution modes (Real Mode ↔ Protected Mode)**
- **Hardware/firmware interfaces used (BIOS interrupts, ROM regions, IVT, option ROMs)**
- **Detector modules (CRC32, signature scan, entropy analysis, baseline persistence)**

##### File tree analysis (what maps to what)
Top-level:
- `Makefile` — build orchestration (NASM invocations, image creation, likely QEMU run target)
- `Readme.md` — requirements + high-level architecture
- `bootloader/` — all runtime code (boot chain + scanning logic)

Inside `bootloader/`:
- `stage1.asm` — **Stage 1 MBR boot sector** (512 bytes). Initializes minimal environment and loads Stage 2 from disk.
- `stage2.asm` — **Stage 2 “kernel”**. Implements the forensic checks, mode switching, disk I/O, etc.
- `gdt.inc` — GDT definition/include used by Stage 2 to enter **32-bit Protected Mode**
- `pm_scanner.asm` — a distinct **Protected-Mode scanner module** (memory scanning routines run after mode switch)

This structure strongly implies a “two-stage bootloader + protected-mode scanning library” architecture.

##### What the README adds (key architectural behaviors)
The README is explicit about:
- **Two-stage boot**: Stage 1 loads Stage 2.
- **Mode switching**:
- Stage 2 sets up **GDT**, enters **Protected Mode** for performance and access patterns.
- Returns to **Real Mode** for **BIOS Interrupt** calls (especially disk I/O via INT 13h).
- **Firmware integrity checks**: CRC32 of BIOS ROM region, reset vector validation, option ROM checksum verification
- **Malware detection**: signature scanning for known implant patterns
- **IVT hook detection**: checking interrupt vectors for RAM pointers
- **Baseline persistence**: storing a baseline to the USB drive for later comparisons
- **Entropy heuristic**: detects packed/encrypted regions

##### Build/Packaging
- “Makefile / NASM toolchain”
- “Bootable USB image artifact” (the output disk image)

##### Boot Medium
- “USB / Disk Image”
- “MBR / Stage 1 (512B)”
- “Stage 2 payload (kernel)”
- “Baseline storage area / file” (where the tool persists known-good measurements)

##### Runtime Execution Environment
- “CPU (x86)”
- “16-bit Real Mode”
- “32-bit Protected Mode”
- “RAM” (where Stage 2 is loaded; where scanning buffers live)
- “Firmware / ROM”
- “BIOS ROM region”
- “Option ROM regions”
- “IVT (Interrupt Vector Table)”
- “Reset Vector @ FFFF:0000”

##### Stage 1
- “Stage 1 Bootloader (bootloader/stage1.asm)”
- minimal init
- disk read to load Stage 2
- transfer control

##### Stage 2 Kernel
- “Stage 2 Kernel (bootloader/stage2.asm)”
- “GDT setup (bootloader/gdt.inc)”
- “Mode switch manager (RM↔PM)”
- “Disk I/O via BIOS INT 13h (RM-only)”
- “Protected-mode scanner (bootloader/pm_scanner.asm)”

- CRC32 BIOS ROM measurement
- Signature scanner (known implants)
- IVT hook detector
- Option ROM checksum verifier
- Reset vector validator
- Entropy analyzer
- Baseline compare + baseline write (to USB)

**Control flow (execution order):**
##### Stage 2 (Protected Mode) → runs pm_scanner routines to scan/measure memory/ROM regions
5. Stage 2 → returns to Real Mode → uses BIOS interrupts for disk persistence (baseline) and possibly display I/O
##### Stage 2 → outputs results (screen) and/or writes baseline

**Data flow (what is being read/written):**
- Protected-mode scanner reads from:
- BIOS ROM region
- Option ROM ranges
- IVT table / interrupt vectors
- Reset vector location
- CRC32/signature/entropy modules produce:
- Measurements (checksums, entropy scores)
- Findings (match/no match, anomalies)
- Baseline module writes to:
- USB/disk “baseline storage”

- “BIOS INT calls available” only in **Real Mode**
- “Fast scanning / linear addressing” in **Protected Mode**

##### Architectural patterns/design principles
For this project, the key “patterns” aren’t MVC; they’re low-level boot/runtime patterns:

- **Two-stage bootloader pattern**
- Stage 1: tiny, fixed-size MBR loader
- Stage 2: full-featured kernel-like payload

- **Mode partitioning**
- Real Mode for firmware services (BIOS interrupts)
- Protected Mode for performance and memory scanning

- **Module separation via includes**
- `gdt.inc` as a reusable definition blob
- `pm_scanner.asm` as a protected-mode “library” called by Stage 2

- **“Pre-OS root of trust-ish” auditing**
- Reads firmware directly before OS is involved
- Baseline persistence for delta detection over time

##### Technologies and important low-level interfaces to label
Labels for:
- **x86 Real Mode (16-bit)** and **x86 Protected Mode (32-bit)**
- **GDT** (Global Descriptor Table)
- **BIOS interrupts** (especially **INT 13h** disk I/O; others if used)
- **Physical memory/ROM regions** (BIOS ROM, option ROM)
- **CRC32** and “signature database” (even if signatures are hardcoded patterns)
- “USB baseline write” (sector/file—label generically if not specified in code)

**Top row (build-time):**
- Dev machine → Makefile/NASM → bootable image

**Middle row (boot medium):**
- USB/disk image containing:
- MBR Stage1
- Stage2 payload
- baseline region/file

**Bottom row (runtime):**
- BIOS/firmware loads Stage1
- Stage1 loads Stage2 into RAM
- Stage2:

That layout captures “as many components as possible” without inventing services that don’t exist.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Build-time (Packaging)
  %% =========================
  subgraph "Build & Packaging (Host)"
    direction TB
    Dev["Developer / Build Host"]:::external
    Mk["Makefile (NASM build + image creation)"]:::build
    Doc["README Architecture Notes"]:::doc
    Img[("Bootable USB / Disk Image Artifact")]:::storage
    Dev -->|"invokes"| Mk
    Doc -.->|"documents"| Mk
    Mk -->|"produces"| Img
  end

  %% =========================
  %% Boot Medium Layout
  %% =========================
  subgraph "Boot Medium Layout (USB / Disk Image)"
    direction TB
    USB[("USB / Disk Image")]:::storage
    MBR["MBR / Stage 1 (512B)"]:::code
    S2PAY["Stage 2 Payload (Kernel)"]:::code
    BASE[("Baseline Storage Area / File")]:::storage

    Img -->|"written_to"| USB
    USB -->|"contains"| MBR
    USB -->|"contains"| S2PAY
    USB -->|"contains"| BASE
  end

  %% =========================
  %% Runtime Environment
  %% =========================
  subgraph "Target Machine (Pre-OS Runtime)"
    direction TB

    subgraph "Hardware / Firmware"
      direction TB
      CPU["x86 CPU"]:::hw
      RAM[("RAM")]:::mem

      subgraph "Firmware / ROM Regions"
        direction TB
        ROM[("System ROM")]:::rom
        BIOSROM["BIOS ROM Region"]:::rom
        OPTROM["Option ROM Regions"]:::rom
        IVT["IVT (Interrupt Vector Table)"]:::rom
        RV["Reset Vector @ FFFF:0000"]:::rom

        ROM -->|"includes"| BIOSROM
        ROM -->|"includes"| OPTROM
        ROM -->|"includes"| IVT
        ROM -->|"includes"| RV
      end
    end

    subgraph "Boot Chain & Kernel"
      direction TB

      BIOS["BIOS / Firmware Boot Strap"]:::fw

      S1["Stage 1 Bootloader"]:::code
      S2["Stage 2 Kernel / Payload"]:::code

      %% Mode partitions
      subgraph "Execution Modes (CPU)"
        direction TB

        subgraph "16-bit Real Mode (RM)"
          direction TB
          RM["RM Control & BIOS Services"]:::mode
          INT13["BIOS INT 13h Disk I/O (RM-only)"]:::iface
          OUT["Output (screen via BIOS or VGA)"]:::iface
          RM -->|"uses"| INT13
          RM -->|"reports_via"| OUT
        end

        subgraph "32-bit Protected Mode (PM)"
          direction TB
          PM["PM High-Speed Scanning"]:::mode
          GDT["GDT Setup / Descriptor Table"]:::code
          PMSCAN["Protected-Mode Scanner Module"]:::code

          PM -->|"requires"| GDT
          PM -->|"runs"| PMSCAN
        end

        MSW["Mode Switch Manager (RM↔PM)"]:::code
        RM -->|"enter_PM"| MSW -->|"ljmp_to_PM"| PM
        PM -->|"return_to_RM"| MSW -->|"restore_RM_state"| RM
      end

      %% Detection pipeline
      subgraph "Detection / Analysis Modules (Stage 2)"
        direction TB
        CRC["CRC32 BIOS ROM Measurement"]:::detect
        SIG["Signature Scan (known implant patterns)"]:::detect
        ENT["Entropy Heuristic (packed/encrypted)"]:::detect
        IVTHOOK["IVT Hook Detector (vectors pointing to RAM)"]:::detect
        OPTCHK["Option ROM Checksum Verifier"]:::detect
        RVCHK["Reset Vector Validator"]:::detect
        BASECMP["Baseline Compare"]:::detect
        BASEWR["Baseline Write (persistence)"]:::detect
      end

      %% Stage2 internal orchestration
      S2 -->|"orchestrates"| MSW
      S2 -->|"invokes_checks"| CRC
      S2 -->|"invokes_checks"| SIG
      S2 -->|"invokes_checks"| ENT
      S2 -->|"invokes_checks"| IVTHOOK
      S2 -->|"invokes_checks"| OPTCHK
      S2 -->|"invokes_checks"| RVCHK
      S2 -->|"compares"| BASECMP
      S2 -->|"persists"| BASEWR

      %% PM scanner used by detection modules
      PMSCAN -->|"feeds_data"| CRC
      PMSCAN -->|"feeds_data"| SIG
      PMSCAN -->|"feeds_data"| ENT
      PMSCAN -->|"feeds_data"| IVTHOOK
      PMSCAN -->|"feeds_data"| OPTCHK
      PMSCAN -->|"feeds_data"| RVCHK

      %% Firmware boot flow
      BIOS -->|"loads_MBR"| S1
      S1 -->|"reads_stage2_from_disk"| S2
      S2 -->|"loaded_into"| RAM
    end
  end

  %% =========================
  %% Data-flow to/from ROM, RAM, USB
  %% =========================
  PMSCAN -.->|"reads"| BIOSROM
  PMSCAN -.->|"reads"| OPTROM
  PMSCAN -.->|"reads"| IVT
  PMSCAN -.->|"reads"| RV
  PMSCAN -.->|"scans_buffers_in"| RAM

  INT13 -.->|"reads/writes"| USB
  BASECMP -.->|"reads_baseline"| BASE
  BASEWR -.->|"writes_baseline"| BASE
  OUT -.->|"prints_results"| CPU

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click Mk "https://github.com/samudragupto/firmware-detector/tree/main/Makefile"
  click Doc "https://github.com/samudragupto/firmware-detector/blob/main/Readme.md"
  click S1 "https://github.com/samudragupto/firmware-detector/blob/main/bootloader/stage1.asm"
  click S2 "https://github.com/samudragupto/firmware-detector/blob/main/bootloader/stage2.asm"
  click GDT "https://github.com/samudragupto/firmware-detector/blob/main/bootloader/gdt.inc"
  click PMSCAN "https://github.com/samudragupto/firmware-detector/blob/main/bootloader/pm_scanner.asm"
  click S2PAY "https://github.com/samudragupto/firmware-detector/tree/main/bootloader/"
  click MBR "https://github.com/samudragupto/firmware-detector/tree/main/bootloader/"

  %% =========================
  %% Styles
  %% =========================
  classDef build fill:#5B8FF9,stroke:#1D39C4,color:#FFFFFF,stroke-width:1px
  classDef doc fill:#9254DE,stroke:#391085,color:#FFFFFF,stroke-width:1px
  classDef code fill:#2F54EB,stroke:#10239E,color:#FFFFFF,stroke-width:1px
  classDef detect fill:#13C2C2,stroke:#006D75,color:#002329,stroke-width:1px
  classDef storage fill:#52C41A,stroke:#237804,color:#092B00,stroke-width:1px
  classDef hw fill:#8C8C8C,stroke:#434343,color:#FFFFFF,stroke-width:1px
  classDef mem fill:#A0D911,stroke:#3F6600,color:#102000,stroke-width:1px
  classDef rom fill:#FAAD14,stroke:#AD6800,color:#2A1600,stroke-width:1px
  classDef fw fill:#FF7A45,stroke:#AD2102,color:#2A0900,stroke-width:1px
  classDef mode fill:#FADB14,stroke:#AD8B00,color:#2A2200,stroke-width:1px
  classDef iface fill:#73D13D,stroke:#135200,color:#062000,stroke-width:1px
  classDef external fill:#0F172A,stroke:#334155,color:#E2E8F0,stroke-width:1px
```
