admin / Synapse-NetscanXi

# NetscanXi Version 13

> Build folder: `NetscanXi Version 13` (forked from `NetscanXi Version12`).
> Product/marketing version: **Version 13**.

## New in Version 13 - Patch and Remedy (OS updates/upgrades + Docker)

Version 13 turns NetscanXi from a tool that only *observes* and *tracks*
remediation into one that can *act* on it.

- **Operating-system updates & upgrades over SSH.** The **Patch and Remedy** tab
  (formerly the reserved "More" tab) applies OS patches to scanned assets. The
  package manager is **auto-detected** (`apt` / `dnf` / `yum` / `zypper` /
  `apk`) and NetscanXi runs an update + upgrade, with an optional **full
  distribution upgrade** and a **simulate (dry-run)** mode that changes nothing.
- **Target a single asset, an asset group, or all assets** from the latest
  scan. (OS patching targets *any* scanned asset - it is no longer limited to
  Docker hosts.)
- **Docker image updates (optional).** A second patch type still pulls the
  latest image for each running container over the Docker Engine API, with an
  optional experimental container recreate.
- **Per-run credentials that are never stored.** SSH/sudo credentials (OS) and
  registry credentials (Docker) are entered *per patch run*, used once, and are
  **never written to the database, never logged, and never returned**. Password
  fields are cleared in the browser as soon as the request is sent, and the
  audit log (`os_patch` / `docker_patch`) records only counts and targets.
- **Automatic remediation activities.** Every patch run **auto-creates a
  Remediation Tracking item per targeted asset** (status `in_progress`) and then
  **updates it** to `resolved` or `blocked` with a result summary - the
  Remediation tab is the single source of truth for what was patched, by whom,
  and with what outcome.
- **Dry-run preview.** **Preview (dry run)** lists the targeted assets and their
  detected OS (for OS patching) or images (for Docker) with **no side effects**
  and no remediation items created; OS preview does not even contact SSH.
- **Role-gated & tenant-separated.** Patching requires the **operator** role;
  scoped users can only ever target their own tenant's assets.
  New endpoints: `POST /api/patch/os`, `POST /api/patch/os/plan`,
  `POST /api/patch/docker`, `POST /api/patch/docker/plan`.
  New module: `app/patcher.py` (no new DB tables - reuses the `remediation`
  table from Version 12). New dependency: **paramiko** (SSH); it is imported
  lazily and degrades gracefully if absent.

> Security note: OS patching performs **privileged remote execution**. Patch
> only assets you are authorised to change, prefer the simulate/dry-run preview,
> and use a maintenance window for production hosts. Windows OS patching
> (WinRM) is a future phase.

### Remediation Tracking enhancements (v13)

- **Multi-select & bulk delete.** Each remediation row has a checkbox (plus a
  header select-all); a **Delete selected (n)** button removes them in one go.
  New endpoint: `POST /api/remediation/bulk-delete` (operator, tenant-scoped -
  a scoped user can never delete another tenant's items).
- **Comments thread per item.** Every remediation item now has an expandable
  **💬 comments** section for a running discussion/work-log. Comments show
  author + timestamp and are tenant-separated; deleting an item removes its
  comments. New endpoints: `GET/POST /api/remediation/<id>/comments`,
  `DELETE /api/remediation/comments/<id>`.
- **New DB table** (auto-migrated on startup): `remediation_comments`.

All Version 12 functionality is retained (see below).

## New in Version 12 - professional blue theme, scalable tabbed dashboard & per-asset compliance export

- **Professional blue theme.** The dark and light palettes move to professional
  shades of blue (navy surfaces, blue primary actions). Semantic colours are
  preserved: red for danger/vulnerabilities, amber for warnings, and green only
  for genuine pass/clean/success states.
- **Scalable tabbed dashboard.** The tab bar is restyled (underline tabs that
  wrap) and gains two reserved growth views - **Reports** (full-scan
  CSV/JSON/PDF, plus a reserved area for scheduled/executive/attestation
  reports) and **More** (reserved for topology map, alerting, asset groups,
  remediation tracker). New feature views drop straight into this framework
  without crowding the scan workflow.
- **Per-asset export on the Compliance tab.** The compliance table now shows
  each asset's **Asset ID** and an **Export** action (CSV / JSON / PDF) per
  asset, wired to the existing `/api/export/host/<ip>/<fmt>` endpoint.
- **Asset groups.** A new **Asset Groups** admin menu (tenant_admin+) lets you
  create/delete tenant-separated groups, and a new **Groups** column on the
  Assets tab lets operators assign each asset to one or more groups.
  Endpoints: `GET/POST /api/asset-groups`, `PATCH/DELETE /api/asset-groups/<id>`,
  `POST /api/assets/<asset_id>/groups`.
- **Remediation Tracking tab.** Track remediation activities (task, priority,
  status, assignee, due date) against each asset. Items are **tenant-separated**
  - a user only ever sees/edits remediation for their own tenant's assets.
  Endpoints: `GET/POST /api/remediation`, `PATCH/DELETE /api/remediation/<id>`.
- **Live scan progress.** The progress bar now advances smoothly and keeps
  moving during long, quiet phases (NSE/vuln scanning) instead of stalling,
  while still snapping to the server's authoritative % each poll.
- **Reports tab removed** - full-scan CSV/JSON/PDF export buttons already live
  at the top of the dashboard, so the redundant tab was dropped.

New DB tables (auto-migrated on startup): `asset_groups`,
`asset_group_members`, `remediation`.

All Version 10r1 functionality is retained (see below).

## New in Version 10r1 - Docker container scanning & vulnerability assessment

Version 10r1 turns NetscanXi's network-level Docker *detection* into deep,
per-container and per-image visibility - leveraging far more scan and
vulnerability data from the Docker hosts it finds. Everything is **best-effort
and degrades gracefully**: if the Docker API isn't reachable and no image
scanner is installed, you still get the original network-level detection plus a
clear capabilities report. Nothing here runs an exploit or mutates a target.

### 1. Authenticated Docker Engine API inventory

When a host's Docker API is reachable (plain `2375`, TLS `2376` with optional
client cert, legacy `4243`, or a local unix socket), NetscanXi pulls real
inventory: engine version/storage-driver/rootless/live-restore (`/version`,
`/info`), **running & stopped containers** (`/containers/json`: image, ports,
privileged, mounts, restart policy, capabilities) and the **image inventory**
(`/images/json`: tags, digests, size).

