🕵️ PhishSentinel

AI-Powered Phishing Email Threat Analyzer

PhishSentinel autonomously analyzes suspicious emails, scores their threat level from 0–100, extracts attack indicators, and presents findings in a live dashboard — in under 10 seconds.

PhishSentinel is an intelligent security tool that detects phishing emails — fake emails designed to trick you into giving up passwords, clicking dangerous links, or sending money to scammers. Think of it as a digital detective that reads every suspicious email and tells you exactly how dangerous it is.

Phishing is the #1 cyber threat of 2026, costing businesses over $3.5 billion every year. Criminals now use artificial intelligence (AI — computer systems that can learn and make decisions) to craft fake emails that are nearly indistinguishable from real ones. These attacks fool even careful, tech-savvy employees. Every company, from small startups to Fortune 500 giants, desperately needs better tools to catch these threats before they cause damage.

What makes PhishSentinel different from basic spam filters is that it uses an AI agent — a program that reasons step-by-step like a human security analyst — instead of simple keyword matching. While traditional tools look for words like "urgent" or "click here," PhishSentinel understands context, analyzes email headers (the behind-the-scenes routing information), detects visual tricks like lookalike domain names, and weighs 12 different risk factors to produce a reliable threat score.

💼 For Managers: PhishSentinel demonstrates production-level skills in AI agent design, cybersecurity tooling, and full-stack Python development. It is the kind of tool real SOC (Security Operations Center) teams request but rarely have. The architecture mirrors enterprise threat intelligence platforms costing tens of thousands of dollars per year.

When you paste an email into PhishSentinel, it passes through 7 specialized AI agents arranged in a pipeline called a graph. Each agent has one job: the first reads and decodes the email, the second checks authentication headers, the third scans the message body for suspicious language, the fourth extracts dangerous links, and so on. These agents pass information forward like an assembly line, with conditional branches that skip unnecessary steps for safe emails. Finally, a scoring agent weighs all findings and a report generator writes a human-readable summary. The entire process completes in seconds, and results are saved to a local database.

┌─────────────────────────────────────────────────────────────────┐
│                        PhishSentinel                            │
│                     LangGraph Agent Flow                        │
└─────────────────────────────────────────────────────────────────┘

  📧 Raw Email Input
        │
        ▼
┌───────────────────┐
│  1. Email Parser  │  ← Extracts headers, body, attachments
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  2. Header Agent  │  ← Checks SPF, DKIM, DMARC, IP hops
└────────┬──────────┘
         │
    ┌────┴────┐
    │ All     │
    │ auth    │ ← Conditional branch (LangGraph edge)
    │ pass?   │
    └────┬────┘
    NO   │ YES
    │    └──────────────────────┐
    ▼                           ▼
┌──────────────┐     ┌──────────────────────┐
│ Deep Header  │     │  Skip deep inspection │
│ Inspection   │     │  (fast path)          │
└──────┬───────┘     └──────────┬────────────┘
       │                        │
       └───────────┬────────────┘
                   ▼
         ┌─────────────────┐
         │  3. Body Agent  │  ← LLM scans for urgency, brand
         └────────┬────────┘    impersonation, homoglyph domains
                  │
                  ▼
         ┌─────────────────┐
         │  4. IOC Extract │  ← Pulls IPs, URLs, domains as
         └────────┬────────┘    Indicators of Compromise
                  │
                  ▼
         ┌─────────────────┐
         │  5. Scoring     │  ← Weights 12 indicators → 0–100
         └────────┬────────┘    threat score
                  │
                  ▼
         ┌─────────────────┐
         │  6. Report Gen  │  ← GPT-4o writes analyst narrative
         └────────┬────────┘
                  │
                  ▼
         ┌─────────────────┐
         │  7. SQLite Save │  ← Stores analysis for history tab
         └────────┬────────┘
                  │
                  ▼
         📊 Streamlit Dashboard

