# nimaturana/vulnhunter architecture

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

- Interactive diagram: https://gitdiagram.com/nimaturana/vulnhunter
- Repository: https://github.com/nimaturana/vulnhunter

## Overview

VulnHunter is an authorized web-security assessment MVP. An API client submits a scan and selected detectors; the scan service runs them in FastAPI background tasks, combines findings into scan results, and exposes status, history, statistics, and PDF reports. It keeps live scans in memory and attempts to persist scan metadata and findings to PostgreSQL. Documented detector capabilities include XSS, SQL injection, security headers, TLS, and directory exposure. The frontend, authentication, and worker queue are future work, not active runtime components. Some detector and report wiring is documented but their source was not sampled.

Main entry points: [`backend/vulnhunter/scans/service.py`](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/service.py) (Scan Service), [`backend/vulnhunter/scans/routes.py`](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/routes.py) (Scan Endpoints), [`backend/vulnhunter/router.py`](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/router.py) (API Router), [`backend/vulnhunter/main.py`](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/main.py) (FastAPI App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Status"]
  node_app["FastAPI App<br/>[main.py]"]
  node_api_router["API Router<br/>[router.py]"]
  node_scan_routes["Scan Endpoints<br/>[routes.py]"]
  node_system_routes["System Endpoints<br/>[routes.py]"]
end

subgraph group_scan["Scan Workflow"]
  node_scan_service["Scan Service<br/>[service.py]"]
  node_scan_models["Scan Models<br/>[models.py]"]
  node_risk["Risk Assessment<br/>[risk.py]"]
end

subgraph group_detectors["Security Detectors"]
  node_directory["Directory Scanner"]
  node_headers["Headers Scanner"]
  node_sqli["SQL Injection Scanner"]
  node_xss["XSS Scanner<br/>[xss_scanner.py]"]
  node_tls["TLS Scanner<br/>[ssl_scanner.py]"]
end

subgraph group_storage["Results and Reports"]
  node_memory["In-Memory Scans<br/>[service.py]"]
  node_db_connection["Database Connection<br/>[connection.py]"]
  node_crud["Scan CRUD<br/>[crud.py]"]
  node_db_models["Database Models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_pdf["PDF Generator<br/>[pdf_generator.py]"]
end

node_client(("API Client"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_api_router
node_api_router -->|"dispatches scans"| node_scan_routes
node_api_router -->|"dispatches status"| node_system_routes
node_scan_routes -->|"creates and queries"| node_scan_service
node_scan_routes -->|"schedules scan"| node_scan_service
node_scan_service -->|"uses models"| node_scan_models
node_scan_service -->|"reads and writes"| node_memory
node_scan_service -->|"dispatches scan"| node_directory
node_scan_service -->|"dispatches scan"| node_headers
node_scan_service -->|"dispatches scan"| node_sqli
node_scan_service -->|"dispatches scan"| node_xss
node_scan_service -->|"dispatches scan"| node_tls
node_system_routes -->|"reads statistics"| node_scan_service
node_scan_service -->|"opens session"| node_db_connection
node_scan_service -->|"saves scan results"| node_crud
node_crud -->|"uses mappings"| node_db_models
node_db_connection -->|"connects"| node_postgres
node_scan_service -->|"generates report"| node_pdf
node_scan_routes -->|"returns results"| node_client

click node_app "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/main.py"
click node_api_router "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/router.py"
click node_scan_routes "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/routes.py"
click node_system_routes "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/system/routes.py"
click node_scan_service "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/service.py"
click node_scan_models "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/models.py"
click node_memory "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/service.py"
click node_risk "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/risk.py"
click node_directory "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/directory_scanner.py"
click node_headers "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/security_headers_scanner.py"
click node_sqli "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/sql_injection_scanner.py"
click node_xss "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/xss_scanner.py"
click node_tls "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/ssl_scanner.py"
click node_db_connection "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/database/connection.py"
click node_crud "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/database/crud.py"
click node_db_models "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/database/models.py"
click node_pdf "https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/reports/pdf_generator.py"

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_app,node_api_router,node_scan_routes,node_system_routes,node_client toneBlue
class node_scan_service,node_scan_models,node_risk toneAmber
class node_directory,node_headers,node_sqli,node_xss,node_tls toneMint
class node_memory,node_db_connection,node_crud,node_db_models,node_postgres,node_pdf toneRose
```

## Components

### API and Status

- [FastAPI App](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/main.py): `backend/vulnhunter/main.py`
- [API Router](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/router.py): `backend/vulnhunter/router.py`
- [Scan Endpoints](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/routes.py): `backend/vulnhunter/scans/routes.py`
- [System Endpoints](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/system/routes.py): `backend/vulnhunter/system/routes.py`

### Scan Workflow

- [Scan Service](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/service.py): `backend/vulnhunter/scans/service.py`
- [Scan Models](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/models.py): `backend/vulnhunter/scans/models.py`
- [Risk Assessment](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/risk.py): `backend/vulnhunter/scans/risk.py`

### Security Detectors

- [Directory Scanner](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/directory_scanner.py): `backend/vulnhunter/scanners/directory_scanner.py`
- [Headers Scanner](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/security_headers_scanner.py): `backend/vulnhunter/scanners/security_headers_scanner.py`
- [SQL Injection Scanner](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/sql_injection_scanner.py): `backend/vulnhunter/scanners/sql_injection_scanner.py`
- [XSS Scanner](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/xss_scanner.py): `backend/vulnhunter/scanners/xss_scanner.py`
- [TLS Scanner](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scanners/ssl_scanner.py): `backend/vulnhunter/scanners/ssl_scanner.py`

### Results and Reports

- [In-Memory Scans](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/scans/service.py): `backend/vulnhunter/scans/service.py`
- [Database Connection](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/database/connection.py): `backend/vulnhunter/database/connection.py`
- [Scan CRUD](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/database/crud.py): `backend/vulnhunter/database/crud.py`
- [Database Models](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/database/models.py): `backend/vulnhunter/database/models.py`
- **PostgreSQL**
- [PDF Generator](https://github.com/nimaturana/vulnhunter/blob/main/backend/vulnhunter/reports/pdf_generator.py): `backend/vulnhunter/reports/pdf_generator.py`

### Other components

- **API Client**

## Connections

- API Client → FastAPI App: sends requests
- FastAPI App → API Router: mounts routes
- API Router → Scan Endpoints: dispatches scans
- API Router → System Endpoints: dispatches status
- Scan Endpoints → Scan Service: creates and queries
- Scan Endpoints → Scan Service: schedules scan
- Scan Service → Scan Models: uses models
- Scan Service → In-Memory Scans: reads and writes
- Scan Service → Directory Scanner: dispatches scan
- Scan Service → Headers Scanner: dispatches scan
- Scan Service → SQL Injection Scanner: dispatches scan
- Scan Service → XSS Scanner: dispatches scan
- Scan Service → TLS Scanner: dispatches scan
- System Endpoints → Scan Service: reads statistics
- Scan Service → Database Connection: opens session
- Scan Service → Scan CRUD: saves scan results
- Scan CRUD → Database Models: uses mappings
- Database Connection → PostgreSQL: connects
- Scan Service → PDF Generator: generates report
- Scan Endpoints → API Client: returns results