### 2. Container image vulnerability scanning

Each discovered image is scanned for OS-package and language CVEs using a
locally-installed scanner - **Trivy** (preferred) or **Grype** - fully offline
once the scanner DB is populated. Results are normalised and run through the
same **KEV/EPSS enrichment** as host findings, so container CVEs inherit
known-exploited flagging, CVSS scores and risk ranking. The Dockerfile installs
Trivy automatically.

### 3. CIS Docker Benchmark misconfiguration audit

Engine + per-container checks (exposed API, no TLS, insecure registry,
`--privileged`, `docker.sock` mounts, host network/PID, added capabilities,
missing restart policy, mutable `:latest` tags, rootless/live-restore) each
reported as **pass / warn / fail** and mapped to CIS Docker controls.

### 4. Registry, SBOM & orchestration awareness

Insecure (non-TLS) registries are flagged; an **SBOM** can be emitted per image
when the scanner supports it; and Swarm / Kubernetes indicators (2377/7946,
6443/2379/10250) are surfaced as structured findings (with sensitive ports like
the kubelet highlighted).

### 5. Dashboard & per-host views

- A new **Docker & Containers** dashboard panel (auto-hides when no Docker hosts
  are present): docker hosts, running containers, images, image CVEs, critical
  image CVEs, privileged containers, `docker.sock` mounts and CIS failures.
- Each host's detail view gains a deep Docker section: API status, engine info,
  a **containers list** (with risk flags), **image vulnerabilities** (severity
  strip + per-image CVE chips, KEV-flagged), the **CIS audit**, and
  orchestration findings. All existing host views and features are unchanged.

### 6. Drift, exports & options

- **Change detection** now reports container/image drift between scans:
  new/removed containers, new images, a container becoming privileged or
  mounting `docker.sock` (critical), and new known-exploited container CVEs.
- **CSV** exports gain Containers / Image CVEs / Image KEV / CIS-fail columns;
  **JSON** exports include the full Docker block; the **per-host PDF** gains a
  Docker container/image/CIS section.
- A new **Deep Docker scan** scan option (on by default) toggles the API
  inventory + image CVE + CIS audit. New endpoint `GET /api/docker/capabilities`
  reports what's available (API enabled, image scanner detected).

> **Configuration** (all optional env vars): `NETSCAN_DOCKER_API=0` disables API
> inventory; `NETSCAN_DOCKER_IMAGE_SCAN=0` disables image scanning;
> `NETSCAN_DOCKER_SCANNER=trivy|grype|auto`; `NETSCAN_DOCKER_MAX_IMAGES`;
> `NETSCAN_DOCKER_TLS_CA|CERT|KEY` for mTLS to `2376`.

## New in Version 9.1

Version 9.1 turns the dashboard from a static report into an interactive,
operationalised security console and adds first-class workflow + tenancy
features. Ten additions:

### 1. Interactive charts

The summary area now renders **clickable, interactive charts** alongside the
cards:

- **OS distribution pie chart** - hosts bucketed by OS family (Windows / Linux
  / Apple / Android / BSD / Network·IoT / Other / Unknown). Click any slice or
  legend entry to filter the Assets table to that family.
- **Vulnerability severity graph** - horizontal bars for Critical / High /
  Medium / Low / Unknown bands (CVSS-banded), excluding findings already marked
  *Remediated* or *False Positive*.

