Gauntlet

Overview

Gauntlet is the web-based management platform for hardware, OT, ICS, and IoT security assessments. It wraps Gearbox — a multi-tool hardware testing engine — in a structured project management layer with real-time console streaming, multi-device collaboration, comprehensive evidence management, and findings aggregation. The typical workflow is:

1. Define the device — Create a project describing the physical device, its sub-components, interfaces, and specific port instances
2. Launch the assessment — Start Gearbox from the browser; it walks through every assigned module on every interface instance automatically
3. Interact in real time — Answer prompts, capture photos from a mobile companion, and watch findings stream in live
4. Review and manage findings — Filter, override, group, rename, and mark false positives across all discovered issues
5. Export results — Download the full project as JSON or ZIP for reporting

Gauntlet runs as a Flask/SocketIO application on port 5700 over HTTPS with session-based authentication. It supports 34 visual themes with dark/light mode toggle.

New Project Wizard

The wizard guides you through defining a new hardware assessment project in five steps. All fields are saved into a YAML configuration file that Gearbox reads to determine what to test.

Step 1 — Client & Engagement Information

Step 2 — Consultant & Point of Contact

All consultant/POC fields are included in JSON exports and report metadata.

Step 3 — Device Under Test

Step 4 — Subdevices & Interfaces

This is the most important step. Here you model the physical structure of the device under test.

Hierarchy

• Subdevice — A distinct physical component of the device (e.g., "Controller Unit", "Display Panel", "Sensor Module"). Add as many as needed with the Add Subdevice button.
• Interface — A communication interface type on a subdevice. Select from the dropdown:

  Category	Interface Types
  Network	Ethernet, Ethernet_tap (passive tap), WiFi
  USB	USB
  Video	HDMI, Dvi, sdi, Dp (DisplayPort), Rca, Aux
  Serial	DB9 (serial + CAN bus)
  Wireless	Bluetooth, Zigbee, SubGHz, UWB, ZWave, LoRa, RFID
  Other	SmartCard

  Each interface type determines which test modules Gearbox will execute.
• Instance — A specific physical port or connection point (e.g., "Front Panel RJ45", "Rear USB-A Port 1"). Every instance gets its own test run through all applicable modules.

Operations

• Add Subdevice — Creates a new named subdevice
• Remove Subdevice — Deletes a subdevice and all its interfaces/instances
• Add Interface — Adds an interface type to a subdevice (from the dropdown)
• Remove Interface — Removes an interface and all its instances
• Add Instance — Adds a physical port/connector to an interface, with a location label
• Remove Instance — Removes a specific instance

Step 5 — Target Directory (Optional)

Optionally specify a custom output directory for the project. If left blank, Gauntlet auto-builds a structured path:

<clients_base>/<client_short>/<year>/gearbox/<client_short>_<YYYYMMDD_HHMMSS>/

The clients base directory is platform-dependent: /clients (Linux), /Users/Shared/clients (macOS), or C:\clients (Windows).

Editing an Existing Project

The Edit Project page uses the same form as the wizard, pre-populated with the current configuration. You can modify any field, add or remove subdevices/interfaces/instances, and save. If the client short name or device name changes, the YAML filename is updated. Stale progress entries for removed interfaces are automatically cleaned up.

Project Dashboard

After creating or selecting a project, you enter the project dashboard — a tabbed interface that covers every aspect of the assessment.

Summary Tab

The overview dashboard showing project status at a glance.

• Progress Gauge — Circular chart showing completed modules vs total modules and completed instances vs total instances
• Risk Breakdown — Color-coded distribution of finding severity: Critical, High, Medium, Low, Info
• Project Information — Client name, device, model number, software version, consultant details, engagement dates
• Instance Progress Table — Per-subdevice/interface/instance breakdown showing which modules are complete, running, pending, skipped, or N/A
• Integrity Alerts — Warnings when modules were reset due to missing evidence (e.g., a required photo was skipped)

Summary Tab Actions

Testing / Console Tab

The live testing console where you launch and monitor the Gearbox assessment.

Controls

Console Features

