# sabyasachirana/webmap architecture

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

- Interactive diagram: https://gitdiagram.com/sabyasachirana/webmap
- Repository: https://github.com/sabyasachirana/webmap

## Overview

1. **Overall shape**
   This is a Django-based dashboard for Nmap XML scans. The core architecture is: Nmap produces XML files, WebMap ingests and parses those files, stores a small amount of user metadata, then renders dashboards, host detail pages, API responses, and PDFs from that scan data.

2. **Deployment boundary**
   The repo is designed around Docker, not a standalone Django install. The container exposes the web app on port 8000 and mounts persistent volumes for scan XML, notes, and schedules. That means the primary state is split between:
   - scan files on a mounted filesystem
   - Django-backed application data for labels/notes/token-like metadata
   - generated outputs such as PDFs and schedules

3. **Request routing and web layer**
   `urls.py`, `views.py`, and `templates/nmapreport/*` define the main browser-facing experience. The HTML pages are organized around:
   - a scan list / overview
   - per-scan report pages
   - per-host detail pages
   - port/service and auth-related views
   - XML file listings
   - network and diff views

4. **Data ingestion and parsing**
   The important architectural input is the Nmap XML report, not live network traffic. The parsing and normalization logic is concentrated in helper modules such as `functions.py`, `functions_nmap.py`, and likely `models.py` for persisted annotations. These modules turn raw XML into host, service, port, OS, and CPE-centric structures used by both HTML and JSON outputs.

5. **Scan execution and scheduling**
   WebMap can also trigger scans itself. The scan orchestration path is split out from the read-only report rendering path:
   - `functions_nmap.py` handles Nmap invocation or command construction
   - `nmap/cron.py` and `nmap/runcron.sh` handle scheduled jobs
   - mounted `/opt/schedule` persists scheduled scan definitions
   This is a separate operational subsystem from the dashboard, even though both consume the same XML output format.

6. **CVE / exploit enrichment**
   A distinct enrichment layer lives under `nmap/cve.py`. It maps CPE data extracted from Nmap into vulnerability lookups, using external data sources referenced in the README such as `cve.circl.lu` and exploit metadata. This enrichment is optional per host/service and is surfaced in host detail and API responses.

7. **Reporting and PDF generation**
   `pdf.py` plus the `templates/nmapreport/*` pages and `static/report.css` form the PDF/reporting subsystem. The report is generated from the same scan model as the web UI, but rendered as a print-friendly document with charts, scan metadata, labels, and notes. The README indicates `wkhtmltopdf` is the conversion engine.

8. **Network and visualization layer**
   `network.py` and the related templates expose a topology/network view of discovered hosts. On the frontend, this is backed by browser-side chart/graph libraries referenced in the README and static assets like `static/async.js` and `static/custom.css`. This is a visualization layer over parsed scan relationships, not a separate data source.

9. **REST API**
   `api.py` provides a JSON API over the same scan corpus. The API exposes:
   - a scan index
   - a scan-by-filename view
   - a scan-by-host view
   - scan metadata plus host annotations and CVE/exploit enrichment
   This is a read-only façade over the parsed XML plus local annotations, and it uses a token for access.

10. **Authentication / access control**
    Access appears token-based rather than a full user-account system. `guitoken.py` and the README’s token-generation flow indicate a lightweight gate protecting the dashboard and API. The repository also warns that the app is intended for localhost/private network use, not internet exposure.

11. **Persistence and annotations**
    User-added labels and notes are part of the application state, likely backed by Django models and saved independently from the XML files. This creates a clear split between immutable scan evidence and mutable operator annotations. The mounted notes volume suggests some of this may also be file-backed or hybrid-persisted.

12. **Nmap custom extension support**
    The `nmap/nse/` directory contains custom NSE scripts, which are bundled with the app to support specialized detection or vulnerability checks during scans. This is an important integration point because it extends the scan data WebMap later consumes.

13. **Quality and release pipeline**
    `.github/workflows/test_django.yml` and `tests/` indicate automated validation around the Django app, with dedicated tests for cron behavior and CVE logic. `build-release.yml` suggests the project is packaged and published as a container image.

14. **Architecture summary for a diagram**
    A good diagram would show:
    - Nmap and scheduled scans as external producers
    - XML files on a mounted volume as the main input store
    - Django app as the central processor/rendering layer
    - separate subpaths for web UI, REST API, PDF generation, network visualization, and CVE enrichment
    - a lightweight token gate in front of user access
    - external services for vulnerability lookup
    - persistent notes/schedules as mutable side data alongside immutable scan artifacts

