🔍 An AI-powered detection system that identifies low-volume, distributed, star-topology coordinated influence operations that evade traditional spike-based detection — built with a multi-engine fusion architecture combining Semantic Analysis, Behavioral Anomaly Detection, and Graph Topology Intelligence.
🏠 Landing Page — System Selection
🏢 Enterprise Console — Full Tactical Dashboard
🕸️ Enterprise — Live Swarm Topology Graph
📊 Enterprise — Attack Wave Heatmap & Influence Velocity
🎯 Enterprise — Suspect Fingerprint Radar & Regional Clustering
📋 Enterprise — Priority Action Queue (Explainable AI)
🧍 User Dashboard — Moderator Alert Interface
Traditional bot detection looks for volume spikes — sudden floods of identical messages. But modern coordinated influence operations have evolved:
❌ Old approach: Detect 1,000 identical tweets in 10 minutes
✅ StarShield: Detect 1 hub + 10 bots posting paraphrased messages within 30 minutes
StarShield targets the micro-swarm pattern — a single "hub" account orchestrating ~10 bot accounts that amplify messages using paraphrased content within tight time windows. This star-topology pattern is invisible to volume-based detectors but detectable through combined semantic, behavioral, and graph analysis.
┌─────────────────────────────────────────────────────────────────────────┐
│ 🖥️ FRONTEND (Next.js 16 · React 19 · Tailwind CSS 4 · TypeScript) │
│ ┌──────────────┐ ┌──────────────────┐ ┌────────────────────────┐ │
│ │ 🏠 Landing │ │ 🧍 User Dash │ │ 🏢 Enterprise Console │ │
│ │ page.tsx │ │ /user │ │ /enterprise │ │
│ └──────────────┘ └──────────────────┘ └────────────────────────┘ │
│ │ │ │ │
│ └─────────────────┴────────────────────────┘ │
│ ↓ │
│ 📡 /api/run-detection (Next.js API Route) │
├─────────────────────────────────────────────────────────────────────────┤
│ ⚙️ BACKEND (FastAPI · Python) │
│ POST /run-detection → detection_service.py (Orchestrator) │
├─────────────────────────────────────────────────────────────────────────┤
│ 🧪 DETECTION ENGINE (Multi-Engine Fusion Pipeline) │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 📝 Semantic │ │ 📈 Behavioral │ │ 🕸️ Graph │ │
│ │ Engine │ │ Engine │ │ Engine │ │
│ │ │ │ │ │ │ │
│ │ Sentence-BERT │ │ Isolation Forest │ │ NetworkX + │ │
│ │ + FAISS Index │ │ Anomaly Detect. │ │ Louvain Comm. │ │
│ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │
│ └──────────────────────┼──────────────────────┘ │
│ ┌───────▼────────┐ │
│ │ 🔀 Fusion │ ┌───────────────────┐ │
│ │ Engine │────▶│ 🛡️ Event Safety │ │
│ │ (60% G + 40% B)│ │ (FP Reducer) │ │
│ └────────────────┘ └───────────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│ 🗃️ DATASET GENERATOR (Faker · NumPy · Pandas) │
│ Synthetic users + posts with injected micro-swarms & FP clusters │
└─────────────────────────────────────────────────────────────────────────┘
StarShield/
│
├── 📄 README.md # You are here
│
├── 🖥️ frontend/ # Next.js 16 + React 19 Application
│ ├── app/
│ │ ├── layout.tsx # Root layout (Geist fonts, metadata)
│ │ ├── page.tsx # 🏠 Landing page — mode selection
│ │ ├── globals.css # Global styles + Tailwind imports
│ │ │
│ │ ├── enterprise/
│ │ │ └── page.tsx # 🏢 Enterprise SOC Console (5 graphs + table)
│ │ │
│ │ ├── user/
│ │ │ └── page.tsx # 🧍 User moderator dashboard (table only)
│ │ │
│ │ ├── api/
│ │ │ └── run-detection/
│ │ │ └── route.ts # 📡 API proxy → FastAPI backend
│ │ │
│ │ └── components/
│ │ ├── SwarmGraph.tsx # 🕸️ D3.js force-directed network graph
│ │ ├── BehavioralRadar.tsx # 🎯 Recharts radar/spider chart
│ │ ├── PropagationTimeline.tsx # 📈 Recharts area chart (influence velocity)
│ │ ├── RiskHeatmap.tsx # 🔥 Recharts bar chart (attack waves)
│ │ ├── GeoCoordination.tsx # 🌍 Recharts donut chart (regional clusters)
│ │ ├── EnterpriseRiskTable.tsx # 📋 Expandable table with Explainable AI
│ │ ├── UserRiskTable.tsx # 📋 Simplified moderator alert table
│ │ ├── RiskTable.tsx # 📋 General-purpose risk table
│ │ ├── Controls.tsx # 🔘 "Run Detection Engine" button
│ │ └── ClientOnly.tsx # 🔒 SSR hydration guard wrapper
│ │
│ ├── lib/
│ │ └── api.ts # 🔌 API client (runDetection function)
│ │
│ ├── public/ # Static assets
│ ├── package.json # Dependencies & scripts
│ ├── next.config.ts # Next.js configuration
│ ├── tailwind.config.ts # Tailwind CSS configuration
│ ├── tsconfig.json # TypeScript configuration
│ ├── postcss.config.mjs # PostCSS configuration
│ └── eslint.config.mjs # ESLint configuration
│
├── ⚙️ backend/ # FastAPI Backend Server
│ ├── main.py # 🚀 FastAPI app entry (health + detection endpoints)
│ ├── schemas.py # 📐 Pydantic models (SuspiciousUser, DetectionResponse)
│ ├── requirements.txt # 📦 Python dependencies
│ ├── vercel.json # ▲ Vercel deployment config
│ ├── __init__.py
│ └── services/
│ ├── detection_service.py # 🎯 Orchestrator — runs all engines & builds response
│ └── __init__.py
│
├── 🧪 detection_engine/ # Core AI Detection Pipeline
│ ├── semantic_engine.py # 📝 Sentence-BERT + FAISS similarity detection
│ ├── behavioral_engine.py # 📈 Isolation Forest anomaly detection
│ ├── graph_engine.py # 🕸️ NetworkX + Louvain star-topology detection
│ ├── fusion.py # 🔀 Multi-engine score fusion (weighted)
│ ├── event_safety.py # 🛡️ False positive reduction (event burst safety)
│ ├── run_pipeline.py # ▶️ Standalone CLI pipeline runner
│ └── __init__.py
│
└── 🗃️ dataset_generator/ # Synthetic Data Generation
├── generate_dataset.py # 🏭 Data generator (organic + swarm injection)
├── users.csv # 👤 Generated user profiles (600 users)
└── posts.csv # 💬 Generated posts with injected swarms
StarShield provides two intelligence layers — a full-featured Enterprise SOC Console and a streamlined User Moderator Dashboard — serving different operational needs from the same detection backend.
Route:
/enterprise· 5 Interactive Graphs + 1 Expandable Table · 1600px layout
The enterprise console is a military/SOC-grade tactical interface designed for security operations centers. It features a dark cybersecurity aesthetic with numbered tactical labels, glowing accents, and staggered fade-in animations.
|
Type: Force-Directed Network Graph
|
Type: Radar / Spider Chart
|
|
Type: Vertical Bar Chart
|
Type: Gradient Area Chart
|
|
Type: Donut / Pie Chart
|
Type: Interactive Expandable Table
|
Route:
/user· 1 Simplified Alert Table · 896px centered layout
The user dashboard is intentionally minimal — designed for content moderators who need quick, actionable threat alerts without information overload.
| Component | Description |
|---|---|
| 🔔 System Status Banner | Shows last scan time, connection status, and a "Run Detection Engine" button |
| 📋 Latest Threat Alerts Table | 3-column table: Alert Priority (#1, #2...), Node ID, Status Badge (HIGH/MEDIUM/LOW). No percentages, no expandable rows — just clear, actionable alerts. |
| 🧹 Clear Results | One-click reset to clear the alert queue |
StarShield uses a multi-engine fusion architecture where three independent detection engines analyze different dimensions of user behavior, and their outputs are combined for robust threat scoring.
CSV Data (users + posts)
│
├──▶ 📝 Semantic Engine
│ ├─ Encode posts → Sentence-BERT embeddings (all-MiniLM-L6-v2)
│ ├─ Build FAISS inner-product index
│ ├─ Find top-5 nearest neighbors per post
│ └─ Filter: similarity ≥ 0.85 AND posted within 30 minutes
│ Output: (user_A, user_B, similarity_score) edge pairs
│
├──▶ 📈 Behavioral Engine
│ ├─ Extract per-user features:
│ │ • Mean posting interval
│ │ • Variance of posting intervals
│ │ • Mean active hour
│ └─ Fit Isolation Forest (contamination = 0.08)
│ Output: anomaly_score per user
│
└──▶ 🕸️ Graph Engine
├─ Build NetworkX graph from semantic edges
├─ Compute: degree centrality, betweenness centrality, clustering coefficient
├─ Run Louvain community detection
└─ Star-topology scoring:
score = 0.5×degree + 0.3×(1-clustering) + 0.2×(1/(avg_neighbor_degree+1))
Output: star_score per user
↓
🔀 Fusion Engine
risk_score = 0.6 × graph_score + 0.4 × behavioral_score
↓
🛡️ Event Burst Safety Checker
IF (distinct_users ≥ 15 AND time_spread ≥ 90min AND max_degree ≤ 0.15):
→ Real organic event detected → scores × 0.4 (60% reduction)
↓
📊 Final ranked list of suspicious users with explainable reasons
| Engine | Technique | Purpose |
|---|---|---|
| Semantic | Sentence-BERT (all-MiniLM-L6-v2) |
Encode post content into dense vector embeddings |
| Semantic | FAISS (Inner Product Index) | Fast approximate nearest-neighbor similarity search |
| Semantic | Temporal Co-occurrence Filter | Ensure similar posts are within 30-min coordination window |
| Behavioral | Isolation Forest | Unsupervised anomaly detection on posting behavior patterns |
| Graph | NetworkX + Louvain | Community detection and graph topology metrics |
| Graph | Custom Star-Topology Scorer | Detect hub-and-spoke bot network patterns |
| Fusion | Weighted Linear Combination | Merge graph (60%) + behavioral (40%) scores |
| Safety | Event Burst Checker | Reduce false positives from organic real-world events |
The dataset generator creates realistic test data with ground-truth labels for validation:
| Data | Count | Description |
|---|---|---|
| Total Users | 600 | Mix of organic and bot accounts |
| Organic Users | ~556 | Pareto-distributed followers, old accounts, 3-8 random posts each |
| Micro-Swarms | 4 swarms × 11 | 1 hub + 10 bots per swarm (44 bot accounts total) |
| Swarm Behavior | — | Hub posts base message → bots post paraphrased versions within 2-10 min |
| False Positive Clusters | Injected | Organic users discussing same topic with wider timing (0-180 min) |
| Paraphrasing | Synonym substitution | 60% probability per keyword to simulate real paraphrasing |
- 🐍 Python 3.11+
- 📦 Node.js 18+ and npm
- 💻 Git
git clone https://github.com/your-username/StarShield.git
cd StarShield# Navigate to backend
cd backend
# Create virtual environment
python -m venv venv
# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Start the FastAPI server
uvicorn main:app --reload --port 8000cd dataset_generator
python generate_dataset.pyThis creates users.csv and posts.csv with injected micro-swarms.
# Navigate to frontend
cd frontend
# Install dependencies
npm install
# Start the development server
npm run devNavigate to http://localhost:3000 in your browser.
Choose between 🧍 User Dashboard or 🏢 Enterprise Console and hit "Run Detection Engine".
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| 🖥️ Frontend | Next.js | 16 | React framework with App Router & API routes |
| React | 19 | UI component library | |
| Tailwind CSS | 4 | Utility-first styling | |
| D3.js | 7 | Force-directed swarm topology graph | |
| Recharts | 3 | Radar, area, bar, and donut charts | |
| ⚙️ Backend | FastAPI | — | High-performance Python API framework |
| Uvicorn | — | ASGI server | |
| 🧪 AI/ML | Sentence-Transformers | — | SBERT embeddings (all-MiniLM-L6-v2) |
| FAISS (CPU) | — | Approximate nearest-neighbor search | |
| scikit-learn | — | Isolation Forest anomaly detection | |
| NetworkX | — | Graph construction & centrality metrics | |
| python-louvain | — | Community detection algorithm | |
| NumPy & Pandas | — | Data manipulation & feature extraction | |
| 🗃️ Data | Faker | — | Synthetic dataset generation |
| Element | Design Choice |
|---|---|
| Theme | Dark-mode cybersecurity / SOC-grade aesthetic |
| Backgrounds | Near-black (#070b14) with frosted-glass panels |
| Typography | Geist Sans (body) · Geist Mono (labels, data) |
| Accents | Blue-Indigo gradient (primary) · Red (danger) · Emerald (safe) · Amber (warning) |
| Animation | Staggered fade-ins, pulsing status dots, hover glows |
| Layout | Enterprise: 12-col grid, 1600px · User: single-col, 896px |
Health check endpoint.
Response:
{ "status": "ok" }Triggers the full detection pipeline.
Response:
{
"top_suspicious_users": [
{
"user_id": "user_123",
"risk_score": 0.472,
"reasons": {
"semantic": "High",
"behavioral": "Medium",
"graph_centrality": "Very High",
"event_safety": "Passed"
}
}
],
"graph_data": {
"nodes": [{ "id": "user_123", "group": 1, "influence": 85.3 }],
"links": [{ "source": "user_123", "target": "user_456", "weight": 0.92 }]
},
"stats": {
"total_users_analyzed": 600,
"threats_detected": 12,
"swarm_clusters": 4
}
}- Fork the repository
- Create your feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is open-source and available under the MIT License.
Built with 🧠 AI + 🔒 Security + 💻 Engineering
StarShield AI — Detecting what traditional systems can't see.