firmware-security-workbench 1.0.0

Firmware Security Workbench defensive firmware analysis toolkit

Firmware Security Workbench

Firmware Security Workbench is an open-source firmware analysis platform for developers, security learners, and embedded engineers.

The goal is to upload or scan firmware images such as .bin, .elf, .hex, and .uf2, extract useful security evidence, detect risky artifacts, compare versions, and generate clear reports.

Why This Exists

Firmware security tools are often either very advanced research tools or small command-line utilities. This project aims to sit in the middle:

• beginner-friendly enough to learn from
• practical enough for real firmware review
• modular enough for open-source contributors
• polished enough to showcase as a serious portfolio project

Planned Capabilities

• CLI firmware scanner
• Local web dashboard
• Firmware metadata extraction
• Hashing and entropy analysis
• Strings and suspicious keyword detection
• Secret and credential detection
• YARA rule scanning
• SBOM-style component discovery
• Possible CVE matching with confidence levels
• Firmware version diffing
• Firmware Risk DNA profile
• Hardening Simulator with what-if security action planning
• HTML, Markdown, and JSON reports
• Sample vulnerable firmware corpus for demos

Signature Feature: Firmware Risk DNA

Firmware Risk DNA will create a behavior-style risk fingerprint for a firmware image. Instead of only listing raw strings, it will summarize evidence into categories such as:

• networking behavior
• debug leftovers
• OTA update logic
• credential exposure
• cryptography usage
• risky service endpoints
• risk added or removed between versions

This feature is designed to make reports more useful to developers than a long unstructured list of findings.

Repository Workflow

This project is built phase by phase.

• main is the stable branch.
• Each phase uses a branch named phase/XX-short-name.
• Work is committed to the phase branch first.
• At the end of the phase, the phase branch is merged back into main.

Example:

git checkout main
git checkout -b phase/02-cli-scanner-mvp

Current Status

Current status: Phase 17 - Hardening Simulator

The project includes the full roadmap feature set through v1.0.0 and an innovation extension: Hardening Simulator for prioritized remediation actions and projected risk reduction scenarios.

Quick Start

Run the scanner:

./scripts/fwb scan samples/demo-firmware.bin

Run scanner without saving:

./scripts/fwb scan samples/demo-firmware.bin --no-save

Scan Intel HEX:

./scripts/fwb scan samples/demo-firmware.hex --json

Print full JSON output:

./scripts/fwb scan samples/demo-firmware.bin --json

Run with an additional custom YARA rule file:

./scripts/fwb scan samples/demo-firmware.bin --rules-file rules/yara/fwb_core_rules.yar

Write CycloneDX SBOM JSON:

./scripts/fwb scan samples/demo-firmware.bin --sbom-out reports/generated/demo-sbom.json

Compare two firmware images:

./scripts/fwb diff samples/corpus/esp32-lab-vuln.bin samples/corpus/stm32-lab-vuln.bin --json --out reports/generated/esp32-vs-stm32.diff.json

Render report from saved JSON:

./scripts/fwb report reports/generated/esp32-vs-stm32.diff.json --kind diff --format html --out reports/generated/esp32-vs-stm32.diff.html

Write JSON report to disk:

./scripts/fwb scan samples/demo-firmware.bin --out reports/generated/demo-scan.json

Run full showcase script:

./scripts/demo-showcase.sh

List saved scan history:

./scripts/fwb history list

Show one saved scan:

./scripts/fwb history show 1 --json

Run tests:

python3 -m unittest discover -s tests -v

Run API server:

uvicorn backend.app:app --reload --port 8000

Run with Docker:

docker build -t fwb:latest .
docker run --rm -p 8000:8000 fwb:latest

API docs:

http://127.0.0.1:8000/docs

Dashboard:

http://127.0.0.1:8000/dashboard

Safety Scope

This project is for defensive firmware analysis, developer education, and security auditing. It does not include exploit generation, unauthorized device access, credential abuse, or malware deployment.

Repo Layout

backend/          FastAPI backend
cli/              Command-line scanner
docs/             Project docs, architecture, learning notes
frontend/         Dashboard UI
.github/          CI workflow
Dockerfile        Container packaging
reports/          Report templates and generated report output
rules/            Detection rules, including YARA rules
samples/          Safe sample firmware and test fixtures
scripts/          Utility scripts
tests/            Automated tests