Working demo of military-grade firmware integrity for edge IoT
This is a complete, working implementation of the FIRM-LOCK attestation system:
- ✅ Backend: FastAPI with WebSocket for real-time updates
- ✅ Frontend: React dashboard with professional UI
- ✅ Hardware Interface: Python module for STM32 + ATECC608A communication
- ✅ Simulation Mode: Works without hardware for demos
┌─────────────────────────────────────────────────────────────────────────┐
│ FIRM-LOCK SYSTEM │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ WebSocket ┌─────────────────────────────┐ │
│ │ React │◀────────────────────▶│ FastAPI Backend │ │
│ │ Dashboard │ HTTP API │ │ │
│ │ │ │ • Attestation Engine │ │
│ │ • Real-time │ │ • Device Registry │ │
│ │ • PCR viz │ │ • Challenge/Response │ │
│ │ • Controls │ │ • WebSocket Manager │ │
│ └──────────────┘ └──────────────┬──────────────┘ │
│ │ │
│ │ Serial/USB │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Hardware Interface │ │
│ │ │ │
│ │ • STM32 (Cortex-M33) │ │
│ │ • ATECC608A Secure Element │ │
│ │ • LoRa/BLE/USB Comms │ │
│ └─────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
- Python 3.9+
- Node.js 18+
- (Optional) STM32 Nucleo board + ATECC608A for hardware mode
# Clone the repository
git clone https://github.com/TeamMavericKX/firmlockv01.git
cd firm-lock
# Setup backend
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
# Setup frontend (in another terminal)
cd ../
npm installcd backend
source venv/bin/activate
python main.pyBackend will start at http://localhost:8000
# In project root
npm run devFrontend will start at http://localhost:5173
Navigate to http://localhost:5173 in your browser.
- Open Dashboard → See device status as "HEALTHY"
- Click "Trigger Attestation" → Watch real-time verification
- Click "Simulate Attack" → See PCR mismatch detection
- Click "Trigger Recovery" → Watch automatic restoration
- Connect STM32 via USB
- Backend auto-detects device
- Dashboard shows "Hardware" badge
- All operations communicate with real device
firm-lock/
├── backend/
│ ├── main.py # FastAPI application
│ ├── requirements.txt # Python dependencies
│ └── hardware/
│ ├── __init__.py
│ └── device_interface.py # STM32/ATECC608A interface
├── src/
│ ├── App.tsx # Main React application
│ ├── App.css # Custom styles
│ └── ... # React components
├── index.html # HTML entry point
├── package.json # Node dependencies
├── vite.config.ts # Vite configuration
└── README.md # This file
| Component | Part Number | Cost |
|---|---|---|
| MCU Dev Board | STM32 Nucleo-U585 | ~$15 |
| Secure Element | ATECC608A Breakout | ~$8 |
| LoRa Module | RFM95W Breakout | ~$20 |
STM32 Nucleo-U585 ATECC608A
────────────────────────────────────
3.3V ─────────────── VCC
GND ─────────────── GND
PB7 (I2C) ─────────────── SDA
PB6 (I2C) ─────────────── SCL
STM32 Nucleo-U585 RFM95W
────────────────────────────────────
3.3V ─────────────── VCC
GND ─────────────── GND
PA5 (SPI) ─────────────── SCK
PA6 (SPI) ─────────────── MISO
PA7 (SPI) ─────────────── MOSI
PA4 (GPIO) ─────────────── NSS
The STM32 firmware and entire project deck is in a separate repository: STM32x --beta Docs
| Endpoint | Method | Description |
|---|---|---|
/api/devices |
GET | List all devices |
/api/devices/{id} |
GET | Get device details |
/api/devices/{id}/challenge |
POST | Create attestation challenge |
/api/devices/{id}/evidence |
POST | Submit attestation evidence |
/api/devices/{id}/recover |
POST | Trigger recovery |
/api/devices/{id}/attack |
POST | Simulate attack (demo) |
/api/metrics |
GET | System metrics |
Connect to ws://localhost:8000/ws
Client → Server Messages:
{ "action": "ping" }
{ "action": "get_devices" }
{ "action": "trigger_attestation", "device_id": "FL-2847-AF" }
{ "action": "simulate_attack", "device_id": "FL-2847-AF" }
{ "action": "trigger_recovery", "device_id": "FL-2847-AF" }Server → Client Messages:
{ "type": "connected", "hardware_available": true }
{ "type": "attestation_complete", "result": "PASS", "latency_ms": 1.2 }
{ "type": "attack_detected", "device_id": "FL-2847-AF" }
{ "type": "device_recovered", "device_id": "FL-2847-AF" }cd backend
pytestnpm test- Start backend and frontend
- Open browser DevTools → Network → WS
- Watch WebSocket messages
- Click buttons, verify responses
npm run buildOutput in dist/ folder.
cd backend
# Using Docker
docker build -t firmlock-backend .
docker run -p 8000:8000 firmlock-backend
# Or using systemd
systemctl enable firmlock-backend
systemctl start firmlock-backend- Start with
backend/main.py- Core attestation logic - Read
hardware/device_interface.py- Hardware communication - Explore
src/App.tsx- Dashboard UI
- PCR (Platform Configuration Register): Cryptographic hash of firmware
- Measured Boot: Hashing each boot stage
- Challenge-Response: Verifier sends nonce, device signs evidence
- Golden Image: Factory-trusted firmware for recovery
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
MIT License - See LICENSE file
- MCUboot project for secure bootloader
- Microchip for ATECC608A secure element
- STMicroelectronics for STM32 platform
- Team: team.m4v3rick@gmail.com
- GitHub: Team Maverick
Trust Your Edge. Verify Every Boot. 🔒