PrivGuard AI🛰️

Privileged Access Management & Insider Threat Detection (Team CITADEL)

PrivGuard AI is a real-time, multi-layered privileged access auditing and security threat detection system designed for high-security environments. By fusing deterministic policy rules, robust statistical behavioral profiling, unsupervised machine learning, and post-quantum cryptographic security, PrivGuard AI isolates rogue insiders, account hijackings, and database breaches before exfiltration can occur.

---

🏛️ System Architecture

PrivGuard AI features a comprehensive data pipeline, moving from deep endpoint visibility to cryptographic evidence sealing.

graph TD
    subgraph Data Collection
        Endpoints[Endpoints / Devices]
        Wazuh[Wazuh Agents]
        Sysmon[Sysmon]
        Endpoints -->|General Telemetry| Wazuh
        Endpoints -->|Kernel-Level Calls| Sysmon
    end

    subgraph ELK Stack
        Wazuh --> Elasticsearch
        Sysmon --> Elasticsearch
        Elasticsearch --> Logstash
        Logstash --> Kibana[Kibana Visualization]
    end

    subgraph PrivGuard Core Pipeline
        Elasticsearch --> Event[Incoming Telemetry Event]
        Event --> Schema[Pydantic Event Schema]
        Schema --> Engines[Detection Engines]
        
        subgraph Engines [Detection Layer]
            Rule[Rule Detector: Policy rules_config.yaml]
            Base[Baseline Engine: Circular Hour, Robust Z-Score]
            ML[ML Anomaly: 12-dim Isolation Forest]
        end
        
        Base -->|Numerical & Categorical Deviations| Fusion[Risk Fusion Engine]
        Rule -->|Triggered Rule Severity| Fusion
        ML -->|Normalized Anomaly Score| Fusion
    end

    subgraph Mitigation & IPFS Sealing
        Fusion -->|Risk Decision| Explain[Explainability Layer]
        Explain --> Analyst[Analyst Mitigation Hub]
        Analyst -->|Account Freeze / Session Block| Pinata[Pinata IPFS]
        Pinata -->|Decentralized Hash| PQC[Post-Quantum Cryptography Vault]
    end

Loading

---

📡 Data Collection & Endpoint Monitoring

Capturing system telemetry and security events in real time.

• Wazuh Agents - Collect system telemetry, security logs, and file integrity monitoring (FIM) data from every endpoint.
• Sysmon Integration - Provides kernel-level process execution, registry, and system call visibility.
• ELK Stack Pipeline - Streams events into Elasticsearch, Logstash, and Kibana for indexing, correlation, and visualization.

---

📈 Robust Baseline Engine (baseline.py)

Building adaptive behavioral baselines for every privileged user.

• MAD-Based Statistics - Detects anomalies using Median Absolute Deviation instead of traditional averages.
• Circular Time Modeling - Correctly compares behaviors across midnight using angular statistics.
• Robust Z-Score Scaling - Converts deviations into standardized anomaly scores.

---

📜 Policy Rule Detector (rule_detector.py)

Enforcing RBAC policies and organizational security rules.

• YAML Rule Engine - Loads RBAC permissions, sensitive resources, regex signatures, and thresholds from rules_config.yaml.
• RBAC Enforcement - Instantly flags commands executed outside an employee's authorized privileges.

---

🤖 Machine Learning Anomaly Detector (ml_detector.py)

AI-powered behavioral analytics for insider threat detection.

• 12-Dimensional Feature Space - Models user behavior using activity, privilege, and peer comparison metrics.
• Isolation Forest Analysis - Converts anomaly scores into normalized risk percentages.

$$\text{normalized} = \frac{\text{raw score}-(-0.35)} {(-0.75)-(-0.35)} \times100$$

• 🔍 Explainable AI - Highlights the features contributing most to each anomaly for analyst transparency.

---

⚖️ Multi-Source Risk Fusion Engine (risk_fusion.py)

Combining statistical, policy, and AI signals into a single risk score.

• Weighted Risk Fusion - Combines Rule, Baseline, and ML scores using configurable weights.
• Exponential Time Decay - Gradually reduces historical risk during periods of inactivity.

$$\text{Risk}_{new} = \text{Risk}_{old} \times e^{-\lambda t}$$

---

🚨 Mitigation Hub & Immutable Audit Vault

Automated response with tamper-proof evidence preservation.

• One-Click Response - Freeze accounts, terminate sessions, or force logouts instantly.
• IPFS Audit Sealing - Stores immutable cryptographic hashes via Pinata IPFS.
• Post-Quantum Security - Protects critical audit records using ML-DSA-65 (Dilithium3) signatures and ML-KEM-768 (Kyber) key encapsulation.

---

🌍 Secure File Sharing & Geofencing

Protecting sensitive information beyond authentication.

