Phishing attacks remain one of the most persistent and damaging cybersecurity threats faced by organizations today. Security teams must quickly analyze suspicious emails while ensuring legitimate communication is not mistakenly blocked. This requires systems that are not only accurate but also transparent and explainable.

This project presents a multi-agent AI phishing detection system that combines deterministic security analysis with explainable AI. The architecture is designed to simulate how real-world Security Operations Centers (SOC) investigate suspicious emails using layered detection, structured risk scoring, and human validation.

Instead of relying solely on large language models, the system prioritizes deterministic detection for reliability and uses AI only for explanation. A human-in-the-loop stage ensures that final decisions remain interpretable and safe, making the system suitable for real-world cybersecurity workflows.

🌍 Real-World Cybersecurity Impact

This system demonstrates how multi-agent AI can improve phishing detection in real-world security environments. It enables security teams to automatically analyze suspicious emails, reduce manual investigation time, and generate explainable phishing risk scores that can be reviewed before taking action.

The architecture reflects how modern Security Operations Centers combine deterministic detection, AI reasoning, and human oversight to prevent phishing attacks safely while maintaining operational efficiency.

✨ Key Features

✅ Deterministic phishing detection (no AI hallucinations)

✅ Email header analysis (SPF, DKIM, DMARC)

✅ Content inspection for phishing language & URLs

✅ DNS & WHOIS domain intelligence

✅ Policy-driven risk scoring

✅ Prefect-based orchestration

✅ Optional CrewAI explanation layer (non-decision-making)

✅ Fully unit-tested using pytest

✅ Python 3.11 compatible (Windows & Linux)

🧠 Architecture Overview

The following diagram illustrates how multiple specialized agents collaborate within a structured orchestration pipeline.

Deterministic detection first, LLM explanation second

📁 Project Structure

phishing_analyzer_project/
│
├── phishing_analyzer/
│   ├── __init__.py
│   │
│   ├── agents/                     # Multi-agent system modules
│   │   ├── __init__.py
│   │   ├── detection_agent.py      # Detection Agent – performs phishing analysis
│   │   ├── risk_agent.py           # Risk Scoring Agent – calculates severity & action
│   │   ├── explanation_agent.py    # Explanation Agent (CrewAI) – generates AI explanation
│   │   └── human_agent.py          # Human-in-the-loop Agent – analyst validation step
│   │
│   ├── samples/                    # Sample .eml phishing emails for testing
│   ├── detector.py                 # Core detection & scoring engine logic
│   ├── guardrails.py               # Safety policies, validation & redaction
│   ├── prefect_flow.py             # Prefect orchestration for multi-agent pipeline
│   └── crewai_explainer.py         # CrewAI-based optional explanation engine
│
├── tests/                          # Unit tests (pytest)
│   ├── test_ingestion.py
│   ├── test_header_analysis.py
│   ├── test_content_analysis.py
│   ├── test_dns_auth.py
│   ├── test_domain_analysis.py
│   └── test_risk_scoring.py
│
├── images/
│   ├── title.png
│   └── architecture.png            # Architecture & cover images
│
├── requirements.txt
├── pyproject.toml
└── README.md

🤖 Multi-Agent Architecture

This project implements a structured multi-agent phishing detection system where specialized agents collaborate to analyze suspicious emails and generate a final security assessment.

1️⃣ Detection Agent

Performs deep phishing detection by analyzing:

• Email headers and sender anomalies
• Email content and phishing indicators
• Domain intelligence and age
• SPF, DKIM, and DMARC authentication

This agent produces structured technical findings from the email.

2️⃣ Risk Scoring Agent

Calculates the overall phishing risk score based on signals generated by the Detection Agent.

Responsibilities:

• Assigns phishing severity level (Low, Medium, High)
• Determines recommended action (Allow, Flag, Quarantine, Block)
• Produces final risk assessment

3️⃣ Explanation Agent (CrewAI)

Generates a human-readable explanation of the phishing analysis for security analysts and non-technical stakeholders.

• Uses CrewAI to simulate a SOC security analyst
• Explains why an email was classified with a given risk
• Improves transparency and interpretability

This agent is optional at runtime but remains an integral part of the multi-agent architecture.

4️⃣ Human Review Agent (Human-in-the-Loop)

Implements a human validation step before final action is taken.

• Allows a security analyst to approve, block, or escalate
• Prevents fully autonomous decision-making
• Ensures safe deployment in real-world environments

🔄 Orchestration

All agents are orchestrated using a Prefect workflow that coordinates execution, ensures reliability, and manages the end-to-end phishing analysis pipeline.

