krox: AI-Powered Behavioral Anomaly Detection & Threat Classifier

krox is a domain-agnostic, near real-time behavioral anomaly detection and threat classification engine designed for enterprise networks, cloud access management, industrial edge gateways, and IoT infrastructure.

Rather than relying on static signatures or fixed rule hashes—which fail against novel attacks, compromised credentials, and zero-day threats—krox models baseline behavioral patterns for users, service accounts, and edge devices. It flags anomalies, categorizes attack tactics into a 7-tier taxonomy, and calculates explainable risk scores (0–100) with SHAP feature attributions and natural language Security Operations Center (SOC) rationales.

---

Technical Capabilities

1. Sequential & Behavioral Profiling: Models per-entity habitual access patterns (working hours, primary IP subnets, expected resource sets, device fingerprints, session lengths, command sequences) over time.
2. Dual-Model Stack: Ensembles a baseline statistical profiler (Mahalanobis distance), an IsolationForest unsupervised model, and deterministic security guardrails for high precision.
3. Multi-Class Threat Categorization: Trains an XGBoost classifier to categorize anomalies into specific attack vectors:
   • Brute Force
   • Impossible Travel
   • Credential Stuffing
   • Lateral Movement
   • Device Spoofing
   • Low-and-Slow Exfiltration
   • Insider Drift
4. Hierarchical Cold-Start Engine: Uses entity-type population priors (user, service_account, edge_device) to score brand-new entities before individual baseline accumulation.
5. Adaptive Concept Drift Engine: Integrates an Exponentially Weighted Moving Average (EWMA) updater ($\alpha = 0.05$) to continuously adapt entity baselines when legitimate work patterns evolve, preventing false positive saturation.
6. Explainability Layer: Computes top-5 SHAP feature contributions and generates readable SOC rationales per alert.
7. Analyst Dashboard & REST API: Features a modern, dark-themed web interface for alert triage, attack analytics, and interactive attack stream simulation, alongside production FastAPI endpoints.

---

Benchmark Metrics Summary

Evaluated on 5,000 imbalanced test access events:

• Overall Accuracy: 99.70%
• ROC-AUC Score: 0.9395
• Attack Recall (Detection Rate): 97.68%
• False Positive Rate @ 1% Alert Budget: 0.0046 (0.46% FPR)
• Average Inference Latency: 4.935 ms per log event
• P99 Inference Latency: 7.721 ms per log event

---

Installation & Setup

Prerequisites

• Linux OS
• Python 3.10+
• Pixi package manager (or standard pip)

Installation via Pixi

Clone the repository and install dependencies:

git clone https://github.com/sophic00/krox.git
cd krox
pixi install

Installation via Standard Pip

pip install numpy pandas scikit-learn xgboost fastapi uvicorn pydantic faker geopy shap

---

Quickstart Guide

1. Launch the Server & SOC Dashboard

Start the FastAPI backend with the embedded SOC Analyst Dashboard:

pixi run python -m uvicorn krox.api.app:app --host 127.0.0.1 --port 8000

Access Points:

• SOC Analyst Web Dashboard: http://127.0.0.1:8000
• Interactive REST API Documentation: http://127.0.0.1:8000/docs

2. Stream Simulated Attacks

Click Run Attack Simulation on the Web Dashboard, or execute a POST request:

curl -X POST "http://127.0.0.1:8000/api/v1/simulate?num_events=100&anomaly_ratio=0.15"

3. Run Benchmark Suite

Execute the benchmark script to generate synthetic access logs, fit models, and output validation metrics:

pixi run python -m krox.evaluation.run_eval

Results are saved to reports/benchmark_results.json.

---

System Architecture

flowchart TD
    Logs["Streaming Access Logs"] --> Pipeline["Feature Pipeline"]
    Pipeline --> DualStack["Dual Model Stack"]
    DualStack --> Profiler["Baseline Mahalanobis Profiler"]
    DualStack --> MLModels["IsolationForest & XGBoost Classifier"]
    Profiler --> Explainer["SHAP & Explainability Engine"]
    MLModels --> Explainer
    Explainer --> Interface["REST API & Analyst Dashboard"]

Loading

---

Documentation

Detailed documentation is available in the docs/ directory:

• System Architecture Specification: Deep-dive into feature extraction, dual modeling, cold-start handling, and EWMA concept drift adaptation.
• REST API Reference: Endpoint specifications, request payloads, and response contracts.
• Synthetic Data & Attack Taxonomy: Simulation parameters, groundtruth schema, and injected attack taxonomy.
• Technical Report & Evaluation Results: Full benchmark metrics, classification matrices, and deployment guidelines.

---

License

MIT License. See LICENSE for details.