Charts are pure inline SVG/CSS (no external chart library, no CDN) so they work
fully offline. Backed by `os_distribution` / `severity_distribution` in
`GET /api/dashboard`.

### 2. CVE finding lifecycle

Every vulnerability can be moved through a **lifecycle**: **Open**,
**✅ Remediated**, **⚠ Accepted Risk**, **🚫 False Positive**. Click **🔄 Set
status** on a finding in the host detail view. A disposition can apply to that
**one asset** or **tenant-wide** to the CVE, with an optional note. Remediated /
false-positive findings are de-emphasised in the UI and dropped from the active
severity chart. Persisted in the new `cve_lifecycle` table and overlaid onto
hosts + the Top-10 list (`POST/GET /api/cve/lifecycle`). Dispositions follow the
**asset ID** across scans.

### 3. Multi-select asset table

The Assets table gains a **checkbox column** plus a **select-all** header box.
A bulk-action bar appears when rows are selected: **Export selected (CSV/JSON)**
and **Re-scan selected**. Selection respects the current text filter.

### 4. Tenant Admin role (RBAC expansion)

RBAC grows to four roles: `viewer` < `operator` < **`tenant_admin`** <
`admin`. A **Tenant Admin** has full administrative control **within their own
tenant** - manage that tenant's users, schedules, scans, integrations,
retention policy and activity log - but can **never** see or modify other
tenants and cannot mint global admins. The global `admin` retains cross-tenant
authority. Enforced in `auth.ROLE_LEVEL` + per-endpoint tenant scoping.

### 5. Global search bar

A **global search bar** sits in the top navigation. As you type it searches the
latest scan across **assets** (ID/IP/hostname/OS/vendor/MAC), **CVEs**
(id + description) and **software**, returning a live dropdown. Selecting a
result jumps to and expands that asset. Backed by `GET /api/search?q=`.

### 6. Configurable data-retention policies

A new **⚙ Admin** panel adds **data-retention policies** editable in the UI:
delete scans older than *N* days and/or keep only the *M* most-recent scans,
with an optional **auto-apply after every scan** toggle and a **Save & purge
now** action. The asset registry and audit log are always preserved.
(`GET/POST /api/settings/retention`, backed by a `settings` table and
`db.purge_old_scans`). Tenant admins purge only their own tenant; global admins
purge across all.

### 7. Patch-aware vulnerability assessment

Scanning is now **patch/version aware** rather than only distro-version aware.
The deep profile adds the version-aware **`vulners`** NSE script (toggle:
**Patch-aware vulns**), and the parser **captures patch / build / package-release
tokens** (e.g. `4ubuntu0.5`, service-pack/build numbers) from service banners
into a per-host **patch level** inventory. Each finding is tagged
**`version-confirmed`** (matched against the exact detected product+version) or
**`heuristic`**, and mitigations cite the concrete detected release - so
vulnerability assessment is materially more accurate.

### 8. Historical risk & compliance trend graphs

After every scan a **risk + compliance snapshot** is recorded
(`risk_snapshots`). A new dashboard chart plots the **overall network risk
score** and **compliance posture (%)** over **30 / 90 / 365 days** as an inline
SVG line graph with selectable ranges (`GET /api/trends?days=`).

### 9. Native service-desk integrations

Built-in, dependency-free integrations for **Jira**, **ServiceNow** and
**Zendesk** (`app/integrations.py`). Configure connections in the **🔗
Integrations** admin panel (base URL, auth, project/table/group), **test** the
connection, then **open a ticket for any CVE finding** straight from the host
detail view (**🎫 Create ticket**). Tickets are recorded for audit/dedupe in a
`tickets` table. (`/api/integrations*`, `/api/tickets`.)

### 10. Customisable dashboard

The dashboard is composed of movable **components** (Summary, Charts, Trends,
Compliance, Top Vulnerabilities). **✎ Customise** mode lets you **drag to
reorder**, **📌 pin** a component to the top, or **✕ hide** it; hidden
components can be restored from a chip list, and **↺ Reset layout** restores the
default. Layout persists in `localStorage` and server-side per user
(`/api/dashboard/layout`).

---

## New in Version 9

1. **Passive scanning** - a one-click, listen-only mode that discovers assets
   without sending any probe traffic. It reads the ARP/neighbour cache and
   overhears mDNS / SSDP-UPnP self-announcements to harvest IP, MAC, vendor,
   hostname, advertised services and a low-confidence device type. It has **no
   selectable options** by design and produces **no** ports, service versions,
   OS accuracy, vulnerabilities, or TLS/AD/Docker/credential findings (risk
   shows as `n/a`) - those require an active scan.
2. **Day & time scheduling** - schedule scans by ticking weekdays (Mon-Sun) and
   entering an hour and minute, alongside the classic "every N minutes"
   interval. Each schedule runs as Active or Passive.
