AI-powered email security analysis to protect you from phishing threats.

SeamSecure is a full-stack web application that analyzes email threads for potential security risks, combining rule-based heuristics with Google Gemini AI to detect phishing attempts, suspicious sender patterns, and other email-based threats.

• Dual Analysis Modes

  • Paste Email: Analyze any email thread by pasting its content
  • Gmail Integration: Connect your Gmail account and analyze emails directly from your inbox

• Hybrid Threat Detection

  • Rule-Based Analysis: Detects urgency language, sensitive data requests, suspicious links, and sender anomalies
  • AI-Powered Analysis: Google Gemini integration for intent drift detection, style anomalies, sentiment shifts, and contextual risk assessment

• Risk Assessment

  • Risk scoring (0-100%) with severity weighting
  • Three-tier risk levels: Safe, Suspicious, Dangerous
  • Detailed indicators with human-readable explanations

• Google OAuth Integration

  • Secure Gmail authentication
  • Read-only access to email content
  • Session management with secure token handling

SeamSecure/
├── backend/
│   ├── app/
│   │   ├── core/
│   │   │   ├── config.py        # Settings & environment variables
│   │   │   └── security.py      # Security utilities
│   │   ├── models/
│   │   │   └── thread.py        # Pydantic models
│   │   ├── routers/
│   │   │   ├── auth_router.py   # Google OAuth endpoints
│   │   │   ├── gmail_router.py  # Gmail API endpoints
│   │   │   └── thread_router.py # Thread analysis endpoints
│   │   ├── services/
│   │   │   ├── analysis_service.py  # Core analysis logic
│   │   │   ├── gemini_service.py    # Gemini AI integration
│   │   │   ├── gmail_service.py     # Gmail API service
│   │   │   └── scoring.py           # Risk scoring algorithms
│   │   └── main.py              # FastAPI application entry
│   ├── requirements.txt
│   └── API_CONTRACT.md          # Detailed API documentation
├── frontend/
│   ├── src/
│   │   ├── api/
│   │   │   ├── gmail.ts         # Gmail API client
│   │   │   └── seamsecure.ts    # Analysis API client
│   │   ├── components/
│   │   │   ├── GmailThreadList.tsx  # Gmail thread list
│   │   │   ├── IndicatorList.tsx    # Risk indicators display
│   │   │   └── RiskBadge.tsx        # Risk level badge
│   │   ├── types/
│   │   │   └── api.ts           # TypeScript interfaces
│   │   ├── utils/
│   │   │   └── emailParser.ts   # Email parsing utilities
│   │   ├── App.tsx              # Main application
│   │   ├── main.tsx             # Entry point
│   │   └── index.css            # Global styles
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
├── .env                         # Environment variables (gitignored)
└── README.md

• Python 3.12+
• Node.js 18+ and npm
• Google Cloud Project (for Gmail OAuth and Gemini API)

git clone https://github.com/yourusername/SeamSecure.git
cd SeamSecure

cd backend

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

cd frontend

# Install dependencies
npm install

Create a .env file in the project root (or backend/ directory):

# Environment
ENVIRONMENT=development

# Gemini AI (optional - enables AI-powered analysis)
GEMINI_API_KEY=your_gemini_api_key
ENABLE_GEMINI=true

# Google OAuth (optional - enables Gmail integration)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
OAUTH_REDIRECT_URI=http://127.0.0.1:8000/auth/google/callback

Gemini API Key:

1. Go to Google AI Studio
2. Create an API key
3. Add it to your .env file

Google OAuth Credentials:

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the Gmail API
4. Configure OAuth consent screen
5. Create OAuth 2.0 credentials (Web application)
6. Add authorized redirect URI: http://127.0.0.1:8000/auth/google/callback
7. Add client ID and secret to your .env file

cd backend
source venv/bin/activate
uvicorn app.main:app --reload

The API will be available at: http://127.0.0.1:8000

cd frontend
npm run dev

The frontend will be available at: http://localhost:5173

Once the backend is running:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

For detailed API specifications, see backend/API_CONTRACT.md.

Rule-Based (always available):

AI-Powered (when Gemini is enabled):

cd backend
pytest

Frontend:

cd frontend
npm run build

Backend: Configure production environment variables and run with:

uvicorn app.main:app --host 0.0.0.0 --port 8000

• Email content is analyzed in real-time and not stored on the server
• Gmail OAuth uses read-only scopes
• Sessions are managed securely with proper token handling
• All API communications use CORS protection
• Sensitive credentials are stored in environment variables (never committed)

• Browser extension for real-time phishing detection
• Support for Outlook and Microsoft 365 accounts
• Organization-wide email threat monitoring
• Machine learning model fine-tuning based on user feedback
• Exportable security reports and threat summaries

This project is for educational and demonstration purposes.

• Google Gemini AI for AI-powered threat analysis
• FastAPI for the excellent web framework
• React and Vite for the modern frontend tooling
• Tailwind CSS for utility-first styling