Certifiedunder the Production-Grade Agentic System module in the Agentic AI In Production program.Certifiedunder the Production-Grade Agentic System module in the Agentic AI In Production program.
Phishing emails remain one of the most common and damaging cybersecurity threats faced by organizations today. Security teams must analyze suspicious emails quickly while ensuring legitimate communication is not incorrectly blocked. This requires detection systems that are accurate, reliable, and transparent.
This project presents a production-ready multi-agent AI phishing detection system designed to simulate real-world enterprise email security workflows. The system analyzes raw .eml email files using a coordinated set of specialized agents that perform header analysis, content inspection, domain intelligence, attachment scanning, and structured risk scoring.
Unlike experimental prototypes, this production-focused implementation emphasizes reliability, monitoring, resilience, and maintainability. It demonstrates how agentic AI systems can be deployed with proper guardrails, logging, testing, and failure handling to meet professional software standards.
The goal of this project is to demonstrate how agentic AI systems can be deployed safely in production environments with clear decision logic, monitoring, and built-in safety guardrails.
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 structured phishing risk scores with recommended actions.
The architecture reflects how modern Security Operations Centers (SOC) combine automated detection, structured validation, and monitoring to prevent phishing attacks safely while maintaining operational efficiency.
This production version focuses on reliability and maintainability rather than experimentation. The system includes structured logging, guardrails, testing, and graceful fallback mechanisms to ensure predictable behavior even when external tools fail.
Each agent performs a clearly defined task and contributes to a deterministic final risk score, making the system easier to audit, debug, and extend. The modular architecture allows independent updates and supports deployment in real-world security workflows.
.eml email filesThe system processes emails using independent detection agents, then correlates their findings using SOC-style logic.
phishing-analyzer-prod/ │ ├── __init__.py ├── logging_config.py # Centralized production logging configuration ├── health.py # System health check & monitoring utility │ ├── app/ │ └── app.py # Streamlit UI for interactive phishing analysis │ ├── phishing_analyzer/ │ ├── agents/ # Core multi-agent detection system │ │ ├── ingestion.py # Email ingestion agent │ │ ├── header_agent.py # Header analysis agent │ │ ├── content_agent.py # Email content analysis agent │ │ ├── url_agent.py # URL analysis agent │ │ ├── domain_agent.py # Domain intelligence agent │ │ ├── attachment_agent.py # Attachment analysis agent │ │ ├── risk_agent.py # Risk scoring & decision agent │ │ └── reporter_agent.py # Final report generation agent │ │ │ ├── orchestration/ │ │ └── prefect_flow.py # Prefect workflow orchestration │ │ │ ├── tools/ # External analysis tools │ │ ├── url_tool.py │ │ ├── attachment_tool.py │ │ └── virustotal_tool.py │ │ │ ├── config/ │ │ └── risk_config.py # Risk scoring configuration │ │ │ ├── safety/ │ │ └── guardrails.py # Input validation & safety guardrails │ │ │ └── utils/ │ ├── error_handler.py # Standardized error handling wrapper │ └── resilience.py # Retry, timeout & resilience utilities │ ├── samples/ # Sample phishing & legitimate emails │ ├── dhl_delivery_failure_phish.eml │ ├── microsoft_password_reset_phish.eml │ ├── Updates to how privacy settings work on Play.eml │ └── Help shape Advent of Cyber 2026.eml │ ├── images/ │ ├── architecture.png │ └── title.png │ ├── tests/ # Testing suite │ └── unit/ # Unit tests for agents & tools │ ├── .env # Environment variables (not committed) ├── requirements.txt ├── pyproject.toml └── README.md
.eml email is ingested.eml files| Score Range | Severity | Action |
|---|---|---|
| 0–49 | Info | Allow |
| 50–69 | Medium | Flag |
| 70–100 | High | Quarantine |
VT_API_KEYdhl_delivery_failure_phish.eml{ "from": "DHL Express <noreply@dhl-track-support.com>", "domain": "dhl-track-support.com", "risk": { "score": 90, "severity": "High", "action": "Quarantine", "confidence": "High" }, "findings": { "headers": [ "Brand impersonation detected: dhl" ], "content": [ "Brand impersonation detected: dhl" ], "urls": { "indicators": [ "Malformed URL detected" ], "virustotal": "not_configured" }, "attachments": { "indicators": [], "virustotal": "not_configured" }, "domain": { "age_days": null, "virustotal": "enabled" } } }
python -m venv venv
venv\Scripts\activate
source venv/bin/activate
pip install -r requirements.txt
streamlit run app/app.py
This project includes a comprehensive testing suite to ensure production reliability and safe multi-agent behavior.
Validate individual agents and tools:
Several tests simulate real workflow paths across multiple components:
These tests ensure agents and tools work together correctly under realistic conditions.
The system can be tested end-to-end using provided .eml samples through:
pytest --cov=phishing_analyzer
✔ Minimum 70% test coverage enforced
CrewAI explanation not generated
→ CrewAI not installed. Install or run deterministic mode.
DNS/WHOIS lookup failure
→ Check internet connectivity.
Timeout during execution
→ Retry execution; timeout handling is built-in.
Dependency errors
pip install -r requirements.txt pip install -e .
The system is designed to fail safely:
The system includes structured error handling to ensure stable execution across all agents and external tool integrations.
These mechanisms ensure the system behaves predictably and avoids silent failures in production-like environments.
.eml files are parsed safely (no execution)This project includes built-in safety mechanisms to ensure robustness, secure handling of untrusted email content, and fail-safe behavior under errors.
All user-supplied and email-derived text is sanitized before analysis or UI rendering:
This prevents:
The system is designed to continue operating even when optional components fail:
This project is an actively maintained production-style prototype developed as part of the ReadyTensor Agentic AI in Production program.
Maintenance scope:
Support:
This repository is maintained for educational and production experimentation purposes.
Issues and improvements can be reported via GitHub Issues.
This project is released under the MIT License.
You are free to use, modify, and distribute this software for educational and commercial purposes with proper attribution.
This project demonstrates how a production-ready multi-agent AI system can be designed for real-world phishing detection using deterministic analysis, structured risk scoring, and modular orchestration. By combining reliability-focused engineering practices such as guardrails, logging, testing, and resilience mechanisms, the system reflects how modern security tools are built for safe and predictable operation.
The architecture highlights how agentic AI can be deployed responsibly in cybersecurity environments, supporting faster and more consistent decision-making while maintaining transparency and control. This implementation serves as a practical foundation for building scalable and trustworthy AI-driven security solutions.