Gauntlet — Overview

⚠️ Authorized Testing Only

Gauntlet orchestrates Gearbox which performs active security testing of physical hardware devices and their network interfaces. Testing devices you do not have explicit authorization to assess is illegal under laws including the CFAA (US), CMA (UK), and equivalent legislation worldwide. Always obtain signed Rules of Engagement (RoE) or Statement of Work (SoW) that explicitly covers the physical device under test before beginning any assessment. pr0t31n does not condone unauthorized testing.

🛡️ Sensitive Data Handling

Hardware assessments may capture proprietary firmware, device configurations, network traffic (PCAP), authentication credentials, and other sensitive data. Handle all collected evidence in compliance with your organization’s data protection policies and applicable regulations (GDPR, CCPA, HIPAA, ITAR). Store evidence in encrypted, access-controlled locations. Sanitize or destroy evidence per your data retention policy upon engagement completion.

What is Gauntlet?

Gauntlet is the web-based management platform for hardware security assessments. It wraps Gearbox — the pr0t31n hardware auditing engine — in a Flask/SocketIO dashboard that handles the full assessment lifecycle: project creation, real-time scan orchestration, findings collection, evidence management, and structured export.

Where Gearbox is the engine that drives 30+ testing modules against physical device interfaces (Ethernet, USB, HDMI, serial, RF, and more), Gauntlet provides the structured project management layer on top: defining what to test, tracking what has been tested, and collecting the results.

Key Capabilities

Core

Structured Project Management

YAML-backed project files define devices, subdevices, interfaces, and instances. A 7-section wizard guides you through engagement setup with progressive field reveal and live validation.

Core

Real-Time Gearbox Orchestration

Launch Gearbox as a managed subprocess, stream stdout/stderr to the browser console, and handle interactive prompts (photo requests, Nessus credentials, sudo passwords) via modal dialogs — from any connected device.

Collaboration

Multi-Device Collaboration

Socket.IO rooms let phones, tablets, and other machines join any active session. QR codes generated per network interface make it easy for field technicians to join and upload photos directly from their device camera.

Automation

Automated Evidence Parsing

Upload evidence files and Gauntlet auto-detects the tool type (Nessus XML/CSV, Nmap XML, sslscan, testssl.sh, ssh-audit, shcheck, nuclei JSON, PCAP) and extracts findings automatically.

Tracking

Module Completion Tracking

Per-instance module status tracking (complete, skipped, N/A, error) with evidence validation that enforces required files before marking modules as complete. Photo modules cannot be skipped.

Findings

Findings Management

Deduplicated findings with risk override, soft-delete with audit trail, manual rename and grouping, false positive marking with recovery, and classification (Unconfirmed / Confirmed / Validated).

Export

Export & Import

JSON export of full project state, ZIP export of the entire project directory with portable relative paths, and ZIP import of previously-exported projects. All exports include findings, evidence, and configuration.

UI

33+ Color Palettes

Rich theme system with 33+ named palettes in both light and dark modes, persisted per-browser via localStorage. Palette and mode controls are in the navigation bar on every page.

Architecture

Gauntlet runs on port 5700 over HTTPS with self-signed TLS. It uses session-based authentication via the shared _auth.py module (bcrypt password hashing, 30-minute sessions, CSRF protection). On first launch, default credentials are generated and printed to the console — you must change them on first login.

The application communicates with Gearbox via protocol tokens printed to stdout: __GB_PROMPT__ (user input requests), __GB_STATUS__ (module progress), __GB_FINDING__ (discovered findings), and __GB_LOG__ (structured log entries). All communication is parsed in real time and broadcast to connected browsers via Socket.IO.

Process Management

Gearbox runs as a sudo subprocess managed by Gauntlet. On termination, Gauntlet sends SIGTERM to the entire process tree (gearbox + all child tools). Gearbox’s signal handler runs cleanup — killing Responder, stopping Nessus scans, reverting DHCP — with a SIGKILL fallback after 8 seconds if cleanup hangs.

Important: Gauntlet never kills the managed tool’s process during a pause. Pause sends a signal that Gearbox handles internally via its checkpoint mechanism.

Data Storage

All project data is stored as files on disk — no database server required:

Project config: CLIENT_DEVICE.yaml (Gearbox reads this)
Findings: findings.jsonl (one JSON object per line)
Deleted findings: deleted_findings.jsonl (audit trail)
False positives: falsePositives.json + falsePositives.csv
Risk overrides: risk_overrides.yaml
Module progress: progress.json
Logs: gearbox_log.jsonl, gauntlet_log.jsonl
Errors: errors.jsonl
Observations: observations.jsonl

Gauntlet vs. Gearbox

Understanding the division of responsibility:

Responsibility	Gauntlet	Gearbox
Project creation & config	✅ Writes YAML	— Reads YAML
Test execution	— Launches process	✅ Runs 30+ modules
Tool invocation (nmap, nuclei, etc.)	—	✅ Directly invokes tools
Interactive prompts	✅ Renders modal UI	✅ Emits __GB_PROMPT__
Findings extraction	✅ Parses uploaded files	✅ Emits __GB_FINDING__
Evidence management	✅ Upload, validate, organize	✅ Writes output files
Module progress tracking	✅ UI + progress.json	✅ Emits __GB_STATUS__
Multi-device support	✅ Socket.IO rooms + QR	—
Report export	✅ JSON, ZIP, XLSX	—

Gauntlet Docs

Overview