Email Guard Lightweight Backend (Dep 0.5.6 Mini)

A streamlined FastAPI backend for email phishing detection, specifically optimized for Replit deployment and designed to work seamlessly with the Email Guard Vercel Frontend.

🔗 Full Version Available: This is a lightweight version of the comprehensive Email Guard project (Dev 0.6.2). For enterprise deployments with advanced security features, see the full version.

🚀 Quick Start

Frontend: https://email-guard-cyan.vercel.app/ Backend: Deployed on Replit (URL configured via VITE_API_URL environment variable)

• Replit deployment code: https://replit.com/@Richdaleintern0/EmailGuardLightweight

📊 Version Comparison

Feature	Lightweight (Dep 0.5.6 Mini)	Full Version (Dev 0.6.2)
Deployment	✅ Replit-optimized	🐳 Docker + APISIX Gateway
AI Models	✅ phishing-detection-py + Rule-based	🧠 DistilBERT + Multiple ML Models
Security	✅ JWT Authentication	🔒 Enterprise Security Stack
Rate Limiting	⚡ Application-level	🛡️ APISIX Gateway-level
Dependencies	📦 Minimal (11 packages)	📚 Comprehensive (50+ packages)
Container Isolation	❌ Single deployment	✅ Isolated Docker containers
Model Complexity	🎯 Lightweight ML	🧠 Heavy transformer models
Setup Time	⚡ < 5 minutes	⏱️ 15-30 minutes

🎯 Features

Core Functionality

• 🤖 AI-Powered Detection: Primary ML analysis using phishing-detection-py
• 🔧 Rule-Based Fallback: Comprehensive pattern matching when ML models are unavailable
• 🔐 JWT Authentication: Secure token-based authentication with HTTP-only cookies
• 📊 Scan History: Track and retrieve analysis results for authenticated users
• ⚡ Replit-Optimized: Specifically configured for seamless Replit deployment

Model Analysis Pipeline

1. Primary ML Model: phishing-detection-py for URL and content analysis
2. Rule-Based Analyzer: Pattern matching for suspicious indicators
3. Metadata Extraction: Content analysis and risk scoring
4. Confidence Scoring: Detailed confidence metrics for each analysis

API Endpoints

• POST /auth/token - Authenticate and receive JWT
• POST /scan/email - Analyze email content for threats
• GET /history - Retrieve scan history
• POST /auth/logout - Clear authentication
• GET /health - Health check endpoint

🏗️ Architecture

Frontend (Vercel)                 Backend (Replit)
┌─────────────────┐               ┌──────────────────┐
│   React + Vite  │──── HTTPS ────│   FastAPI App    │
│                 │               │                  │
│  Dashboard UI   │               │  ┌─────────────┐ │
│  Auth Flow      │               │  │ JWT Auth    │ │
│  Results Display│               │  │ Module      │ │
└─────────────────┘               │  └─────────────┘ │
                                  │                  │
                                  │  ┌─────────────┐ │
                                  │  │ AI Analysis │ │
                                  │  │ Engine      │ │
                                  │  └─────────────┘ │
                                  │                  │
                                  │  ┌─────────────┐ │
                                  │  │ Scan        │ │
                                  │  │ History     │ │
                                  │  └─────────────┘ │
                                  └──────────────────┘

🛠️ Technology Stack

Backend Core

• FastAPI: Modern Python web framework
• Uvicorn: ASGI server for production
• Python 3.11+: Latest Python features

AI/ML Models

• phishing-detection-py: Primary ML model for URL/content analysis
• Rule-based analyzer: Custom pattern matching engine
• Content analyzer: Metadata extraction and risk scoring

Authentication & Security

• python-jose: JWT token handling
• passlib: Secure password hashing
• HTTP-only cookies: XSS protection

Dependencies (Lightweight)

fastapi
uvicorn[standard]
python-multipart
python-jose[cryptography]
passlib[bcrypt]
python-dotenv
pydantic
requests
aiofiles
phishing-detection-py

🚀 Deployment

Replit Deployment (Recommended)

1. Import Repository: Import this repository to Replit
2. Install Dependencies: Replit auto-installs from requirements.txt
3. Set Environment Variables:

   JWT_SECRET_KEY=your-super-secure-jwt-secret-key-here

