PhishGuard

PhishGuard

Inspiration Phishing is still the entry point for the majority of breaches, and the people on the front line — SOC analysts and everyday users — are drowning. Triaging a single suspicious email means manually eyeballing headers, hovering over links, and judging whether the tone feels like a scam. It's slow, repetitive, and inconsistent. Worse, most automated tools spit out a single black-box risk score with no explanation, so analysts can't trust it and users can't learn from it.

We wanted to flip that. Instead of one opaque model, we imagined a small crew of specialist AI agents that each examine one facet of an email and show their work — so the verdict is fast and defensible. That transparency is the whole point: a human should be able to see exactly why PhishGuard said what it said.

What it does PhishGuard takes pasted email content (raw headers + body, or just the body) and runs it through a coordinated team of AI agents, then returns a single, evidence-backed verdict.

Orchestrator agent routes the email to three specialists and synthesizes the result. Header Analyst (deterministic) inspects sender identity: Reply-To / Return-Path domain mismatches, brand impersonation from free-mail accounts, display-name vs. domain mismatches, and high-risk TLDs. Link Analyst (deterministic) extracts every URL and scores it for IP-address hosts, punycode / look-alike domains, shorteners, anchor-text vs. href mismatch, excessive subdomains, and insecure login links. Content Analyst (Gemini) classifies the social-engineering intent — urgency, authority impersonation, fear, and credential/payment lures — and cites the exact phrases. Verdict synthesizer combines weighted findings into a calibrated confidence score, maps it to safe / suspicious / malicious, and phrases a clear recommended action. The output is twofold: a structured JSON object (machine-readable) and a human-readable summary with per-agent evidence — both viewable and downloadable in the UI. Every finding includes the raw snippet that triggered it, so nothing is a black box. How we built it Google ADK defines the multi-agent graph — a root orchestrator with three specialist sub-agents — runnable via adk web / adk run. Gemini 2.0 Flash powers the two reasoning steps: social-engineering intent classification and verdict phrasing. Deterministic Python tools handle header and URL analysis with pure heuristics and zero network calls, so those findings are explainable and never hallucinated. Pydantic v2 schemas (Finding, AgentReport, PhishVerdict) give every agent a strict, JSON-serializable contract. A weighted scoring layer turns severity-tagged findings into a 0–100 confidence score with threshold bands and a hard override (any critical finding forces at least "suspicious"). Streamlit delivers the demo UI: one-click sample emails, a color-coded verdict badge, a confidence bar, expandable per-agent evidence, and JSON / summary export. We deliberately kept two paths: a real ADK agent graph for genuine agentic delegation, and a deterministic orchestration path that drives the UI for a crash-proof demo.

Challenges we ran into Keeping the verdict trustworthy. Letting an LLM decide everything is unreliable and unexplainable. We split the system so header/URL analysis is deterministic and only intent + phrasing use the model — then made the synthesizer compute the score with math, not the LLM, so the model can never contradict the evidence. Demo reliability under time pressure. Agentic tool-routing can intermittently skip steps. We mirrored the ADK graph with a deterministic control flow for the UI so the demo never breaks on camera. Failing gracefully without an API. We made every Gemini call fail-soft — if the model is unreachable, PhishGuard still returns a verdict from the deterministic agents and templated phrasing instead of crashing. Calibrating the score. Tuning the severity weights and thresholds so a clear phish lands red, a newsletter lands green, and an ambiguous invoice lands amber took iterative testing against sample emails. Accomplishments that we're proud of A genuinely multi-agent, explainable triage system — every verdict comes with the evidence behind it, grouped by agent. A clean separation of deterministic vs. LLM reasoning that makes the output both fast and defensible. Fail-soft design: the app degrades gracefully and never hard-crashes, even with no API key. A demo-ready UI with structured JSON and a human-readable report, both downloadable. It runs locally with three commands and no external security APIs required. What we learned Agentic ≠ "let the LLM do everything." The most robust design uses agents for decomposition and reasoning, but anchors the final decision in deterministic, auditable logic. How to structure a Google ADK multi-agent graph — orchestrator, sub-agents, and function tools — and where structured (Pydantic) outputs dramatically improve reliability. That explainability is a feature, not a nice-to-have — showing the evidence is what makes a security verdict usable by a real analyst. Practical prompt design for calibrated classification (resisting the model's tendency to over-flag). What's next Live URL/domain reputation and WHOIS lookups as additional agent tools (currently heuristic-only). .eml file upload and attachment static analysis. Batch inbox triage mode for processing many emails at once. MITRE ATT&CK technique mapping in the content analysis. Auto-generated incident reports and Slack / SIEM alerting for SOC workflows.