Skip to content

README.md

Latest commit

 

History

History
413 lines (289 loc) · 8.43 KB

README.md

File metadata and controls

413 lines (289 loc) · 8.43 KB

🛡️ Spectus — AI Cyber-Forensics Platform for Real-Time Scam Detection

Enterprise-grade cyber-forensics platform engineered to detect, analyze, and neutralize advanced digital fraud operations in real time.

Spectus moves beyond traditional rule-based detection systems and simple AI wrappers by leveraging a multi-engine ensemble intelligence architecture that combines machine learning, semantic retrieval, behavioral analytics, and large language models to identify sophisticated scams before financial damage occurs.

🚀 Overview

Spectus is a fully decoupled cyber-forensics platform consisting of:

  • High-performance FastAPI backend
  • Interactive forensic investigation dashboard
  • AI-powered threat analysis pipeline
  • Real-time scam intelligence and correlation engine
  • Incident response and mitigation toolkit

The platform analyzes SMS messages, emails, call transcripts, URLs, UPI handles, and community threat reports to provide comprehensive scam intelligence.

🏗️ System Architecture

Core Intelligence Pipeline (4-Signal Ensemble)

Every incoming threat payload is evaluated through four independent intelligence engines functioning as a digital jury.

flowchart LR

A[Threat Input] --> B[ML Classifier]
A --> C[Semantic Search]
A --> D[LLM Analysis]
A --> E[Behavioral Fingerprinting]

B --> F[Final Verdict Engine]
C --> F
D --> F
E --> F

F --> G[Threat Intelligence Report]
Loading

Intelligence Layers

1️⃣ Machine Learning Classifier

A supervised model trained on linguistic risk boundaries and scam communication patterns.

Technology:

  • Scikit-learn
  • TF-IDF Vectorization
  • Logistic Regression

2️⃣ Semantic Vector Search

Uses semantic embeddings to compare incoming content against official advisories and known scam reports.

Knowledge Sources:

  • Ministry of Home Affairs (MHA)
  • Reserve Bank of India (RBI)
  • Securities and Exchange Board of India (SEBI)
  • Law Enforcement Alerts

Technology:

  • ChromaDB
  • Sentence Transformers
  • Vector Similarity Search

3️⃣ Advanced Contextual LLM Analysis

Powered by Llama 3.1 through Groq's LPU infrastructure for deep psychological and contextual analysis.

Detects:

  • Artificial urgency
  • Authority impersonation
  • Social engineering tactics
  • Emotional manipulation
  • Cognitive bias exploitation

4️⃣ Behavioral Fingerprinting

Deterministic pattern matching engine for identifying operational indicators frequently used by threat actors.

Examples:

  • Brand impersonation formatting
  • Leet-speak obfuscation
  • Suspicious URL structures
  • Credential harvesting patterns

⚡ Key Features

🎯 AI Debate Panel

A transparent forensic console displaying:

  • Individual engine verdicts
  • Confidence scores
  • Weighted risk calculations
  • Cross-model disagreements
  • Final consensus verdict

🔗 Cross-Channel Nexus Correlation

Correlates multiple attack vectors into a unified threat graph.

Examples:

  • Phishing SMS → Malicious URL → Fraudulent UPI Handle
  • Email Campaign → Domain Infrastructure → Scam Network

Technology:

  • NetworkX
  • Graph-Based Relationship Mapping

🧬 Mutation Diff Engine

Tracks structural evolution of scams over time.

Capabilities:

  • Character-level comparisons
  • Word-level mutation analysis
  • Historical variant matching
  • Threat lineage tracking

Technology:

  • Python difflib

🧠 Scam Psychological Profiler & Simulator

Analyzes scammer intent and predicts probable next-stage actions.

Identifies:

  • Authority Bias
  • Scarcity Principle
  • Fear Appeals
  • Urgency Manipulation
  • Reciprocity Exploitation

🌐 Zero-Day URL Intelligence Hub

Detects newly registered and previously unseen phishing domains.

Integrations:

  • VirusTotal API
  • WHOIS XML API

Analysis Factors:

  • Domain age
  • Registrar patterns
  • Infrastructure anomalies
  • Reputation indicators

🚨 Golden Hour Emergency Toolkit

Rapid-response incident mitigation center.

