How samudragupto/firmware-detector works
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.