A production-grade, full-stack cybersecurity application powered by Deep Learning.
Traditional side-channel detection relies on static, highly technical post-incident analysis of hardware performance counters. CacheGuard moves this to the edge. By utilizing a streaming PyTorch LSTM neural network, CacheGuard classifies cache access latency signatures instantaneously and broadcasts the results to a cinematic, highly-responsive React dashboard.
Imagine a security camera system, but instead of watching a physical door, it watches the microscopic speed limit of your computer's memory. Here is how information flows through CacheGuard:
- 🔬 The Sensors (The Lookouts): Lightweight scripts running on edge servers constantly monitor memory access speeds (cache latency). If a hacker attempts to steal data using a side-channel attack (like Flush+Reload), the memory access times will artificially slow down or spike in unnatural patterns.
- 🧠 The AI Brain (FastAPI & PyTorch): These speed measurements are blasted over a real-time WebSocket connection to the CacheGuard API. The API feeds this telemetry into a Neural Network (an LSTM) specifically trained to recognize the "rhythm" of a hacker's attack.
- 📡 The Broadcast (The Alarm): The moment the AI calculates a high probability of an attack (e.g.,
99.8% threat), the API instantly broadcasts a "Threat Alert" to all connected dashboards globally. - 🖥️ The UI (The Control Room): The dashboard receives this broadcast in milliseconds. Instead of displaying a dense, unreadable log file, it translates the mathematical threat probability into visual alarms and feeds it directly into our Guardian Robot.
graph TD
subgraph "Edge Environment"
S1[Hardware Sensor 1]
S2[Hardware Sensor 2]
end
subgraph "Backend Engine"
API[FastAPI Server]
AI[PyTorch LSTM]
State[(In-Memory Buffer)]
end
subgraph "Presentation Layer"
UI1[React Dashboard]
end
S1 -- "WebSocket\n/ws/v1/telemetry" --> API
S2 -- "WebSocket\n/ws/v1/telemetry" --> API
API -- "Inference Request" --> AI
AI -- "0.0 - 1.0 Threat Prob" --> API
API -- "Store History" --> State
API -- "WebSocket Broadcast\n/ws/v1/stream" --> UI1
At the center of the dashboard is the Guardian Mascot—a custom-built, animated HTML5 canvas robot designed to translate complex AI mathematics into instant human emotion.
To a non-technical stakeholder, a raw output of 0.85 Sigmoid Probability means nothing. CacheGuard solves this by mapping the AI's confidence levels directly to the robot's "personality":
- 🟢 Safe (Cyan): When traffic is clean, the robot breathes calmly, blinks slowly, and the entire dashboard glows in a soothing cyan. It indicates "All systems normal."
- 🟡 Warning (Yellow): If the AI detects slightly unusual behavior (30% - 49% threat probability), the robot's eyes widen, its breathing quickens, and the dashboard shifts to yellow. It acts as an early warning system.
- 🔴 Critical Threat (Red): The moment a definitive attack pattern is recognized (>50% probability), the robot instantly becomes "angry." Its eyes narrow, the interface flashes red, and alarms slide onto the screen.
By tying the underlying mathematical models to the emotional state of a character, anyone in the room can instantly understand the security status of the network just by looking at the robot.
CacheGuard is built with a modern, decoupled architecture separating the AI inference engine from the presentation layer.
- Model: A 2-Layer Long Short-Term Memory (LSTM) network.
- Why LSTM? Cache timing attacks are inherently sequential. An attacker's signature isn't a single slow memory access, but rather a temporal pattern of cache hits and misses over time. LSTMs excel at learning these temporal dependencies.
- Architecture Details: The network takes sequence windows of 50 latency timings, normalizes them via Z-score scaling, and passes them through two hidden layers (128 units) with
LayerNormandDropout(0.3) to prevent overfitting.
- High-Concurrency API: Capable of handling thousands of telemetry events per second via asynchronous Python.
- Dual WebSocket Design:
/ws/v1/telemetry: Ingestion endpoint for sensors to stream raw hardware latency arrays./ws/v1/stream: A PubSub broadcast endpoint that pushes classified events to all connected UI dashboards simultaneously.
- Visual Design: A premium, dark-mode-first aesthetic heavily inspired by cyberpunk and cinematic UIs. Features CSS glassmorphism, dynamic scanlines, and CSS custom properties for global theming.
- Performance: Real-time canvas scrolling time-series plots and smooth D3-style SVG arc gauges render the incoming probability stream without DOM-thrashing.
Requires Python 3.11+ and Node.js 18+.
# Clone the repository
git clone https://github.com/yourusername/cacheguard.git
cd cacheguard
# Set up Python environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
# Configure environment variables
cp .env.example .envBefore starting the API, you must generate the synthetic dataset and train the LSTM weights.
python cacheguard/ml/train.pyYou will need three terminal instances to run the full stack locally.
Terminal 1: The API Engine
python api.pyTerminal 2: The UI Dashboard
cd frontend
npm install
npm run devTerminal 3: The Sensor Simulator
python sensor.py🌐 Open your browser to http://localhost:5173 to view the live dashboard.
CacheGuard includes a production-ready, multi-stage Docker setup. It packages the API into a non-root container, serves the compiled React frontend via NGINX, and spins up Prometheus and Grafana for backend observability.
docker compose -f docker/docker-compose.yml up --build -d- 🖥️ Dashboard:
http://localhost:80 - 📖 FastAPI Docs:
http://localhost:8000/docs - 📊 Grafana:
http://localhost:3001
Released under the MIT License. See LICENSE for more information.