THREAT SCORE LEGEND
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  0 – 20  │ ✅ Safe              │ No significant indicators found
 21 – 45  │ ⚠️  Suspicious       │ Minor anomalies, exercise caution  
 46 – 74  │ 🚨 Likely Phishing   │ Multiple strong indicators present
 75 – 100 │ ☠️  Critical         │ High-confidence phishing attack
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The main dashboard showing a Plotly gauge chart with threat score 87/100 (Critical), four metric cards, and a radar chart plotting all 12 indicator scores.

Threat Analysis Tab

The IOC (Indicator of Compromise) report tab showing extracted malicious URLs, sender IPs, and suspicious domains in a sortable table with CSV export.

IOC Report Tab

The history tab showing the last 20 email analyses stored in SQLite, with timestamps, threat scores, and clickable rows to reload past results.

Analysis History Tab

Before you begin, ensure you have:

• Python 3.11 or higher — Download from python.org
• pip — Python's package installer (included with Python 3.4+)
• OpenAI API Key — Get yours at OpenAI (requires account creation and billing setup)

# Step 1: Clone the repository
git clone https://github.com/AnandSundar/phishsentinel.git
cd phishsentinel

# Step 2: Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Step 3: Install dependencies
pip install -r requirements.txt

# Step 4: Set your OpenAI API key
cp .env.example .env
# Edit .env and add: OPENAI_API_KEY=your_key_here

# Step 5: Run the app
streamlit run app.py

The app will open at http://localhost:8501 in your browser.

💡 Pro Tip: Test the app immediately using the included sample email: samples/sample_phish.eml

phishsentinel/
│
├── 📄 app.py                    # Streamlit UI entry point — run this to start the app
│
├── 🤖 agent/
│   ├── __init__.py
│   ├── graph.py                 # LangGraph StateGraph — defines the AI agent pipeline
│   ├── nodes.py                 # 7 agent node functions (the "workers" in the pipeline)
│   ├── state.py                 # Shared data structure passed between agents
│   └── schemas.py               # Data models for structured AI output (Pydantic)
│
├── 🛠️  utils/
│   ├── email_parser.py          # Reads and extracts raw email components
│   ├── homoglyph.py             # Detects lookalike Unicode characters in domains
│   ├── scoring.py               # Converts indicator results into 0–100 threat score
│   └── db.py                    # SQLite database read/write helpers
│
├── 📊 data/
│   └── phishsentinel.db         # Auto-created SQLite database (analysis history)
│
├── 📧 samples/
│   └── sample_phish.eml         # Demo phishing email — use this to test the app instantly
│
├── 📸 docs/screenshots/         # Dashboard screenshots for this README
│
├── .env.example                 # Template for your API key config
├── requirements.txt             # Python package dependencies
└── README.md                    # You are here

PhishSentinel is designed with privacy as a core principle:

Emails are analyzed in memory and never stored. Only the analysis results (threat scores, extracted IOCs, summary text) are saved to the local SQLite database. The original email content is discarded after processing completes. This means sensitive email content stays ephemeral — there is no growing archive of private communications on your server.

Your OpenAI API key is protected through multiple layers:

• Local development: Stored in .env file (which is gitignored by default)
• Production deployment: Managed via st.secrets in Streamlit Cloud
• Never in code: The application reads from environment variables, keeping credentials out of version control

PhishSentinel runs entirely on your own machine or private server. Emails are sent to only two places:

1. Your local SQLite database — for history storage
2. OpenAI's API — for AI analysis (via encrypted HTTPS connection)

No third-party analytics, no external logging services, no data brokers.

According to OpenAI's API data usage policy, data sent through the API:

• Is NOT used to train OpenAI's models
• Is retained temporarily only for abuse monitoring (up to 30 days for enterprise, shorter for standard)
• Can be zero retention for eligible enterprise customers

⚠️ Important: Do not analyze emails containing sensitive personal data (SSNs, medical records, passwords) unless you have reviewed OpenAI's data usage policy and your organization's data handling requirements.

