Update README.md

README.md

@@ -1,262 +1,262 @@
----
-title: SentinelScan WSS
-emoji: 🛡️
-colorFrom: indigo
-colorTo: red
-sdk: docker
-pinned: true
----
-# 🛡️ SentinelScan — Website Security Scanner (WSS)
-
-SentinelScan is a full-stack, enterprise-grade **Dynamic Application Security Testing (DAST)** platform designed to automate vulnerability detection across target domains and web APIs. Featuring a highly modular architecture, SentinelScan orchestrates a pipeline of custom security scanning agents concurrently, storing findings in a structured database and presenting them in a premium, real-time dashboard.
-
----
-
-## 🚀 Key Features
-
-* **Multi-Agent Concurrency**: Uses an asynchronous thread pool execution model (`ThreadPoolExecutor`) inside Celery tasks to run up to 17 specialized scanner modules in parallel.
-* **Real-time Log Streaming**: Captures and exposes live, color-coded execution logs in-memory, enabling users to monitor active scans line-by-line.
-* **Scheduled Scans**: Leverage Celery Beat to automate recurring scans (daily, weekly, monthly) for regular status monitoring.
-* **Alert Webhooks**: Automatically dispatches security alerts to external services (e.g., Discord, custom webhooks) when critical or high vulnerabilities are discovered.
-* **Authenticated Scanning**: Supports credentials/cookies injection via custom HTTP request headers, bypassing login perimeters to test deep backend routes.
-* **Interactive Remediation**: Offers interactive, language-specific code remediation templates for each identified vulnerability type.
-* **Dynamic PDF Reports**: Generates professional PDF summaries of completed scans, containing detailed risk score matrices and remediation guidelines.
-
----
-
-## 📁 Directory Structure
-
-```text
-Project-WSS/
-├── backend/                        # Flask Backend Application
-│   ├── app/                        # Main Flask Application Package
-│   │   ├── routes/                 # REST API Endpoints & Route Blueprints
-│   │   │   ├── auth.py             # User Authentication (Login, Register)
-│   │   │   ├── reports.py          # PDF Generation and Scan Reports
-│   │   │   ├── scans.py            # Scan Configuration, Triggering, Logs
-│   │   │   └── vulnerabilities.py  # Remediation & Vulnerability Queries
-│   │   ├── scanners/               # Security Engine Modules & Core Pipelines
-│   │   │   ├── __init__.py         # Pipeline Definitions and Class Dispatcher
-│   │   │   ├── api_scanner.py      # Exposed REST API Route Finder
-│   │   │   ├── base_scanner.py     # Abstract Base Class and Shared Log Utilities
-│   │   │   ├── cloud_scanner.py    # Public S3/Cloud Storage Auditor
-│   │   │   ├── cors_scanner.py     # CORS Misconfigurations Tester
-│   │   │   ├── cve_scanner.py      # Vulnerability Database Version Matcher
-│   │   │   ├── directory_scanner.py# Directory/File brute-forcer
-│   │   │   ├── fuzzer_scanner.py   # SQLi & XSS Parameter Fuzzer
-│   │   │   ├── headers_scanner.py  # HTTP Security Headers & Cache Poisoning
-│   │   │   ├── nmap_scanner.py     # Port & Service Banner Scanner (via Nmap)
-│   │   │   ├── nuclei_scanner.py   # Nuclei Template-based Scanner
-│   │   │   ├── robots_scanner.py   # robots.txt Crawler
-│   │   │   ├── secrets_scanner.py  # Page Secrets/API Key Scanner
-│   │   │   ├── sslyze_scanner.py   # SSL/TLS Configurations & Ciphers Auditor
-│   │   │   ├── subdomain_scanner.py# Subdomain DNS Enumerator
-│   │   │   ├── tech_scanner.py     # Technology Stack Fingerprinting
-│   │   │   ├── waf_scanner.py      # WAF Detection & Fingerprinting
-│   │   │   ├── whois_scanner.py    # Domain Registrar and Whois Lookup
-│   │   │   └── zap_scanner.py      # OWASP ZAP Active Spider Integration
-│   │   ├── utils/                  # Utility Scripts & Helpers
-│   │   │   ├── pdf_generator.py    # ReportLab PDF Generation
-│   │   │   └── webhook.py          # Discord & Webhook Dispatcher
-│   │   ├── database.py             # SQLAlchemy Extension Instance
-│   │   ├── extensions.py           # Rate Limiter & Security Extensions
-│   │   ├── models.py               # SQLAlchemy Database Models (SQLite/PostgreSQL)
-│   │   └── scanner.py              # Celery Tasks, Beat Schedules & Orchestration
-│   ├── celery_app.py               # Celery Broker and Beat Scheduler Configuration
-│   ├── config.py                   # Environment Variable Parsing and App Constants
-│   ├── requirements.txt            # Python Dependencies List
-│   ├── run.py                      # Flask Application Startup Launcher
-│   └── .env                        # Local Environment Secret Key Configurations
-│
-├── frontend/                       # React Frontend Application (Vite-powered SPA)
-│   ├── src/                        # React Application Source
-│   │   ├── assets/                 # SVGs, Fonts, and Static UI Elements
-│   │   ├── components/             # Reusable UI Components
-│   │   │   ├── AuthContext.jsx     # Global JWT Login State & API Interceptor
-│   │   │   ├── CodeBlock.jsx       # Syntax-highlighted Remediation Viewer
-│   │   │   ├── Layout.jsx          # Dashboard App Shell & Navigation Sidebar
-│   │   │   ├── ProtectedRoute.jsx  # Auth Check Router Wrapper
-│   │   │   └── ThreatGauge.jsx     # SVG Semi-circle Security Score Indicator
-│   │   ├── pages/                  # Top-level Routing View Pages
-│   │   │   ├── Dashboard.jsx       # Overview, Scan Metrics, and Status Cards
-│   │   │   ├── LandingPage.jsx     # Modern Dark Mode Promotional Marketing Page
-│   │   │   ├── Login.jsx           # Clean Secure Authentication Portal
-│   │   │   ├── NewScan.jsx         # Target, Pipeline and Cookie Configurations
-│   │   │   ├── Register.jsx        # Account Creation Portal
-│   │   │   ├── ReportsHistory.jsx  # Past Scan Lists and Export Center
-│   │   │   ├── ScanResults.jsx     # Vulnerability breakdown & Live terminal logs
-│   │   │   └── Settings.jsx        # Notification threshold & webhook configuration
-│   │   ├── App.css                 # Main Layout styling
-│   │   ├── App.jsx                 # Routing configuration
-│   │   ├── index.css               # Global theme tokens, inputs, animations
-│   │   ├── main.jsx                # DOM Injection root
-│   │   ├── mockApi.js              # Standalone local frontend mock testing DB
-│   │   └── theme.css               # Precision Sentinel palette values
-│   ├── vite.config.js              # React Hot Module Reloading server options
-│   └── package.json                # Frontend NPM scripts & dependencies
-│
-└── docker-compose.yml              # Multi-container orchestrator (Redis service)
-```
-
----
-
-## 🏛️ System Architecture
-
-```mermaid
-graph TD
-    User([Security Auditor]) -->|Browser| FE[React Frontend SPA]
-    FE -->|API Requests| BE[Flask Web Backend]
-    BE -->|Store Scans/Vulns| DB[(SQLite / PostgreSQL)]
-    BE -->|Enqueue Jobs| Redis[(Redis Broker)]
-    Celery[Celery Task Workers] -->|Dequeue Jobs| Redis
-    Celery -->|Write Live Logs| MemLog[(In-Memory Logs)]
-    Celery -->|Execute Scanners Concurrently| Scanners{Scanner Suite}
-    Scanners -->|Target Requests| Target[Target System]
-    Scanners -->|Persist Findings| DB
-    Celery -->|Trigger Alert| Webhook[Webhook Notification]
-```
-
-### Backend Components
-1. **Flask (REST API)**: Exposes endpoints for managing accounts, starting scans, listing results, downloading PDFs, and tracking setting updates.
-2. **Celery Worker**: Dequeues scan tasks and runs them asynchronously. 
-3. **ThreadPoolExecutor**: Multi-threads individual scanners inside a Celery task.
-4. **Celery Beat**: Runs continuously to process scheduled periodic scans.
-5. **Redis**: Acts as the fast in-memory message broker.
-
----
-
-## 🗄️ Database Schema
-
-The database schema, defined in `backend/app/models.py`, includes five main tables:
-
-1. **`User`**: Manages credential hashing (via `bcrypt`) and session links.
-2. **`Scan`**: Details the target domain, scan mode (Quick, Standard, Deep), authorization headers, overall security score, scan status, and timings.
-3. **`Vulnerability`**: Stores findings linked to a scan. Contains details like CVSS score, severity classification, category, description, and copy-pasteable remediation snippets.
-4. **`ScheduledScan`**: Saves user-configured scanning intervals (daily, weekly, monthly) for targets.
-5. **`AlertSettings`**: Manages notification flags, webhook URL destinations, and minimum severity thresholds.
-
----
-
-## ⚙️ Scan Pipelines
-
-Pipeline routes are configured in `backend/app/scanners/__init__.py`. Depending on the target criticality and scan duration limits, auditors choose between:
-
-| Pipeline | Target Speed | Underlying Scanner Suite | Description |
-| :--- | :--- | :--- | :--- |
-| **`Quick`** | ~30 seconds | Headers, Nmap (top 100 ports), SSLyze, Tech stack, WHOIS, WAF | Surface audit for standard misconfigurations |
-| **`Standard`** | ~2–3 minutes | Quick + SQLi/XSS Fuzzer, Subdomains, API pathways, Cloud, Secrets, CVEs | Comprehensive assessment of application business logic |
-| **`Deep`** | ~10–15 minutes| Standard + CORS, robots.txt, Directory brute-force, Nuclei, ZAP (active) | Deep crawling and automated vulnerability exploitation |
-| **`SSL`** | ~15 seconds | SSLyze, Headers | SSL certificate validation and cipher security audit |
-| **`Port`** | ~45 seconds | Nmap (standard 1000 ports) | Port and network service banner reconnaissance |
-
----
-
-## 🛠️ The Scanner Suite (17 Specialized Modules)
-
-Each scanner inherits from `BaseScanner` (`backend/app/scanners/base_scanner.py`) which coordinates logging, domain parsing, and vulnerability formatting:
-
-1. **Headers Scanner (`headers_scanner.py`)**: Checks HTTP security headers (HSTS, CSP, CORS, X-Frame-Options, permissions, Referrer policy) and runs a custom check for HTTP host parameter cache poisoning.
-2. **Nmap Scanner (`nmap_scanner.py`)**: Fires `nmap` commands directly via sub-process, checking exposed network services and testing for vulnerabilities using script scanning banners.
-3. **SSLyze Scanner (`sslyze_scanner.py`)**: Audits SSL certificates, verifying trust status, expiration, and highlighting weak legacy protocols (TLS 1.0, SSLv3).
-4. **Tech Scanner (`tech_scanner.py`)**: Fingerprints backend technologies, libraries, servers, and frameworks.
-5. **Whois Scanner (`whois_scanner.py`)**: Looks up registrar information, IP ownership, and registration details.
-6. **WAF Scanner (`waf_scanner.py`)**: Detects the presence of firewalls (Cloudflare, AWS WAF, ModSecurity, etc.) by inspecting response indicators.
-7. **CORS Scanner (`cors_scanner.py`)**: Audits cross-origin resource sharing declarations to prevent credential leaks.
-8. **Robots Scanner (`robots_scanner.py`)**: Parses target `robots.txt` entries to extract hidden directories or disallowed routes.
-9. **Directory Scanner (`directory_scanner.py`)**: Brute-forces directories using wordlists to discover hidden panels (`/admin`, `/phpmyadmin`, `/api/v1`).
-10. **Fuzzer Scanner (`fuzzer_scanner.py`)**: Performs automated query parameter fuzzing, validating parameters against Cross-Site Scripting (XSS) and SQL Injection (SQLi) patterns.
-11. **API Scanner (`api_scanner.py`)**: Maps routing interfaces, documenting open APIs and JSON payloads.
-12. **Cloud Scanner (`cloud_scanner.py`)**: Audits exposed public storage assets (AWS S3 Buckets, Azure Blobs, etc.).
-13. **Secrets Scanner (`secrets_scanner.py`)**: Scrapes source HTML code for exposed keys, AWS access IDs, and connection credentials.
-14. **CVE Scanner (`cve_scanner.py`)**: Cross-references identified technology versions against public vulnerability registries.
-15. **Nuclei Scanner (`nuclei_scanner.py`)**: Performs targeted scans using ProjectDiscovery's template engine.
-16. **ZAP Scanner (`zap_scanner.py`)**: Coordinates deep active spider scanning via the OWASP ZAP API integration.
-17. **CORS/API Helper Scanners**: Secondary scanners focused on validation and authorization testing.
-
----
-
-## 🚀 Setup & Local Execution
-
-### Prerequisites
-* **Python 3.10+**
-* **Node.js v18+**
-* **Nmap** (must be added to system `PATH` environment variables)
-* **Redis** (running locally on port `6379`)
-
----
-
-### Step 1: Start Redis
-You can run Redis using Docker:
-```bash
-docker-compose up -d
-```
-
----
-
-### Step 2: Configure and Start Backend
-
-1. Navigate to the backend directory:
-   ```bash
-   cd backend
-   ```
-2. Create a virtual environment and activate it:
-   ```bash
-   python -m venv venv
-   # On Windows:
-   venv\Scripts\activate
-   # On Unix/macOS:
-   source venv/bin/activate
-   ```
-3. Install dependencies:
-   ```bash
-   pip install -r requirements.txt
-   ```
-4. Verify your `.env` configuration. Ensure the keys and configurations are correct.
-5. Seed the database and start the API server:
-   ```bash
-   python run.py
-   ```
-   *The Flask application will start on `http://127.0.0.1:5000`.*
-
----
-
-### Step 3: Launch Celery Workers & Beat
-Keep your backend running, open two new terminal sessions (with the virtual environment activated), and run:
-
-1. **Celery Task Worker**:
-   ```bash
-   celery -A celery_app.celery worker --loglevel=info
-   ```
-2. **Celery Beat Scheduler**:
-   ```bash
-   celery -A celery_app.celery beat --loglevel=info
-   ```
-
----
-
-### Step 4: Configure and Run Frontend
-
-1. Navigate to the frontend directory:
-   ```bash
-   cd ../frontend
-   ```
-2. Install npm modules:
-   ```bash
-   npm install
-   ```
-3. Start the Vite development server:
-   ```bash
-   npm run dev
-   ```
-   *The frontend application will boot on `http://localhost:5173`.*
-
----
-
-## 🧪 Seeding and Testing
-
-On the first initialization, the database is pre-seeded with a default user and dummy mock security scan data so you can preview the platform immediately:
-
-* **Mock Account Email**: `admin@gmail.com`
-* **Mock Account Password**: `admin123`
-
-You can log in with these credentials, explore the interactive remediation code windows, trigger new scans, check your live-updating terminal dashboard logs, and download auto-generated PDF reports directly from the history view.
+---
+title: SentinelScan WSS
+emoji: 🛡️
+colorFrom: indigo
+colorTo: red
+sdk: docker
+pinned: true
+---
+# 🛡️ SentinelScan — Website Security Scanner (WSS) by larxius
+
+SentinelScan is a full-stack, enterprise-grade **Dynamic Application Security Testing (DAST)** platform designed to automate vulnerability detection across target domains and web APIs. Featuring a highly modular architecture, SentinelScan orchestrates a pipeline of custom security scanning agents concurrently, storing findings in a structured database and presenting them in a premium, real-time dashboard.
+
+---
+
+## 🚀 Key Features
+
+* **Multi-Agent Concurrency**: Uses an asynchronous thread pool execution model (`ThreadPoolExecutor`) inside Celery tasks to run up to 17 specialized scanner modules in parallel.
+* **Real-time Log Streaming**: Captures and exposes live, color-coded execution logs in-memory, enabling users to monitor active scans line-by-line.
+* **Scheduled Scans**: Leverage Celery Beat to automate recurring scans (daily, weekly, monthly) for regular status monitoring.
+* **Alert Webhooks**: Automatically dispatches security alerts to external services (e.g., Discord, custom webhooks) when critical or high vulnerabilities are discovered.
+* **Authenticated Scanning**: Supports credentials/cookies injection via custom HTTP request headers, bypassing login perimeters to test deep backend routes.
+* **Interactive Remediation**: Offers interactive, language-specific code remediation templates for each identified vulnerability type.
+* **Dynamic PDF Reports**: Generates professional PDF summaries of completed scans, containing detailed risk score matrices and remediation guidelines.
+
+---
+
+## 📁 Directory Structure
+
+```text
+Project-WSS/
+├── backend/                        # Flask Backend Application
+│   ├── app/                        # Main Flask Application Package
+│   │   ├── routes/                 # REST API Endpoints & Route Blueprints
+│   │   │   ├── auth.py             # User Authentication (Login, Register)
+│   │   │   ├── reports.py          # PDF Generation and Scan Reports
+│   │   │   ├── scans.py            # Scan Configuration, Triggering, Logs
+│   │   │   └── vulnerabilities.py  # Remediation & Vulnerability Queries
+│   │   ├── scanners/               # Security Engine Modules & Core Pipelines
+│   │   │   ├── __init__.py         # Pipeline Definitions and Class Dispatcher
+│   │   │   ├── api_scanner.py      # Exposed REST API Route Finder
+│   │   │   ├── base_scanner.py     # Abstract Base Class and Shared Log Utilities
+│   │   │   ├── cloud_scanner.py    # Public S3/Cloud Storage Auditor
+│   │   │   ├── cors_scanner.py     # CORS Misconfigurations Tester
+│   │   │   ├── cve_scanner.py      # Vulnerability Database Version Matcher
+│   │   │   ├── directory_scanner.py# Directory/File brute-forcer
+│   │   │   ├── fuzzer_scanner.py   # SQLi & XSS Parameter Fuzzer
+│   │   │   ├── headers_scanner.py  # HTTP Security Headers & Cache Poisoning
+│   │   │   ├── nmap_scanner.py     # Port & Service Banner Scanner (via Nmap)
+│   │   │   ├── nuclei_scanner.py   # Nuclei Template-based Scanner
+│   │   │   ├── robots_scanner.py   # robots.txt Crawler
+│   │   │   ├── secrets_scanner.py  # Page Secrets/API Key Scanner
+│   │   │   ├── sslyze_scanner.py   # SSL/TLS Configurations & Ciphers Auditor
+│   │   │   ├── subdomain_scanner.py# Subdomain DNS Enumerator
+│   │   │   ├── tech_scanner.py     # Technology Stack Fingerprinting
+│   │   │   ├── waf_scanner.py      # WAF Detection & Fingerprinting
+│   │   │   ├── whois_scanner.py    # Domain Registrar and Whois Lookup
+│   │   │   └── zap_scanner.py      # OWASP ZAP Active Spider Integration
+│   │   ├── utils/                  # Utility Scripts & Helpers
+│   │   │   ├── pdf_generator.py    # ReportLab PDF Generation
+│   │   │   └── webhook.py          # Discord & Webhook Dispatcher
+│   │   ├── database.py             # SQLAlchemy Extension Instance
+│   │   ├── extensions.py           # Rate Limiter & Security Extensions
+│   │   ├── models.py               # SQLAlchemy Database Models (SQLite/PostgreSQL)
+│   │   └── scanner.py              # Celery Tasks, Beat Schedules & Orchestration
+│   ├── celery_app.py               # Celery Broker and Beat Scheduler Configuration
+│   ├── config.py                   # Environment Variable Parsing and App Constants
+│   ├── requirements.txt            # Python Dependencies List
+│   ├── run.py                      # Flask Application Startup Launcher
+│   └── .env                        # Local Environment Secret Key Configurations
+│
+├── frontend/                       # React Frontend Application (Vite-powered SPA)
+│   ├── src/                        # React Application Source
+│   │   ├─�� assets/                 # SVGs, Fonts, and Static UI Elements
+│   │   ├── components/             # Reusable UI Components
+│   │   │   ├── AuthContext.jsx     # Global JWT Login State & API Interceptor
+│   │   │   ├── CodeBlock.jsx       # Syntax-highlighted Remediation Viewer
+│   │   │   ├── Layout.jsx          # Dashboard App Shell & Navigation Sidebar
+│   │   │   ├── ProtectedRoute.jsx  # Auth Check Router Wrapper
+│   │   │   └── ThreatGauge.jsx     # SVG Semi-circle Security Score Indicator
+│   │   ├── pages/                  # Top-level Routing View Pages
+│   │   │   ├── Dashboard.jsx       # Overview, Scan Metrics, and Status Cards
+│   │   │   ├── LandingPage.jsx     # Modern Dark Mode Promotional Marketing Page
+│   │   │   ├── Login.jsx           # Clean Secure Authentication Portal
+│   │   │   ├── NewScan.jsx         # Target, Pipeline and Cookie Configurations
+│   │   │   ├── Register.jsx        # Account Creation Portal
+│   │   │   ├── ReportsHistory.jsx  # Past Scan Lists and Export Center
+│   │   │   ├── ScanResults.jsx     # Vulnerability breakdown & Live terminal logs
+│   │   │   └── Settings.jsx        # Notification threshold & webhook configuration
+│   │   ├── App.css                 # Main Layout styling
+│   │   ├── App.jsx                 # Routing configuration
+│   │   ├── index.css               # Global theme tokens, inputs, animations
+│   │   ├── main.jsx                # DOM Injection root
+│   │   ├── mockApi.js              # Standalone local frontend mock testing DB
+│   │   └── theme.css               # Precision Sentinel palette values
+│   ├── vite.config.js              # React Hot Module Reloading server options
+│   └── package.json                # Frontend NPM scripts & dependencies
+│
+└── docker-compose.yml              # Multi-container orchestrator (Redis service)
+```
+
+---
+
+## 🏛️ System Architecture
+
+```mermaid
+graph TD
+    User([Security Auditor]) -->|Browser| FE[React Frontend SPA]
+    FE -->|API Requests| BE[Flask Web Backend]
+    BE -->|Store Scans/Vulns| DB[(SQLite / PostgreSQL)]
+    BE -->|Enqueue Jobs| Redis[(Redis Broker)]
+    Celery[Celery Task Workers] -->|Dequeue Jobs| Redis
+    Celery -->|Write Live Logs| MemLog[(In-Memory Logs)]
+    Celery -->|Execute Scanners Concurrently| Scanners{Scanner Suite}
+    Scanners -->|Target Requests| Target[Target System]
+    Scanners -->|Persist Findings| DB
+    Celery -->|Trigger Alert| Webhook[Webhook Notification]
+```
+
+### Backend Components
+1. **Flask (REST API)**: Exposes endpoints for managing accounts, starting scans, listing results, downloading PDFs, and tracking setting updates.
+2. **Celery Worker**: Dequeues scan tasks and runs them asynchronously. 
+3. **ThreadPoolExecutor**: Multi-threads individual scanners inside a Celery task.
+4. **Celery Beat**: Runs continuously to process scheduled periodic scans.
+5. **Redis**: Acts as the fast in-memory message broker.
+
+---
+
+## 🗄️ Database Schema
+
+The database schema, defined in `backend/app/models.py`, includes five main tables:
+
+1. **`User`**: Manages credential hashing (via `bcrypt`) and session links.
+2. **`Scan`**: Details the target domain, scan mode (Quick, Standard, Deep), authorization headers, overall security score, scan status, and timings.
+3. **`Vulnerability`**: Stores findings linked to a scan. Contains details like CVSS score, severity classification, category, description, and copy-pasteable remediation snippets.
+4. **`ScheduledScan`**: Saves user-configured scanning intervals (daily, weekly, monthly) for targets.
+5. **`AlertSettings`**: Manages notification flags, webhook URL destinations, and minimum severity thresholds.
+
+---
+
+## ⚙️ Scan Pipelines
+
+Pipeline routes are configured in `backend/app/scanners/__init__.py`. Depending on the target criticality and scan duration limits, auditors choose between:
+
+| Pipeline | Target Speed | Underlying Scanner Suite | Description |
+| :--- | :--- | :--- | :--- |
+| **`Quick`** | ~30 seconds | Headers, Nmap (top 100 ports), SSLyze, Tech stack, WHOIS, WAF | Surface audit for standard misconfigurations |
+| **`Standard`** | ~2–3 minutes | Quick + SQLi/XSS Fuzzer, Subdomains, API pathways, Cloud, Secrets, CVEs | Comprehensive assessment of application business logic |
+| **`Deep`** | ~10–15 minutes| Standard + CORS, robots.txt, Directory brute-force, Nuclei, ZAP (active) | Deep crawling and automated vulnerability exploitation |
+| **`SSL`** | ~15 seconds | SSLyze, Headers | SSL certificate validation and cipher security audit |
+| **`Port`** | ~45 seconds | Nmap (standard 1000 ports) | Port and network service banner reconnaissance |
+
+---
+
+## 🛠️ The Scanner Suite (17 Specialized Modules)
+
+Each scanner inherits from `BaseScanner` (`backend/app/scanners/base_scanner.py`) which coordinates logging, domain parsing, and vulnerability formatting:
+
+1. **Headers Scanner (`headers_scanner.py`)**: Checks HTTP security headers (HSTS, CSP, CORS, X-Frame-Options, permissions, Referrer policy) and runs a custom check for HTTP host parameter cache poisoning.
+2. **Nmap Scanner (`nmap_scanner.py`)**: Fires `nmap` commands directly via sub-process, checking exposed network services and testing for vulnerabilities using script scanning banners.
+3. **SSLyze Scanner (`sslyze_scanner.py`)**: Audits SSL certificates, verifying trust status, expiration, and highlighting weak legacy protocols (TLS 1.0, SSLv3).
+4. **Tech Scanner (`tech_scanner.py`)**: Fingerprints backend technologies, libraries, servers, and frameworks.
+5. **Whois Scanner (`whois_scanner.py`)**: Looks up registrar information, IP ownership, and registration details.
+6. **WAF Scanner (`waf_scanner.py`)**: Detects the presence of firewalls (Cloudflare, AWS WAF, ModSecurity, etc.) by inspecting response indicators.
+7. **CORS Scanner (`cors_scanner.py`)**: Audits cross-origin resource sharing declarations to prevent credential leaks.
+8. **Robots Scanner (`robots_scanner.py`)**: Parses target `robots.txt` entries to extract hidden directories or disallowed routes.
+9. **Directory Scanner (`directory_scanner.py`)**: Brute-forces directories using wordlists to discover hidden panels (`/admin`, `/phpmyadmin`, `/api/v1`).
+10. **Fuzzer Scanner (`fuzzer_scanner.py`)**: Performs automated query parameter fuzzing, validating parameters against Cross-Site Scripting (XSS) and SQL Injection (SQLi) patterns.
+11. **API Scanner (`api_scanner.py`)**: Maps routing interfaces, documenting open APIs and JSON payloads.
+12. **Cloud Scanner (`cloud_scanner.py`)**: Audits exposed public storage assets (AWS S3 Buckets, Azure Blobs, etc.).
+13. **Secrets Scanner (`secrets_scanner.py`)**: Scrapes source HTML code for exposed keys, AWS access IDs, and connection credentials.
+14. **CVE Scanner (`cve_scanner.py`)**: Cross-references identified technology versions against public vulnerability registries.
+15. **Nuclei Scanner (`nuclei_scanner.py`)**: Performs targeted scans using ProjectDiscovery's template engine.
+16. **ZAP Scanner (`zap_scanner.py`)**: Coordinates deep active spider scanning via the OWASP ZAP API integration.
+17. **CORS/API Helper Scanners**: Secondary scanners focused on validation and authorization testing.
+
+---
+
+## 🚀 Setup & Local Execution
+
+### Prerequisites
+* **Python 3.10+**
+* **Node.js v18+**
+* **Nmap** (must be added to system `PATH` environment variables)
+* **Redis** (running locally on port `6379`)
+
+---
+
+### Step 1: Start Redis
+You can run Redis using Docker:
+```bash
+docker-compose up -d
+```
+
+---
+
+### Step 2: Configure and Start Backend
+
+1. Navigate to the backend directory:
+   ```bash
+   cd backend
+   ```
+2. Create a virtual environment and activate it:
+   ```bash
+   python -m venv venv
+   # On Windows:
+   venv\Scripts\activate
+   # On Unix/macOS:
+   source venv/bin/activate
+   ```
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+4. Verify your `.env` configuration. Ensure the keys and configurations are correct.
+5. Seed the database and start the API server:
+   ```bash
+   python run.py
+   ```
+   *The Flask application will start on `http://127.0.0.1:5000`.*
+
+---
+
+### Step 3: Launch Celery Workers & Beat
+Keep your backend running, open two new terminal sessions (with the virtual environment activated), and run:
+
+1. **Celery Task Worker**:
+   ```bash
+   celery -A celery_app.celery worker --loglevel=info
+   ```
+2. **Celery Beat Scheduler**:
+   ```bash
+   celery -A celery_app.celery beat --loglevel=info
+   ```
+
+---
+
+### Step 4: Configure and Run Frontend
+
+1. Navigate to the frontend directory:
+   ```bash
+   cd ../frontend
+   ```
+2. Install npm modules:
+   ```bash
+   npm install
+   ```
+3. Start the Vite development server:
+   ```bash
+   npm run dev
+   ```
+   *The frontend application will boot on `http://localhost:5173`.*
+
+---
+
+## 🧪 Seeding and Testing
+
+On the first initialization, the database is pre-seeded with a default user and dummy mock security scan data so you can preview the platform immediately:
+
+* **Mock Account Email**: `admin@gmail.com`
+* **Mock Account Password**: `admin123`
+
+You can log in with these credentials, explore the interactive remediation code windows, trigger new scans, check your live-updating terminal dashboard logs, and download auto-generated PDF reports directly from the history view.