# notreallyaryann/vulnscanner architecture

> Architecture diagram of the GitHub repository notreallyaryann/vulnscanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/notreallyaryann/vulnscanner
- Repository: https://github.com/notreallyaryann/vulnscanner

## Overview

#### Purpose and Entry Points
VulnScanner is a Next.js application that launches and monitors automated web-security scans, persists scan data, and produces remediation/reporting outputs. UI entry points are `src/app/page.tsx` and `src/app/dashboard/page.tsx`; HTTP control-plane endpoints live under `src/app/api/scan/route.ts`, `src/app/api/scan/[scanId]/stop/route.ts`, and `src/app/api/scan-logs/[scanId]/route.ts`.

#### Scan Control Plane
The scan API creates, tracks, and can cancel scan work by scan ID. `src/lib/scan-controller.ts` is the lifecycle/cancellation boundary, while `src/lib/scanner.ts` is the central orchestration engine. `src/lib/scan-logger.ts` records progress/events for the log API and dashboard. This separates interactive Next.js request handling from longer-running scanner execution.

#### Discovery and Application Analysis
The scanner first maps the target and its attack surface through crawling, request/payload construction, and JavaScript inspection. `src/lib/scanner/crawler.ts` discovers HTML and SPA routes; `src/lib/scanner/payloads.ts` builds multi-format injection inputs; `src/lib/scanner/js-analyzer.ts` parses JavaScript with Acorn for DOM sinks and exposed secrets. These stages feed targets and evidence into active probes rather than directly coupling crawling to individual checks.

#### Active Vulnerability Probes
Probe implementations are organized by vulnerability domain: `src/lib/scanner/probes/sqli.ts`, `src/lib/scanner/probes/xss.ts`, and `src/lib/scanner/probes/api.ts`. The orchestrator coordinates these checks alongside HTTP/security configuration analysis and aggregates findings into the scan result. Probe execution is the principal boundary where the system sends potentially intrusive requests to the scanned target.

#### Browser Verification Service
Dynamic client-side verification uses Playwright through browser abstractions in `src/lib/browser.ts` and `src/lib/browser-pool.ts`. A separately containerized service, defined by `browser-service/server.js` and `browser-service/Dockerfile`, provides browser rendering/hydration and supports verification of dynamic behavior such as DOM XSS, storage exposure, and intercepted requests. This isolates heavyweight browser runtime dependencies from the main Next.js process.

#### Network Scanning Service
Network port/service discovery is delegated to a dedicated Nmap container. The application-side client is `src/lib/nmap.ts`; its service boundary is implemented by `nmap-service/server.js` and packaged in `nmap-service/Dockerfile`. This keeps native Nmap execution outside the web application runtime and returns network-level evidence to the main scan workflow.

#### Persistence, AI, and Delivery
Prisma provides persistence, with the data model in `prisma/schema.prisma` and access centralized in `src/lib/prisma.ts`; vector migration support is in `prisma/migrate-vectors.ts`, indicating PostgreSQL/Neon-backed vector retrieval. Findings can be enriched through Cerebras AI and RAG via `src/lib/cerebras.ts`, `src/lib/rag.ts`, and `src/lib/embeddings.ts`. Final scan summaries are dispatched through Nodemailer integration in `src/lib/mail.ts`. A third isolated service, `nuclei-service/server.js`, is containerized in `nuclei-service/Dockerfile` for Nuclei-based scanning capability.