3. **Scan-type on reports** - CSV, JSON and PDF exports state whether the data
   is from a **Passive** or **Active** scan (PDF header stamp, CSV comment line
   + column, JSON `scan_type`).
4. **Unique 8-character asset IDs** - every device gets a stable `[A-Z0-9]` ID
   **bound to its MAC address** (IP-derived when no MAC), stored in NetscanXi so
   findings attach to the same physical device across scans and are not
   duplicated. Included in every export.
5. **Editable asset Type** - correct a mis-identified device type inline; the
   override is bound to the asset ID and re-applied on future scans.

The dashboard layout and design are retained.

---

# NetscanXi v8 (Release 3)

## New in v8 Release 3 - NIST CSF & NCSC CAF compliance frameworks

Release 3 extends the regulatory compliance cross-reference with **two new
frameworks**, bringing the total to **eight**:

### 1. NIST CSF (Cybersecurity Framework)

NIST CSF alignment provides an internationally recognised standard for
private-sector enterprise buyers. Every host finding is now mapped to the
relevant CSF 2.0 outcome categories - e.g. cleartext authentication → **PR.DS-02**
(data-in-transit protection), unauthenticated service → **PR.AA-01/05**
(identity & access), known-exploited vuln → **ID.RA-06 / RS.MA**.

### 2. NCSC Cyber Assessment Framework (CAF)

Integrating NCSC CAF principles delivers a major value proposition for UK
public-sector entities and operators of essential services, ensuring network
discovery directly supports national cyber security assurance requirements.
Findings map to CAF objectives/principles - e.g. cleartext/unencrypted transport
→ **B3.c** (data in transit), unauthenticated access → **B2.a** (identity &
authentication), vulnerability exposure → **B4.d** (vulnerability management),
remote admin exposure → **B4.a/B2.c** (secure config & privileged access).

Both frameworks appear automatically in the **dashboard site-wide summary**, the
per-host **Compliance** tab grid (now eight columns), the expandable per-host
control detail, and the **PDF report** compliance overview - no scan changes
required; they reuse the existing defensive findings.

---

## New in v8 Release 2 - account password management

Release 2 adds full credential management for accounts:

### 1. Admin can set/reset any user's password

In **User Admin**, every user row now has a **🔑 set password** button. An admin can
set a fresh password for any account - including a user who has **locked themselves
out**. The change is applied immediately and recorded in the activity log
(`user_password_reset`).

### 2. Admin can edit usernames inline

The username in each User Admin row is now an **editable field**. Renames are unique-
checked, audited (`user_rename`), and if an admin renames their own account the session
stays in sync. Combined with (1), admins have full editable control over every account's
username and password.

### 3. Self-service "Change password" for every user

The top-bar **🔐 Security** panel (now titled *Account Security*) gains a **Change your
password** section. Any signed-in user supplies their current password plus a new one
(≥ 8 chars, confirmed) via `POST /api/account/password`. The admin **User Admin** view
reflects account state live on open, so password changes are immediately visible there.

> **Security note:** passwords are stored as one-way salted hashes (werkzeug). Admins can
> **set/reset** any password and **edit** usernames, but no one - not even an admin - can
> *view* an existing password, by design. Self-service changes require the current
> password; admin resets do not.

All password/username events appear in the **📋 Activity** log: `user_password_reset`,
`user_rename`, `password_change`, `password_change_failed`.

---

## New in v8 - multi-tenancy, audit log, single-host reports, live scan IP, UX

### 1. Soft multi-tenancy with data separation

Every user, scan and schedule now carries a **tenant** tag. Non-admin users
only see scans/exports/history belonging to their own tenant; **admins see all
tenants**. Auth-disabled installs behave as a single `default` tenant.
Admins assign a tenant when creating a user, or edit it inline in **User
Admin**. It's "soft" separation (one database, scoped queries) rather than
separate databases.

### 2. Sort & filter options

The **Software**, **Certificates** and **Compliance** tabs gain text filters
and clickable sortable column headers (the Assets tab already had both). The
activity log is filterable too.

### 3. Text banner instead of logo

The logo image is replaced by a **"NetscanXi" + version** text banner across
the top of the dashboard and the login screen.

### 4. Toolbar action buttons

The top-right text links become export-style buttons: **Schedule**,
**🔐 Security**, **👥 User Admin**, **📋 Activity**, and **⎋ Logout**.

### 5. Login/logout times + user activity log

A new `activity_log` table records **logins, logouts, failed logins**, scans,
re-scans, exports, schedule runs and user-admin changes (with timestamp,
user, tenant, client IP). Admins view it via the **Activity** modal
(`GET /api/activity`), filterable by tenant and free text.

### 6. Single-host report export

Expand any host and use its **Export: CSV / JSON / PDF** buttons to download a
focused report for just that host
(`GET /api/export/host/<ip>/<fmt>`): overview, open ports/services, software
and vulnerabilities.

