🛡️ ShadowGuard AI

Real-Time Shadow AI/IT Detection Platform
AI-powered security monitoring for enterprise environments

---

📋 Overview

ShadowGuard AI is an enterprise-grade security platform that detects and monitors unauthorized AI tools and Shadow IT usage in real-time. It uses a multi-layer detection engine combining semantic analysis, behavioral analysis, and rule-based detection to identify potential data exfiltration risks.

🎯 Key Highlights

• 🧠 AI-Powered Detection — Semantic similarity analysis using embeddings
• 📊 Real-Time Dashboard — Live alerts with risk scores and explanations
• 🔌 Browser Extension — Capture real user browsing activity
• ⚡ Instant Alerts — Slack notifications for high-risk events
• 🐳 Docker-Ready — Full containerized deployment

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              ShadowGuard AI                                  │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         │                            │                            │
         ▼                            ▼                            ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│ Browser Extension│         │   Generator     │         │   Dashboard     │
│  (Real Traffic)  │         │ (Synthetic Logs)│         │  (React + API)  │
└────────┬────────┘         └────────┬────────┘         └────────▲────────┘
         │                            │                            │
         └────────────────┬───────────┘                            │
                          ▼                                        │
                 ┌─────────────────┐                               │
                 │    Collector    │                               │
                 │    (FastAPI)    │                               │
                 └────────┬────────┘                               │
                          │ Redis Pub/Sub                          │
                          ▼                                        │
                 ┌─────────────────┐                               │
                 │     Worker      │                               │
                 │ (Detection Engine)                              │
                 │  ├── Semantic   │                               │
                 │  ├── Behavioral │                               │
                 │  └── Fusion     │───────────────────────────────┘
                 └────────┬────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │  Slack Notifier │
                 │ (Real-time Alerts)│
                 └─────────────────┘

---

📁 Project Structure

shadowguard-ai/
├── 📁 collector/              # Log ingestion service (FastAPI)
│   ├── app/                   # API routes and handlers
│   ├── core/                  # Configuration and Redis client
│   ├── models/                # Data models
│   ├── schemas/               # Pydantic schemas
│   ├── services/              # Business logic
│   ├── main.py                # Application entry point
│   ├── Dockerfile
│   └── requirements.txt
│
├── 📁 worker/                 # Multi-layer detection engine
│   ├── worker.py              # Main event consumer
│   ├── fusion.py              # Risk score fusion algorithm
│   ├── semantic.py            # Semantic similarity analysis
│   ├── behavior.py            # Behavioral anomaly detection
│   ├── rules.py               # Rule-based detection
│   ├── slack_notifier.py      # Slack alert integration
│   ├── Dockerfile
│   └── requirements.txt
│
├── 📁 dashboard/              # Web UI and backend API
│   ├── frontend/              # React 19 + Vite + TailwindCSS v4
│   │   ├── src/
│   │   │   ├── components/    # UI components
│   │   │   ├── pages/         # Page components
│   │   │   └── App.tsx
│   │   ├── package.json
│   │   └── vite.config.ts
│   ├── backend/               # FastAPI backend
│   │   ├── main.py            # API endpoints
│   │   └── requirements.txt
│   ├── nginx.conf             # Reverse proxy configuration
│   ├── start.sh               # Orchestration script
│   └── Dockerfile             # Multi-stage build
│
├── 📁 generator/              # Synthetic log generator
│   ├── generate_logs.py       # Log generation script
│   ├── Dockerfile
│   └── requirements.txt
│
├── 📁 extension/              # Chrome browser extension
│   ├── manifest.json          # MV3 extension manifest
│   ├── background.js          # Service worker
│   ├── content.js             # Content script
│   ├── popup/                 # Extension popup UI
│   ├── options/               # Extension settings page
│   └── icons/
│
├── 📁 config/                 # Shared configuration
│   ├── anchors.json           # Category definitions for semantic analysis
│   ├── blacklist.json         # Blocked domains
│   └── whitelist.json         # Allowed domains
│
├── 📁 docs/                   # Documentation
│   ├── API.md
│   ├── ARCHITECTURE.md
│   └── SETUP.md
│
├── docker-compose.yml         # Service orchestration
├── .env.example               # Environment variables template
├── .gitignore
├── TESTING.md
└── README.md

---

🛠️ Tech Stack

Category	Technology
Frontend
Backend
Database
AI/ML
Infrastructure
Extension

---

✨ Features

🔍 Multi-Layer Detection Engine