• Secure File Burner - End-to-end encrypted file sharing with automatic destruction after viewing.
• Intelligent Geofencing - Detects impossible travel and blocks anomalous cross-border access attempts.

---

🖥️ Security Analyst Portal (Frontend)

Built with React 19 and Tailwind CSS v4, the dashboard offers a fast, dark-mode, information-dense workspace:

1. Overview Dashboard: Renders real-time aggregate KPI counters, alert volume over time, and policy trigger frequencies.
2. Alert Queue: Provides a list of active alerts with threat level color-coding.
3. Alert Detail Panel: Slides in to display plain-English justifications detailing exactly why the engines triggered.
4. User Baselines: Compares live deviations against established cohorts, plotting login hours on a circular 24h clock.

---

📂 Project Structure

├── backend/
│   ├── app/
│   │   ├── api/            # FastAPI Router endpoints (Events, Alerts, Users)
│   │   ├── core/           # Scoring engines (baseline.py, rule_detector.py, pqc_vault.py, etc.)
│   │   ├── models/         # SQLAlchemy Database models (Alert, Session, User, etc.)
│   │   ├── schemas/        # Pydantic v2 schemas
│   │   └── services/       # Seeding pipeline and telemetry data generators
│   ├── tests/              # Pytest automated unit tests
│   ├── main.py             # FastAPI Server bootloader and auto-migrations
│   └── requirements.txt    # Python dependencies
│
└── frontend/
    ├── src/
    │   ├── App.tsx         # Main interactive dashboard UI
    │   ├── main.tsx        # React mounting entrypoint
    │   └── style.css       # Tailwind CSS v4 directives
    ├── index.html          # Web page wrapper
    ├── vite.config.ts      # Vite bundler configuration
    └── package.json        # Node.js dependencies

---

🚀 Setup & Execution

1. Run using Docker (Recommended)

Make sure you have Docker Desktop installed and running.

docker compose up --build -d

• Frontend Analyst Dashboard: http://localhost:3001
• Backend API Docs (Swagger): http://localhost:8001/docs

2. Manual Backend Setup

Make sure you have Python 3.10+ installed.

1. Activate Virtual Environment & Install dependencies: To avoid using a global Python environment (which might contain incompatible library versions like Pydantic v1), run commands within the project's local virtual environment:

   • Windows (PowerShell):

     .venv\Scripts\Activate.ps1
     cd backend
     pip install -r requirements.txt

   • macOS / Linux:

     source .venv/bin/activate
     cd backend
     pip install -r requirements.txt

   (Alternatively, you can run directly via the environment's python interpreter from the backend/ folder: ..\.venv\Scripts\python main.py)

2. Start the FastAPI Server: From inside the backend directory with the virtual environment activated:

   python main.py

   [!NOTE] Database Path Resolution: The application dynamically resolves the SQLite connection string to point to the pre-seeded privguard.db database at the workspace root directory. This ensures the dashboard always displays the ~4,670 historical events and baseline profiling data.

   The server will start at http://localhost:8000. The OpenAPI docs will be available at http://localhost:8000/docs.

3. Manual Frontend Setup

Make sure you have Node.js 18+ installed.

cd frontend
npm install --legacy-peer-deps
npm run dev

4. Automated Test Suite

To verify statistical calculations, risk fusion algorithms, and cryptographic vaults, run:

$env:PYTHONPATH="."; python -m pytest backend/tests/

4. Running the Live Attack Simulator (Optional)

To generate new real-time administrative telemetry, anomalies, and security threats that stream live to the analyst dashboard:

1. From the project workspace root directory, run:

   • Windows (PowerShell):

     $env:PYTHONIOENCODING="utf-8"
     .venv\Scripts\python.exe attack_simulator.py

   • macOS / Linux:

     PYTHONIOENCODING=utf-8 .venv/bin/python attack_simulator.py

   The script will continuously post simulated access logs (such as database queries, bulk downloads, and location anomalies) to the backend API. You will see normal events and real-time alerts outputted directly to your terminal.

---

Enterprise Security Features ⚡

Behavioral Analytics Adaptive user baselines Robust statistical profiling Explainable anomaly detection	Access Governance RBAC policy enforcement Privileged session monitoring Least-privilege validation	Threat Detection Multi-layer risk correlation Real-time threat scoring Isolation Forest ML engine
Incident Response One-click mitigation Session termination Account isolation	Evidence Protection Immutable IPFS audit trail Post-Quantum Cryptography Digital evidence sealing	Advanced Protection Secure File Burner Network Geofencing Impossible Travel Detection

---

🛡️ Developed by Team CITADEL

• Observability: Wazuh, Sysmon, ELK Stack, and Median Absolute Deviation baselines.
• Control: Role-Based Access Control, Geofencing, and automated session blocking.
• Cryptography: Pinata IPFS immutable hashes and Post-Quantum secure audit vaults (Dilithium/Kyber).