MailShield AI – Email Threat Analysis and SOC Investigation Platform

MailShield AI is an industry-inspired, full-stack email forensics and Threat Detection Hub designed for Security Operations Center (SOC) teams. Built to replicate enterprise security incident workflows, this platform simulates security incident response processes to scan, investigate, and remediate email-borne corporate campaigns.

This project is configured as a robust resume submission suitable for a 3rd-year Computer Science Engineering student applying for technical support trainee roles at enterprise cybersecurity firms.

---

🚀 Core Capabilities & Highlights

1. RFC 5322 Email Parser

   • Extracts complete transport layer attributes: From, To, Subject, Date, Reply-To, Return-Path, Message-ID, and Origin Gateway IP headers.
   • Decomposes nested MIME multi-part streams to extract and isolate document attachments.

2. Deterministic Threat Logic Engine

   • Sender Mismatch Validation: Automatically correlates visible From headings with SMTP transport envelope headers and Reply-To fields to detect active domain spoofing or look-alike impersonations.
   • Hyperlink Deep Audits: Scans every URL for bulk distribution traits, high-risk top-level domain zones (.xyz, .tk), or credential-mimicking strings.
   • File Payload Sweeps: Identifies highly malicious script signatures and executables (.exe, .scr, .vbs, .zip).
   • Risk Score Metrics: Automatically ranks incident parameters into standard threat severities: Safe, Low, Medium, High, and Critical.

3. Cognitive AI Forensic Sweeps (Powered by Google Gemini 3.5 Flash)

   • Delivers in-depth, automated incident reports.
   • Translates raw text structures into high-quality technical scenario explanations.
   • MITRE ATT&CK Matrix Alignment: Maps isolated attack campaigns to official standards (e.g., Spearphishing Link T1566.002, Impersonation T1566).
   • Generates step-by-step Remediation Playbooks with interactive checklist items for local infrastructure locks.

4. Interactive Security Operations Command Center

   • Stunning slate-dark SOC theme crafted with Tailwind CSS variables.
   • Live analytical charting for incoming attack vectors and risk distributions using Recharts.
   • Unified search indexes matching sender aliases, subjects, and categorizations.
   • Ingestion wizard supporting drag-and-drop .eml logs and raw copy-paste analysis.

---

📂 System Folder Structure

The project follows a clean, single-point-bound, modular architecture:

mailshield-ai/
├── src/
│   ├── components/
│   │   ├── ThreatCharts.tsx         # Recharts data charts for vector mix & severity analysis
│   │   ├── UploadModal.tsx          # Drag-and-drop EML and copy-paste text uploader
│   │   └── InvestigationPanel.tsx   # Forensic Sandbox & AI Playbook drawer
│   ├── data/
│   │   ├── db.json                  # SQLite equivalent file-system database
│   │   └── preseeded.ts             # pre-loaded simulated EML files
│   ├── utils/
│   │   └── parser.ts                # Deterministic EML parser & Threat Detection Engine
│   ├── types.ts                     # TypeScript definitions for logs, incidents and analyses
│   ├── App.tsx                      # Primary SOC Dashboard UI orchestration
│   ├── index.css                    # Global tailwind integrations & theme variables
│   └── main.tsx                     # React root mount
├── server.ts                        # Unified Express API server & Vite production asset routing
├── package.json                     # Dependency manifests & compiled build runners
├── tsconfig.json                    # Type configurations
└── vite.config.ts                   # Bundler layout & HMR configurations

---

⚙️ Setup and Ingress Setup

Technical Prerequisite Details

The container workspace operates seamlessly on Node version 18+ and binds port 3000 under all ingress rules. All development environment dependencies are fully managed.

Installation Steps

1. Install Local Dependencies:

   npm install

2. Run in Development Mode: Loads the joint Express API endpoints and mounts the Vite React application seamlessly on port 3000:

   npm run dev

3. Production Compiling Node Build: Compiles frontend static assets to dist/ and compiles TypeScript server.ts to standard, high-speed CommonJS format for cold-start optimizations:

   npm run build

4. Launch Production Daemon:

   npm run start

