Skip to content

cysec-don/DonScan

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
.zscripts
.zscripts
 
 
db
db
 
 
download
download
 
 
examples/websocket
examples/websocket
 
 
mini-services
mini-services
 
 
prisma
prisma
 
 
public
public
 
 
skills
skills
 
 
src
src
 
 
.env
.env
 
 
.gitignore
.gitignore
 
 
Caddyfile
Caddyfile
 
 
README.md
README.md
 
 
bun.lock
bun.lock
 
 
components.json
components.json
 
 
cpanel_advisory.json
cpanel_advisory.json
 
 
cpanel_blog.json
cpanel_blog.json
 
 
cve_search1.json
cve_search1.json
 
 
cve_search2.json
cve_search2.json
 
 
eslint.config.mjs
eslint.config.mjs
 
 
hadrian_cve.json
hadrian_cve.json
 
 
horizon3_cve.json
horizon3_cve.json
 
 
next.config.ts
next.config.ts
 
 
nvd_cve.json
nvd_cve.json
 
 
package.json
package.json
 
 
postcss.config.mjs
postcss.config.mjs
 
 
rapid7_cve.json
rapid7_cve.json
 
 
tsconfig.json
tsconfig.json
 
 
watchtowr_cve.json
watchtowr_cve.json
 
 
worklog.md
worklog.md
 
 

Repository files navigation

DonScan Version Python FastAPI Next.js License

DonScan

Intelligent Vulnerability Discovery Platform

Built by Cysec Don

DonScan is an enterprise-grade, full-stack vulnerability scanning platform that combines network discovery, service fingerprinting, CVE intelligence enrichment, TLS analysis, and professional reporting into a single unified system. Designed for security professionals, penetration testers, and SOC teams who need comprehensive visibility into their attack surface.

Table of Contents

Features

Network Discovery & Scanning

  • Async Port Scanning — High-performance asynchronous TCP connect scanner supporting all 65,535 ports with configurable concurrency, timeouts, and rate limiting
  • Host Discovery — ICMP ping, ARP discovery, and CIDR range parsing for efficient network sweeping
  • Service Fingerprinting — Banner grabbing for 10+ protocols (SSH, FTP, HTTP, SMTP, POP3, IMAP, MySQL, Redis, cPanel, and more) with automatic version extraction
  • HTTP Fingerprinting — Server header analysis, technology detection, and framework identification from HTTP responses

CVE Intelligence Engine

  • NVD Integration — Real-time querying of the National Vulnerability Database (NVD) API v2.0 for CVE data with API key support for higher rate limits
  • CPE Matching — Automatic mapping of discovered services to Common Platform Enumeration (CPE) strings for accurate vulnerability correlation
  • Known Critical CVE Database — Built-in detection for high-profile vulnerabilities including CVE-2026-41940 (cPanel auth bypass), CVE-2024-3094 (XZ Backdoor), CVE-2024-27198 (TeamCity auth bypass)
  • Redis-Cached Enrichment — All CVE lookups are cached in Redis with configurable TTL to minimize API calls and accelerate repeated scans

TLS/SSL Analysis

  • Certificate Analysis — Full certificate chain inspection with expiry monitoring (30-day warning), self-signed detection, weak key size identification (less than 2048-bit), and deprecated algorithm flagging (SHA-1, MD5)
  • Cipher Suite Evaluation — Grading of cipher strength, identification of weak ciphers, and TLS version enforcement checks
  • Protocol Analysis — Detection of deprecated protocols (SSLv3, TLS 1.0, TLS 1.1) and validation of TLS 1.2/1.3 support

Web Application Detection

  • CMS Detection — WordPress, Joomla, Drupal, and other content management system fingerprinting
  • Technology Identification — Frontend frameworks, backend servers, JavaScript libraries, and analytics platforms
  • Security Header Audit — Evaluation of 8 critical security headers (CSP, HSTS, X-Frame-Options, etc.)
  • Cookie Analysis — Secure flag, HttpOnly flag, SameSite attribute, and session cookie risk assessment

Professional Reporting

  • Multi-Format Export — Generate reports in PDF, HTML, JSON, CSV, and Markdown formats
  • Branded Templates — Professional HTML reports with DonScan branding, severity breakdowns, and actionable recommendations
  • Custom Report Names — Assign meaningful names to reports for organized tracking
  • Direct Download — API endpoints for downloading generated report files with proper MIME types

