firmware-fortress 1.0.0

Autonomous firmware supply chain security — CVE scanning, incident detection, CI/CD gating, and email forensics

🛡 Firmware Fortress

Autonomous firmware supply chain security — powered by four AI agents.

pip install firmware-fortress
firmware-fortress demo

Firmware Fortress hunts CVEs in firmware binaries, reconstructs attack timelines from breach logs, enforces CI/CD pipeline security, and performs deep email phishing forensics — all from a single CLI.

---

Quick Start

pip install firmware-fortress

# Run the offline demo instantly (no backend, no API keys needed)
firmware-fortress demo

# Or connect to a running backend for real analysis
firmware-fortress scan --file firmware.bin
firmware-fortress correlate --logs breach_logs.json
firmware-fortress ci-check --artifact build.bin --repo myorg/repo --branch main
firmware-fortress email-check --file suspicious.eml
firmware-fortress watch   # stream live events
firmware-fortress status  # platform stats

---

Four AI Agents

Command	Agent	What it does
scan	CVE Hunter	Extracts components from firmware, queries NVD, enriches with Groq LLaMA
correlate	Incident Detective	Correlates logs with CVEs, reconstructs attack timeline
ci-check	CI/CD Watchdog	Scans build artifacts for CVEs and secrets, blocks/approves
email-check	Email Forensics	Homograph detection, SPF/DMARC/MX checks, risk score 0–100

---

Demo Mode

Works without any backend, API keys, or internet connection. Preloaded TP-Link WR740N v4.30 breach scenario:

firmware-fortress demo                                    # full offline demo
firmware-fortress scan --file firmware.bin --demo         # instant CVE results
firmware-fortress correlate --logs logs.json --demo       # instant incident report
firmware-fortress ci-check --artifact build.bin \
  --repo x --branch main --demo                          # instant build decision
firmware-fortress email-check --file email.eml --demo     # instant forensics

---

Themes

firmware-fortress scan --file fw.bin --theme cyberpunk   # default — matrix green
firmware-fortress scan --file fw.bin --theme minimal     # clean monochrome
firmware-fortress scan --file fw.bin --theme light       # light terminal

---

Backend (Optional)

The CLI connects to a FastAPI backend for real analysis. Install the full stack:

pip install firmware-fortress[backend]

# Start the backend
uvicorn backend.main:app --reload --port 8000

# CLI auto-connects to http://localhost:8000
firmware-fortress scan --file firmware.bin

Configure via .env or environment variables:

GROQ_API_KEY=your_groq_api_key        # https://console.groq.com (free)
NVD_API_KEY=your_nvd_api_key          # https://nvd.nist.gov/developers (free)
SUPABASE_URL=https://...supabase.co   # https://supabase.com (free tier)
SUPABASE_SERVICE_KEY=your_key
BACKEND_URL=http://localhost:8000
WS_URL=ws://localhost:8000/ws

All API keys are optional — the system falls back to demo data when they're missing.

---

What the Demo Shows

The built-in demo scenario is a TP-Link WR740N v4.30 router compromise:

• 12 CVEs detected (2 CRITICAL: CVE-2019-7406 CVSS 9.8, CVE-2018-17177 CVSS 9.1)
• Attack timeline: port scan → buffer overflow → backdoor → DNS exfiltration
• CI/CD gate: build blocked due to CRITICAL CVEs
• Phishing email: tp-iink.com homograph attack, risk score 92/100

---

Requirements

• Python 3.11+
• No other system dependencies for the CLI

---

Links

• GitHub: https://github.com/your-org/firmware-fortress
• Backend API docs: http://localhost:8000/docs (when running)
• Issues: https://github.com/your-org/firmware-fortress/issues

---

License

MIT