Main entry points: [`src/lib/scanner.ts`](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scanner.ts) (Scan orchestrator), [`src/lib/scan-controller.ts`](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scan-controller.ts) (Scan lifecycle), [`src/app/dashboard/page.tsx`](https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/dashboard/page.tsx) (Scan dashboard), [`src/app/api/scan/route.ts`](https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/api/scan/route.ts) (Scan API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js control plane"]
  node_home["Scan launch UI<br/>Next.js page<br/>[page.tsx]"]
  node_dashboard["Scan dashboard<br/>Next.js page<br/>[page.tsx]"]
  node_scan_api["Scan API<br/>HTTP endpoint<br/>[route.ts]"]
  node_stop_api["Stop scan API<br/>HTTP endpoint<br/>[route.ts]"]
  node_logs_api["Scan logs API<br/>HTTP endpoint<br/>[route.ts]"]
end

subgraph group_engine["Scan engine"]
  node_controller["Scan lifecycle<br/>controller<br/>[scan-controller.ts]"]
  node_scanner{{"Scan orchestrator<br/>scanner engine<br/>[scanner.ts]"}}
  node_logger["Scan event log<br/>progress logger<br/>[scan-logger.ts]"]
  node_discovery["Discovery analysis<br/>crawler and analyzers<br/>[crawler.ts]"]
  node_probes["Active probes<br/>SQLi, XSS, API checks<br/>[sqli.ts]"]
  node_browser_client["Browser client and pool<br/>Playwright abstraction<br/>[browser-pool.ts]"]
  node_nmap_client["Nmap client<br/>service client<br/>[nmap.ts]"]
end

subgraph group_services["Isolated scan services"]
  node_browser_service["Browser verification<br/>container service<br/>[server.js]"]
  node_nmap_service["Network scanner<br/>Nmap container service<br/>[server.js]"]
  node_nuclei_service["Nuclei scanner<br/>container service<br/>[server.js]"]
end

subgraph group_data["Persistence and delivery"]
  node_prisma[("Scan database<br/>Prisma / PostgreSQL<br/>[prisma.ts]")]
  node_ai_rag["AI enrichment<br/>Cerebras RAG<br/>[rag.ts]"]
  node_mail["Report delivery<br/>Nodemailer<br/>[mail.ts]"]
end

node_target(("Scanned target<br/>external web application"))

node_home -->|"starts scan"| node_scan_api
node_dashboard -->|"reads progress"| node_logs_api
node_dashboard -->|"cancels scan"| node_stop_api
node_scan_api -->|"creates job"| node_controller
node_stop_api -->|"requests cancellation"| node_controller
node_controller -->|"runs scan"| node_scanner
node_scanner -->|"emits events"| node_logger
node_logs_api -->|"returns events"| node_logger
node_scanner -->|"maps attack surface"| node_discovery
node_discovery -->|"crawls and inspects"| node_target
node_scanner -->|"coordinates checks"| node_probes
node_probes -->|"active requests"| node_target
node_scanner -->|"requests dynamic verification"| node_browser_client
node_browser_client -->|"uses Playwright runtime"| node_browser_service
node_browser_service -->|"renders and observes"| node_target
node_scanner -->|"requests network discovery"| node_nmap_client
node_nmap_client -->|"delegates Nmap"| node_nmap_service
node_nmap_service -->|"ports and services"| node_target
node_scanner -->|"delegates templates"| node_nuclei_service
node_scanner -->|"persists results"| node_prisma
node_scanner -->|"enriches findings"| node_ai_rag
node_ai_rag -->|"retrieves vectors"| node_prisma
node_scanner -->|"dispatches summary"| node_mail

click node_home "https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/page.tsx"
click node_dashboard "https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/dashboard/page.tsx"
click node_scan_api "https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/api/scan/route.ts"
click node_stop_api "https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/api/scan/%5BscanId%5D/stop/route.ts"
click node_logs_api "https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/api/scan-logs/%5BscanId%5D/route.ts"
click node_controller "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scan-controller.ts"
click node_scanner "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scanner.ts"
click node_logger "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scan-logger.ts"
click node_discovery "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scanner/crawler.ts"
click node_probes "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scanner/probes/sqli.ts"
click node_browser_client "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/browser-pool.ts"
click node_browser_service "https://github.com/notreallyaryann/vulnscanner/blob/main/browser-service/server.js"
click node_nmap_client "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/nmap.ts"
click node_nmap_service "https://github.com/notreallyaryann/vulnscanner/blob/main/nmap-service/server.js"
click node_nuclei_service "https://github.com/notreallyaryann/vulnscanner/blob/main/nuclei-service/server.js"
click node_prisma "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/prisma.ts"
click node_ai_rag "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/rag.ts"
click node_mail "https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/mail.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_dashboard,node_scan_api,node_stop_api,node_logs_api toneBlue
class node_controller,node_scanner,node_logger,node_discovery,node_probes,node_browser_client,node_nmap_client toneAmber
class node_browser_service,node_nmap_service,node_nuclei_service toneMint
class node_prisma,node_ai_rag,node_mail toneRose
class node_target toneNeutral
```

## Components

### Next.js control plane

- [Scan launch UI](https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/page.tsx): Next.js page · `src/app/page.tsx`
- [Scan dashboard](https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/dashboard/page.tsx): Next.js page · `src/app/dashboard/page.tsx`
- [Scan API](https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/api/scan/route.ts): HTTP endpoint · `src/app/api/scan/route.ts`
- [Stop scan API](https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/api/scan/%5BscanId%5D/stop/route.ts): HTTP endpoint · `src/app/api/scan/[scanId]/stop/route.ts`
- [Scan logs API](https://github.com/notreallyaryann/vulnscanner/blob/main/src/app/api/scan-logs/%5BscanId%5D/route.ts): HTTP endpoint · `src/app/api/scan-logs/[scanId]/route.ts`

### Scan engine

- [Scan lifecycle](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scan-controller.ts): controller · Owns scan tracking and cancellation. · `src/lib/scan-controller.ts`
- [Scan orchestrator](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scanner.ts): scanner engine · Coordinates discovery, probes, services, and results. · `src/lib/scanner.ts`
- [Scan event log](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scan-logger.ts): progress logger · `src/lib/scan-logger.ts`
- [Discovery analysis](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scanner/crawler.ts): crawler and analyzers · Maps routes, payload inputs, and JavaScript evidence. · `src/lib/scanner/crawler.ts`
- [Active probes](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/scanner/probes/sqli.ts): SQLi, XSS, API checks · Sends intrusive vulnerability-check requests. · `src/lib/scanner/probes/sqli.ts`
- [Browser client and pool](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/browser-pool.ts): Playwright abstraction · `src/lib/browser-pool.ts`
- [Nmap client](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/nmap.ts): service client · `src/lib/nmap.ts`

### Isolated scan services

- [Browser verification](https://github.com/notreallyaryann/vulnscanner/blob/main/browser-service/server.js): container service · Renders dynamic clients and verifies browser-side findings. · `browser-service/server.js`
- [Network scanner](https://github.com/notreallyaryann/vulnscanner/blob/main/nmap-service/server.js): Nmap container service · `nmap-service/server.js`
- [Nuclei scanner](https://github.com/notreallyaryann/vulnscanner/blob/main/nuclei-service/server.js): container service · `nuclei-service/server.js`

### Persistence and delivery

- [Scan database](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/prisma.ts): Prisma / PostgreSQL · Persists scans, findings, and vector-backed retrieval data. · `src/lib/prisma.ts`
- [AI enrichment](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/rag.ts): Cerebras RAG · Enriches findings using embeddings and retrieval. · `src/lib/rag.ts`
- [Report delivery](https://github.com/notreallyaryann/vulnscanner/blob/main/src/lib/mail.ts): Nodemailer · `src/lib/mail.ts`

### Other components

- **Scanned target**: external web application

## Connections

- Scan launch UI → Scan API: starts scan
- Scan dashboard → Scan logs API: reads progress
- Scan dashboard → Stop scan API: cancels scan
- Scan API → Scan lifecycle: creates job
- Stop scan API → Scan lifecycle: requests cancellation
- Scan lifecycle → Scan orchestrator: runs scan
- Scan orchestrator → Scan event log: emits events
- Scan logs API → Scan event log: returns events
- Scan orchestrator → Discovery analysis: maps attack surface
- Discovery analysis → Scanned target: crawls and inspects
- Scan orchestrator → Active probes: coordinates checks
- Active probes → Scanned target: active requests
- Scan orchestrator → Browser client and pool: requests dynamic verification
- Browser client and pool → Browser verification: uses Playwright runtime
- Browser verification → Scanned target: renders and observes
- Scan orchestrator → Nmap client: requests network discovery
- Nmap client → Network scanner: delegates Nmap
- Network scanner → Scanned target: ports and services
- Scan orchestrator → Nuclei scanner: delegates templates
- Scan orchestrator → Scan database: persists results
- Scan orchestrator → AI enrichment: enriches findings
- AI enrichment → Scan database: retrieves vectors
- Scan orchestrator → Report delivery: dispatches summary