Web Dashboard

  • Real-Time Dashboard — At-a-glance view of total scans, discovered assets, vulnerability counts, and exploit availability
  • Severity Distribution Charts — Visual breakdown of vulnerability severity levels with percentage calculations
  • Scan Launch Form — One-click scan creation supporting Quick, Full, Web, Stealth, and CVE-focused scan types
  • Recent Scans Table — Live scan tracking with progress bars, status badges, and type indicators
  • Responsive Sidebar Navigation — Full navigation for Dashboard, Scans, Vulnerabilities, Assets, Reports, and Settings

Security & Authentication

  • JWT Authentication — Secure access and refresh token flow with bcrypt password hashing (12 rounds)
  • Role-Based Access Control — Three-tier role system (admin, analyst, viewer) with endpoint-level authorization
  • API Rate Limiting — Atomic Redis-based sliding window rate limiter protecting all API endpoints
  • Security Headers Middleware — Automatic injection of CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Permissions-Policy headers
  • Audit Logging — Comprehensive request logging with timestamps, method, path, status code, duration, and client IP

Architecture

DonScan follows a modular, service-oriented architecture designed for extensibility and horizontal scaling:

┌──────────────┐     ┌──────────────────┐     ┌───────────────┐
│   Frontend   │────▶│   NGINX Proxy    │────▶│   Backend     │
│  (Next.js)   │     │   (Port 80)      │     │   (FastAPI)   │
└──────────────┘     └──────────────────┘     └───────┬───────┘
                                                       │
                              ┌─────────────────────────┼────────────────────────┐
                              │                         │                        │
                     ┌────────▼────────┐      ┌────────▼────────┐     ┌────────▼────────┐
                     │   PostgreSQL    │      │     Redis       │     │  Scan Worker    │
                     │   (Port 5432)   │      │   (Port 6379)   │     │  (Async Tasks)  │
                     └─────────────────┘      └─────────────────┘     └────────┬────────┘
                                                                               │
                                                      ┌────────────────────────┼────────────────────────┐
                                                      │                        │                        │
                                             ┌────────▼────────┐    ┌────────▼────────┐    ┌────────▼────────┐
                                             │  Network Engine │    │   CVE Engine    │    │  TLS Analyzer   │
                                             │  (Port Scan +   │    │  (NVD + CPE +   │    │  (Cert + Cipher │
                                             │   Fingerprint)  │    │   Cache)        │    │   + Protocol)   │
                                             └─────────────────┘    └─────────────────┘    └─────────────────┘

Key Design Principles:

  • Async-First — The entire backend is built on Python asyncio for non-blocking I/O during network operations, database queries, and HTTP requests
  • Engine Separation — Each scanning engine (network, CVE, TLS, web) is a self-contained module with its own internal API, making them independently testable and extensible
  • Plugin Architecture — The BasePlugin abstract class and PluginRegistry enable third-party extensions without modifying core code
  • Background Execution — Scans run as FastAPI BackgroundTasks, keeping API responses snappy while heavy scanning happens asynchronously with Redis-tracked progress

Technology Stack

Layer Technology Version Purpose
Backend Python 3.12+ Core runtime
Web Framework FastAPI 0.110+ Async REST API
Database PostgreSQL 16 Persistent storage
ORM SQLAlchemy 2.0+ Async database models
Migrations Alembic 1.13+ Schema versioning
Cache Redis 7+ Caching, rate limiting, scan state
Authentication python-jose + passlib 3.3+ / 1.7+ JWT + bcrypt
Validation Pydantic 2.5+ Schema validation with email support
Scanning python-nmap 0.7+ Nmap wrapper for port scanning
TLS cryptography + pyOpenSSL 42+ / 24+ Certificate and cipher analysis
Reporting ReportLab + WeasyPrint + Jinja2 4.1+ / 61+ / 3.1+ PDF/HTML/Markdown/CSV/JSON reports
HTTP Client aiohttp + httpx 3.9+ / 0.26+ Async NVD API queries
Frontend Next.js 16 React dashboard
UI Components shadcn/ui + Radix Latest Accessible component library
Styling Tailwind CSS 4 Utility-first CSS
Charts Recharts 2.15+ Data visualization
Reverse Proxy NGINX Alpine Production routing
Containerization Docker + Docker Compose Latest Containerized deployment

Project Structure