Main entry points: [`views.py`](https://github.com/sabyasachirana/webmap/blob/master/views.py) (Views), [`functions.py`](https://github.com/sabyasachirana/webmap/blob/master/functions.py) (Helpers), [`api.py`](https://github.com/sabyasachirana/webmap/blob/master/api.py) (API), [`docker/startup.sh`](https://github.com/sabyasachirana/webmap/blob/master/docker/startup.sh) (Startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_startup["Startup<br/>entrypoint<br/>[startup.sh]"]
  node_dockersettings["Settings<br/>django config<br/>[settings.py]"]
  node_dockerurls["URLs<br/>route config<br/>[urls.py]"]
end

subgraph group_core["Core app"]
  node_urls["Routes<br/>django routing<br/>[urls.py]"]
  node_views["Views<br/>request handlers<br/>[views.py]"]
  node_functions["Helpers<br/>scan utils<br/>[functions.py]"]
  node_functions_nmap["Nmap funcs<br/>scan orchestration<br/>[functions_nmap.py]"]
  node_models[("Models<br/>persisted metadata<br/>[models.py]")]
  node_guitoken["Token gate<br/>access control<br/>[guitoken.py]"]
end

subgraph group_presentation["Presentation"]
  node_api["API<br/>json facade<br/>[api.py]"]
  node_pdf["PDF<br/>report renderer<br/>[pdf.py]"]
  node_reportcss["Report CSS<br/>static styling<br/>[report.css]"]
  node_customcss["UI CSS<br/>static styling<br/>[custom.css]"]
  node_asyncjs["Async JS<br/>browser script<br/>[async.js]"]
  node_mainhtml["Main page<br/>template<br/>[main.html]"]
  node_hostdetails["Host page<br/>template"]
  node_portdetails["Port page<br/>template"]
  node_networktpl["Network page<br/>template<br/>[nmap_network.html]"]
  node_xmlfiles["XML files<br/>template<br/>[nmap_xmlfiles.html]"]
  node_ndiffpage["Diff page<br/>template<br/>[nmap_ndiff.html]"]
  node_reporttpl["Report page<br/>template<br/>[report.html]"]
  node_authpage["Auth page<br/>template<br/>[nmap_auth.html]"]
end

subgraph group_analysis["Analysis"]
  node_network["Network<br/>topology view<br/>[network.py]"]
  node_ndiff["Diff<br/>scan compare<br/>[ndiff.py]"]
  node_cve["CVE enrich<br/>vuln mapping<br/>[cve.py]"]
end

subgraph group_ops["Ops"]
  node_cron["Cron<br/>scheduler<br/>[cron.py]"]
  node_runcron["Cron runner<br/>shell job<br/>[runcron.sh]"]
  node_nse["NSE scripts<br/>custom nmap scripts"]
end

node_dockerfile -->|"starts"| node_startup
node_startup -->|"loads"| node_dockersettings
node_startup -->|"routes"| node_dockerurls
node_dockerurls -->|"delegates"| node_urls
node_urls -->|"dispatches"| node_views
node_views -->|"uses"| node_functions
node_views -->|"triggers"| node_functions_nmap
node_views -->|"persists"| node_models
node_views -->|"checks"| node_guitoken
node_views -->|"renders"| node_mainhtml
node_views -->|"renders"| node_hostdetails
node_views -->|"renders"| node_portdetails
node_views -->|"renders"| node_xmlfiles
node_views -->|"renders"| node_ndiffpage
node_views -->|"renders"| node_authpage
node_functions_nmap -->|"scheduled by"| node_cron
node_cron -->|"invokes"| node_runcron
node_functions_nmap -->|"extends"| node_nse
node_functions -->|"feeds"| node_network
node_functions -->|"feeds"| node_ndiff
node_functions -->|"normalizes"| node_cve
node_cve -->|"augments"| node_api
node_cve -->|"augments"| node_hostdetails
node_network -->|"renders"| node_networktpl
node_ndiff -->|"renders"| node_ndiffpage
node_pdf -->|"renders"| node_reporttpl
node_pdf -->|"styles"| node_reportcss
node_api -->|"reads"| node_functions
node_api -->|"reads"| node_models
node_api -->|"checks"| node_guitoken
node_mainhtml -->|"styles"| node_customcss
node_mainhtml -->|"scripts"| node_asyncjs
node_networktpl -->|"scripts"| node_asyncjs
node_reporttpl -->|"styles"| node_reportcss

click node_dockerfile "https://github.com/sabyasachirana/webmap/tree/master/docker/Dockerfile"
click node_startup "https://github.com/sabyasachirana/webmap/blob/master/docker/startup.sh"
click node_dockersettings "https://github.com/sabyasachirana/webmap/blob/master/docker/settings.py"
click node_dockerurls "https://github.com/sabyasachirana/webmap/blob/master/docker/urls.py"
click node_urls "https://github.com/sabyasachirana/webmap/blob/master/urls.py"
click node_views "https://github.com/sabyasachirana/webmap/blob/master/views.py"
click node_functions "https://github.com/sabyasachirana/webmap/blob/master/functions.py"
click node_functions_nmap "https://github.com/sabyasachirana/webmap/blob/master/functions_nmap.py"
click node_models "https://github.com/sabyasachirana/webmap/blob/master/models.py"
click node_guitoken "https://github.com/sabyasachirana/webmap/blob/master/guitoken.py"
click node_api "https://github.com/sabyasachirana/webmap/blob/master/api.py"
click node_pdf "https://github.com/sabyasachirana/webmap/blob/master/pdf.py"
click node_network "https://github.com/sabyasachirana/webmap/blob/master/network.py"
click node_ndiff "https://github.com/sabyasachirana/webmap/blob/master/ndiff.py"
click node_cve "https://github.com/sabyasachirana/webmap/blob/master/nmap/cve.py"
click node_cron "https://github.com/sabyasachirana/webmap/blob/master/nmap/cron.py"
click node_runcron "https://github.com/sabyasachirana/webmap/blob/master/nmap/runcron.sh"
click node_nse "https://github.com/sabyasachirana/webmap/tree/master/nmap/nse"
click node_reportcss "https://github.com/sabyasachirana/webmap/blob/master/static/report.css"
click node_customcss "https://github.com/sabyasachirana/webmap/blob/master/static/custom.css"
click node_asyncjs "https://github.com/sabyasachirana/webmap/blob/master/static/async.js"
click node_mainhtml "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/main.html"
click node_hostdetails "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_hostdetails.html"
click node_portdetails "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_portdetails.html"
click node_networktpl "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_network.html"
click node_xmlfiles "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_xmlfiles.html"
click node_ndiffpage "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_ndiff.html"
click node_reporttpl "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/report.html"
click node_authpage "https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_auth.html"

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_dockerfile,node_startup,node_dockersettings,node_dockerurls toneBlue
class node_urls,node_views,node_functions,node_functions_nmap,node_models,node_guitoken toneAmber
class node_api,node_pdf,node_reportcss,node_customcss,node_asyncjs,node_mainhtml,node_hostdetails,node_portdetails,node_networktpl,node_xmlfiles,node_ndiffpage,node_reporttpl,node_authpage toneMint
class node_network,node_ndiff,node_cve toneRose
class node_cron,node_runcron,node_nse toneIndigo
```

## Components

### Deployment

Containerized runtime and entrypoint wiring.

- [Dockerfile](https://github.com/sabyasachirana/webmap/tree/master/docker/Dockerfile): container build · Builds the WebMap runtime image. · `docker/Dockerfile`
- [Startup](https://github.com/sabyasachirana/webmap/blob/master/docker/startup.sh): entrypoint · Container bootstrap and service startup script. · `docker/startup.sh`
- [Settings](https://github.com/sabyasachirana/webmap/blob/master/docker/settings.py): django config · Docker-specific Django configuration. · `docker/settings.py`
- [URLs](https://github.com/sabyasachirana/webmap/blob/master/docker/urls.py): route config · Container-side URL routing setup. · `docker/urls.py`

### Core app

Django application logic for scan parsing, storage, and routing.

- [Routes](https://github.com/sabyasachirana/webmap/blob/master/urls.py): django routing · Main URL dispatcher for browser and API endpoints. · `urls.py`
- [Views](https://github.com/sabyasachirana/webmap/blob/master/views.py): request handlers · Primary Django views for scans, hosts, auth, and reports. · `views.py`
- [Helpers](https://github.com/sabyasachirana/webmap/blob/master/functions.py): scan utils · Shared parsing and report helper functions. · `functions.py`
- [Nmap funcs](https://github.com/sabyasachirana/webmap/blob/master/functions_nmap.py): scan orchestration · Nmap command construction and scan execution helpers. · `functions_nmap.py`
- [Models](https://github.com/sabyasachirana/webmap/blob/master/models.py): persisted metadata · Stored labels, notes, and other scan annotations. · `models.py`
- [Token gate](https://github.com/sabyasachirana/webmap/blob/master/guitoken.py): access control · Lightweight token-based access helper. · `guitoken.py`

### Presentation

Browser UI, reports, and static assets.

- [API](https://github.com/sabyasachirana/webmap/blob/master/api.py): json facade · Read-only JSON API over scans, hosts, and annotations. · `api.py`
- [PDF](https://github.com/sabyasachirana/webmap/blob/master/pdf.py): report renderer · Print-oriented report generation from scan data. · `pdf.py`
- [Report CSS](https://github.com/sabyasachirana/webmap/blob/master/static/report.css): static styling · Styles for PDF and report rendering. · `static/report.css`
- [UI CSS](https://github.com/sabyasachirana/webmap/blob/master/static/custom.css): static styling · Browser-facing custom styles. · `static/custom.css`
- [Async JS](https://github.com/sabyasachirana/webmap/blob/master/static/async.js): browser script · Client-side async behavior and UI interactions. · `static/async.js`
- [Main page](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/main.html): template · Scan overview and landing page template. · `templates/nmapreport/main.html`
- [Host page](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_hostdetails.html): template · Per-host detail view template. · `templates/nmapreport/nmap_hostdetails.html`
- [Port page](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_portdetails.html): template · Service and port detail template. · `templates/nmapreport/nmap_portdetails.html`
- [Network page](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_network.html): template · Topology visualization template. · `templates/nmapreport/nmap_network.html`
- [XML files](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_xmlfiles.html): template · Listing of stored scan XML files. · `templates/nmapreport/nmap_xmlfiles.html`
- [Diff page](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_ndiff.html): template · Scan diff presentation template. · `templates/nmapreport/nmap_ndiff.html`
- [Report page](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/report.html): template · Printable report template. · `templates/nmapreport/report.html`
- [Auth page](https://github.com/sabyasachirana/webmap/blob/master/templates/nmapreport/nmap_auth.html): template · Token and access prompt template. · `templates/nmapreport/nmap_auth.html`

### Analysis

Topology, diff, and vulnerability enrichment.

- [Network](https://github.com/sabyasachirana/webmap/blob/master/network.py): topology view · Host relationship and network visualization logic. · `network.py`
- [Diff](https://github.com/sabyasachirana/webmap/blob/master/ndiff.py): scan compare · Scan comparison and change reporting. · `ndiff.py`
- [CVE enrich](https://github.com/sabyasachirana/webmap/blob/master/nmap/cve.py): vuln mapping · Maps CPE data to vulnerability and exploit lookups. · `nmap/cve.py`

### Ops

Scheduled scans, custom NSE support, and release/testing.

- [Cron](https://github.com/sabyasachirana/webmap/blob/master/nmap/cron.py): scheduler · Scheduled scan job handling. · `nmap/cron.py`
- [Cron runner](https://github.com/sabyasachirana/webmap/blob/master/nmap/runcron.sh): shell job · Shell wrapper for scheduled execution. · `nmap/runcron.sh`
- [NSE scripts](https://github.com/sabyasachirana/webmap/tree/master/nmap/nse): custom nmap scripts · Bundled custom NSE scripts used during scans. · `nmap/nse`

## Connections

- Dockerfile → Startup: starts · Container image boots the app through startup.
- Startup → Settings: loads · Entrypoint activates Django settings.
- Startup → URLs: routes · Entrypoint wires container URL config.
- URLs → Routes: delegates · Container routing forwards to main URL dispatcher.
- Routes → Views: dispatches · Main routes resolve to Django views.
- Views → Helpers: uses · Views rely on parsing and normalization helpers.
- Views → Nmap funcs: triggers · Views can initiate scan execution workflows.
- Views → Models: persists · Views store labels, notes, and annotation data.
- Views → Token gate: checks · Access-controlled views consult token gate.
- Views → Main page: renders · Main browser experience is rendered from templates.
- Views → Host page: renders · Host detail pages are rendered from templates.
- Views → Port page: renders · Port/service pages are rendered from templates.
- Views → XML files: renders · XML file listing is rendered from templates.
- Views → Diff page: renders · Diff view is rendered from templates.
- Views → Auth page: renders · Access prompt page is rendered from templates.
- Nmap funcs → Cron: scheduled by · Scheduled execution uses cron coordination.
- Cron → Cron runner: invokes · Cron job is executed by shell wrapper.
- Nmap funcs → NSE scripts: extends · Scan execution can include custom NSE scripts.
- Helpers → Network: feeds · Parsed scan relationships power topology views.
- Helpers → Diff: feeds · Parsed scans also support comparison logic.
- Helpers → CVE enrich: normalizes · CPE and service data are prepared for vulnerability enrichment.
- CVE enrich → API: augments · Enriched vulnerability data is exposed by the API.
- CVE enrich → Host page: augments · Host details surface vulnerability enrichment.
- Network → Network page: renders · Topology data is shown in the network template.
- Diff → Diff page: renders · Scan diffs are shown in the diff template.
- PDF → Report page: renders · Printable reports are assembled from the report template.
- PDF → Report CSS: styles · PDF output uses report-specific styling.
- API → Helpers: reads · API reads the same parsed scan corpus.
- API → Models: reads · API includes stored annotations and metadata.
- API → Token gate: checks · API access is token-protected.
- Main page → UI CSS: styles · Browser UI uses custom static styling.
- Main page → Async JS: scripts · Browser UI uses client-side async behavior.
- Network page → Async JS: scripts · Topology view may use browser-side interactivity.
- Report page → Report CSS: styles · Printable report template uses report styling.
