🛡️ PhishGuard - AI-Powered Phishing Detection

An intelligent email security system that analyzes Gmail messages for phishing threats using heuristic detection algorithms.

🚀 Quick Start

1. Set Up Virtual Environment & Install Dependencies

# Create virtual environment
python -m venv .venv

# Activate virtual environment
. .\.venv\Scripts\Activate.ps1

# Install dependencies
.\.venv\Scripts\python -m pip install -U pip
.\.venv\Scripts\python -m pip install streamlit google-api-python-client google-auth-oauthlib google-auth-httplib2 beautifulsoup4 python-dateutil

2. Configure Gmail API Access

You need to create Gmail API credentials before running the app.

📖 See SETUP_GMAIL_API.md for detailed step-by-step instructions

Quick Summary:

1. Create a Google Cloud Project
2. Enable Gmail API
3. Configure OAuth consent screen
4. Create OAuth 2.0 credentials (Desktop app)
5. Download the JSON file and rename it to Gmail_Credentials.json
6. Place it in this directory

3. Run the Application

# Make sure venv is activated
.\.venv\Scripts\streamlit run app.py

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

On first run, you'll be prompted to authorize the app with your Gmail account.

🎯 Features

• Real-time Email Scanning - Fetch and analyze emails from your Gmail inbox
• Heuristic Threat Detection - Identifies phishing indicators:
  • Urgency tactics
  • Credential requests
  • Suspicious links
  • Risky attachments
  • Lookalike domains
  • IP-based URLs
• Risk Scoring - Emails rated 0-10 for threat level
• Auto-refresh - Continuously monitor for new threats
• Dark Theme UI - Clean, modern interface

📂 Project Structure

PhishGuard-main/
├── app.py                    # Main Streamlit dashboard
├── gmail_client.py           # Gmail API client
├── parser_heuristics.py      # Email parsing & heuristics
├── main.py                   # CLI entry point
├── pyproject.toml            # Dependencies
├── SETUP_GMAIL_API.md        # Gmail API setup guide
├── README.md                 # This file
├── Gmail_Credentials.json    # Your credentials (create this)
└── token.pickle              # Auto-generated auth token

🔒 Security & Privacy

• Read-only access - The app can only read emails, not send or delete
• Local processing - All analysis happens on your machine
• No data collection - Your emails are never sent to external servers
• OAuth 2.0 - Secure authentication via Google's OAuth flow

📊 How It Works

1. Fetch - Retrieves recent emails via Gmail API
2. Parse - Extracts headers, body, links, and attachments
3. Analyze - Applies heuristic rules to detect phishing indicators
4. Score - Calculates risk score (0-10) based on indicators found
5. Display - Shows results with severity classification (Safe/Review/High Risk)

🛠️ Troubleshooting

"No such file or directory: 'Gmail_Credentials.json'"

• Follow the Gmail API Setup Guide to create credentials
• Make sure the file is in the project root directory
• Verify the filename is exactly Gmail_Credentials.json

"Access blocked: This app's request is invalid"

• Add your email as a test user in the OAuth consent screen
• Make sure the OAuth client is configured as "Desktop app"

Browser doesn't open for authentication

• Check if it opened in the background
• Look for the authorization URL in the terminal output

📝 Requirements

• Python 3.11+
• Gmail account
• Google Cloud Project with Gmail API enabled

🔗 Dependencies

• streamlit - Web interface
• google-api-python-client - Gmail API client
• google-auth-oauthlib - OAuth authentication
• beautifulsoup4 - HTML parsing
• python-dateutil - Date handling

📄 License

This project is for educational and personal use.

⚠️ Disclaimer

This tool is designed to assist in identifying potential phishing emails but should not be your only line of defense. Always exercise caution with suspicious emails and verify important communications through alternative channels.