⚙️ How It Works

This system analyzes suspicious emails using a coordinated multi-agent pipeline that combines deterministic phishing detection, risk scoring, AI explanation, and human validation.

Each agent performs a specialized role to ensure reliable and explainable phishing detection.

🔄 Agent Workflow

The system follows a structured multi-agent workflow:

1. Email Ingestion
   Loads and parses email data from .eml files.

2. Detection Agent
   Analyzes headers, content, domains, and authentication signals to identify phishing indicators.

3. Risk Scoring Agent
   Calculates overall phishing risk score and determines severity and recommended action.

4. Human Review Agent (Human-in-the-Loop)
   Allows a security analyst to approve, block, or escalate the decision before final output.

5. Explanation Agent (CrewAI)
   Generates a human-readable explanation of the analysis for analysts and stakeholders.

This structured workflow ensures reliable phishing detection while maintaining transparency and human oversight.

🧠 Why a Multi-Agent Approach?

Traditional phishing detection systems often rely on a single model or rule-based engine, which can limit transparency and reliability. This system adopts a multi-agent architecture where each agent performs a specialized task such as header inspection, content analysis, domain intelligence, and risk scoring.

By separating responsibilities across agents, the system becomes easier to maintain, test, and extend. Each agent contributes structured findings that are combined into a final risk assessment, making the decision process transparent and explainable.

This modular approach mirrors how real-world security teams analyze suspicious emails using layered validation rather than relying on a single automated decision.

⚙️ Deterministic Detection with AI Explanation

The system prioritizes deterministic phishing detection techniques such as header validation, domain intelligence, authentication checks, and structured risk scoring. These methods provide reliable and reproducible results.

AI is used selectively for generating human-readable explanations of the findings rather than making final decisions. This hybrid approach ensures both accuracy and transparency, allowing analysts to understand why an email is flagged without relying entirely on probabilistic model outputs.

🏢 Practical Use in Security Operations

This architecture can support enterprise email security teams by automating the initial analysis of suspicious emails while maintaining human oversight. Security analysts can use the structured output to make faster and more consistent decisions.

The system can also serve as a foundation for building SOC automation tools, training datasets, or advanced threat analysis pipelines where explainability and reliability are critical.

⚙️ Installation

Requirements

Python 3.11 (recommended)

Install Dependencies

python -m pip install -r requirements.txt
python -m pip install -e .

CrewAI is optional. Uncomment it in requirements.txt only if required.

▶️ Running the Analyzer

C:\Python311\python.exe -m phishing_analyzer.prefect_flow --eml phishing_analyzer/samples/phish_high_confidence.eml

🧪 Testing

Run all unit tests:

python -m pytest -v

Tests cover:

• Email ingestion
• Header anomaly detection
• Content analysis logic
• DNS / WHOIS handling
• Policy-based risk scoring

📤 Sample Output (High‑Confidence Phishing)

Input

samples/phish_high_confidence.eml

================ FINAL REPORT ================

1️⃣ EXECUTIVE SUMMARY
This email shows strong indicators commonly associated with phishing attacks.

2️⃣ FINAL VERDICT
Decision: Block

3️⃣ RISK SCORE
Score: 36
Severity: High

4️⃣ KEY FINDINGS
- Header issue: SPF failed
- Header issue: DMARC failed
- Content indicator: Urgent or credential-harvesting language detected
- Domain age: Unable to determine
- Authentication issue: SPF missing
- Authentication issue: DMARC missing
- Authentication issue: DKIM missing

5️⃣ EVIDENCE
From Email: alert@goog1e-security.com
From Domain: goog1e-security.com
SPF Result: fail
DKIM Result: missing
DMARC Result: spf=fail dkim=none dmarc=fail

6️⃣ SUGGESTED ACTION
Do NOT interact with this email. Block sender and report to security.

================ AI EXPLANATION ================

{'status': 'skipped', 'reason': 'CrewAI not installed'}

🧠 Design Principles

• Deterministic security logic first
• LLMs used only for explainability
• Fail-safe risk elevation
• SOC-aligned architecture
• Strong guardrails & sanitization
• High test coverage

⚠️ Limitations and Future Improvements

While the system demonstrates a robust multi-agent architecture, it currently focuses on deterministic phishing detection using structured signals. Future improvements could include integration with threat intelligence feeds, advanced URL sandboxing, and continuous learning from analyst feedback.

The modular design allows these enhancements to be incorporated without major architectural changes.

📜 License

MIT License

This project demonstrates how multi-agent AI systems can be safely applied in cybersecurity environments where reliability, explainability, and human oversight are critical.