• Real-time stdout/stderr streaming via Socket.IO with color-coded output (stdout = normal, stderr = red, status updates highlighted, findings highlighted)
• Console history ring buffer (2,000 entries) preserved in memory and on disk — late-joining devices receive full history
• Auto-scroll with scroll-lock detection (scrolling up pauses auto-scroll)
• Password prompts are masked in the console echo

Interactive Prompts

When Gearbox needs user input (e.g., photo confirmation, IP address, Nessus credentials), a modal dialog appears on all connected devices simultaneously. Any device can answer — first response wins. Prompts support:

• Text input — Free-form answers (IP addresses, hostnames)
• Password input — Masked input for credentials
• Choice selection — Multiple-choice options
• Photo confirmation — Confirm photo quality or request retake

Each prompt has a 30-minute timeout. If no answer is provided, Gearbox continues with a default or skips the module.

Live Progress Sidebar

A real-time sidebar shows per-module status updates: pending → running → complete/skipped/na/error. Status arrives via __GB_STATUS__ tokens and /api/live_progress polling.

Findings Tab

Complete list of all security findings discovered during the assessment.

Display & Sorting

Findings are sorted by risk severity (Critical first), then alphabetically by title. Each row shows: title, risk badge, IP:port, tool/source, and CVE IDs.

Filtering

Finding Actions

Classification States

Findings can be classified as: Unconfirmed (default — tool-generated), Confirmed (tester-validated), or Validated (independently verified).

Targets Tab

All discovered hosts and open ports from the assessment.

• Observed IPs — Table showing IP address, MAC address, hostname, OS, discovery sources, associated instances, first-seen timestamp, and IP-level tools run (Nessus, Responder, tcpdump, tshark)
• Open Ports — Expandable per-IP list showing port, protocol, service, version, timestamp, and which tools produced output for that port (nmap, sslscan, testssl, nuclei, ssh-audit, etc.)

Data is sourced from the Gearbox SQLite database (discovered_hosts and open_ports tables) and observed_ips.csv from passive traffic capture.

Evidence Tab

File-based evidence management organized by the device's physical structure.

Evidence Tree

A hierarchical browser: Subdevice → Interface → Instance → Module. Each module shows a status badge (pending, running, complete, skipped, N/A). Click to expand and see individual files.

Evidence Operations

Special Evidence Directories

• _Tools/ — Device-level tool photos, organized by interface type
• _Photos/ — Per-subdevice photos in three views: FRONT, BACK, and INTERFACES

Observations Tab

Tool observations and notable events during the assessment. Observations arrive in real time from Gearbox via __GB_OBSERVATION__ tokens. Findings automatically create synthetic observations. For completed projects without live observation data, observations are reconstructed from findings.jsonl to provide a high-level summary.

Logs Tab

Combined log viewer with three views:

• Combined Logs — Merged timeline of all Gearbox and Gauntlet entries
• Gearbox Logs — Tool-specific entries parsed from __GB_LOG__ tokens with severity levels: INFO, WARNING, ERROR, FATAL, FINDING, PROMPT, ANSWER, STATUS, DONE
• Gauntlet Logs — Application-level events: device joins/disconnects, UI actions, with session ID, IP, user agent, and active tab

Log Features

• Time-range filter — From/To datetime pickers to narrow the view to a specific window
• Error-count pills — Tab badges show the error count only (not total log count), using the levels ERROR, EXCEPTION, TOOL_ERROR, FATAL, CRITICAL
• Auto-refresh — Live updates via Socket.IO events

Errors Tab

All errors encountered during the assessment, auto-categorized into three types:

• Communication — Network, socket, timeout, DNS errors
• Tool — Subprocess failures, non-zero exit codes, permission errors
• Gearbox — Internal errors from the engine itself

Error types include ERROR, WARNING, FATAL, STDERR, and TOOL_ERROR. Features include time-range filtering (From/To datetime pickers) and error-count pills that reflect only error-level entries.

Deleted Tab

Archive of all deleted and archived items — evidence files that were replaced, findings that were deleted, and modules that were cleared. Shows original filename, archive timestamp, and file size. You can view the content of deleted files (images rendered, text displayed).

Testing Modules by Interface Type

Each interface type has a predefined set of test modules that Gearbox executes. The table below shows the primary modules and their tools.

