# maverickaayush/onus architecture

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

- Interactive diagram: https://gitdiagram.com/maverickaayush/onus
- Repository: https://github.com/maverickaayush/onus

## Overview

ONUS is an authorized-target vulnerability assessment tool. The principal workflow takes a domain and authorization from the operator, dispatches parallel scanning modules, handles incomplete runs, then aggregates, passively verifies, deterministically scores, and optionally adds AI explanations before persisting results for a dashboard and PDF report. Hosted deployments add account and domain-ownership verification; these features are configurable and off by default. The README documents product stages not fully represented in sampled excerpts; links based only on that documentation cite README.md.

Main entry points: [`backend/tasks/scan_orchestrator.py`](https://github.com/maverickaayush/onus/blob/main/backend/tasks/scan_orchestrator.py) (Scan orchestrator), [`backend/routers/scan.py`](https://github.com/maverickaayush/onus/blob/main/backend/routers/scan.py) (Scan routes), [`frontend/lib/api.ts`](https://github.com/maverickaayush/onus/blob/main/frontend/lib/api.ts) (API client), [`backend/main.py`](https://github.com/maverickaayush/onus/blob/main/backend/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Operator interface"]
  node_frontend["Next.js dashboard<br/>[page.tsx]"]
  node_scanform["New scan<br/>[new-scan.tsx]"]
  node_statusview["Scan status<br/>[scan-status.tsx]"]
  node_scanlist["Scan history<br/>[scans-list.tsx]"]
  node_reportview["Report dashboard"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_scan_api["Scan routes<br/>[scan.py]"]
  node_verify_api["Domain verification<br/>[verify.py]"]
  node_auth_api["Hosted authentication<br/>[auth.py]"]
end

subgraph group_scanning["Scanning and orchestration"]
  node_orchestrator["Scan orchestrator"]
  node_recon["Network reconnaissance<br/>[recon.py]"]
  node_webscan["Web application scan<br/>[webscan.py]"]
  node_ssl["SSL/TLS scan<br/>[ssl_tls.py]"]
  node_headers["HTTP headers scan<br/>[headers.py]"]
  node_owasp["OWASP checks<br/>[owasp.py]"]
  node_fingerprint["Technology fingerprint"]
  node_nuclei["CVE scan<br/>[nuclei_scan.py]"]
  node_enumeration["Directory enumeration<br/>[enumeration.py]"]
end

subgraph group_analysis["Finding analysis"]
  node_aggregator["Findings aggregator<br/>[aggregator.py]"]
  node_verifier["Confidence verifier<br/>[verifier.py]"]
  node_scorer["CVSS scorer<br/>[cvss_scorer.py]"]
  node_ai["AI descriptions<br/>[ollama_client.py]"]
end

subgraph group_results["Results and persistence"]
  node_pdf["PDF report generator<br/>[generator.py]"]
  node_models["Scan data models<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_redis[("Redis credentials<br/>[auth_store.py]")]
end

node_operator(("Operator"))
node_target(("Authorized target"))
node_ollama(("Local LLM service"))

node_operator -->|"uses"| node_frontend
node_frontend -->|"presents"| node_scanform
node_scanform -.->|"submits scan"| node_api_client
node_statusview -.->|"requests status"| node_api_client
node_scanlist -.->|"requests history"| node_api_client
node_reportview -.->|"requests results"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"routes scans"| node_scan_api
node_api_app -->|"routes verification"| node_verify_api
node_api_app -->|"routes auth"| node_auth_api
node_scan_api -->|"dispatches scans"| node_orchestrator
node_verify_api -->|"checks ownership"| node_target
node_orchestrator -->|"dispatches module"| node_recon
node_orchestrator -->|"dispatches module"| node_webscan
node_orchestrator -->|"dispatches module"| node_ssl
node_orchestrator -->|"dispatches module"| node_headers
node_orchestrator -->|"dispatches module"| node_owasp
node_orchestrator -->|"dispatches module"| node_fingerprint
node_orchestrator -->|"dispatches module"| node_nuclei
node_orchestrator -->|"dispatches module"| node_enumeration
node_recon -->|"scans target"| node_target
node_webscan -->|"scans target"| node_target
node_ssl -->|"scans target"| node_target
node_headers -->|"scans target"| node_target
node_owasp -->|"scans target"| node_target
node_fingerprint -->|"scans target"| node_target
node_nuclei -->|"scans target"| node_target
node_enumeration -->|"scans target"| node_target
node_orchestrator -->|"aggregates findings"| node_aggregator
node_orchestrator -->|"verifies findings"| node_verifier
node_orchestrator -->|"scores findings"| node_scorer
node_orchestrator -->|"describes findings"| node_ai
node_ai -->|"requests analysis"| node_ollama
node_orchestrator -->|"stores results"| node_models
node_models -->|"persists records"| node_database
node_scan_api -->|"stores credentials"| node_redis
node_orchestrator -->|"enables report"| node_pdf
node_pdf -->|"reads scan data"| node_models
node_scan_api -->|"reads and writes scans"| node_models
node_scan_api -->|"queries records"| node_database
node_reportview -->|"downloads report"| node_pdf

click node_frontend "https://github.com/maverickaayush/onus/blob/main/frontend/app/page.tsx"
click node_scanform "https://github.com/maverickaayush/onus/blob/main/frontend/components/new-scan.tsx"
click node_statusview "https://github.com/maverickaayush/onus/blob/main/frontend/components/scan-status.tsx"
click node_scanlist "https://github.com/maverickaayush/onus/blob/main/frontend/components/scans-list.tsx"
click node_reportview "https://github.com/maverickaayush/onus/blob/main/frontend/components/report-dashboard.tsx"
click node_api_client "https://github.com/maverickaayush/onus/blob/main/frontend/lib/api.ts"
click node_api_app "https://github.com/maverickaayush/onus/blob/main/backend/main.py"
click node_scan_api "https://github.com/maverickaayush/onus/blob/main/backend/routers/scan.py"
click node_verify_api "https://github.com/maverickaayush/onus/blob/main/backend/routers/verify.py"
click node_auth_api "https://github.com/maverickaayush/onus/blob/main/backend/routers/auth.py"
click node_orchestrator "https://github.com/maverickaayush/onus/blob/main/backend/tasks/scan_orchestrator.py"
click node_recon "https://github.com/maverickaayush/onus/blob/main/backend/tasks/recon.py"
click node_webscan "https://github.com/maverickaayush/onus/blob/main/backend/tasks/webscan.py"
click node_ssl "https://github.com/maverickaayush/onus/blob/main/backend/tasks/ssl_tls.py"
click node_headers "https://github.com/maverickaayush/onus/blob/main/backend/tasks/headers.py"
click node_owasp "https://github.com/maverickaayush/onus/blob/main/backend/tasks/owasp.py"
click node_fingerprint "https://github.com/maverickaayush/onus/blob/main/backend/tasks/tech_fingerprint.py"
click node_nuclei "https://github.com/maverickaayush/onus/blob/main/backend/tasks/nuclei_scan.py"
click node_enumeration "https://github.com/maverickaayush/onus/blob/main/backend/tasks/enumeration.py"
click node_aggregator "https://github.com/maverickaayush/onus/blob/main/backend/analysis/aggregator.py"
click node_verifier "https://github.com/maverickaayush/onus/blob/main/backend/analysis/verifier.py"
click node_scorer "https://github.com/maverickaayush/onus/blob/main/backend/analysis/cvss_scorer.py"
click node_ai "https://github.com/maverickaayush/onus/blob/main/backend/analysis/ollama_client.py"
click node_pdf "https://github.com/maverickaayush/onus/blob/main/backend/reports/generator.py"
click node_models "https://github.com/maverickaayush/onus/blob/main/backend/models.py"
click node_database "https://github.com/maverickaayush/onus/blob/main/backend/database.py"
click node_redis "https://github.com/maverickaayush/onus/blob/main/backend/tasks/auth_store.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_frontend,node_scanform,node_statusview,node_scanlist,node_reportview,node_api_client toneBlue
class node_api_app,node_scan_api,node_verify_api,node_auth_api toneAmber
class node_orchestrator,node_recon,node_webscan,node_ssl,node_headers,node_owasp,node_fingerprint,node_nuclei,node_enumeration toneMint
class node_aggregator,node_verifier,node_scorer,node_ai toneRose
class node_pdf,node_models,node_database,node_redis,node_operator,node_target,node_ollama toneIndigo
```

## Components

### Operator interface

- [Next.js dashboard](https://github.com/maverickaayush/onus/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [New scan](https://github.com/maverickaayush/onus/blob/main/frontend/components/new-scan.tsx): `frontend/components/new-scan.tsx`
- [Scan status](https://github.com/maverickaayush/onus/blob/main/frontend/components/scan-status.tsx): `frontend/components/scan-status.tsx`
- [Scan history](https://github.com/maverickaayush/onus/blob/main/frontend/components/scans-list.tsx): `frontend/components/scans-list.tsx`
- [Report dashboard](https://github.com/maverickaayush/onus/blob/main/frontend/components/report-dashboard.tsx): `frontend/components/report-dashboard.tsx`
- [API client](https://github.com/maverickaayush/onus/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and access

- [FastAPI application](https://github.com/maverickaayush/onus/blob/main/backend/main.py): `backend/main.py`
- [Scan routes](https://github.com/maverickaayush/onus/blob/main/backend/routers/scan.py): `backend/routers/scan.py`
- [Domain verification](https://github.com/maverickaayush/onus/blob/main/backend/routers/verify.py): `backend/routers/verify.py`
- [Hosted authentication](https://github.com/maverickaayush/onus/blob/main/backend/routers/auth.py): `backend/routers/auth.py`

### Scanning and orchestration

- [Scan orchestrator](https://github.com/maverickaayush/onus/blob/main/backend/tasks/scan_orchestrator.py): `backend/tasks/scan_orchestrator.py`
- [Network reconnaissance](https://github.com/maverickaayush/onus/blob/main/backend/tasks/recon.py): `backend/tasks/recon.py`
- [Web application scan](https://github.com/maverickaayush/onus/blob/main/backend/tasks/webscan.py): `backend/tasks/webscan.py`
- [SSL/TLS scan](https://github.com/maverickaayush/onus/blob/main/backend/tasks/ssl_tls.py): `backend/tasks/ssl_tls.py`
- [HTTP headers scan](https://github.com/maverickaayush/onus/blob/main/backend/tasks/headers.py): `backend/tasks/headers.py`
- [OWASP checks](https://github.com/maverickaayush/onus/blob/main/backend/tasks/owasp.py): `backend/tasks/owasp.py`
- [Technology fingerprint](https://github.com/maverickaayush/onus/blob/main/backend/tasks/tech_fingerprint.py): `backend/tasks/tech_fingerprint.py`
- [CVE scan](https://github.com/maverickaayush/onus/blob/main/backend/tasks/nuclei_scan.py): `backend/tasks/nuclei_scan.py`
- [Directory enumeration](https://github.com/maverickaayush/onus/blob/main/backend/tasks/enumeration.py): `backend/tasks/enumeration.py`

### Finding analysis

- [Findings aggregator](https://github.com/maverickaayush/onus/blob/main/backend/analysis/aggregator.py): `backend/analysis/aggregator.py`
- [Confidence verifier](https://github.com/maverickaayush/onus/blob/main/backend/analysis/verifier.py): `backend/analysis/verifier.py`
- [CVSS scorer](https://github.com/maverickaayush/onus/blob/main/backend/analysis/cvss_scorer.py): `backend/analysis/cvss_scorer.py`
- [AI descriptions](https://github.com/maverickaayush/onus/blob/main/backend/analysis/ollama_client.py): `backend/analysis/ollama_client.py`

### Results and persistence

- [PDF report generator](https://github.com/maverickaayush/onus/blob/main/backend/reports/generator.py): `backend/reports/generator.py`
- [Scan data models](https://github.com/maverickaayush/onus/blob/main/backend/models.py): `backend/models.py`
- [PostgreSQL](https://github.com/maverickaayush/onus/blob/main/backend/database.py): `backend/database.py`
- [Redis credentials](https://github.com/maverickaayush/onus/blob/main/backend/tasks/auth_store.py): `backend/tasks/auth_store.py`

### Other components

- **Operator**
- **Authorized target**
- **Local LLM service**

## Connections

- Operator → Next.js dashboard: uses (evidence: `README.md`)
- Next.js dashboard → New scan: presents (evidence: `README.md`)
- New scan → API client: submits scan
- Scan status → API client: requests status
- Scan history → API client: requests history
- Report dashboard → API client: requests results
- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Scan routes: routes scans (evidence: `backend/main.py`)
- FastAPI application → Domain verification: routes verification (evidence: `backend/main.py`)
- FastAPI application → Hosted authentication: routes auth (evidence: `backend/main.py`)
- Scan routes → Scan orchestrator: dispatches scans (evidence: `backend/routers/scan.py`)
- Domain verification → Authorized target: checks ownership (evidence: `README.md`)
- Scan orchestrator → Network reconnaissance: dispatches module (evidence: `README.md`)
- Scan orchestrator → Web application scan: dispatches module (evidence: `README.md`)
- Scan orchestrator → SSL/TLS scan: dispatches module (evidence: `README.md`)
- Scan orchestrator → HTTP headers scan: dispatches module (evidence: `README.md`)
- Scan orchestrator → OWASP checks: dispatches module (evidence: `README.md`)
- Scan orchestrator → Technology fingerprint: dispatches module (evidence: `README.md`)
- Scan orchestrator → CVE scan: dispatches module (evidence: `README.md`)
- Scan orchestrator → Directory enumeration: dispatches module (evidence: `README.md`)
- Network reconnaissance → Authorized target: scans target (evidence: `README.md`)
- Web application scan → Authorized target: scans target (evidence: `README.md`)
- SSL/TLS scan → Authorized target: scans target (evidence: `README.md`)
- HTTP headers scan → Authorized target: scans target (evidence: `README.md`)
- OWASP checks → Authorized target: scans target (evidence: `README.md`)
- Technology fingerprint → Authorized target: scans target (evidence: `README.md`)
- CVE scan → Authorized target: scans target (evidence: `README.md`)
- Directory enumeration → Authorized target: scans target (evidence: `README.md`)
- Scan orchestrator → Findings aggregator: aggregates findings (evidence: `backend/tasks/scan_orchestrator.py`)
- Scan orchestrator → Confidence verifier: verifies findings (evidence: `backend/tasks/scan_orchestrator.py`)
- Scan orchestrator → CVSS scorer: scores findings (evidence: `backend/tasks/scan_orchestrator.py`)
- Scan orchestrator → AI descriptions: describes findings (evidence: `backend/tasks/scan_orchestrator.py`)
- AI descriptions → Local LLM service: requests analysis (evidence: `README.md`)
- Scan orchestrator → Scan data models: stores results (evidence: `backend/tasks/scan_orchestrator.py`)
- Scan data models → PostgreSQL: persists records (evidence: `backend/models.py`)
- Scan routes → Redis credentials: stores credentials (evidence: `backend/tasks/auth_store.py`)
- Scan orchestrator → PDF report generator: enables report (evidence: `README.md`)
- PDF report generator → Scan data models: reads scan data (evidence: `backend/reports/generator.py`)
- Scan routes → Scan data models: reads and writes scans (evidence: `backend/routers/scan.py`)
- Scan routes → PostgreSQL: queries records (evidence: `backend/routers/scan.py`)
- Report dashboard → PDF report generator: downloads report (evidence: `README.md`)