---

📖 Forensics Demonstration Guideline

1. Launch the platform and enjoy the pre-seeded dataset of 5 realistic corporate alerts reflecting phishing campaigns, malware attachments, and clean corporate mail flows.
2. Under the incident table, tap Forensics on any row to open the deep-dive investigation sidebar.
3. Conduct step-by-step investigations:
   • Analyst Sandbox: View critical mismatch warnings (such as SMTP Return-Path mismatch), trace origin gate IPs, inspect clean body texts, and evaluate attachment ext scopes.
   • AI Forensic Briefing: Click ENGAGE GEMINI COGNITIVE SCAN. The platform will trace live hooks and query Gemini on the server side using your secure API keys. Check off playbook steps or read the MITRE classifications.
   • Raw Headers: View RFC 5322 transport parameters in the green command line block.
4. Test new payloads: Tap INGEST MAIL in the top right. Paste an email header or drag a .eml file, or simply click Crawl Sample Payloads to instantly populate fields with high-threat simulations.
5. Restore the testing grounds: Tap RESET LAB to restore everything to its clean default seed stage.

---

📡 Real-Time WebSockets Stream & Gmail Active Sync (Upgraded)

The platform now supports a state-of-the-art Gmail Active Sync Pipeline paired with real-time updates using WebSockets (Socket.IO):

1. WebSockets Stream Engine (Socket.IO)

• Allows the Operations Command Center to reflect incoming threat analytics instantly without page refreshes.
• Backend pushes critical threat warnings to the React layer, triggering smooth UI entries powered by Framer Motion.
• Live popup notifications appear dynamically for High and Critical severity threats, displaying threat categories, severity levels, and logs.
• Automatic connection monitoring, graceful reconnection handshakes, and event duplication guards are fully integrated.

2. Gmail Mailbox Monitoring Sync (GCP OAuth 2.0)

• Integrates directly with the official Google Gmail API and node-cron to scan unread messages automatically.
• Cron poller triggers every 30 seconds to scan, decode, and analyze email payloads via the deterministic threat detection parser and Google Gemini AI models.
• Automatically marks scanned messages as read in your corporate Google inbox to avoid duplicate processing cycles.
• MIME multi-part decoding safely separates and flags malicious scripts (.exe, .zip, .scr) and isolates suspicious web links.

3. Security Simulation Sandbox

• If Google Cloud Console credentials are not yet configured, click SIMULATE MAIL in the top operations bar to trigger real-time, randomized phishing simulations.
• Each simulation injects a fresh credential theft, Sharepoint spoofing, or payroll fraud attack directly into the backend.
• Instantly, the WebSocket broadcasts events, updates charts, prepends table logs, and fires Framer Motion push notifications.

---

🔒 Google Cloud Console OAuth 2.0 Integration Setup

To connect a live Google Gmail inbox to MailShield AI:

1. Create a project on the Google Cloud Console.
2. Enable the Gmail API under APIs & Services.
3. Configure the OAuth Consent Screen (User Type: External/Internal, Scopes: https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/userinfo.email).
4. Generate an OAuth 2.0 Client ID as a Web Application.
5. Register the following Authorized Redirect URIs:

   http://localhost:3000/api/auth/google/callback
   

6. Add the credentials to your environment variables in .env (refer to .env.example):

   GOOGLE_CLIENT_ID="your-client-id-here"
   GOOGLE_CLIENT_SECRET="your-client-secret-here"
   GOOGLE_REDIRECT_URI="http://localhost:3000/api/auth/google/callback"

7. Start the application (npm run dev) and click CONNECT GMAIL on the operations bar to complete authentication!

---

🛡️ Enterprise Security Design & Integrity

• Server-Side API Key Hiding: The process.env.GEMINI_API_KEY and Google client secrets are maintained strictly within the server-side Express runtime. They are never transmitted or compiled into client bundle files, ensuring high posture security.
• Fail-Safe Robustness: If the API key is not yet configured or lacks internet routing permissions, the server implements graceful fallbacks to allow simulation sessions to load safe metadata and remain functional during assessments.