#### CVE descriptions & mitigations in exports

All export formats now carry the full **CVE description** and a **suggested
mitigation** for every finding:

- **CSV** gains dedicated `CVE Descriptions` and `Mitigations` columns (whole
  scan and single-host).
- **PDF** gains a *Vulnerability Detail - CVE Descriptions & Mitigations* table
  (a network-wide table in the full report; a per-host table in the single-host
  report). KEV/exploit findings are flagged inline.
- **JSON** already includes the full per-vulnerability `description` and
  `mitigation` fields.

Mitigations come from CISA's authoritative required-action for known-exploited
CVEs where available, otherwise tailored service/product hardening advice.

### 7. Dynamic scan progress bar

The live progress bar (phase-weighted %, elapsed clock) is retained and polled
~1x/second during a scan.

### 8. Current IP shown during scan

The scanner now parses nmap's per-host output and the status API exposes
`current_ip`; the progress area shows **"Scanning: <ip>"** for the host nmap is
actively working on.

---

## New in v7 - Cyber Essentials, AD/DC auditing, PDF reports, TLS cert tracking

### 1. Cyber Essentials mapping

**Cyber Essentials** joins the compliance cross-reference (now six frameworks).
Findings map to its five technical control areas - Firewalls, Secure
Configuration, User Access Control, Malware Protection, Security Update
Management - e.g. cleartext auth -> *Secure Configuration*, unpatched
vulnerabilities -> *Security Update Management*.

### 2. Active Directory / Domain Controller auditing (toggle)

New **"AD / DC audit"** scan-option toggle. It identifies Domain Controllers
(Kerberos/LDAP/Global-Catalog ports + LDAP/SMB fingerprints) and reports
directory hardening posture: **SMBv1 enabled**, **SMB signing not required**,
**LDAP without LDAPS**, Kerberos user-enumeration exposure, plus detected
domain/forest names. Surfaced in a new **Active Directory** tab and fed into
compliance.

> Defensive enumeration only - no password spraying / `*-brute` scripts.

### 3. Branded PDF report export

Alongside CSV and JSON there is now an **Export PDF** button producing a
branded report (executive summary, compliance overview, host inventory, TLS
certs needing attention, and Domain Controller findings). Requires `reportlab`
(see `requirements.txt`); the endpoint returns HTTP 501 with guidance if it's
not installed.

### 4. Deep SSL/TLS certificate expiry tracking (toggle)

New **"SSL/TLS certs"** toggle inspects certificates on every TLS port and
reports **expired**, **expiring** (<= 30 days), or **weak** (MD5/SHA1/small-key)
certs with subject, issuer, expiry date and days remaining - in a new
**Certificates** tab and the compliance view.

---

# NetScan Xi v6

## New in v6 - Credential-exposure, Software inventory, Compliance, UI scheduling

Four additions, all reachable from the dashboard:

### 1. Credential-exposure detection (defensive)

A new **"Credential exposure"** scan-option toggle. When enabled it runs
detection-only NSE scripts (`ssl-enum-ciphers`, `http-auth`, `ftp-anon`,
`ssh-auth-methods`, `rdp-ntlm-info`, `banner`) to surface **weak / cleartext
authentication** and **exposed or unauthenticated services**.