donscan/
├── backend/                          # Python FastAPI backend
│   ├── alembic/                      # Database migration scripts
│   │   └── env.py                    # Alembic configuration
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py                   # FastAPI application entry point
│   │   ├── config.py                 # Centralized settings (pydantic-settings)
│   │   ├── api/v1/                   # REST API endpoints
│   │   │   ├── router.py             # Aggregated API router
│   │   │   ├── auth.py               # Registration, login, token refresh
│   │   │   ├── scans.py              # Scan CRUD + background execution
│   │   │   ├── vulns.py              # Vulnerability search, stats, triage
│   │   │   ├── assets.py             # Discovered asset management
│   │   │   ├── reports.py            # Report generation and download
│   │   │   └── system.py             # Health check, banner, stats
│   │   ├── core/                     # Infrastructure layer
│   │   │   ├── database.py           # Async SQLAlchemy engine + sessions
│   │   │   ├── security.py           # JWT, password hashing, RBAC
│   │   │   ├── redis.py              # Cache, rate limiting, scan state
│   │   │   ├── middleware.py         # Audit logging + security headers
│   │   │   └── exceptions.py         # Custom exception hierarchy
│   │   ├── engine/                   # Network scanning engine
│   │   │   ├── network.py            # Async TCP port scanner
│   │   │   ├── port_scanner.py       # Port scan logic
│   │   │   ├── host_discovery.py     # Host discovery (ICMP/ARP)
│   │   │   └── cidr_parser.py        # CIDR range parsing
│   │   ├── cve_engine/               # CVE intelligence engine
│   │   │   ├── nvd_client.py         # NVD API v2.0 client
│   │   │   ├── cpe_matcher.py        # CPE string matching
│   │   │   ├── enricher.py           # Vulnerability enrichment pipeline
│   │   │   └── vuln_cache.py         # In-memory vulnerability cache
│   │   ├── fingerprinting/           # Service identification
│   │   │   ├── banner.py             # Protocol banner grabbing
│   │   │   ├── http_fp.py            # HTTP server fingerprinting
│   │   │   ├── ssl_fp.py             # SSL/TLS certificate fingerprinting
│   │   │   └── service_db.py         # Known service signature database
│   │   ├── web_detection/            # Web application analysis
│   │   │   ├── cms_detect.py         # CMS identification
│   │   │   ├── tech_detect.py        # Technology stack detection
│   │   │   ├── header_analyzer.py    # Security header audit
│   │   │   └── cookie_analyzer.py    # Cookie security analysis
│   │   ├── tls_analysis/             # TLS/SSL security analysis
│   │   │   ├── cert_analyzer.py      # Certificate chain analysis
│   │   │   ├── cipher_analyzer.py    # Cipher suite evaluation
│   │   │   └── protocol_analyzer.py  # TLS protocol version checks
│   │   ├── models/                   # SQLAlchemy ORM models
│   │   │   ├── user.py               # User accounts + RBAC
│   │   │   ├── scan.py               # Scan records + lifecycle
│   │   │   ├── vulnerability.py      # Vulnerability data + severity
│   │   │   ├── asset.py              # Discovered hosts + services
│   │   │   └── report.py             # Generated report metadata
│   │   ├── schemas/                  # Pydantic request/response schemas
│   │   │   ├── auth.py               # Login, register, token schemas
│   │   │   ├── scan.py               # Scan creation + result schemas
│   │   │   ├── vulnerability.py      # Vulnerability search + triage
│   │   │   ├── asset.py              # Asset response schemas
│   │   │   ├── report.py             # Report generation schemas
│   │   │   └── common.py             # Shared types + pagination
│   │   ├── services/                 # Business logic layer
│   │   │   ├── scan_service.py       # Scan orchestration
│   │   │   ├── vuln_service.py       # Vulnerability management
│   │   │   ├── asset_service.py      # Asset tracking
│   │   │   └── report_service.py     # Report generation
│   │   ├── reporting/                # Report generators
│   │   │   ├── pdf_generator.py      # PDF report (ReportLab)
│   │   │   ├── html_generator.py     # HTML report (Jinja2)
│   │   │   ├── json_generator.py     # JSON report export
│   │   │   └── csv_generator.py      # CSV report export
│   │   ├── workers/                  # Background task workers
│   │   │   └── scan_worker.py        # Async scan execution manager
│   │   └── plugins/                  # Plugin system
│   │       ├── base_plugin.py        # Abstract plugin + registry
│   │       └── __init__.py
│   ├── tests/                        # Test suite
│   │   ├── conftest.py               # Pytest fixtures
│   │   ├── test_api/                 # API endpoint tests
│   │   └── test_engine/             # Engine unit tests
│   ├── Dockerfile                    # Backend container
│   ├── requirements.txt              # Python dependencies
│   ├── pyproject.toml                # Project metadata + tool config
│   ├── alembic.ini                   # Migration configuration
│   ├── Makefile                      # Development commands
│   └── .env.example                  # Environment template
├── docker/
│   └── nginx.conf                    # NGINX reverse proxy config
├── docker-compose.yml                # Full stack orchestration
├── frontend/                         # Next.js frontend (port 3000)
├── src/                              # Next.js application source
│   ├── app/
│   │   ├── page.tsx                  # DonScan dashboard
│   │   ├── layout.tsx                # Root layout
│   │   └── globals.css               # Tailwind v4 + theme
│   ├── components/ui/                # shadcn/ui components (47)
│   ├── lib/                          # Utilities
│   └── hooks/                        # React hooks
├── download/
│   └── cve_2026_41940_scanner.py     # Standalone CVE-2026-41940 scanner
├── .gitignore
└── README.md