Includes:

  • Automated incident reports
  • Evidence serialization
  • Cybercrime complaint preparation
  • National Cyber Helpline integration (1930)
  • cybercrime.gov.in reporting assistance

📂 Project Structure

Spectus/
├── backend/
│   ├── main.py
│   ├── config.py
│   ├── requirements.txt
│   ├── .env
│   ├── scamshield.db
│   │
│   ├── routers/
│   │   ├── analyze.py
│   │   ├── url.py
│   │   ├── upi.py
│   │   ├── community.py
│   │   ├── audio.py
│   │   ├── mutation.py
│   │   └── nexus.py
│   │
│   └── services/
│       ├── database.py
│       ├── behavioral.py
│       ├── classifier.py
│       ├── chromadb_service.py
│       ├── groq_service.py
│       ├── url_service.py
│       └── advanced_analysis.py
│
└── frontend/
    └── index.html

🛠️ Technology Stack

Backend

Component Technology
Framework FastAPI
Language Python 3.10+
ORM SQLAlchemy
Database SQLite3
Validation Pydantic

Machine Learning & AI

Component Technology
ML Models Scikit-learn (TF-IDF + Logistic Regression)
Embeddings Sentence Transformers
Vector DB ChromaDB
LLM Engine Llama 3.1
Inference Provider Groq
Graph Analysis NetworkX

Threat Intelligence

Service Purpose
VirusTotal API URL Reputation Analysis
WHOIS XML API Domain Intelligence
MHA Advisories Scam Knowledge Base
RBI Alerts Financial Fraud Intelligence
SEBI Notices Investment Scam Detection

Frontend

Component Technology
UI Layer HTML5
Styling Custom CSS
Visualization Pure SVG (no external chart library)
Logic Vanilla JavaScript
PDF Export jsPDF

🔍 Analysis Workflow

Input
  ↓
Preprocessing
  ↓
4-Signal Ensemble Analysis
  ↓
Threat Correlation Engine
  ↓
Psychological Profiling
  ↓
Mutation Detection
  ↓
Threat Scoring
  ↓
Forensics Report Generation
  ↓
Emergency Response Recommendations

🚀 Deployment

Backend Deployment (Render)

The backend is deployed as a web service on Render.

Live URL: https://spectus-t3r5.onrender.com

Start Command

uvicorn main:app --host 0.0.0.0 --port 10000

Infrastructure Features

  • Lazy model initialization (SentenceTransformer loads on first request, not at boot)
  • CPU-optimized PyTorch for low memory footprint
  • Environment variable masking
  • Persistent ChromaDB scam pattern storage
  • Automated dependency installation

Frontend Deployment (Vercel)

The frontend is deployed for global edge delivery using Vercel.

Live URL: https://spectus-cyberforensics.vercel.app

Features

  • Static asset optimization
  • CDN-backed distribution
  • Low-latency delivery
  • Decoupled architecture
  • Backend API integration

🔒 Security Architecture

Current Model

Frontend (Vercel)
   ↓
Direct API Communication
   ↓
FastAPI Backend (Render)

Enterprise Upgrade Path

Frontend
   ↓
Reverse Proxy
   ↓
API Gateway
   ↓
FastAPI Services
   ↓
External Intelligence APIs

Benefits:

  • API key isolation
  • Request inspection
  • Rate limiting
  • Enhanced observability
  • Enterprise-grade security posture

🎯 Use Cases

  • Banking Fraud Detection
  • UPI Scam Investigation
  • Phishing Email Analysis
  • SMS Fraud Intelligence
  • Deepfake Call Screening
  • Threat Hunting
  • Incident Response
  • Digital Evidence Collection
  • Cybercrime Reporting

📈 Future Roadmap

  • Real-time Telegram Scam Monitoring
  • WhatsApp Intelligence Connector
  • OCR-Based Screenshot Analysis
  • Browser Extension Integration
  • SIEM Platform Connectors
  • Threat Actor Attribution Engine
  • Enterprise SOC Dashboard
  • Multi-Language Scam Detection

📜 License

This project is intended for cybersecurity research, fraud prevention, digital forensics, and educational purposes.

⚠️ Disclaimer

Spectus assists in scam detection and cyber-forensics investigations. Threat assessments are generated using machine learning, heuristic analysis, and AI systems and should be reviewed alongside professional security practices and human verification when handling critical incidents.