Trinetra AI - Seeing Beyond Deception 👁️

Trinetra AI is an advanced, multi-layered cybersecurity platform designed to detect, analyze, and neutralize sophisticated email phishing attacks, malicious URLs, and weaponized attachments. Built with a modern, high-performance tech stack, it provides real-time threat intelligence through four distinct "Eyes" of analysis.

---

🚀 Key Features & Functionality

1. The Four Eyes of Threat Intelligence

• Eye I (Content Intelligence): Uses natural language processing and Gemini AI to scan email body text for urgency tactics, credential harvesting attempts, financial fraud indicators, and social engineering manipulation.
• Eye II (URL Intelligence): Extracts and analyzes links for typosquatting, suspicious TLDs, IP-based domains, and high-entropy strings. Integrates with VirusTotal for real-time global threat reputation.
• Eye III (Sender Intelligence): Parses email headers to verify sender identity, checking SPF, DKIM, and DMARC authentication status to detect brand impersonation and spoofing.
• Eye IV (Attachment Intelligence): Multimodal attachment scanning (PDF, CSV, MP4). Uses Gemini AI to detect irrelevant or malicious files, with a robust offline heuristic fallback engine (using PyPDF2) that locally scans document text for macro injections, hidden links, and context mismatch (e.g., rejecting unexpected resumes).

2. Live Dashboard & Analytics

Provides a bird's-eye view of your organization's threat landscape. Tracks daily/monthly attack trends, categorizes threats (e.g., Business Email Compromise vs. Credential Harvesting), and identifies the top spoofed brands targeting your network.

3. Report Generation & History

Every analysis is permanently logged in MongoDB. Users can browse their scan history, search past threats, export aggregate data to CSV, or generate professional PDF Threat Reports for individual email scans.

4. AI Security Assistant (Chatbot)

An integrated cybersecurity assistant powered by Gemini. Users can ask questions about email security standards, phishing indicators, or ask for explanations regarding specific threat scores.

---

🛠️ Tech Stack

Frontend (Client Interface)

• Framework: React 18 + TypeScript + Vite
• Styling & Animation: Vanilla CSS (Cyberpunk aesthetic), Framer Motion, TailwindCSS
• State Management: Zustand
• Authentication: Firebase Auth

Backend (API & Analysis Engine)

• Framework: FastAPI (Python 3.10+)
• Server: Uvicorn (ASGI)
• Database: MongoDB (Motor Async Driver)
• AI / ML Integration: Google Generative AI (Gemini 2.0 Flash), LangChain
• Security Integrations: VirusTotal API
• File Processing: PyPDF2 (Offline document parsing), python-multipart
• Report Generation: ReportLab

---

🧠 System Architecture

The architecture follows a decoupled client-server model. The frontend acts as a modern SPA communicating with a high-concurrency asynchronous FastAPI backend.

graph TD
    %% User and Frontend
    U([User / Security Analyst]) -->|Submits Email/Files| F[React Frontend SPA]
    F -->|Firebase Auth Token| FA[Firebase Authentication]
    
    %% API Gateway
    F -->|REST / JSON / FormData| API[FastAPI Backend]
    API -->|Validates Token| FA
    
    %% Analysis Engine
    subgraph Trinetra Decision Engine
        API --> Engine[Core Analysis Engine]
        Engine --> E1[Eye I: Content NLP]
        Engine --> E2[Eye II: URL Extraction]
        Engine --> E3[Eye III: Header Auth]
        Engine --> E4[Eye IV: Attachment Scanner]
    end
    
    %% External Integrations
    E1 -.->|AI Summary| GEM[Google Gemini API]
    E4 -.->|Multimodal Analysis| GEM
    E4 -->|Fallback: Local Parsing| PYPDF[PyPDF2 Offline Engine]
    E2 -.->|URL Reputation| VT[VirusTotal API]
    
    %% Storage
    Engine -->|Saves Threat Report| DB[(MongoDB)]
    
    %% Output
    API -->|Returns Threat Score & Mitre Tactics| F
    API -->|Generates Report| PDF[PDF Generator]

Loading

---

⚙️ How It Works (The Analysis Flow)

1. Input Submission: The user pastes an email (Subject, Sender, Body, Headers) and optionally uploads attachments via the React frontend.
2. Payload Routing: The frontend constructs a multipart/form-data payload and sends it to the FastAPI /analyze/email endpoint.
3. Parallel Execution: FastAPI leverages asyncio.gather to run the Four Eyes concurrently:
   • Eye 1 searches for regex patterns of manipulation and requests an AI summary.
   • Eye 2 extracts URLs and pings VirusTotal.
   • Eye 3 analyzes the domain against known safe brands and checks SPF/DKIM/DMARC headers.
   • Eye 4 attempts to send attachments to Gemini; if it fails or the API key is invalid, it seamlessly falls back to the local PyPDF2 heuristic engine to extract text and evaluate relevance.
4. Scoring & Decision: The engine calculates a weighted final threat score (0-100). If the score exceeds 50, it maps the attack to MITRE ATT&CK framework techniques (e.g., T1566.001 - Spearphishing Attachment).
5. Persistence & Response: The complete report is assigned a UUID, saved to MongoDB, and returned to the frontend where Framer Motion animations reveal the threat breakdown to the user.

---

🚀 Running Locally

Prerequisites

• Node.js (v18+)
• Python (3.10+)
• Firebase Project setup

Quick Start

You can launch the entire stack using the provided batch script on Windows:

./start-trinetra.bat

This script will automatically:

1. Create and activate a Python virtual environment.
2. Install all backend dependencies from requirements.txt.
3. Start the FastAPI backend on http://localhost:8000.
4. Start the Vite React frontend on http://localhost:5173.

Note: Ensure you have copied backend/.env.example to backend/.env and populated it with your API keys (Gemini, VirusTotal) before running.