Prerequisites

Requirement Minimum Version Notes
Python 3.12+ Required for backend
Node.js 18+ Required for frontend
PostgreSQL 16+ Primary database
Redis 7+ Caching and rate limiting
Docker 20+ Containerized deployment
Docker Compose 2.0+ Multi-container orchestration
Nmap 7.94+ Network scanning (install on host or in container)

Installation

Quick Start with Docker

The fastest way to get DonScan running is with Docker Compose, which orchestrates all services (PostgreSQL, Redis, backend API, frontend, and NGINX) in isolated containers:

# Clone the repository
git clone https://github.com/cysec-don/DonScan.git
cd DonScan

# Copy environment template and customize
cp download/donscan/backend/.env.example download/donscan/backend/.env

# IMPORTANT: Generate a secure secret key for production
# Replace the default value in .env with:
SECRET_KEY=$(openssl rand -hex 32)
# Then update the SECRET_KEY in download/donscan/backend/.env

# Optional: Add your NVD API key for faster CVE lookups
# Get a free key at: https://nvd.nist.gov/developers/request-an-api-key
# Set NVD_API_KEY=your-key-here in the .env file

# Build and start all services
cd download/donscan
docker compose build
docker compose up -d

# Verify all services are running
docker compose ps

After startup, the services are available at:

Service URL Description
Dashboard http://localhost Next.js frontend via NGINX
API http://localhost/api/v1 Backend REST API via NGINX
API Docs http://localhost/api/docs Interactive Swagger UI
ReDoc http://localhost/api/redoc Alternative API documentation

To stop all services:

docker compose down

# To also remove persistent data volumes:
docker compose down -v

Manual Installation (Backend)

For development or environments where Docker is not available:

# 1. Install system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y python3.12 python3.12-venv python3-pip \
    postgresql-16 redis-server nmap \
    libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0 libffi-dev

# 2. Clone the repository
git clone https://github.com/cysec-don/DonScan.git
cd DonScan/download/donscan/backend

# 3. Create and activate a virtual environment
python3.12 -m venv venv
source venv/bin/activate

# 4. Install Python dependencies
pip install -r requirements.txt
pip install -e .

# 5. Set up PostgreSQL database
sudo -u postgres createdb donscan
sudo -u postgres createuser donscan -P
# Enter password: donscan_secure_pass
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE donscan TO donscan;"

# 6. Configure environment
cp .env.example .env
# Edit .env with your database URL, secret key, etc.

# 7. Run database migrations
alembic upgrade head

# 8. Start the backend server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Manual Installation (Frontend)

# From the project root directory
cd DonScan

# Install Node.js dependencies
npm install
# or with Bun:
# bun install

# Start the development server
npm run dev
# or:
# bun run dev

The frontend will be available at http://localhost:3000.

Configuration

All configuration is managed through environment variables, loaded from a .env file. Copy .env.example and customize:

cp .env.example .env

Core Settings

