How sabyasachirana/webmap works
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 Views · functions.py Helpers · api.py API · startup.sh Startup
Components 29
Deployment
Containerized runtime and entrypoint wiring.
- Dockerfile · Builds the WebMap runtime image.
docker/Dockerfile - Startup · Container bootstrap and service startup script.
docker/startup.sh - Settings · Docker-specific Django configuration.
docker/settings.py - URLs · Container-side URL routing setup.
docker/urls.py
Core app
Django application logic for scan parsing, storage, and routing.
- Routes · Main URL dispatcher for browser and API endpoints.
urls.py - Views · Primary Django views for scans, hosts, auth, and reports.
views.py - Helpers · Shared parsing and report helper functions.
functions.py - Nmap funcs · Nmap command construction and scan execution helpers.
functions_nmap.py - Models · Stored labels, notes, and other scan annotations.
models.py - Token gate · Lightweight token-based access helper.
guitoken.py
Presentation
Browser UI, reports, and static assets.
- API · Read-only JSON API over scans, hosts, and annotations.
api.py - PDF · Print-oriented report generation from scan data.
pdf.py - Report CSS · Styles for PDF and report rendering.
static/report.css - UI CSS · Browser-facing custom styles.
static/custom.css - Async JS · Client-side async behavior and UI interactions.
static/async.js - Main page · Scan overview and landing page template.
templates/nmapreport/main.html - Host page · Per-host detail view template.
templates/nmapreport/nmap_hostdetails.html - Port page · Service and port detail template.
templates/nmapreport/nmap_portdetails.html - Network page · Topology visualization template.
templates/nmapreport/nmap_network.html - XML files · Listing of stored scan XML files.
templates/nmapreport/nmap_xmlfiles.html - Diff page · Scan diff presentation template.
templates/nmapreport/nmap_ndiff.html - Report page · Printable report template.
templates/nmapreport/report.html - Auth page · Token and access prompt template.
templates/nmapreport/nmap_auth.html
Analysis
Topology, diff, and vulnerability enrichment.
- Network · Host relationship and network visualization logic.
network.py - Diff · Scan comparison and change reporting.
ndiff.py - CVE enrich · Maps CPE data to vulnerability and exploit lookups.
nmap/cve.py
Ops
Scheduled scans, custom NSE support, and release/testing.
- Cron · Scheduled scan job handling.
nmap/cron.py - Cron runner · Shell wrapper for scheduled execution.
nmap/runcron.sh - NSE scripts · Bundled custom NSE scripts used during scans.
nmap/nse
Connections 34
- 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.