4. Run: Execute python main.py
5. Configure Frontend: Set VITE_API_URL in Vercel to your Replit URL

Local Development

1. Clone Repository:

   git clone https://github.com/Richdale04/Email-Guard-Lightweight.git
   cd Email-Guard-Lightweight

2. Install Dependencies:

   pip install -r requirements.txt

3. Environment Setup:

   # Create .env file
   JWT_SECRET_KEY=your-jwt-secret-key

4. Run Server:

   python main.py

5. Access API: http://localhost:5000

Environment Variables

Variable	Description	Required	Default
JWT_SECRET_KEY	Secret key for JWT signing	✅ Yes	None
PORT	Server port (Replit auto-sets)	❌ No	5000

📁 Project Structure

Email-Guard-Lightweight/
├── ai/                          # AI Analysis Engine
│   ├── email_guard.py          #   Main analyzer with multiple models
│   └── README.md               #   AI documentation
├── backend/                     # FastAPI Backend
│   ├── app.py                  #   Main FastAPI application
│   ├── scan.py                 #   Email scanning logic
│   ├── modules/                #   Backend modules
│   │   ├── authenticate.py     #     JWT authentication
│   │   └── verify.py           #     Input validation
│   └── db/                     #   User database
│       └── users.csv           #     User tokens storage
├── main.py                     # Replit entry point
├── requirements.txt            # Python dependencies
├── pyproject.toml             # Project configuration
└── README.md                  # This file

🧠 AI Analysis Pipeline

1. Primary ML Model (phishing-detection-py)

# URL Analysis
urls = extract_urls(email_text)
result = detector.predict(urls[0])
decision = 'phishing' if result.prediction == 1 else 'safe'

2. Rule-Based Fallback

# Pattern Detection
suspicious_patterns = ['urgent', 'account suspended', 'verify identity']
risk_score = calculate_risk_score(email_text, patterns)
decision = map_risk_to_decision(risk_score)

3. Response Format

{
  "results": [
    {
      "model_source": "PyPI",
      "model_name": "phishing-detection-py",
      "decision": "phishing|safe|spam|error",
      "confidence": 0.85,
      "description": "Detailed analysis description"
    }
  ],
  "timestamp": "2024-01-01T12:00:00",
  "email_snippet": "Email content preview..."
}

🔐 Authentication System

Token-Based Authentication

# Sample tokens (backend/db/users.csv)
sample_token_1,user1,user      # Standard user
sample_token_2,user2,admin     # Admin user

JWT Flow

1. Frontend sends token to /auth/token
2. Backend validates token and creates JWT
3. JWT stored in HTTP-only cookie
4. Subsequent requests use JWT for authentication

Security Features

• HTTP-only cookies (XSS protection)
• JWT expiration handling
• Input sanitization and validation
• CORS configuration for Vercel frontend

📊 API Usage Examples

Authentication

curl -X POST https://your-replit-url.repl.co/auth/token \
  -H "Content-Type: application/json" \
  -d '{"token": "sample_token_1"}'

Email Analysis

curl -X POST https://your-replit-url.repl.co/scan/email \
  -H "Content-Type: application/json" \
  -b "auth_token=your-jwt-token" \
  -d '{"email_text": "URGENT: Your account has been suspended..."}'

Scan History

curl -X GET https://your-replit-url.repl.co/history?limit=5 \
  -b "auth_token=your-jwt-token"

🧪 Test Cases

Phishing Email Example

Subject: URGENT: Account Verification Required

Dear Customer,

Your bank account has been suspended due to suspicious activity. 
Please verify your identity immediately by clicking the link below:

http://suspicious-bank-verify.com/urgent-verify

Failure to verify within 24 hours will result in permanent account closure.

Best regards,
Security Team

Expected Result: phishing with high confidence

Safe Email Example

Subject: Meeting Reminder

Hi John,

Just a reminder about our team meeting tomorrow at 2 PM in the conference room.

Please bring the quarterly reports we discussed.

Thanks,
Sarah

Expected Result: safe with high confidence

🔄 Migration from Full Version