Layer	Description
Semantic Analysis	Uses AI embeddings to detect category matches (Generative AI, File Storage, Anonymous Services, etc.)
Behavioral Analysis	Tracks user patterns and flags anomalies (first-time access, unusual upload volumes)
Rule-Based Detection	Configurable whitelist/blacklist for immediate allow/block decisions
Fusion Engine	Combines all signals with intent-aware scoring (POST/PUT uploads weighted differently than GET)

📊 Real-Time Dashboard

• Live Alert Feed — Real-time security events with risk scores
• Alert Simulation — Test scenarios for demo purposes
• Risk Level Indicators — CRITICAL, HIGH, MEDIUM, LOW, SAFE
• AI-Generated Explanations — Powered by Gemini API
• Responsive Design — Modern glassmorphism UI with animations

🔌 Browser Extension

• Passive Monitoring — Captures browsing activity without user intervention
• Configurable Endpoint — Point to any collector instance
• Privacy-Focused — Only sends metadata, not page content
• Chrome MV3 — Built on the latest manifest version

🔔 Notifications

• Slack Integration — Real-time alerts to security team channels
• Threshold-Based — Only notify on HIGH/CRITICAL events

---

🚀 Quick Start

Prerequisites

• Docker + Docker Compose
• Node.js (v18+) — for frontend development
• Python 3.11 — for local development
• API keys (optional but recommended):
  • OPENROUTER_API_KEY — For semantic embeddings
  • GEMINI_API_KEY — For AI-generated explanations

1️⃣ Clone & Configure

git clone https://github.com/your-org/shadowguard-ai.git
cd shadowguard-ai

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
nano .env

2️⃣ Start All Services (Docker)

docker-compose up --build

This starts:

Service	Port	Description
Redis	6379	Message broker & data store
Collector	Internal	Log ingestion (accessible via dashboard)
Worker	8000	Detection engine
Dashboard	3000	UI + API gateway

3️⃣ Access the Dashboard

Open http://localhost:3000 in your browser.

4️⃣ Generate Test Alerts

Option A: Use the Browser Extension (Recommended)

1. Open chrome://extensions/
2. Enable "Developer mode"
3. Click "Load unpacked" → Select the extension/ folder
4. Configure the collector URL: http://localhost:3000/logs
5. Browse the web normally — events are captured automatically

Option B: Synthetic Logs

python generator/generate_logs.py \
  --url http://localhost:3000/logs \
  --type mixed \
  --num-logs 50 \
  --once

---

⚙️ Environment Configuration

Create a .env file at the project root:

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379

# Service Ports
COLLECTOR_PORT=8000
DASHBOARD_PORT=3000

# AI/ML APIs (optional but recommended)
OPENROUTER_API_KEY=your_openrouter_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here

# Self-hosted Embedding Model (alternative to OpenRouter)
EMBEDDING_API_URL=http://YOUR_VM_IP:8000/embed

API Keys

Key	Purpose	Required
OPENROUTER_API_KEY	Semantic embeddings for domain categorization	Optional (falls back to keyword matching)
GEMINI_API_KEY	AI-generated alert explanations	Optional (shows "AI explanation unavailable" if missing)
EMBEDDING_API_URL	Self-hosted embedding model endpoint	Optional (alternative to OpenRouter)

---

🧪 Development

Hybrid Mode (Recommended for Frontend Dev)

Terminal 1 — Backend Services (Docker)

docker-compose up redis collector worker

Terminal 2 — Frontend (Vite HMR)

cd dashboard/frontend
npm install
npm run dev

Access at: http://localhost:3000 (with hot reload)

Full Local Development

Collector:

cd collector
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Worker:

cd worker
pip install -r requirements.txt
python worker.py

Dashboard Backend:

cd dashboard/backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8001

Dashboard Frontend:

cd dashboard/frontend
npm install
npm run dev

---

🔄 API Endpoints

Dashboard API (http://localhost:3000/api/)

Method	Endpoint	Description
GET	/api/health	Health check with Redis status
GET	/api/alerts	Fetch security alerts
GET	/api/users	Get user statistics

Collector API (Internal, proxied through dashboard)

Method	Endpoint	Description
POST	/logs	Ingest log events
GET	/logs?params	Ingest via query params (for proxies)
GET	/health	Collector health check

---

🔧 Operations

Reset All Data

docker-compose down -v
docker-compose up --build

The -v flag removes volumes, wiping all stored alerts.

View Service Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f worker

Health Checks

# Dashboard API
curl http://localhost:3000/api/health

# Collector (via proxy)
curl http://localhost:3000/health