The Solution
URL Forensics Sandbox is a multi-tiered phishing and social engineering detection system that analyzes suspicious messages and URLs through four progressive analysis layers — stopping early when threats are confirmed to save resources.
The Problem: Scam messages (loan sharks, phishing, fake government notices) are increasingly sophisticated. They use legitimate platforms like WhatsApp as delivery vehicles, obfuscate text with character substitution ("PR0FESSI0NAL"), and combine clean-looking URLs with manipulative language. Traditional URL blacklists miss these entirely.
How It Works:
- Tier 1 (Reputation): Checks URLs against VirusTotal and local blacklist feeds (PhishTank, URLHaus, OpenPhish). Known-bad URLs are flagged instantly.
- Tier 2A (Heuristics): Analyzes URL structure for suspicious TLDs, brand impersonation in domains, excessive subdomains, login keywords, and homograph attacks. Fetches page content to detect cross-domain forms and obfuscated JavaScript.
- Tier 3 (Sandbox): Launches a headless Chromium browser via Playwright to follow redirect chains, capture screenshots, and detect brand spoofing through perceptual hashing.
- Tier 2B (LLM Context): Sends surrounding text to a local Ollama LLM that identifies psychological manipulation vectors — urgency, authority impersonation, financial baiting, and character obfuscation.
Scores from all tiers are aggregated into a composite verdict (0-100), with short-circuit logic for obvious threats.
Deployment: Available as both a dark-themed desktop GUI (CustomTkinter) and a Telegram bot that anyone can message to instantly check suspicious messages. The bot replies with emoji-coded verdicts (🔴🟡🟢), contributing factors, and warnings.
Results: Tested against real-world scam messages from Singapore (loan shark SMS, fake LTA/DHL notices). The system correctly flags social engineering that pure URL analysis would miss, combining heuristic signals with LLM comprehension for robust detection.
How was Kiro used
Spec-Driven Development (Requirements → Design → Tasks): It started by assessing an externally generated handover document, then used Kiro's spec workflow to produce formal requirements (13 requirements with EARS-pattern acceptance criteria), a technical design (architecture diagrams, data models, 18 correctness properties), and a wave-based task list. This structured approach prevented scope creep and kept implementation focused.
Task Execution with Subagents: Kiro's task orchestration executed 19+ implementation tasks in parallel waves, respecting dependency ordering. Each task was dispatched to a subagent with the right context files, producing clean implementations that followed the spec exactly.
Hooks (Agent Automation):
- Tests After Task — Automatically ran pytest after each completed task to catch regressions
- Run Tests on Save — Triggered the test suite when Python files were edited
- Verify Code Patterns — Pre-write hook ensuring all tier implementations follow the TierAnalyzer protocol, use proper async patterns, and include type annotations
Steering Files: A workspace-level steering file (
python-conventions.md) automatically injected project conventions (architecture rules, async patterns, error handling, naming, testing standards) whenever source files were touched — ensuring consistency across all 14 modules without manual reminders.Property-Based Testing: The spec's correctness properties translated directly into Hypothesis-based tests (18 properties) that generate hundreds of random inputs per property, providing stronger guarantees than example-based tests alone.
How Kiro Shaped the Build: The spec workflow forced some thinking about correctness properties upfront (before writing code), which meant the implementation was testable by design. The hooks caught regressions during development that would have been missed without automated checks. The steering file eliminated "style drift" across the 14-module codebase — every file follows the same patterns without manual review.
Log in or sign up for Devpost to join the conversation.