Removed Components

• Docker Containerization: Single Replit deployment
• APISIX Gateway: Direct FastAPI routing
• DistilBERT Models: Heavy transformer models removed
• Redis Caching: Simplified in-memory processing
• Advanced Rate Limiting: Application-level only
• Multiple Model Pipeline: Streamlined to essential models

Maintained Compatibility

• ✅ API Response Format: Identical to full version
• ✅ Authentication Flow: Same JWT implementation
• ✅ Frontend Integration: No changes required
• ✅ Core Analysis: Essential detection capabilities preserved

📈 Performance Characteristics

Resource Usage

• Memory: ~100-200MB (vs 1GB+ for full version)
• CPU: Lightweight processing
• Storage: Minimal file system usage
• Startup Time: ~10-30 seconds (vs 2-5 minutes)

Response Times

• Authentication: < 200ms
• Email Analysis: 1-3 seconds
• History Retrieval: < 100ms
• Health Check: < 50ms

Scalability

• Concurrent Users: 50-100 on Replit
• Request Volume: 100-500 requests/hour
• Analysis Capacity: Suitable for small-medium deployments

🚨 Limitations & Trade-offs

Reduced Capabilities

• Model Accuracy: 80-90% (vs 95%+ in full version)
• Security Features: Basic vs enterprise-grade
• Scalability: Limited vs highly scalable
• Model Diversity: 2 analyzers vs 10+ in full version

Appropriate Use Cases

• ✅ Development/Testing: Perfect for prototyping
• ✅ Small Teams: Up to 50 users
• ✅ Educational: Learning and demonstration
• ✅ Quick Deployment: Rapid setup requirements

Not Suitable For

• ❌ Enterprise Production: Use full version instead
• ❌ High Volume: > 1000 requests/hour
• ❌ Critical Security: Mission-critical applications
• ❌ Advanced Features: Complex workflow requirements

🔗 Related Projects

Full Version

• Repository: Email Guard Full
• Version: Dev 0.6.2
• Deployment: Docker + APISIX
• Use Case: Enterprise production environments

Frontend

• Live Demo: Email Guard Dashboard
• Technology: React + TypeScript + Vite
• Deployment: Vercel
• Integration: Works with both versions

🛠️ Troubleshooting

Common Issues

Models Not Loading:

# Check if phishing-detection-py is installed
pip list | grep phishing-detection-py

# Reinstall if missing
pip install phishing-detection-py

CORS Errors:

# Verify CORS origins in backend/app.py
allow_origins=[
    "https://email-guard-cyan.vercel.app",
    "http://localhost:5173"  # For local development
]

Authentication Failures:

# Check if JWT_SECRET_KEY is set
echo $JWT_SECRET_KEY

# Generate new secret key
python -c "import secrets; print(secrets.token_hex(32))"

Replit Deployment Issues:

1. Ensure main.py is the entry point
2. Check that requirements.txt is in root directory
3. Verify environment variables are set in Replit secrets

📚 Documentation

Code Documentation

• AI Models: /ai/README.md
• API Reference: Built-in FastAPI docs at /docs
• Authentication: See backend/modules/authenticate.py

External Resources

• FastAPI Documentation: https://fastapi.tiangolo.com/
• Phishing Detection Py: https://pypi.org/project/phishing-detection-py/
• Replit Deployment: https://docs.replit.com/

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create feature branch: git checkout -b feature/new-feature
3. Test changes locally
4. Submit pull request with description

Coding Standards

• Python: Follow PEP 8 style guidelines
• Type Hints: Add type annotations
• Error Handling: Comprehensive exception handling
• Documentation: Update README for new features

📄 License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

🆘 Support & Contact

Getting Help

• Issues: GitHub Issues
• Documentation: This README and inline code documentation
• Full Version: See original repository for advanced features

Version Information

• Current Version: Dep 0.5.6 Mini
• Full Version: Dev 0.6.2
• Compatibility: Frontend compatible with both versions
• Last Updated: 2024

---

Email Guard Lightweight - Streamlined email security analysis for rapid deployment and development environments.

For production enterprise deployments, consider the full version with advanced security features and comprehensive model pipeline.