README.md

---
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.