Fsa

PhishX v2.0 is a sophisticated, full-stack cybersecurity platform engineered to neutralize phishing threats in real-time. Now powered by Next.js 15, a real-time WebSocket scanning engine, xAI heuristic analysis, Celery distributed task queues, and a GDPR/DPDP compliant legal framework — PhishX delivers enterprise-grade URL threat intelligence wrapped in a stunning, fully-responsive production-ready interface optimized for mobile and desktop.

---

✦ Core Capabilities

🧠 AI-Driven Threat Detection Custom ML model combined with a Zero-Latency Offline Top 10k Whitelist and a Dynamic Community Feedback loop. Identifies zero-day phishing attempts while organically adapting to prevent false positives — completely free of charge.	⚡ Zero-Latency Backend Built on async FastAPI — every scan, auth check, and admin call is fully non-blocking. Engineered for high-throughput workloads with sub-100ms median response times.	🌐 Browser Extension A custom Chromium extension that performs real-time URL scanning directly from your toolbar. No copy-paste — get threat verdicts on any URL in one click.
🔐 Hardened Authentication End-to-end local JWT authentication with HttpOnly cookie sessions and bcrypt password hashing. Zero dependency on third-party auth providers — your data stays sovereign.	💳 SaaS-Ready Payments Fully scaffolded subscription management and payment endpoints ready for enterprise scaling. Plug in your payment processor and go live with tiered plans immediately.	☁️ Production-Containerized Fully Dockerized with separate development and production docker-compose configurations. Automated CI/CD pipelines via GitHub Actions for zero-downtime deployments.
🎨 Immersive UI/UX A sleek, responsive dark-mode interface with a full-screen scanning panel. The URL input and scan button are precisely parallel for a frictionless, focused user experience.	🛡️ Rate Limiting & Abuse Guard Integrated API-level rate limiting prevents brute-force attacks and endpoint abuse. Alembic-managed database migrations ensure schema integrity across all environments.	🔓 Open & Auditable No hardcoded secrets. No black boxes. All credentials managed via .env files with a comprehensive .env.example. Ready for CodeQL and GitHub Advanced Security scanning.

---

✦ System Architecture

The PhishX ecosystem is built as a set of fully decoupled services, each with a distinct responsibility:

graph TD
    subgraph CLIENT["🖥️  CLIENT LAYER"]
        A["⚛️ Next.js 15\nFrontend\n(Vercel)"]
        B["🧩 Browser Extension\n(Chromium)"]
    end

    subgraph BACKEND["⚙️  BACKEND LAYER  ·  FastAPI"]
        C["🔐 Auth API\n/api/v1/auth"]
        D["🔍 Scan API\n/api/v1/scans"]
        E["👤 User API\n/api/v1/users"]
        F["💳 Payments API\n/api/v1/payments"]
        G["🛡️ Admin API\n/api/v1/admin"]
        N["📡 News API\n/api/v1/news"]
        CT["🎫 Contact API\n/api/v1/contact"]
        WS["🔌 WebSocket\n/ws/scan"]
    end

    subgraph INTELLIGENCE["🤖  ML INTELLIGENCE LAYER  ·  Python"]
        H["📊 Feature Extractor\n(Lexical Analysis)"]
        I["🧠 Phishing Classifier\n(Trained ML Model)"]
        J["📁 Dataset\nphishing_site_urls.csv"]
        W["⚡ Zero-Latency\nTop 10k & Feedback Whitelist"]
        XAI["🔬 xAI Heuristics\n(Zero-Day Detection)"]
    end

    subgraph DATA["🗄️  DATA LAYER"]
        K[("🐘 PostgreSQL\nDatabase")]
        L["📜 Alembic\nMigrations"]
    end

    A -- "HTTPS REST" --> C & D & E & F
    A -- "WebSocket" --> WS
    B -- "HTTPS REST" --> D
    D --> W --> H --> I --> J
    D --> XAI
    C & D & E & F & G & N & CT --> K
    L --> K

    style CLIENT fill:#0d1117,stroke:#00E676,color:#ffffff
    style BACKEND fill:#0d1117,stroke:#00BCD4,color:#ffffff
    style INTELLIGENCE fill:#0d1117,stroke:#7C4DFF,color:#ffffff
    style DATA fill:#0d1117,stroke:#FF6D00,color:#ffffff

Loading

---

✦ Project Structure

📂 Click to expand the full directory tree

