`# ScamShield: Explainable Real-Time Threat Analysis & Deterministic Risk Scoring Architecture
Authors: Lakshya Kurup, Rajdeep Sharma
Published: August 2026 | Repository: GitHub
Abstract
Modern social engineering and phishing attacks targeting digital consumers rely heavily on cognitive pressure, brand spoofing, and obscure link shorteners. Traditional detection platforms frequently rely on black-box LLM scoring or delayed blocklists, leading to non-deterministic outputs, API latency, and a lack of actionable transparency for non-technical end-users.
ScamShield (GuardScam AI) addresses these limitations by introducing a hybrid, rule-driven, and explainable threat analysis engine. Built using Next.js 16, TypeScript, FastAPI, Pydantic, SQLite, and Docker, ScamShield provides real-time risk scoring, granular evidence breakdowns, and AI-assisted plain-language summaries across suspicious URLs, emails, SMS, and WhatsApp messages.
1. Introduction & Problem Statement
Phishing vectors are evolving rapidly across non-email channels like SMS, WhatsApp, and messaging apps. Common failure modes in consumer-facing threat protection include:
- Black-box decisions: Users receive binary flags (Safe/Unsafe) without granular context on why a message is malicious.
- High API overhead & Latency: Directing every inbound string directly to an LLM introduces significant latency and cloud API costs ($0.02–$0.10/request).
- Over-reliance on Static Blocklists: Newly registered domain names (Zero-Day phishing sites) bypass domain reputation databases.
ScamShield decouples deterministic heuristic verification from generative summary modules, maintaining execution speeds below 150ms while delivering clear reasoning.
2. System Architecture & Tech Stack
The platform uses a decoupled client-server model optimized for high throughput, low latency, and deterministic analysis.
| Component | Technology | Primary Role |
|---|---|---|
| Frontend | Next.js 16 (App Router), React, TypeScript, Tailwind CSS | Client Dashboard, Evidence Cards & Plain-Language Breakdown |
| Backend Framework | Python (FastAPI), Pydantic | Data validation, schema enforcement, heuristic evaluation |
| Database & Persistence | SQLite, REST APIs | Rule pattern persistence and local threat telemetry storage |
| Infrastructure | Docker, CORS Middleware, Rate-limiting layers | Containerized deployment, API protection, and scalability |
Data Flow Pipeline
- Payload Ingestion: Incoming Payload (URL, Email, SMS/WhatsApp) is captured by the endpoint.
-
Analysis Engine: FastAPI Backend / Pydantic Engine executes:
- Heuristic Rule Evaluation (Urgency, Deceptive Links, Payment Triggers)
- Deterministic Risk Scoring (0–100 Scale)
- Structured Output Generation
- Client Presentation: Next.js 16 Client Dashboard renders Evidence Cards & Plain-Language Summaries.
3. Threat Analysis Engine & Heuristics
The engine evaluates incoming payloads across multiple deterministic feature matrices:
- Urgency & Pressure Triggers: Regex pattern matching for psychological coercion ("account suspended within 2 hours", "immediate legal action", "OTP required now").
- Deceptive URL & Structure Analysis: Detection of typosquatting, sub-domain stacking, IP-based hostnames, and suspicious URL shorteners.
- Financial & Credential Harvesting Indicators: Automated identification of unverified banking requests, gift card incentives, and fraudulent payment gateway links.
- Deterministic Risk Scoring: Assigns normalized threat scores (0–100) with strict categorization (Safe, Caution, High Risk, Malicious).
4. Key Performance Metrics & Results
- Deterministic Execution Speed: Sub-150ms throughput for rule-based heuristics engine.
- Cost Efficiency: Decreases generative API overhead by routing structured payloads for AI summarization only when necessary.
- Zero Silent Failures: Comprehensive input parsing via Pydantic prevents silent script failures across malformed or obfuscated input payloads.
5. Future Roadmap
- Modular integration of local lightweight NLP models for off-grid threat classification.
- Browser extension rollout for automated background DOM inspection.
- Real-time community reporting loop backed by crowdsourced verification signals.
Published by Lakshya Kurup & Rajdeep Sharma — Open Source Technical Documentation.`
Top comments (0)