Variable Default Description
APP_NAME DonScan Application display name
APP_VERSION 1.0.0 Current version
APP_CREATOR Cysec Don Creator attribution
APP_CONTACT cysecdon@gmail.com Contact email
DEBUG false Enable debug mode (verbose logging)
LOG_LEVEL INFO Logging verbosity (DEBUG, INFO, WARNING, ERROR)

Database Settings

Variable Default Description
DATABASE_URL postgresql+asyncpg://donscan:donscan_secure_pass@localhost:5432/donscan PostgreSQL connection string
DATABASE_POOL_SIZE 10 Connection pool size
DATABASE_MAX_OVERFLOW 20 Max overflow connections beyond pool size
DATABASE_POOL_RECYCLE 3600 Recycle connections after N seconds

Authentication Settings

Variable Default Description
SECRET_KEY (change in production) JWT signing key — must be changed in production
ALGORITHM HS256 JWT signing algorithm
ACCESS_TOKEN_EXPIRE_MINUTES 60 Access token lifetime
REFRESH_TOKEN_EXPIRE_DAYS 7 Refresh token lifetime
PASSWORD_BCRYPT_ROUNDS 12 bcrypt hashing rounds (higher = more secure, slower)

Scanning Settings

Variable Default Description
SCAN_TIMEOUT 300 Overall scan timeout (seconds)
SCAN_CONNECT_TIMEOUT 10 TCP connect timeout (seconds)
SCAN_PORT_TIMEOUT 5 Individual port timeout (seconds)
MAX_CONCURRENT_SCANS 10 Maximum simultaneous scans

CVE Intelligence Settings

Variable Default Description
NVD_API_KEY (empty) NVD API key for higher rate limits
NVD_API_URL https://services.nvd.nist.gov/rest/json/cves/2.0 NVD CVE endpoint
NVD_CPE_URL https://services.nvd.nist.gov/rest/json/cpes/2.0 NVD CPE endpoint
NVD_RATE_LIMIT_DELAY 0.6 Delay between NVD requests (seconds)
CVE_CACHE_TTL 86400 CVE cache time-to-live (seconds, 24h default)

Usage

Starting the Platform

Docker (recommended):

cd download/donscan
docker compose up -d

Manual (backend only):

cd download/donscan/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Manual (frontend only):

npm run dev

On startup, you will see the DonScan ASCII banner in the backend logs confirming successful initialization of the database and Redis connections.

API Reference

DonScan exposes a comprehensive REST API at /api/v1/. Interactive documentation is available at:

Endpoint Group Prefix Description
Authentication /api/v1/auth Register, login, token refresh, profile
Scans /api/v1/scans Create, list, monitor, stop, delete scans
Vulnerabilities /api/v1/vulnerabilities Search, filter, triage, stats
Assets /api/v1/assets List and inspect discovered hosts
Reports /api/v1/reports Generate, list, download reports
System /api/v1/system Health check, banner, version, stats

Creating Scans

Via the Web Dashboard:

  1. Open http://localhost in your browser
  2. In the "Launch New Scan" panel, enter your target (IP, domain, CIDR, or URL)
  3. Select a scan type:
    • Quick — Scans the top 1000 most common ports
    • Full — Scans all 65,535 TCP ports
    • Web — Focuses on web application vulnerabilities
    • Stealth — Lower rate, harder to detect
    • CVE — Prioritizes CVE intelligence enrichment
  4. Click "Start Scan"

Via the API:

# First, register and get a token
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "email": "admin@example.com", "password": "SecurePass123!"}'

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "SecurePass123!"}'

# Save the access_token from the response, then create a scan:
curl -X POST http://localhost:8000/api/v1/scans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.0/24", "scan_type": "quick"}'

# Check scan status
curl http://localhost:8000/api/v1/scans/{scan_id}/status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get full scan results
curl http://localhost:8000/api/v1/scans/{scan_id}/results \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Managing Vulnerabilities

# List all vulnerabilities with pagination
curl "http://localhost:8000/api/v1/vulnerabilities?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by severity
curl "http://localhost:8000/api/v1/vulnerabilities?severity=critical" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Search across CVE IDs, titles, descriptions, and products
curl "http://localhost:8000/api/v1/vulnerabilities/search?q=cpanel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get vulnerability statistics
curl http://localhost:8000/api/v1/vulnerabilities/stats \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Triage: Mark as false positive
curl -X PUT http://localhost:8000/api/v1/vulnerabilities/{vuln_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_false_positive": true}'