PhishX/
│
├── 📁 backend/                          # FastAPI Application Core
│   ├── 📁 alembic/                      # Database migration scripts & env
│   ├── 📁 app/
│   │   ├── 📁 api/v1/                   # Versioned API Endpoints
│   │   │   ├── auth.py                  #   → JWT Login / Register / OAuth (Google)
│   │   │   ├── scans.py                 #   → URL Threat Scanning (real-time + history)
│   │   │   ├── users.py                 #   → User Profile & Settings
│   │   │   ├── payments.py              #   → Subscription & Billing
│   │   │   ├── admin.py                 #   → Admin Operations & Safety Locks
│   │   │   ├── contact.py               #   → In-App Support Ticketing (NEW v2)
│   │   │   ├── news.py                  #   → CyberPulse News Proxy (NEW v2)
│   │   │   └── ws.py                    #   → WebSocket Telemetry (NEW v2)
│   │   ├── 📁 core/
│   │   │   ├── config.py                #   → Pydantic Settings & Env Vars
│   │   │   ├── security.py              #   → JWT, bcrypt, HttpOnly Cookies
│   │   │   └── rate_limit.py            #   → Abuse Prevention
│   │   ├── 📁 db/
│   │   │   ├── models.py                #   → SQLAlchemy ORM Models (incl. ContactQuery)
│   │   │   ├── session.py               #   → DB Session Factory
│   │   │   └── seed.py                  #   → Database Seeder Script
│   │   ├── 📁 schemas/                  # Pydantic Request/Response Contracts
│   │   └── 📁 services/
│   │       ├── feature_extractor.py     #   → ML Lexical Feature Pipeline
│   │       ├── top_10k.py               #   → Trusted Domain Whitelist
│   │       └── xai.py                   #   → Zero-Day Heuristic Analysis (NEW v2)
│   ├── worker.py                        # Async Celery Worker (NEW v2)
│   └── Dockerfile                       # Backend Container Image
│
├── 📁 browser-extension/                # Chromium Real-Time Extension
│
├── 📁 phishx-frontend/                  # Next.js 15 Frontend (UPGRADED v2)
│   ├── 📁 src/
│   │   ├── 📁 app/                      #   → Next.js App Router
│   │   ├── 📁 components/               #   → UI Components
│   │   │   ├── AdminPanel.jsx           #   → Admin Dashboard + Diagnostics
│   │   │   ├── AuthModal.jsx            #   → Auth with Consent Checkbox (v2)
│   │   │   ├── ContactModal.jsx         #   → In-App Support Form (NEW v2)
│   │   │   ├── CookieBanner.jsx         #   → GDPR Cookie Consent (NEW v2)
│   │   │   └── ScanPanel.jsx            #   → Real-time WebSocket Scanner
│   │   └── 📁 views/                    #   → Page-level Views
│   └── 📁 public/                       #   → Static Assets & Logos
│
├── 📁 terraform/                        # Infrastructure as Code (NEW v2)
├── 📁 .github/workflows/                # CI/CD Pipelines
│   ├── ci-pipeline.yml
│   └── cd-pipeline.yml
│
├── docker-compose.yml                   # Development Environment
├── CHANGELOG_v2.md                      # v2.0.0 Full Release Notes
└── README.md

---

✦ Getting Started

Prerequisites

Requirement	Version	Purpose
Docker + Docker Compose	Latest	Full stack orchestration
Python	3.10+	Backend & ML model development
Node.js	18+	Frontend & extension development

---

🐳 Quickstart with Docker (Recommended)

The fastest way to run the complete PhishX stack locally.

# 1. Clone the repository
git clone https://github.com/Uditpandya07/PhishX.git
cd PhishX

# 2. Configure environment variables
cp .env.example .env
# → Open .env and fill in: DB credentials, JWT secret, SMTP config

# 3. Launch the full stack
docker-compose up -d --build

The API is live at http://localhost:8000
Interactive Swagger UI is available at http://localhost:8000/docs

---

🛠️ Local Development Setup (Backend without Docker)

# Navigate to the backend directory
cd backend

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate       # macOS / Linux
# venv\Scripts\activate        # Windows

# Install all dependencies
pip install -r requirements.txt

# Run database migrations
alembic upgrade head

# (Optional) Seed the database with sample data
python app/db/seed.py

# Start the development server with hot-reload
uvicorn app.main:app --reload

The API will be available at http://localhost:8000.

---

🌐 Installing the Browser Extension

1. Open your Chromium-based browser and navigate to chrome://extensions/
2. Toggle Developer mode ON in the top-right corner
3. Click Load unpacked and select the browser-extension/ folder from the repository root
4. The PhishX shield icon will appear in your toolbar — click it to scan any URL instantly

---

✦ Security Standards

PhishX is engineered with a security-first philosophy at every layer of the stack.

Standard	Implementation
🔑 No Hardcoded Secrets	All keys and passwords managed exclusively via .env files; excluded from version control via .gitignore
🍪 Secure Session Management	JWT tokens delivered via HttpOnly + Secure cookies — immune to XSS token theft
🔒 Password Security	bcrypt adaptive hashing with configurable work factors — future-proof against brute force
🚦 API Rate Limiting	Per-endpoint rate limiting middleware blocks credential stuffing and scan abuse
🗄️ Schema Integrity	All database changes managed through Alembic migration scripts — no ad-hoc mutations
🔍 Static Analysis Ready	Codebase structured for seamless integration with GitHub Advanced Security and CodeQL

---

✦ Documentation

🚀 Deployment Guide docs/DEPLOYMENT.md Step-by-step instructions for pushing PhishX to a production environment with Docker.

📖 Development Journey docs/JOURNEY.md The history, architecture decisions, and trade-offs made throughout the build.

✍️ Rule Authoring docs/RULE_AUTHORING.md Guidelines for writing custom threat detection rules for the scanning engine.

⚖️ Rule Precedence docs/RULE_PRECEDENCE.md How conflicting rules are evaluated and resolved by the detection pipeline.

---

✦ License

PhishX is released under the PolyForm Noncommercial License 1.0.0.

Permission	Details
✅ Personal use	Free to use for personal, educational, and research purposes
✅ Modification	Fork, modify, and adapt the source code
✅ Distribution	Share the software in its original or modified form
❌ Commercial use	Using PhishX or any derivative in a paid product, SaaS, or commercial service is not permitted

For commercial licensing enquiries, please open an issue or contact the maintainer directly.

---

Built with precision. Deployed for impact. Defending the web — one URL at a time.

_{© PhishX — Open Source Cybersecurity Intelligence}