> ⚠️ This is **defensive only**. It identifies risk (e.g. "FTP accepts logins
> without TLS", "Redis exposed with no auth") so you can fix it. It does **not**
> brute-force, capture, or guess credentials - password-grabbing / `*-brute`
> scripts are deliberately excluded.

Findings (severity + remediation) appear per host and feed the compliance view.

### 2. Enhanced software & application inventory

The scan now builds a full **per-host software inventory** - product, version,
service, port, OS/device type and CPEs for every detected application. Browse it
in the new **Software** tab (filterable across all hosts). Best results with the
*Running services* option enabled (`-sV`).

### 3. Regulatory compliance cross-reference

Each host is cross-referenced against **PCI DSS, GDPR, ISO 27001, SOC 2,
HIPAA, Cyber Essentials, NIST CSF and NCSC CAF**. Issues are mapped to specific named controls - e.g. cleartext auth →
*PCI DSS 4.2.1 / HIPAA 164.312(e)(1)*; known-exploited vuln → *ISO 27001 A.8.8*.

- Dashboard shows a **site-wide compliance summary** (pass/fail per framework).
- The new **Compliance** tab shows a per-host pass/fail grid; click a host to
  expand the exact failing controls and the evidence behind each.

### 4. UI-managed scheduled scanning

Scheduling is no longer env-only. Open **Schedules** in the header (operator+)
to add named recurring scans with a target, profile, interval, and the creds
option - enable/disable, **Run now**, or delete. Schedules are persisted in the
`schedules` table and survive restarts.

> The legacy `NETSCAN_SCHEDULE_MINUTES` / `_TARGET` / `_PROFILE` env config
> still works and is auto-seeded as an editable schedule on first boot.

---

# NetScan Xi v5

## New in v5 - Multi-Factor Authentication (TOTP)

Per-user **two-factor authentication** with authenticator apps (TOTP) plus
one-time backup codes.

- **Require MFA** toggle when creating a user, or per-user in the **Users**
  panel (admins can also **reset MFA** if someone loses their device).
- Enforced users are **prompted to enroll** on next login: scan a QR code, then
  confirm a 6-digit code. They receive **10 one-time backup codes** (shown once).
- Subsequent logins ask for the 6-digit code (or a backup code) after the
  password.
- TOTP secrets and backup codes are stored hashed; needs `pyotp` + `qrcode`
  (see `requirements.txt`). Optional `NETSCAN_MFA_ISSUER` sets the label shown
  in the authenticator app (default "NetScan Xi").

---

# NetScan Xi v4

## New in v4 - User Accounts & Roles

NetScan Xi now supports **multi-user login with role-based access** (replacing
the single shared password, which still works as a fallback until you create
accounts).

**Roles**

| Role | Can do |
|------|--------|
| `admin` | Everything, including user management |
| `operator` | Run / cancel / re-scan + everything a viewer can |
| `viewer` | Read-only: dashboard, assets, history, export |

**Create the first admin** (any one of these):

```bash
# CLI (recommended)
python -m app.server seed-admin --username admin
# (prompts for password if --password omitted)

# or via env vars on a fresh install (auto-creates on first boot)
export NETSCAN_ADMIN_USER=admin
export NETSCAN_ADMIN_PASSWORD='a-strong-password'
```

After that, manage users from the **Users** link in the header (admin only):
add users, set roles, reset passwords, delete. Passwords are hashed with
Werkzeug (PBKDF2); the last remaining admin can never be deleted or demoted.

> Set **`NETSCAN_SECRET`** to a long random string so login sessions survive
> restarts. Auth is only enforced once accounts exist *or* `NETSCAN_PASSWORD`
> is set - otherwise the app stays open (single-user mode), exactly like before.

---

# NetScan Xi v3

A self-hosted Flask web app for **Debian** that scans your local network,
identifies what's on it, finds vulnerabilities, scores risk, and **watches for
changes over time**. The successor to the original LAN Scanner, with everything
turned up to eleven.

![dashboard](docs/dashboard.png)

## New in v3

- **Docker host detection** - flags hosts running Docker / a container runtime
  (Docker API, Swarm, etcd, kubelet, k8s API ports + the `docker-version` NSE
  probe), shows engine version and an **⚠ API-exposed** warning, with a
  dedicated Docker section in each asset's detail and a dashboard count.
- **Selectable scan options** - tick/untick **Ports**, **Running services**,
  **OS detection**, **Docker hosts**, and **Vulnerabilities** before scanning;
  the nmap command is built to match.
- **Dynamic progress bar** that polls and updates roughly **every 1 second**
  (nmap runs with `--stats-every 1s`).
- **Scan start time + live elapsed timer** shown above the progress bar, with a
  final "completed in mm:ss".
- Recent Changes / Top-Vulns panels capped at **150px** and scrollable so they
  never elongate the page.
- **Light / Dark mode toggle** - a header button switches themes; the choice is
  saved in `localStorage` and applied before first paint (no flash). Defaults to
  your OS `prefers-color-scheme`. Works on both the dashboard and login page.

## What's new vs. the original LAN Scanner

| Area | v1 | v2 |
|---|---|---|
| Storage | in-memory (lost on restart) | **SQLite** with full scan history |
| Scan depth | one fixed deep scan | **profiles**: quick / standard / deep |
| Progress | basic bar | live bar **+ stop/cancel** |
| Concurrency | 409 if busy | **job queue** (manual + scheduled coexist) |
| Vulns | raw nmap NSE | NSE **+ CISA KEV + optional NVD** enrichment |
| Triage | none | **risk score** + **device-type** guessing |
| Monitoring | none | **change detection** + **alerts** (webhook/email) |
| Automation | none | **scheduled** recurring scans |
| Dashboard | table only | **summary cards + Top-10 vulnerabilities** |
| Output | none | **CSV / JSON export** |
| Access | open | optional **password auth** |
| UX | sortable table | search/filter, per-host re-scan, history view |

## Features

- **🐳 Deep Docker / container scanning (v10r1)** - authenticated Engine
  API inventory (containers + images), per-image CVE scanning (Trivy/Grype) with
  KEV/EPSS enrichment, a CIS Docker benchmark audit, registry/SBOM/orchestration
  awareness, plus dashboard tiles, per-host detail and container drift detection.
- **Dashboard** with summary cards (hosts, vulns, KEV count, high-risk assets,
  critical changes) and a **Top 10 Vulnerabilities** panel ranked by
  Known-Exploited → exploit-available → CVSS → host spread.
- **Two-phase scanning for speed** - for a network range, a fast ping/ARP
  discovery sweep finds live hosts first, then the heavy service/OS/vuln scan
  runs **only against hosts that are actually up**. On a typical /24 with a
  handful of live devices this cuts wall-clock time by roughly 50-80% vs.
  scanning all 254 addresses. Single-IP targets skip discovery.
- **Scan profiles**
  - *Quick* - top 100 ports, light service detection, no vuln scripts (seconds).
  - *Standard* - top 1000 ports + OS + service detection.
  - *Deep* - adds `--script vuln` for CVE detection.
- **Live progress bar** with phase labels and a **Stop** button that actually
  kills the nmap process.
- **Job queue** so a scheduled scan won't collide with a manual one.
- **Per-asset CVE codes + mitigation suggestions** - each finding in an asset's
  detail panel shows its **CVE code** (linked to NVD) and a **mitigation
  suggestion**: CISA's authoritative required-action for KEV vulns, service- or
  product-specific hardening advice otherwise.
- **Vulnerability identification** via nmap's `vuln` NSE scripts, enriched with
  the **CISA Known Exploited Vulnerabilities** catalog (flagged `KEV`) and,
  optionally, **NVD** for CVSS scores + descriptions.
- **Risk scoring** (0-100) per asset from vulns, exploitability, exposed-port
  count, and dangerous services (telnet/FTP/RDP/SMB/VNC...).
- **Device-type guessing** from MAC vendor + open-port fingerprints
  (router, camera, printer, NAS, IoT, phone, ...).
- **Software / application inventory** - per-host list of every detected app
  with product, version, service, port and CPE ids (v6).
- **Regulatory compliance cross-reference** against **PCI DSS, GDPR, ISO 27001,
  SOC 2, HIPAA, Cyber Essentials, NIST CSF and NCSC CAF** (v6-v8r3).
- **Credential-exposure detection** (defensive) - cleartext logins, exposed /
  unauthenticated services, weak TLS (v6).
- **Active Directory / Domain Controller auditing** - DC identification + SMB
  signing / SMBv1 / LDAPS / Kerberos posture (v7).
- **SSL/TLS certificate expiry tracking** - expired / expiring / weak certs (v7).
- **Change detection** - every scan is diffed against the previous one:
  new/gone hosts, opened/closed ports, service-version changes, **new
  vulnerabilities**, OS fingerprint changes.
- **Alerting** - notable changes are pushed to a **webhook** (Slack/Discord/
  generic) and/or **email** (SMTP).
- **Scheduled scans** - managed from the UI (add/enable/run-now) or seeded via
  env vars (v6).
- **Export** the current scan as **CSV**, **JSON**, or a **branded PDF report**
  (v7).
- **Multi-user accounts & roles** (admin/operator/viewer, v4) with optional
  **TOTP multi-factor authentication** + backup codes (v5).
- **Per-host re-scan**, **search/filter**, **expandable detail** view, and a
  **scan history** tab.
- Optional **password protection** for the whole UI.

---

## Quick start (Docker - recommended)

```bash
cd netscan-xi
docker compose up --build
```

Open **http://localhost:5000** (or `http://<host-ip>:5000`).

> **Linux only for real scanning.** `network_mode: host` + `NET_ADMIN`/`NET_RAW`
> let nmap see your physical LAN and do SYN/OS detection. On Docker Desktop for
> Mac/Windows the container runs in a VM and host networking won't reach your
> real network - use the native install there.

Scan history and CVE caches persist in `./data` (mounted as a volume).

## Native install (no Docker)

```bash
sudo apt update && sudo apt install -y nmap python3 python3-venv
cd netscan-xi
chmod +x run.sh
sudo ./run.sh                 # http://localhost:5000
sudo ./run.sh 127.0.0.1 8080  # custom host/port
```

Root is needed for `-O` (OS detection) and `-sS` (SYN scan).

### Python dependencies

Installed automatically by `run.sh` / the Docker image from `requirements.txt`:

| Package | Used for |
|---|---|
| `Flask`, `Werkzeug` | web server + password hashing |
| `pyotp` | TOTP multi-factor authentication (v5) |
| `qrcode[pil]` | MFA enrollment QR codes (v5) |
| `reportlab` | **branded PDF report export (v7)** |

To install manually: `pip install -r requirements.txt`.

> **PDF export is optional at runtime.** If `reportlab` is missing, CSV/JSON
> export still work and the PDF endpoint returns HTTP 501 with a hint to
> install it. Everything else degrades gracefully.

---

## Configuration (environment variables)

All optional - the app works out of the box with safe defaults.

| Variable | Default | Purpose |
|---|---|---|
| `NETSCAN_PASSWORD` | *(unset)* | Enables login. Unset = open access. |
| `NETSCAN_SECRET` | random | Flask session signing key (set for stable sessions). |
| `NETSCAN_USE_NVD` | `0` | `1` to enrich CVEs via the NVD API (CVSS + descriptions). |
| `NETSCAN_DB` | `data/netscan.db` | SQLite path. |
| `NETSCAN_SCHEDULE_MINUTES` | `0` | Recurring scan interval (0 = off). |
| `NETSCAN_SCHEDULE_TARGET` | auto `/24` | Target for scheduled scans. |
| `NETSCAN_SCHEDULE_PROFILE` | `standard` | Profile for scheduled scans. |
| `NETSCAN_WEBHOOK_URL` | *(unset)* | Slack/Discord/generic webhook for alerts. |
| `NETSCAN_ALERT_MIN_SEV` | `warn` | Minimum severity to alert (`info`/`warn`/`critical`). |
| `NETSCAN_SMTP_HOST` ... `_TO` | *(unset)* | SMTP email alerting (host/port/user/pass/from/to). |
| `NETSCAN_ADMIN_USER` / `NETSCAN_ADMIN_PASSWORD` | *(unset)* | Auto-create first admin on a fresh install. |
| `NETSCAN_MFA_ISSUER` | `NetScan Xi` | Label shown in authenticator apps for MFA (v5). |

> Scheduling can also be managed from the UI (**Schedules**, v6); the
> `NETSCAN_SCHEDULE_*` vars seed an initial editable schedule on first boot.
> PDF / AD-audit / SSL-cert / credential-exposure features are toggled per scan
> in the UI (v6-v7), not via env vars.

Example - a hardened, scheduled, alerting deployment:

```bash
export NETSCAN_PASSWORD="supersecret"
export NETSCAN_SECRET="$(openssl rand -hex 32)"
export NETSCAN_USE_NVD=1
export NETSCAN_SCHEDULE_MINUTES=360          # every 6 hours
export NETSCAN_SCHEDULE_PROFILE=deep
export NETSCAN_WEBHOOK_URL="https://hooks.slack.com/services/XXX/YYY/ZZZ"
export NETSCAN_ALERT_MIN_SEV=critical
sudo -E ./run.sh
```

---

## How vulnerability ranking works

Each finding is annotated and the dashboard's Top 10 is sorted by:

1. **KEV** - in CISA's Known Exploited Vulnerabilities catalog (actively
   exploited in the wild). Highest priority.
