# shagunchaudhary794/scanner architecture

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

- Interactive diagram: https://gitdiagram.com/shagunchaudhary794/scanner
- Repository: https://github.com/shagunchaudhary794/scanner

## Overview

Scanner MVP is a Flask control plane for tenant-scoped asset inventory, scan scheduling, vulnerability assessment, and report delivery. Users manage assets and schedules through the web app; asynchronous workers execute scans, record findings, and support reporting. The worker’s assessment branches include network/service discovery, default-credential checks, CVSS scoring, and unsupported-OS detection. PostgreSQL stores application records, while Redis supports Celery and distributed locks. The README documents the OpenVAS agent/scanner role and reporting formats; unsampled route and task implementations limit some detailed flow links.

Main entry points: [`tasks.py`](https://github.com/shagunchaudhary794/scanner/blob/main/tasks.py) (Async Scan Worker), [`routes.py`](https://github.com/shagunchaudhary794/scanner/blob/main/routes.py) (Web Workflows), [`models.py`](https://github.com/shagunchaudhary794/scanner/blob/main/models.py) (Tenant and Scan Models), [`app.py`](https://github.com/shagunchaudhary794/scanner/blob/main/app.py) (Flask Web App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Plane"]
  node_web["Flask Web App<br/>[app.py]"]
  node_routes["Web Workflows<br/>[routes.py]"]
  node_assets["Asset Inventory<br/>[routes.py]"]
  node_scheduling["Scan Scheduling<br/>[routes.py]"]
  node_reports["Report Workflows<br/>[routes.py]"]
end

subgraph group_assessment["Assessment"]
  node_discovery["Scope Discovery<br/>[discovery.py]"]
  node_network["Network Scanners<br/>[tasks.py]"]
  node_credentials["Default Credentials<br/>[default_creds.py]"]
  node_scoring["CVSS Scoring<br/>[cvss_engine.py]"]
  node_eol["OS Support Checks<br/>[eol_os.py]"]
end

subgraph group_persistence["State and Storage"]
  node_domain["Tenant and Scan Models<br/>[models.py]"]
  node_reportfiles["Report File Storage<br/>[report_storage.py]"]
end

subgraph group_runtime["Worker Runtime"]
  node_worker["Async Scan Worker<br/>[tasks.py]"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_locks["Asset Scan Locks<br/>[lock_manager.py]"]
end

node_user(("Scanner User"))
node_postgres[("PostgreSQL")]
node_redis["Redis and Celery"]
node_openvas["OpenVAS Scanner"]
node_nvd["NVD CVE Service"]
node_agent(("Presence Agent"))

node_user -->|"uses"| node_web
node_web -->|"registers"| node_routes
node_web -->|"loads models"| node_domain
node_web -->|"loads settings"| node_config
node_routes -->|"reads and writes"| node_domain
node_routes -->|"handles inventory"| node_assets
node_routes -->|"creates schedules"| node_scheduling
node_routes -->|"queues scans"| node_worker
node_worker -->|"records scan data"| node_domain
node_worker -->|"uses discovery"| node_discovery
node_worker -->|"runs scans"| node_network
node_worker -->|"checks credentials"| node_credentials
node_worker -->|"scores findings"| node_scoring
node_worker -->|"checks OS support"| node_eol
node_worker -->|"acquires locks"| node_locks
node_locks -->|"stores locks"| node_redis
node_worker -->|"uses Celery"| node_redis
node_domain -->|"persists records"| node_postgres
node_scoring -->|"looks up CVEs"| node_nvd
node_reports -->|"saves and loads"| node_reportfiles
node_routes -->|"serves exports"| node_reports
node_reports -->|"uses report metadata"| node_domain
node_agent -->|"sends heartbeat"| node_routes
node_worker -->|"runs internal scans"| node_openvas
node_worker -.->|"dispatches internal scans"| node_agent

click node_web "https://github.com/shagunchaudhary794/scanner/blob/main/app.py"
click node_routes "https://github.com/shagunchaudhary794/scanner/blob/main/routes.py"
click node_domain "https://github.com/shagunchaudhary794/scanner/blob/main/models.py"
click node_assets "https://github.com/shagunchaudhary794/scanner/blob/main/routes.py"
click node_scheduling "https://github.com/shagunchaudhary794/scanner/blob/main/routes.py"
click node_worker "https://github.com/shagunchaudhary794/scanner/blob/main/tasks.py"
click node_discovery "https://github.com/shagunchaudhary794/scanner/blob/main/discovery.py"
click node_network "https://github.com/shagunchaudhary794/scanner/blob/main/tasks.py"
click node_credentials "https://github.com/shagunchaudhary794/scanner/blob/main/default_creds.py"
click node_scoring "https://github.com/shagunchaudhary794/scanner/blob/main/cvss_engine.py"
click node_eol "https://github.com/shagunchaudhary794/scanner/blob/main/eol_os.py"
click node_reports "https://github.com/shagunchaudhary794/scanner/blob/main/routes.py"
click node_reportfiles "https://github.com/shagunchaudhary794/scanner/blob/main/report_storage.py"
click node_config "https://github.com/shagunchaudhary794/scanner/blob/main/config.py"
click node_locks "https://github.com/shagunchaudhary794/scanner/blob/main/lock_manager.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_web,node_routes,node_assets,node_scheduling,node_reports,node_user toneBlue
class node_discovery,node_network,node_credentials,node_scoring,node_eol,node_postgres,node_redis toneAmber
class node_domain,node_reportfiles toneMint
class node_worker,node_config,node_locks toneRose
class node_openvas,node_nvd,node_agent toneIndigo
```

## Components

### Control Plane

- [Flask Web App](https://github.com/shagunchaudhary794/scanner/blob/main/app.py): `app.py`
- [Web Workflows](https://github.com/shagunchaudhary794/scanner/blob/main/routes.py): `routes.py`
- [Asset Inventory](https://github.com/shagunchaudhary794/scanner/blob/main/routes.py): `routes.py`
- [Scan Scheduling](https://github.com/shagunchaudhary794/scanner/blob/main/routes.py): `routes.py`
- [Report Workflows](https://github.com/shagunchaudhary794/scanner/blob/main/routes.py): `routes.py`

### Assessment

- [Scope Discovery](https://github.com/shagunchaudhary794/scanner/blob/main/discovery.py): `discovery.py`
- [Network Scanners](https://github.com/shagunchaudhary794/scanner/blob/main/tasks.py): `tasks.py`
- [Default Credentials](https://github.com/shagunchaudhary794/scanner/blob/main/default_creds.py): `default_creds.py`
- [CVSS Scoring](https://github.com/shagunchaudhary794/scanner/blob/main/cvss_engine.py): `cvss_engine.py`
- [OS Support Checks](https://github.com/shagunchaudhary794/scanner/blob/main/eol_os.py): `eol_os.py`

### State and Storage

- [Tenant and Scan Models](https://github.com/shagunchaudhary794/scanner/blob/main/models.py): `models.py`
- [Report File Storage](https://github.com/shagunchaudhary794/scanner/blob/main/report_storage.py): `report_storage.py`

### Worker Runtime

- [Async Scan Worker](https://github.com/shagunchaudhary794/scanner/blob/main/tasks.py): `tasks.py`
- [Runtime Configuration](https://github.com/shagunchaudhary794/scanner/blob/main/config.py): `config.py`
- [Asset Scan Locks](https://github.com/shagunchaudhary794/scanner/blob/main/lock_manager.py): `lock_manager.py`

### Other components

- **Scanner User**
- **PostgreSQL**
- **Redis and Celery**
- **OpenVAS Scanner**
- **NVD CVE Service**
- **Presence Agent**

## Connections

- Scanner User → Flask Web App: uses (evidence: `README.md`)
- Flask Web App → Web Workflows: registers (evidence: `app.py`)
- Flask Web App → Tenant and Scan Models: loads models (evidence: `app.py`)
- Flask Web App → Runtime Configuration: loads settings (evidence: `app.py`)
- Web Workflows → Tenant and Scan Models: reads and writes (evidence: `routes.py`)
- Web Workflows → Asset Inventory: handles inventory (evidence: `routes.py`)
- Web Workflows → Scan Scheduling: creates schedules (evidence: `routes.py`)
- Web Workflows → Async Scan Worker: queues scans (evidence: `README.md`)
- Async Scan Worker → Tenant and Scan Models: records scan data (evidence: `tasks.py`)
- Async Scan Worker → Scope Discovery: uses discovery (evidence: `tasks.py`)
- Async Scan Worker → Network Scanners: runs scans (evidence: `tasks.py`)
- Async Scan Worker → Default Credentials: checks credentials (evidence: `tasks.py`)
- Async Scan Worker → CVSS Scoring: scores findings (evidence: `tasks.py`)
- Async Scan Worker → OS Support Checks: checks OS support (evidence: `tasks.py`)
- Async Scan Worker → Asset Scan Locks: acquires locks (evidence: `tasks.py`)
- Asset Scan Locks → Redis and Celery: stores locks (evidence: `lock_manager.py`)
- Async Scan Worker → Redis and Celery: uses Celery (evidence: `README.md`)
- Tenant and Scan Models → PostgreSQL: persists records (evidence: `README.md`)
- CVSS Scoring → NVD CVE Service: looks up CVEs (evidence: `cvss_engine.py`)
- Report Workflows → Report File Storage: saves and loads (evidence: `routes.py`)
- Web Workflows → Report Workflows: serves exports (evidence: `README.md`)
- Report Workflows → Tenant and Scan Models: uses report metadata (evidence: `README.md`)
- Presence Agent → Web Workflows: sends heartbeat (evidence: `routes.py`)
- Async Scan Worker → OpenVAS Scanner: runs internal scans (evidence: `README.md`)
- Async Scan Worker → Presence Agent: dispatches internal scans