# Triage: Add remediation notes
curl -X PUT http://localhost:8000/api/v1/vulnerabilities/{vuln_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"remediation": "Upgraded OpenSSH to 9.8p1 per vendor advisory"}'

Generating Reports

# Generate an HTML report for a completed scan
curl -X POST http://localhost:8000/api/v1/reports \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scan_id": "YOUR_SCAN_ID", "name": "Q1 Network Audit", "format": "html", "report_type": "executive"}'

# Supported formats: json, csv, html, pdf, md

# List all reports
curl http://localhost:8000/api/v1/reports \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Download a generated report file
curl -O http://localhost:8000/api/v1/reports/{report_id}/download \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Standalone CVE Scanner

DonScan includes a standalone scanner for CVE-2026-41940 (cPanel & WHM Authentication Bypass, CVSS 9.8 CRITICAL) that can be run independently without the full platform:

# Single target scan
python3 download/cve_2026_41940_scanner.py -t 192.168.1.100

# Multiple targets
python3 download/cve_2026_41940_scanner.py -t 192.168.1.100 -t 10.0.0.5 -t cpanel.example.com

# CIDR range
python3 download/cve_2026_41940_scanner.py -t 192.168.1.0/24

# Custom ports and verbose output
python3 download/cve_2026_41940_scanner.py -t target.com -p 2082 2083 2086 2087 -v

# Export results to JSON
python3 download/cve_2026_41940_scanner.py -t target.com -o results.json

# Install required dependency
pip install requests colorama

The scanner performs three detection layers:

  1. Version-Based Detection — Compares the detected cPanel version against the six known patched releases (11.110.0.97, 11.118.0.63, 11.126.0.54, 11.132.0.29, 11.134.0.20, 11.136.0.5)
  2. CRLF Injection Probe — Non-exploitative behavioral testing of the session handling surface by injecting CRLF sequences and analyzing server responses for reflection or anomalous behavior
  3. Security Header Audit — Evaluates the presence of critical security headers (CSP, HSTS, X-Frame-Options, etc.)

Scanning Engines

Network Engine

The AsyncNetworkEngine is the core scanning workhorse. It operates in a pipeline:

  1. Target Resolution — Parses IPs, hostnames, CIDR ranges, and IP ranges into individual host lists
  2. Host Discovery — Probes each host with ICMP ping and TCP SYN to port 80 to determine liveness
  3. Port Scanning — For each alive host, performs async TCP connect scans against the specified port range with configurable concurrency (semaphore-based)
  4. Service Fingerprinting — Grabs banners from common protocol ports (SSH, FTP, HTTP, SMTP, MySQL, Redis, etc.)
  5. CVE Enrichment — Matches discovered services against the known CVE database and queries NVD for additional vulnerabilities
  6. Result Aggregation — Compiles all findings into a structured result object with per-host breakdowns

The engine supports progress callbacks for real-time tracking via Redis, allowing the web dashboard to display live progress bars during active scans.

CVE Intelligence Engine

The CVE engine enriches raw scan data with actionable vulnerability intelligence:

  • Service-to-CPE Mapping — 16 pre-mapped service types with vendor/product CPE identifiers
  • Known Critical CVEs — Built-in database of actively exploited vulnerabilities with severity, CVSS, CWE, exploit/patch availability, and remediation guidance
  • NVD API Integration — Real-time queries to the NVD v2.0 API for CVEs matching discovered products and versions
  • Intelligent Caching — All NVD responses cached in Redis with 24-hour TTL, dramatically reducing API calls for repeated scans of similar infrastructure
  • Deduplication — Vulnerabilities are deduplicated by CVE ID + asset IP + port to prevent duplicate entries from overlapping scan results

TLS Analysis Engine

The TLS analyzer provides deep inspection of SSL/TLS configurations:

  • Certificate Chain — Parses X.509 certificates using the cryptography library for reliable extraction of subject, issuer, SAN, validity dates, signature algorithm, and key parameters
  • Expiry Monitoring — Flags expired certificates and those expiring within 30 days
  • Key Strength Assessment — Identifies RSA keys below 2048 bits and ECDSA keys below 256 bits as weak
  • Algorithm Deprecation — Detects SHA-1 and MD5 signature algorithms as deprecated
  • Self-Signed Detection — Flags certificates where issuer equals subject

Security Model

DonScan is designed with a defense-in-depth security model appropriate for a security scanning platform:

