How notreallyaryann/vulnscanner works
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: scanner.ts Scan orchestrator · scan-controller.ts Scan lifecycle · page.tsx Scan dashboard · route.ts Scan API
Components 19
Next.js control plane
- Scan launch UI
src/app/page.tsx - Scan dashboard
src/app/dashboard/page.tsx - Scan API
src/app/api/scan/route.ts - Stop scan API
src/app/api/scan/[scanId]/stop/route.ts - Scan logs API
src/app/api/scan-logs/[scanId]/route.ts
Scan engine
- Scan lifecycle · Owns scan tracking and cancellation.
src/lib/scan-controller.ts - Scan orchestrator · Coordinates discovery, probes, services, and results.
src/lib/scanner.ts - Scan event log
src/lib/scan-logger.ts - Discovery analysis · Maps routes, payload inputs, and JavaScript evidence.
src/lib/scanner/crawler.ts - Active probes · Sends intrusive vulnerability-check requests.
src/lib/scanner/probes/sqli.ts - Browser client and pool
src/lib/browser-pool.ts - Nmap client
src/lib/nmap.ts
Isolated scan services
- Browser verification · Renders dynamic clients and verifies browser-side findings.
browser-service/server.js - Network scanner
nmap-service/server.js - Nuclei scanner
nuclei-service/server.js
Persistence and delivery
- Scan database · Persists scans, findings, and vector-backed retrieval data.
src/lib/prisma.ts - AI enrichment · Enriches findings using embeddings and retrieval.
src/lib/rag.ts - Report delivery
src/lib/mail.ts
Other components
- Scanned target
Connections 23
- 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