Architecture Overview¶

This page describes the high-level system architecture, layers, and design of WebSecScan.

System Layers¶

WebSecScan separates concerns into distinct layers:

graph TB
    Client["🖥️ Client Layer<br/>React UI + Browser"]
    API["⚡ API Layer<br/>REST Routes + Server Actions + SSE"]
    Scanning["🔍 Security Scanning<br/>Static + Dynamic + Library Scanners"]
    Data["💾 Data & Utilities<br/>Database + Logging + Scoring"]

    Client --> API
    API --> Scanning
    Scanning --> Data
    Data -.-> API

    style Client fill:#e1f5ff
    style API fill:#fff3cd
    style Scanning fill:#f8d7da
    style Data fill:#d4edda

Client Layer¶

React-based web UI running in the browser:

• Scan configuration form
• Real-time progress display (via SSE)
• Results visualization and reporting
• Scan history and management

API Layer¶

Next.js Route Handlers and Server Actions:

• POST /api/scan/start — Initiate new scan
• GET /api/scan/{id} — Fetch scan status and results
• GET /api/scan/{id}/logs — Stream live logs via SSE
• Server Actions for database queries

Scanning Layer¶

Security scanning engines (isolated, composable modules):

• Static Analyzer — Code pattern matching
• Dynamic Tester — Runtime HTTP-based testing
• Library Scanner — Dependency vulnerability detection

Each agent: - Executes independently - Produces structured findings - Enforces safety constraints - Logs detailed debug info

Data Layer¶

Persistence and utilities:

• Prisma ORM — Database abstraction
• Logging — Real-time and persistent logs
• Scoring — Vulnerability severity calculation
• Utilities — URL normalization, OWASP rules

Request Flow¶

When you initiate a scan:

graph LR
    UI[User Submits Form]
    API["POST /api/scan/start<br/>(1. Validate URL)"]
    Queue["(2. Enqueue Job)"]
    Static["Static Analysis<br/>(3. Run JS/HTML/Deps)"]
    Dynamic["Dynamic Testing<br/>(3. Crawl & Test)"]
    Rules["OWASP Mapping<br/>(4. Classify)"]
    Score["Scoring Engine<br/>(5. Calculate Risk)"]
    DB["Database<br/>(6. Store Results)"]
    UI2["Results Display<br/>(7. Show to User)"]

    UI -->|2. Enter URL, choose mode| API
    API -->|3a. If STATIC or BOTH| Static
    API -->|3b. If DYNAMIC or BOTH| Dynamic
    API -->|Live logs via SSE| UI2
    Static -->|Findings| Rules
    Dynamic -->|Findings| Rules
    Rules -->|Categorized| Score
    Score -->|Risk score| DB
    DB -->|Query results| UI2

    style UI fill:#e1f5ff
    style API fill:#fff3cd
    style Static fill:#f8d7da
    style Dynamic fill:#f8d7da
    style DB fill:#d4edda

Step-by-Step¶

1. User submits scan request with target URL and mode
2. API validates URL (format, protocol, redirects)
3. URL is normalized (HTTPS upgrade attempt, etc.)
4. Scan job is enqueued (if async) or executed directly
5. Static analyzer runs (if mode = STATIC or BOTH)
6. Dynamic tester runs (if mode = DYNAMIC or BOTH)
7. Findings are classified using OWASP 2025 rules
8. Security score is calculated from findings
9. Results are stored in database
10. Real-time logs stream to client via SSE
11. Final results are displayed in UI

Technology Stack¶

Core Framework¶

Database¶

Security Testing¶

UI/Styling¶

Key Components¶

Static Analyzer¶

Responsibilities: - Pattern matching against dangerous APIs - HTML/template security checks - Dependency version scanning

Input: Source code files (JavaScript, TypeScript, HTML)
Output: Structured vulnerability objects
Speed: Very fast (no network calls)

Dynamic Tester¶

Responsibilities: - URL crawling and endpoint discovery - XSS, SQLi, CSRF, authentication testing - Security header analysis

Input: Target URL
Output: Structured vulnerability objects
Speed: Moderate-slow (network-based)
Safety: Non-destructive, rate-limited

Library Scanner¶

Responsibilities: - Parse package.json, requirements.txt, etc. - Check against vulnerability databases (NVD, CVE) - Identify outdated packages

Input: Manifest files
Output: Vulnerability objects
Speed: Fast (local database lookups)

See Components & Agents for detailed agent specifications.

Database Schema¶

WebSecScan uses a simple, auditable schema:

Core Models: - Scan — A single security scan (ID, URL, mode, score, status) - Vulnerability — A finding (type, OWASP category, severity, evidence) - SecurityTest — A specific test performed (header check, XSS payload, etc.) - ScanLog — Real-time log entries during scan

All data is deterministic and reproducible: same input → same findings.

Error Handling & Resilience¶

Error Categories¶

Timeouts & Limits¶

Security Constraints¶

All security operations are deterministic, auditable, and non-destructive:

• ✅ No random payloads or fuzzing
• ✅ No brute force or credential guessing
• ✅ No data extraction or modification
• ✅ No exploit chaining
• ✅ Explicit authorization checks
• ✅ All logic is rule-based and reviewable

See Security & Ethics for details.

Extensibility¶

To add new detection rules:

1. Create a new rule module in src/security/rules/
2. Implement detection logic (deterministic pattern matching)
3. Map to OWASP 2025 category
4. Add unit tests
5. Update documentation

See Contributing Guide for details.

Next Steps¶

• Agents & Components — Detailed agent specifications
• How Scanning Works — Scan modes explained
• API Reference — REST endpoints
• OWASP 2025 — Vulnerability taxonomy