Ethernet Modules

USB Modules

Video Modules (HDMI, DVI, DisplayPort, SDI)

Wireless & RF Modules

Serial & Passive Modules

Multi-Device Collaboration

Gauntlet supports simultaneous participation from multiple devices during a physical assessment.

• Socket.IO Rooms — All devices viewing the same project share a room. Console output, prompts, findings, and status updates are broadcast to everyone.
• QR Code Join — The Testing tab displays QR codes for each network interface on the host machine. Mobile devices scan the QR to open a companion page (/join/<project_id>) for photo capture and prompt answering.
• Photo Context — The desktop Evidence tab can set a target context (module/instance) so mobile photo uploads are automatically filed into the correct evidence directory without the mobile user selecting it.
• Prompt Collaboration — When Gearbox asks for input, the prompt appears on all connected devices. The first response wins — useful for distributed teams where one person is at the keyboard and another is at the device.
• Late Join — Devices joining mid-assessment receive the full console history and current state, so they can catch up without missing context.

Nessus Integration

To use the Nessus vulnerability scanner during assessments, set environment variables before starting Gauntlet:

export NESSUS_USER=admin
export NESSUS_PASS=yourpassword
python3 app.py

Gauntlet forwards these to Gearbox as --nessus-user / --nessus-pass CLI arguments, ensuring credentials survive the sudo boundary. Gearbox handles scan creation, launching, status polling, and result export. Nessus findings are automatically ingested into the findings store.

Automated Evidence Parsing

When evidence files are uploaded (or generated by Gearbox), Gauntlet automatically detects the tool that produced them and extracts security findings. Supported formats:

Export & Import

Export Options

Import Options

Gearbox Communication Protocol

Gearbox communicates with Gauntlet through structured protocol tokens in stdout:

Prompt responses are written to Gearbox's stdin. When multiple clients are connected, the first response wins.

Process Management

• Sequential Execution — Only one Gearbox instance runs at a time per Gauntlet server. Additional requests are placed in a disk-persisted queue.
• Queue Persistence — The execute queue is saved to execute_queue.json and survives Gauntlet restarts. When the current assessment completes, the next queued job auto-starts.
• Graceful Shutdown — SIGTERM allows Gearbox to run cleanup (kills Responder, stops Nessus, reverts DHCP). SIGKILL fallback after 8 seconds. Full process tree termination via psutil.
• Subprocess Tree — View and manage every running subprocess from the Testing tab. Kill individual child processes without terminating the entire assessment.
• System Cleanup — Dedicated cleanup action that kills any running Responder, stops Nessus scans, and reverts the test interface to DHCP defaults.

Integration Points

Transport Security

Gauntlet runs exclusively over HTTPS using a self-signed TLS certificate (ssl.crt / ssl.key). The Flask-SocketIO server binds to 0.0.0.0:5700 with ssl_context provided by the shared _auth module. All communication between the browser and Gauntlet is encrypted.

Authentication

Session-based authentication via the shared _auth.py module (identical pattern across Crucible, Vantage, Bastion, Spectre, and Gauntlet). Every request passes through _auth.auth_gate() before reaching any route. The login page is rendered at /login; successful authentication creates a session cookie.

Session Management

• Session cookie: gauntlet_session, HttpOnly, SameSite=Lax
• Session timeout: 30 minutes (configurable via PERMANENT_SESSION_LIFETIME)
• Session ping: POST /api/session_ping extends the session without a full page reload
• Password change: Available at /auth/change-password

Security Headers

Applied via _auth.apply_security_headers() on every response:

• Cache-Control: no-store, no-cache, must-revalidate, max-age=0 on HTML responses
• Pragma: no-cache
• X-Frame-Options, X-Content-Type-Options, and other standard headers

Upload Security

• Max upload size: 4 GB (for project ZIP imports)
• Photo uploads: Extension whitelist (jpg, jpeg, png, gif, webp) with content-type fallback for iOS live captures
• Path traversal protection: All file-read operations validate that the resolved path is within the project directory. The /api/read_file endpoint compares the absolute path against the project root and rejects any path containing .. segments or falling outside the project tree.
• Evidence uploads: Content validation per module type (e.g., verifying PCAP magic bytes, XML structure for Nessus files, JSON validity for structured output).

CSRF Protection

State-changing operations use POST requests with JSON bodies. The session cookie's SameSite=Lax policy provides baseline CSRF protection. Secret keys are generated and managed by the _auth module.

Process Isolation

Gearbox runs as a sudo subprocess. Gauntlet does not execute arbitrary commands from user input. The Gearbox path is resolved to the canonical install location (/opt/pr0t31n/Gearbox/gearbox.py) if the provided path is not absolute or does not exist. Nessus credentials are read from environment variables and passed as CLI arguments rather than being stored on disk.

Finding Identity

Gearbox findings use the catalogue ID prefix GB-NNN (e.g., GB-001, GB-042). Each finding is assigned a UUID for unique identification within the project. Findings are stored in findings.jsonl (one JSON object per line) and optionally in a SQLite database (gearbox.db).

Risk Levels

Findings use five risk levels, always uppercase: CRITICAL, HIGH, MEDIUM, LOW, INFO. The UI also recognizes Informational (legacy) and Unknown for unclassified findings. Risk colors: Critical=magenta (#FF00FF), High=red (#E7716F), Medium=amber (#FFC000), Low=green (#92D050), Informational=light blue (#BDD7EC), Unknown=gray (#A0AEC0).

Hardware-Specific Fields

Gearbox findings include hardware-specific fields beyond the universal schema:

• subdevice: The sub-device this finding pertains to (e.g., "Controller Unit", "Sensor Module")
• interface: The interface type tested (e.g., "Ethernet", "USB", "Bluetooth")
• instance: The specific interface instance (e.g., "eth1", "usb_a_front")
• classification: Finding validation status: Unconfirmed, Confirmed, or Validated
• tools_used: List of tools that produced or contributed to this finding
• commands_used: List of commands executed to discover this finding
• output_files: List of evidence file paths (relative to project directory)

Finding Grouping

Related findings can be merged under a single display title. For example, multiple SSL certificate findings on different ports can be grouped as "SSL Certificate Issues." Grouping:

• Creates a new finding with a fresh UUID and the grouped title
• Inherits the highest risk level from all originals
• Combines all output_files and affected items
• Merges all tools_used lists (deduplicated)
• Soft-deletes originals to deleted_findings.jsonl with _grouped_into markers
• Records the operation in finding_grouping_changes.jsonl for audit

Finding Lifecycle

A finding can transition through these states:

1. Active: Present in findings.jsonl, displayed in the Findings tab
2. Risk-adjusted: Risk level overridden by the tester (persisted to JSONL and DB)
3. Renamed: Title changed for clarity (audit logged)
4. Grouped: Original soft-deleted; new grouped finding created
5. Deleted: Moved to deleted_findings.jsonl (recoverable via the deleted findings view)
6. False Positive: Moved to falsePositives.json + falsePositives.csv (recoverable)

Module-Based Progress Tracking

Gauntlet does not use a traditional action-items model. Instead, it tracks progress through a module-based completion system. Each interface instance has a set of assigned test modules, and the module status (pending, running, complete, failed) drives the progress dashboard.

Progress Calculation

Progress is computed as completed modules divided by total modules across all instances. When Gearbox emits a __GB_STATUS__ token with a module's completion status, the progress counter updates in real time. When all modules across all instances show as completed, the project status transitions to "complete."

Module Status States

Evidence Verification

Each module defines expected evidence files (output types, patterns, photo requirements). The evidence verification system (/api/check_evidence) validates whether required files exist for completed modules. Modules missing required evidence can be individually reset and re-run without affecting other modules.

Observations

The observations panel synthesizes action-worthy insights from findings automatically. Each finding is converted to an observation entry with timestamp, title, description, tools used, risk level, and associated output file. For completed projects, observations are reconstructed from findings.jsonl, providing a high-level summary of what was found and where.

Sequential Queue

When multiple projects need testing, the execute queue manages the order. Only one Gearbox instance runs at a time. The queue is persisted to disk and survives Gauntlet restarts. When the current test completes, the next queued job auto-starts without manual intervention.