DOCS README
Support# Bauxite Simulation & Demonstration Suite
This directory contains a suite of interactive, end-to-end demonstrations designed for Systems Engineers, CISOs, and Systems Developers. They demonstrate how Bauxite protects edge nodes, distributed robotic platforms, and edge networks against network congestion, firmware corruption, network hijacking, and volumetric floods.
All visualizations are conducted using **Foxglove Studio**, mapping systems telemetry alongside Bauxite's kernel/eBPF-resolution security metrics.
---
## Prerequisites
To run these demonstrations locally, ensure you have:
1. **Linux Environment** with kernel version $\ge 5.8$ (for eBPF/XDP hooks).
2. **Root Access** (`sudo`) for XDP attachments and Traffic Control (`tc`) configuration.
3. **Rust/Cargo** installed to compile agent and helper binaries.
4. **Python 3** installed to execute simulation harnesses.
5. **Foxglove Studio** Desktop Application (download from [foxglove.dev](https://foxglove.dev/)) installed on your visualization workstation.
---
## 1. Demo 1: Cryptographic Identity Verification in Distributed Control Networks
* **Directory:** `docs/demos/imposter/`
* **The Narrative:** "An attacker gains physical access to the edge local network and floods the command stream (`/cmd_vel`) with spoofed packets. Bauxite's identity-based command authorization framework blocks the packets, protecting the control loop. Upon detecting the intrusion, Bauxite triggers a safe fallback sequence on the control stack."
* **Concepts Shown:** Authenticated channels, eBPF XDP filter drops, automatic fallback state transitions.
### How to Run:
1. Navigate to the repository root and run the launcher:
```bash
./docs/demos/imposter/run.sh
```
2. The script will compile the generator, simulate the incident timeline, and save an MCAP file (typically under `/tmp/bauxite_recordings/imposter-demo-robot-*.mcap`).
3. Open **Foxglove Studio**.
4. Select **Open local file...** and load the generated `.mcap` file.
5. Import the custom layout configuration from:
`docs/demos/imposter/foxglove_layout.json`
6. **Timeline Playback:**
* **0s - 5s (Clean Mode):** Healthy control loop operation with low latency and minimal path deviation.
* **5s - 10s (Attack Active, No Protection):** Spoofed commands cause significant control command deviation and latency spikes.
* **10s - 15s (Bauxite Active):** Spoofed packets are dropped early (drops counter spikes), the system engages its fallback sequence, and command deviation resolves.
---
## 2. Demo 2: Prioritizing Control Traffic During Bandwidth Saturation
* **Directory:** `docs/demos/qos_swerve/`
* **The Narrative:** "A robotics workload consisting of navigation corrections, control traffic, telemetry, and video streams experiences sudden bandwidth saturation, dropping from high-speed connection to a constrained 1.5 Mbps link. Bauxite QoS lane-shaping degrades bulk video stream quality early in the network path to prioritize systems-critical control and navigation correction traffic, keeping latency low."
* **Concepts Shown:** eBPF Traffic Control (`tc`) queue priority lanes, bandwidth choke resilience.
### How to Run:
1. Run the QoS saturation demo (optionally specifying network interface like `lo` and duration):
```bash
sudo ./docs/demos/qos_swerve/run.sh lo 20
```
2. Open the generated MCAP output file in **Foxglove Studio**.
3. Import the custom layout from:
`docs/demos/qos_swerve/foxglove_layout.json`
4. **Timeline Playback:**
* **Act 1 (Standard Linux Stack - Saturation):** Network bandwidth drops, navigation packets queue up (latency rises to 500ms+), and control messages are delayed.
* **Act 2 (Bauxite QoS Active - Saturation):** Bulk video packets are dropped to clear queue lag, keeping control traffic latency at ~1.2 ms and correction update delay under 10 ms.
---
## 3. Demo 3: Fault-Tolerant, Cryptographically Secure Firmware Updates for Remote Edge Nodes
* **Directory:** `docs/demos/ota_resilient/`
* **The Narrative:** "Deploying a large virtual 3GB firmware package to a remote edge node. During transfer, the node suffers power loss and a network partition, followed by a supply-chain tampering attack. Bauxite checkpoint resumes the download from the last verified block without starting over, validates chunk-level integrity, rejects the tampered update, and performs an atomic rollback to the previous stable version."
* **Concepts Shown:** BLAKE3 chunk validation, resume-safety checkpoints, Ed25519 signature checks, atomic rollback.
### How to Run:
1. Run the OTA deployment script:
```bash
sudo ./docs/demos/ota_resilient/run.sh 20
```
2. Open the generated MCAP log file in **Foxglove Studio**.
3. Import the layout from:
`docs/demos/ota_resilient/foxglove_layout.json`
4. **Timeline Playback:**
* Observe the download progress bar, the interrupted transfer state, the resume sequence, the signature verification rejection of the tampered firmware, and the rollback timeline.
---
## 4. Demo 4: Volumetric Flood Protection and Edge Forensic Telemetry
* **Directory:** `docs/demos/security_telemetry/`
* **The Narrative:** "An edge node is subjected to a volumetric UDP flooding attack. Bauxite's kernel XDP hook drops the attack traffic instantly at the network driver layer, preventing host CPU exhaustion and control loop starvation."
* **Concepts Shown:** Early packet filtering in the XDP path, telemetry drop logs.
### How to Run:
1. Run the volumetric telemetry script:
```bash
sudo ./docs/demos/security_telemetry/run.sh eth0 30
```
2. Open the generated MCAP log in **Foxglove Studio**.
3. Import the layout from:
`docs/demos/security_telemetry/foxglove_layout.json`