Phishing is the #1 cyber threat facing businesses today. According to the FBI's Internet Crime Complaint Center, phishing attacks cost organizations over $3.5 billion annually. In 2026, AI-generated phishing emails have become nearly impossible to distinguish from legitimate communications — even security professionals fall for sophisticated attacks.

Yet most companies still rely on basic spam filters that use simple keyword matching. They need intelligent tools that understand context, detect nuanced deception, and provide actionable intelligence — exactly what PhishSentinel delivers.

Building PhishSentinel required mastery of eight critical engineering skills:

• 🤖 AI Agent Architecture — Designed a multi-node agent system using LangGraph with conditional branching and state management
• 🔗 LLM Integration — Integrated OpenAI GPT-4o with structured output schemas for reliable, parseable results
• 🔒 Cybersecurity Domain Knowledge — Implemented SPF/DKIM/DMARC authentication checks and IOC extraction patterns used by enterprise SOC teams
• 📊 Data Visualization — Created interactive Plotly charts (gauge, radar) that communicate threat data intuitively
• 🗄️ Database Design — Built a SQLite-backed history system with proper schema design and query optimization
• 🧪 Input Validation — Handled raw email parsing, file uploads, and edge cases in user-provided data
• 🌐 Full-Stack Development — Delivered a complete application from backend AI agents to frontend dashboard
• 📝 Technical Documentation — Produced clear README and inline documentation for maintainability

PhishSentinel mirrors the architectural patterns found in commercial threat intelligence platforms costing $50,000+ per year:

• Agent Graphs — Modular AI components that can be extended or replaced independently
• Structured LLM Output — Using Pydantic schemas to ensure AI responses are machine-parseable
• IOC Extraction — Automated threat indicator harvesting for integration with SIEM (Security Information and Event Management) tools
• Scoring Algorithms — Weighted multi-factor analysis rather than binary yes/no decisions

🎯 Bottom line: PhishSentinel is not a tutorial project. It is a working security tool built with the same architectural patterns (agent graphs, structured LLM output, IOC extraction) used in enterprise threat intelligence platforms costing tens of thousands of dollars per year.

Status Key:

• ✅ Complete — Ready to use
• 🔄 In Progress — Currently being developed
• 📋 Planned — Scheduled for upcoming release
• 💡 Idea — Under consideration

We welcome contributions from the security and AI community!

1. Fork the Repository: Click the "Fork" button on GitHub
2. Create a Branch: git checkout -b feature/your-feature-name
3. Make Changes: Write code, add tests, update docs
4. Commit: git commit -m "Add: your feature description"
5. Push: git push origin feature/your-feature-name
6. Pull Request: Open a PR with a clear description of changes

• Formatting: Use Black (black .)
• Type Hints: All functions must have type annotations
• Docstrings: Google-style docstrings for all public functions
• Tests: Include tests for new indicators or features

Want to make PhishSentinel smarter? Here's how to add a new detection indicator:

1. Define the Logic: Create a function in utils/ (e.g., utils/new_detector.py)
2. Add to Pipeline: Import and call your function in agent/nodes.py (in the appropriate agent node)
3. Update State: Add the new indicator to agent/state.py (in PhishingAnalysisState)
4. Update Scoring: Add weight to utils/scoring.py (INDICATOR_WEIGHTS)
5. Update Schema: Add to agent/schemas.py (in IndicatorResult or similar)
6. Update UI: Add visualization in app.py

Follow the node pattern: Each agent node receives the current state, performs analysis, and returns an updated state. The graph handles passing data between nodes.

This project is licensed under the MIT License — see the LICENSE file for details.

• ✅ Commercial use allowed
• ✅ Modification allowed
• ✅ Distribution allowed
• ✅ Private use allowed
• ⚠️ No warranty provided

• GitHub: @AnandSundar
• LinkedIn: Anand Sundar
• Email: anandsundar96@gmail.com