Authentication Layer

  • JWT Access Tokens — Short-lived (configurable, default 60 minutes) tokens signed with HS256
  • JWT Refresh Tokens — Long-lived (default 7 days) tokens for seamless re-authentication
  • Bcrypt Password Hashing — 12-round bcrypt with automatic salt generation
  • First-User-Admin — The first registered user automatically receives the admin role

Authorization Layer

  • Role-Based Access Control — Three roles: admin (full access), analyst (scan + triage), viewer (read-only)
  • Endpoint Protection — Admin-only endpoints use the require_role("admin") dependency
  • Self-Service Profile — Users can update their own email and name, but not their role or active status

Infrastructure Layer

  • Rate Limiting — Atomic Redis-based sliding window rate limiter on all API endpoints
  • Security Headers — CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy
  • CORS Enforcement — Configurable origin whitelist (default: localhost only)
  • Audit Logging — Every API request logged with method, path, status, duration, and client IP
  • SQL Injection Prevention — SQLAlchemy ORM with parameterized queries throughout; LIKE wildcards are escaped
  • XSS Prevention — HTML report output is escaped with html.escape(); CSP blocks inline scripts

Development

Running Tests

cd download/donscan/backend

# Activate virtual environment
source venv/bin/activate

# Run all tests
make test

# Run with coverage report
make test-cov

# Run specific test file
pytest tests/test_api/test_auth.py -v

# Run with verbose output
pytest tests/ -v --tb=long

Code Quality

# Lint with ruff
make lint

# Auto-format code
make format

# Type check with mypy
mypy app/

Database Migrations

# Create a new migration after model changes
make migrate-create msg="add_vulnerability_epss_field"

# Apply pending migrations
make migrate

# Rollback the last migration
make migrate-rollback

Makefile Commands

Command Description
make install Install Python dependencies
make run Start production server (4 workers)
make dev Start development server (auto-reload)
make test Run test suite
make test-cov Run tests with coverage report
make lint Run ruff linter + mypy type checker
make format Auto-format code with ruff
make migrate Apply database migrations
make migrate-create Create a new migration (requires msg=)
make migrate-rollback Rollback last migration
make docker-build Build Docker images
make docker-up Start Docker containers
make docker-down Stop Docker containers
make clean Remove build artifacts
make info Display project info

Deployment

Production Checklist

Before deploying DonScan in production, ensure the following:

  • SECRET_KEY — Generate a unique, cryptographically secure key: openssl rand -hex 32
  • Database password — Change the default donscan_secure_pass to a strong, unique password
  • CORS origins — Restrict to your actual domain names
  • DEBUG=false — Ensure debug mode is disabled
  • NVD_API_KEY — Register for a free NVD API key to avoid public rate limits (5 requests/30s without key, 50 requests/30s with key)
  • HTTPS — Configure TLS certificates (Let's Encrypt recommended) for the NGINX proxy
  • Backups — Set up PostgreSQL backup strategy (pg_dump cron job)
  • Monitoring — Configure log aggregation and alerting for the health check endpoint

Scaling Considerations

  • Horizontal Scaling — Run multiple backend instances behind a load balancer; ensure ScanWorker.active_scans state is externalized to Redis for cross-process visibility
  • Database — Increase DATABASE_POOL_SIZE and DATABASE_MAX_OVERFLOW for high-concurrency deployments; consider read replicas for dashboard queries
  • Redis — Use Redis Cluster for high-availability caching; increase maxmemory for large-scale deployments
  • Network Scanning — Distribute scan workers across multiple nodes for parallel scanning of large networks

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature-name
  3. Write tests for your changes
  4. Ensure all tests pass: make test
  5. Run the linter: make lint
  6. Commit with a descriptive message
  7. Push to your fork and open a Pull Request

For major changes, please open an issue first to discuss the proposed changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Credits

DonScan is designed and developed by:

Cysec Don
cysecdon@gmail.com
github.com/cysec-don

Creator credit appears in:

  • Terminal ASCII banner on application startup
  • Web dashboard sidebar and footer
  • HTTP response headers (in debug mode)
  • Generated report headers and footers
  • API response metadata
  • Login screen attribution

DonScan — Intelligent Vulnerability Discovery Platform
Built with purpose by Cysec Don

About

DonScan — Intelligent Vulnerability Discovery Platform | Built by Cysec Don

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages