Secure. Adaptive. Observable.
KAIROS combines entropy collection, cryptographic session management, ML-based threat detection, dynamic threat response, and real-time security monitoring into a unified security platform.
KAIROS is a modular security platform designed around a cryptographic gateway architecture.
The system combines:
- Hardware-assisted entropy collection
- Cryptographic session management
- Secure key generation and distribution
- ML-based anomaly and threat detection
- Dynamic Threat Response Engine (DTRE)
- Real-time security telemetry
- SOC-style security visualization
- Network topology monitoring
- Administrative security controls
The architecture separates detection, decision-making, cryptographic operations, and visualization, allowing each subsystem to be developed, tested, and extended independently.
KAIROS
│
┌───────────────────┴───────────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Security SOC │ │ Entropy / Hardware │
│ Dashboard │ │ Layer │
│ │ │ │
│ React + TypeScript │ │ ESP32 / QRNG │
│ Vite + Tailwind │ │ C++ Entropy Pool │
│ Recharts + xterm │ │ OpenSSL Fallback │
└──────────┬──────────┘ └──────────┬──────────┘
│ │
│ REST / WebSocket │
│ │
└──────────────────┬───────────────────┘
│
▼
┌─────────────────────────┐
│ KAIROS GATEWAY │
│ │
│ Session Management │
│ Cryptographic Engine │
│ Device Registry │
│ Key Distribution │
│ Policy Integration │
│ Logging │
└────────────┬────────────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ ML Threat Engine │ │ Dynamic Threat │
│ │ │ Response Engine │
│ Python │ │ │
│ FastAPI │ │ Node.js │
│ Isolation Forest │ │ Policy Engine │
│ Threat Scoring │ │ Security Actions │
└─────────────────────┘ └─────────────────────┘
The entropy subsystem provides randomness for cryptographic operations.
- Hardware entropy collection
- ESP32-based entropy source
- Serial/USB entropy interface
- C++ entropy pool
- OpenSSL entropy fallback
- Entropy analysis tools
- Statistical randomness testing
The system is designed to maintain entropy availability even when the external hardware source is unavailable.
The Gateway forms the central security boundary of the platform.
- Session management
- Device registration
- Key distribution
- Cryptographic operations
- Entropy management
- WebSocket communication
- REST APIs
- ML integration
- Policy integration
- Security logging
The project includes support for:
- RSA-OAEP key exchange
- AES-256-GCM encryption
- Secure session keys
- Nonce generation
- Hashing
- Key generation
The Gateway acts as the controlled interface between external clients and internal security services.
KAIROS separates threat detection from security response.
The Python service analyzes connection and session features and produces a threat assessment.
Current implementation uses:
Isolation Forest
The service produces:
Threat Score
Security Level
Attack Label
Supported attack labels include:
DOS
BRUTE_FORCE
PORT_SCAN
- Python
- FastAPI
- scikit-learn
- NumPy
- pandas
- joblib
- Pydantic
The Node.js DTRE consumes threat assessments and applies configurable security policies.
Depending on the policy and threat level, actions can include:
rotateSessionKey
blockIP
rateLimitClient
forceReAuthentication
alertAdmin
Additional policy functionality includes:
- Threat thresholds
- Attack-specific rules
- Confidence gates
- IP blocklists
- Rate limiting
- Automatic expiry
- Dependency-injected actions
ML Service
│
│ Threat Assessment
▼
DTRE Policy Engine
│
│ Decision
▼
Security Action
The ML service identifies suspicious behavior.
The DTRE decides what should happen.
This separation keeps detection and response logic independently configurable.
The KAIROS frontend provides a real-time SOC-style monitoring interface.
| Technology | Purpose |
|---|---|
| React | UI framework |
| TypeScript | Type safety |
| Vite | Frontend tooling |
| Tailwind CSS | UI styling |
| Zustand | State management |
| Recharts | Security telemetry visualization |
| Framer Motion | Controlled UI animation |
| xterm.js | Administrative terminal |
| WebSocket | Real-time events |
| Axios | Gateway API communication |
The dashboard provides visibility into:
- Live threat telemetry
- Threat score trends
- Security levels
- Security events
- Active sessions
- Device health
- Security actions
- Network topology
- Gateway status
- Administrative operations
The frontend communicates with the Gateway, not directly with the ML service.
FRONTEND
│
│
REST / WebSocket
│
▼
KAIROS GATEWAY
│
┌──────────┴──────────┐
│ │
▼ ▼
ML SERVICE DTRE
This prevents internal ML infrastructure from becoming a direct client-facing interface.
Real-time visualization of:
- Threat scores
- Security levels
- Attack classifications
- Threat events
- Historical trends
Provides operational visibility into active sessions while exposing only safe session metadata.
Displays connected devices and their operational state.
Shows actions generated by the Dynamic Threat Response Engine.
Visualizes relationships between security components and connected devices.
Provides a terminal-style interface for supported administrative operations.
When the Gateway is unavailable, the frontend can use a controlled mock-data layer for development and UI testing.
The mock layer does not replace the real Gateway integration.
KAIROS/
│
├── analyzer/
│ ├── entropy_analyzer.py
│ ├── nist_tests.py
│ └── test_results_schema.json
│
├── backend/
│ ├── include/
│ └── src/
│ ├── Crypto/
│ ├── entropy/
│ └── utilities/
│
├── config/
│ ├── backend_config.json
│ └── logging_config.json
│
├── docs/
│ ├── CONTEXT.md
│ └── report_text.txt
│
├── frontend/
│ ├── src/
│ │ ├── services/
│ │ ├── store/
│ │ └── ...
│ ├── package.json
│ ├── vite.config.ts
│ └── index.html
│
├── hardware/
│ └── PQHardware.ino
│
├── nodejs/
│ ├── config/
│ ├── src/
│ │ └── policy/
│ └── tests/
│
├── python/
│ ├── ml_service/
│ ├── models/
│ ├── training/
│ ├── tests/
│ └── main.py
│
├── scripts/
│ ├── build.sh
│ ├── run.bat
│ └── run.sh
│
├── tests/
│ ├── example.spec.ts
│ └── site-audit.spec.ts
│
├── CMakeLists.txt
├── CMakePresets.json
├── package.json
├── playwright.config.ts
├── tsconfig.json
└── vcpkg.json
Install:
- Git
- Node.js
- npm
- Python 3.x
- CMake
- A C++ compiler
- vcpkg
- OpenSSL
Hardware functionality additionally requires the supported entropy hardware.
Navigate to the frontend:
cd frontendInstall dependencies:
npm installStart the development server:
npm run devBuild for production:
npm run buildThe frontend currently builds successfully using the Vite production build.
Navigate to the Python service:
cd pythonInstall dependencies:
pip install -r requirements.txtTrain the model:
python training/train.pyStart the service:
python main.pyThe ML service exposes threat-analysis functionality through the Gateway architecture.
Navigate to the Node.js engine:
cd nodejsInstall dependencies:
npm installRun tests:
npm testConfigure the C++ project using the appropriate CMake preset:
cmake --preset <preset>Build:
cmake --build --preset <preset>On Windows, the repository also provides:
scripts/run.bat
The script launches the compiled backend executable using the configured backend configuration.
KAIROS contains tests across multiple layers.
cd python
pytestcd nodejs
npm testcd frontend
npm run buildFrom the project root:
npx playwright testConfiguration is separated from application code.
config/
nodejs/config/
Configuration includes:
- Backend settings
- Logging settings
- DTRE thresholds
- Security policies
- Action parameters
Local secrets and environment-specific credentials should never be committed to the repository.
KAIROS follows a security-first architecture.
The frontend communicates through the Gateway rather than directly accessing internal services.
ML determines whether activity appears anomalous.
DTRE determines how the system responds.
The dashboard must never expose:
Private Keys
Session Keys
Passwords
JWT Secrets
Raw Entropy
Credentials
Sensitive Decrypted Payloads
Only appropriate operational telemetry should be exposed.
Security components are designed to maintain safe behavior when dependent services become unavailable.
Each subsystem can be developed and tested independently while maintaining defined interfaces between components.
Client / Device
│
▼
KAIROS Gateway
│
├── Session Metadata
│
▼
ML Threat Detection
│
│ threat_score
│ security_level
│ attack_label
▼
DTRE Policy Engine
│
▼
Security Decision
│
├── Rotate Session Key
├── Rate Limit Client
├── Block IP
├── Force Re-authentication
└── Alert Administrator
│
▼
SOC Dashboard
Threat assessments use a normalized score:
0.0 ─────────────────────────────── 1.0
│ │
Low High
Threat Threat
The dashboard visualizes the resulting security state and associated events in real time.
KAIROS is designed around several principles:
Security by design
Security controls are integrated into the architecture rather than added as an afterthought.
Clear service boundaries
Each subsystem has a defined responsibility and communication boundary.
Observable security
Security events and decisions should be visible through operational telemetry.
Modular engineering
Components should remain independently testable and replaceable.
Fail-safe behavior
Service failures should not silently disable security controls.
Minimal exposure
Sensitive cryptographic material and internal service details should remain outside the presentation layer.
- Entropy collection infrastructure
- C++ entropy pool
- OpenSSL entropy fallback
- Cryptographic utilities
- Python ML threat detection service
- Isolation Forest anomaly detection
- Threat scoring
- Attack classification
- Node.js Dynamic Threat Response Engine
- Threat policies and thresholds
- IP blocklist
- Rate limiting
- Security response actions
- React + TypeScript SOC dashboard
- Gateway API abstraction
- Mock telemetry fallback
- Production frontend build
- Automated testing infrastructure
- Complete Gateway REST API integration
- Complete Gateway WebSocket event integration
- Full live telemetry pipeline
- Production authentication flow
- Expanded administrative controls
- Additional threat models
- Hardware-to-Gateway integration refinement
[✓] Entropy subsystem
│
▼
[✓] Cryptographic Gateway components
│
▼
[✓] ML Threat Detection
│
▼
[✓] Dynamic Threat Response Engine
│
▼
[✓] SOC Dashboard foundation
│
▼
[ ] Full Gateway integration
│
▼
[ ] Real-time production telemetry
│
▼
[ ] Expanded threat intelligence
│
▼
[ ] Production deployment
| Layer | Technologies |
|---|---|
| SOC Frontend | React, TypeScript, Vite, Tailwind CSS |
| State | Zustand |
| Visualization | Recharts, Three.js |
| Animation | Framer Motion |
| Terminal | xterm.js |
| Gateway / Core | C++, CMake, OpenSSL |
| Entropy | ESP32, QRNG, Serial/USB |
| ML | Python, FastAPI, scikit-learn |
| ML Model | Isolation Forest |
| DTRE | Node.js |
| Testing | pytest, Jest, Playwright |
| Configuration | JSON |
| Build | CMake, npm, vcpkg |
KAIROS is built around a simple principle:
Detect threats. Decide intelligently. Respond dynamically. Observe everything that matters.
The goal is not simply to encrypt traffic or detect anomalies independently, but to connect entropy, cryptography, intelligence, response, and observability into one coherent security architecture.
KAIROS
Quantum-Inspired Cryptographic Gateway & Security Operations Platform
Built for secure systems research, engineering, and experimentation.