2. **Exploit available** - nmap/`vulners` flagged a public exploit.
3. **CVSS score** - highest base score wins.
4. **Host spread** - how many assets are affected.

The per-asset **risk score** combines all of a host's findings with its
exposure (open ports, risky services) into a single 0-100 number for triage.

---

## Architecture

```
app/
├── server.py     Flask routes, auth, dashboard/export APIs
├── manager.py    single-worker job queue, progress, cancel, orchestration
├── scanner.py    nmap profiles, live progress parsing, process control
├── parser.py     nmap XML -> hosts, risk scoring, device-type guessing
├── enrich.py     CISA KEV + optional NVD CVE enrichment (cached)
├── diff.py       change detection between consecutive scans
├── alerts.py     webhook + SMTP alerting
├── exporter.py   CSV / JSON export
├── scheduler.py  interval-based recurring scans
├── db.py         SQLite persistence + Top-10 vuln aggregation
├── templates/    index.html, login.html
└── static/       style.css, app.js
```

---

## Notes & gotchas

- **Only scan networks you own or are authorised to scan.** Port and
  vulnerability scanning other people's networks can be illegal.
- **Root** is required for accurate OS detection and SYN scans.
- **Performance tuning** - scans use a two-phase live-host discovery pass plus
  timing flags (`--min-rate`, `--max-retries 2`, `-n` to skip reverse-DNS, and
  a per-host `--host-timeout` so one slow host can't stall the whole scan).
  These are tuned for LAN speed; on lossy/remote networks you may want to relax
  `--max-retries`/`--host-timeout` in `app/scanner.py`.
- **Deep scans are still the slowest** - `--script vuln` adds real time. Use
  *quick* or *standard* for fast discovery, *deep* when you want CVEs.
- **Vuln findings are leads, not gospel** - confirm before acting. KEV/NVD
  enrichment improves signal but nmap's NSE output is still heuristic.
- **NVD rate limits** - without an API key, enrichment is throttled and capped
  per scan (cached afterwards). It degrades gracefully offline.
- **Auth is basic** by design (single shared password). For exposure beyond
  your LAN, put it behind a reverse proxy with TLS.

## Run as a service (optional)

```ini
# /etc/systemd/system/netscan-xi.service
[Unit]
Description=NetScan Xi
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/netscan-xi
EnvironmentFile=/opt/netscan-xi/.env
ExecStart=/opt/netscan-xi/.venv/bin/python -m app.server --host 0.0.0.0 --port 5000
Restart=on-failure

[Install]
WantedBy=multi-user.target
```