admin / Synapse-NetscanXi

public
Network Scanning, Vulnerability and Compliance Application
Code Issues Pull requests Pipelines Packages Security Insights Wiki Settings
Synapse-NetscanXi / NetscanXiVersion13 / docs / user-guide.html 69794 B · main
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>NetscanXi Version 13 - Admin &amp; User Guide</title>
<style>
  @page { size: A4; margin: 18mm 16mm 18mm 16mm; }
  * { box-sizing: border-box; }
  html { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
  body {
    font-family: "Segoe UI", -apple-system, Roboto, Helvetica, Arial, sans-serif;
    color: #1c2430; font-size: 10.5pt; line-height: 1.5; margin: 0;
  }
  h1, h2, h3 { color: #0f2a47; font-weight: 700; }
  h2 { font-size: 15pt; margin: 22px 0 8px; padding-bottom: 5px;
       border-bottom: 2px solid #2496ed; }
  h3 { font-size: 12pt; margin: 16px 0 4px; color: #14507a; }
  p { margin: 6px 0; }
  ul, ol { margin: 6px 0 6px 0; padding-left: 20px; }
  li { margin: 3px 0; }
  code { font-family: "Consolas", "SF Mono", monospace; background: #eef3f8;
         padding: 1px 5px; border-radius: 4px; font-size: 9.5pt; color: #0a3d62; }
  pre { background: #0f1419; color: #e6edf3; padding: 12px 14px; border-radius: 7px;
        font-family: "Consolas", monospace; font-size: 9pt; line-height: 1.45;
        overflow-x: auto; white-space: pre-wrap; }
  pre code { background: none; color: inherit; padding: 0; }
  .keep { page-break-inside: avoid; }
  .pagebreak { page-break-before: always; }

  /* Cover */
  .cover { height: 247mm; display: flex; flex-direction: column;
           justify-content: center; align-items: center; text-align: center;
           page-break-after: always; }
  .cover .logo { font-size: 54pt; margin-bottom: 4px; }
  .cover h1 { font-size: 40pt; margin: 0; color: #0f2a47; letter-spacing: -1px; }
  .cover h1 .x { color: #1f9d3a; }
  .cover .ver { display: inline-block; margin-top: 12px; background: #1f9d3a;
                color: #fff; font-weight: 700; padding: 4px 16px; border-radius: 20px;
                font-size: 13pt; }
  .cover .tag { color: #5a6675; font-size: 13pt; margin-top: 18px; max-width: 135mm; }
  .cover .foot { position: absolute; bottom: 22mm; color: #8b97a5; font-size: 9.5pt; }

  /* Feature badges */
  .badges { margin: 4px 0 0; }
  .badge { display: inline-block; background: #eef3f8; border: 1px solid #cfe0f0;
           color: #14507a; border-radius: 14px; padding: 2px 10px; font-size: 9pt;
           margin: 3px 4px 3px 0; font-weight: 600; }

  /* Part divider */
  .part { background: #0f2a47; color: #fff; border-radius: 9px; padding: 14px 18px;
          margin: 26px 0 12px; page-break-inside: avoid; }
  .part h2 { color: #fff; border: none; margin: 0; padding: 0; font-size: 17pt; }
  .part p { margin: 4px 0 0; color: #b9c7d8; font-size: 10pt; }

  /* Callout boxes */
  .note, .warn, .tip, .role {
    border-radius: 7px; padding: 9px 12px; margin: 10px 0; font-size: 9.8pt;
    border-left: 4px solid; page-break-inside: avoid;
  }
  .note { background: #eef3f8; border-color: #2496ed; }
  .warn { background: #fdeceb; border-color: #d12d24; }
  .tip  { background: #eafaf0; border-color: #1f9d3a; }
  .role { background: #f3eefe; border-color: #7b46d1; }
  .note b, .tip b, .warn b, .role b { color: #0f2a47; }

  /* Tables */
  table { width: 100%; border-collapse: collapse; margin: 8px 0; font-size: 9.5pt; }
  th, td { text-align: left; padding: 6px 9px; border: 1px solid #d4dae0;
           vertical-align: top; }
  th { background: #0f2a47; color: #fff; font-weight: 600; }
  tr:nth-child(even) td { background: #f4f7fa; }

  .toc li { margin: 4px 0; }
  .toc a { color: #14507a; text-decoration: none; }
  .toc .grp { font-weight: 700; color: #0f2a47; margin-top: 8px; }
  .lead { font-size: 11pt; color: #34404e; }
  .pill { display:inline-block; background:#0f2a47; color:#fff; border-radius:5px;
          padding:1px 7px; font-size:9pt; font-weight:600; }
  .pill.green { background:#1f9d3a; } .pill.amber { background:#9a6700; }
  .pill.red { background:#d12d24; } .pill.purple { background:#7b46d1; }
</style>
</head>
<body>

<!-- ============ COVER ============ -->
<div class="cover">
  <div class="logo">🛰️</div>
  <h1><span class="x">N</span>etscanXi</h1>
  <div class="ver">Version 13 - Admin &amp; User Guide</div>
  <div class="tag">Discover every device on your network, identify software and
    vulnerabilities, audit Active Directory and TLS, score risk, map compliance, and
    watch for change - and now look <b>inside your Docker hosts</b> with deep
    container &amp; image vulnerability scanning - secured with user accounts,
    roles, MFA and multi-tenant data separation, all from one self-hosted
    dashboard.</div>
  <div class="badges" style="margin-top:24px; max-width:160mm;">
    <span class="badge">Asset Discovery</span>
    <span class="badge">Service &amp; Software ID</span>
    <span class="badge">🐳 Docker Detection</span>
    <span class="badge">Vulnerability Scanning</span>
    <span class="badge">Risk Scoring</span>
    <span class="badge">Change Detection</span>
    <span class="badge">Compliance Mapping</span>
    <span class="badge">AD / DC Audit</span>
    <span class="badge">TLS Cert Tracking</span>
    <span class="badge">PDF Reports</span>
    <span class="badge">Accounts · Roles · MFA</span>
    <span class="badge">🏢 Multi-Tenancy</span>
    <span class="badge">📋 Activity Log</span>
    <span class="badge">📡 Passive Scanning</span>
    <span class="badge">🆔 Unique Asset IDs</span>
    <span class="badge">🗓️ Day/Time Scheduling</span>
    <span class="badge">✎ Editable Asset Type</span>
    <span class="badge">🐳 Deep Docker Scanning</span>
    <span class="badge">📦 Container Inventory</span>
    <span class="badge">🔎 Image CVE Scanning</span>
    <span class="badge">🛡️ CIS Docker Audit</span>
  </div>
  <div class="foot">Self-hosted · Flask + nmap · Built for Debian &nbsp;|&nbsp; © 2026</div>
</div>

<!-- ============ TOC ============ -->
<h2>Contents</h2>
<ol class="toc">
  <li class="grp">Part I - Everyone</li>
  <li><a href="#intro">1. What is NetscanXi?</a></li>
  <li><a href="#dashboard">2. The Dashboard at a Glance</a></li>
  <li><a href="#login">3. Signing In &amp; Your Account</a></li>
  <li><a href="#mfa">4. Account Security: Password &amp; Two-Factor</a></li>
  <li class="grp">Part II - Using NetscanXi (Operators &amp; Admins)</li>
  <li><a href="#scanning">5. Running a Scan</a></li>
  <li><a href="#options">6. Scan Options &amp; Profiles</a></li>
  <li><a href="#assets">7. Reading Asset Details &amp; Sorting/Filtering</a></li>
  <li><a href="#vulns">8. Vulnerabilities, CVEs &amp; Mitigations</a></li>
  <li><a href="#tabs">9. Software, Compliance, Certificates &amp; AD Tabs</a></li>
  <li><a href="#docker">10. Docker Host Detection</a></li>
  <li><a href="#changes">11. Change Detection &amp; Alerts</a></li>
  <li><a href="#export">12. Exporting Reports (Full &amp; Single-Host)</a></li>
  <li><a href="#schedule">13. Scheduled Scans</a></li>
  <li class="grp">Part III - Administration</li>
  <li><a href="#roles">14. Roles &amp; Permissions</a></li>
  <li><a href="#users">15. User Administration</a></li>
  <li><a href="#tenancy">16. Multi-Tenancy &amp; Data Separation</a></li>
  <li><a href="#activity">17. Activity &amp; Audit Log</a></li>
  <li><a href="#install">18. Installation &amp; First-Run Setup</a></li>
  <li><a href="#config">19. Configuration Reference</a></li>
  <li><a href="#tips">20. Safety, Tips &amp; Troubleshooting</a></li>
  <li class="grp">Part IV - New in Version 9.1</li>
  <li><a href="#charts">21. Interactive Dashboard Charts</a></li>
  <li><a href="#lifecycle">22. CVE Finding Lifecycle &amp; Status</a></li>
  <li><a href="#multiselect">23. Multi-Select Asset Table &amp; Bulk Actions</a></li>
  <li><a href="#tenantadmin">24. The Tenant Admin Role</a></li>
  <li><a href="#search">25. Global Search Bar</a></li>
  <li><a href="#retention">26. Data-Retention Policies</a></li>
  <li><a href="#patchaware">27. Patch-Aware Vulnerability Assessment</a></li>
  <li><a href="#trends">28. Historical Trend Graphs</a></li>
  <li><a href="#integrations">29. Service-Desk Integrations</a></li>
  <li><a href="#customdash">30. Customisable Dashboard</a></li>
  <li><a href="#api91">31. API Additions in 9.1</a></li>
  <li class="grp">Part V - New in Version 10r1 (Docker)</li>
  <li><a href="#dk-intro">32. Deep Docker Scanning Overview</a></li>
  <li><a href="#dk-api">33. Authenticated Docker API Inventory</a></li>
  <li><a href="#dk-containers">34. Containers &amp; Images in the Host View</a></li>
  <li><a href="#dk-imgcve">35. Image Vulnerability Scanning (Trivy / Grype)</a></li>
  <li><a href="#dk-cis">36. CIS Docker Benchmark Audit</a></li>
  <li><a href="#dk-dash">37. The Docker Dashboard Panel</a></li>
  <li><a href="#dk-drift">38. Container Drift &amp; Exports</a></li>
  <li><a href="#dk-howto">39. Step-by-Step: Running a Deep Docker Scan</a></li>
  <li><a href="#dk-apiref">40. API &amp; Configuration Reference (10r1)</a></li>
  <li class="grp">Part VI - New in Version 13 (Patch and Remedy)</li>
  <li><a href="#pa-intro">41. Patch and Remedy Overview</a></li>
  <li><a href="#pa-run">42. Running a Patch (OS or Docker; Single / Group / All)</a></li>
  <li><a href="#pa-ref">43. Patch API, Safety &amp; Audit Reference</a></li>
  <li><a href="#pa-remediation">44. Remediation Tracking: Multi-Select Delete &amp; Comments</a></li>
</ol>

<!-- ===================================================================== -->
<div class="part">
  <h2>Part I - Everyone</h2>
  <p>For all signed-in users, whatever their role.</p>
</div>

<!-- ============ 1 INTRO ============ -->
<h2 id="intro">1. What is NetscanXi?</h2>
<p class="lead">NetscanXi is a self-hosted web application that scans your local
network and tells you exactly what's on it - now with full account security and
multi-team data separation.</p>
<p>It wraps the industry-standard <code>nmap</code> scanner in a clean dashboard and
layers on risk scoring, vulnerability enrichment, Docker detection, regulatory
compliance mapping, Active-Directory and TLS auditing, change tracking and alerting.
Point it at your network and you get a sortable, searchable inventory of every live
host - its software, open ports, OS, known vulnerabilities (with fixes) and an
at-a-glance risk score.</p>
<div class="note"><b>Who it's for:</b> home-lab owners, sysadmins, MSPs and
security-minded teams who want continuous visibility of one or many networks without
heavy enterprise tooling. If you can run <code>docker compose up</code>, you can run
NetscanXi.</div>

<h3>What's new in Version 9.1</h3>
<ul>
  <li><b>📡 Passive scanning</b> - a one-click, listen-only mode that discovers assets
      <i>without sending any probe traffic</i>. It reads the ARP/neighbour cache and
      overhears self-announcements (mDNS, SSDP/UPnP) to harvest IP, MAC, vendor,
      hostname, advertised services and a low-confidence device type. No ports, service
      versions, OS accuracy, vulnerabilities, TLS/AD/Docker or credential findings are
      produced - those require an active scan.</li>
  <li><b>🆔 Unique 8-character asset IDs</b> - every discovered device is assigned a
      stable <code>[A-Z0-9]</code> ID <i>bound to its MAC address</i> and stored in
      NetscanXi. The same physical device keeps the same ID across scans, so newly found
      vulnerabilities are attributed to the asset rather than duplicated.</li>
  <li><b>🗓️ Day &amp; time scheduling</b> - schedule scans by ticking the days of the week
      and entering an hour and minute, in addition to the classic “every N minutes”
      interval. Each schedule can run an Active or Passive scan.</li>
  <li><b>✎ Editable asset Type</b> - correct a mis-identified device type inline. The
      correction is bound to the asset's ID and re-applied on every future scan.</li>
  <li><b>🏷️ Scan-type on every report</b> - CSV, JSON and PDF exports now clearly state
      whether the data came from a <b>Passive</b> or <b>Active</b> scan, and include the
      asset ID per device.</li>
</ul>

<h3>What's new in version 8</h3>
<ul>
  <li><b>🏢 Soft multi-tenancy</b> - users, scans and schedules carry a <i>tenant</i>
      tag; people see only their tenant's data, while admins see everything.</li>
  <li><b>📋 Activity &amp; audit log</b> - login/logout times plus scans, exports and
      admin actions, all timestamped with user, tenant and client IP.</li>
  <li><b>📄 Single-host report export</b> - export CSV/JSON/PDF for just one host.</li>
  <li><b>Sort &amp; filter everywhere</b> - Software, Certificates and Compliance tabs
      gain filters and sortable columns.</li>
  <li><b>Live scanning IP</b> - the progress area shows the exact host nmap is working
      on right now.</li>
  <li><b>Refreshed UI</b> - a clean text banner replaces the logo, and the top-right
      links become action buttons (Schedule, Security, User Admin, Activity, Logout).</li>
</ul>
<p>Version 8 builds on accounts &amp; roles (v4), TOTP MFA (v5), credential-exposure,
software inventory, compliance and UI scheduling (v6), and Cyber-Essentials mapping,
AD/DC auditing, PDF reports and TLS cert tracking (v7).</p>

<!-- ============ 2 DASHBOARD ============ -->
<h2 id="dashboard" class="pagebreak">2. The Dashboard at a Glance</h2>
<p>The main screen is organised top-to-bottom:</p>
<table>
  <tr><th>Area</th><th>What it shows</th></tr>
  <tr><td><b>Banner</b></td><td>The <b>NetscanXi Version 13</b> text banner and tagline.</td></tr>
  <tr><td><b>Top bar</b></td><td>Your username + role tag, your <span class="pill">🏢 tenant</span>
      (if scoped), scheduler status, and the action buttons:
      <span class="pill">🌓 theme</span>, <b>⏱ Schedule</b>, <b>🔐 Security</b>,
      <b>👥 User Admin</b> (admins), <b>📋 Activity</b> (admins), <b>⎋ Logout</b>.</td></tr>
  <tr><td><b>Controls bar</b></td><td>Target box, profile selector, <b>Scan</b>, <b>Passive Scan</b>, <b>Stop</b>
      buttons, and <b>Export CSV / JSON / PDF</b>.</td></tr>
  <tr><td><b>Scan options</b></td><td>Checkboxes: Ports, Running services, OS detection,
      Docker hosts, Vulnerabilities, Credential exposure, AD/DC audit, SSL/TLS certs.</td></tr>
  <tr><td><b>Progress</b></td><td>Live bar with start time, elapsed timer, current phase,
      and the <b>IP currently being scanned</b>.</td></tr>
  <tr><td><b>Summary cards</b></td><td>Hosts, Vulnerabilities, Known-Exploited (KEV),
      High-risk assets, Docker hosts, Critical changes.</td></tr>
  <tr><td><b>Compliance / Top-10 / Recent Changes</b></td><td>Regulatory posture, the
      highest-priority findings, and what changed since last scan.</td></tr>
  <tr><td><b>Tabs</b></td><td>Assets · Software · Compliance · Certificates ·
      Active Directory · Scan History.</td></tr>
</table>

<!-- ============ 3 LOGIN ============ -->
<h2 id="login">3. Signing In &amp; Your Account</h2>
<p>If your administrator has enabled authentication, you'll land on a sign-in page.
Enter your <b>username</b> and <b>password</b>. If MFA is set up, you'll then be asked
for a 6-digit code (see §4).</p>
<ul>
  <li><b>Your role</b> appears as a tag next to your name (viewer / operator / admin).
      It controls what you can do - see §14.</li>
  <li><b>Your tenant</b> is shown as a 🏢 badge if you're scoped to one team's data.</li>
  <li><b>Logout</b> - use the <b>⎋ Logout</b> button in the top bar. Your login and
      logout times are recorded in the activity log.</li>
</ul>
<div class="note"><b>Open mode:</b> if no accounts exist and no password is set, the
dashboard is open and everything runs under a single <code>default</code> tenant. Admins
should secure it before exposing it beyond localhost (§18).</div>

<!-- ============ 4 MFA ============ -->
<h2 id="mfa">4. Account Security: Password &amp; Two-Factor</h2>
<p>Click <b>🔐 Security</b> in the top bar to open the <b>Account Security</b> panel, where
you manage your own password and two-factor authentication.</p>

<h3>Change your password (self-service)</h3>
<p>In the <b>Change your password</b> section, enter your <b>current password</b>, then a
<b>new password</b> (at least 8 characters) and confirm it. Click <b>Update password</b>.
The change takes effect immediately and is recorded in the activity log. If you get the
current password wrong, the update is refused.</p>
<div class="tip"><b>Locked out and can't sign in at all?</b> You can't reach this panel
without logging in — ask an administrator to reset your password for you (§15).</div>

<h3>Two-factor authentication (TOTP)</h3>
<ol>
  <li>Open <b>Security</b>; a QR code and secret appear.</li>
  <li>Scan it with an authenticator app (Google Authenticator, Authy, 1Password...).</li>
  <li>Enter the current 6-digit code to confirm and enable MFA.</li>
  <li><b>Save your backup codes</b> - shown once, each usable a single time if you lose
      your device. You can regenerate them later (this invalidates the old set).</li>
</ol>
<ul>
  <li>At next sign-in you'll enter your password, then your authenticator code. Lost your
      phone? Choose <b>"Use a backup code instead."</b></li>
  <li>You can <b>disable MFA</b> yourself unless an admin has <i>enforced</i> it for your
      account.</li>
</ul>
<div class="tip"><b>Admins can require MFA</b> per user. If required but not yet set up,
you'll be prompted to enrol at login.</div>

<!-- ===================================================================== -->
<div class="part">
  <h2>Part II - Using NetscanXi</h2>
  <p>Day-to-day scanning and reporting. Requires the <b>operator</b> or <b>admin</b>
     role (viewers can read and export, but not start scans).</p>
</div>

<!-- ============ 5 SCANNING ============ -->
<h2 id="scanning">5. Running a Scan</h2>
<ol>
  <li>The <b>target</b> box auto-fills with your detected network (e.g.
      <code>192.168.1.0/24</code>). Edit it for a range or single host
      (<code>192.168.1.10</code>).</li>
  <li>Pick a <b>profile</b> (§6) and tick the <b>scan options</b> you want.</li>
  <li>Click <b>Scan</b>. The progress bar shows live percentage, current phase, start
      time, elapsed time, and the <b>IP currently being scanned</b>.</li>
  <li>Click <b>Stop</b> to cleanly terminate a running scan.</li>
  <li>When finished, the dashboard and tabs populate automatically.</li>
</ol>
<div class="tip"><b>Faster scans:</b> NetscanXi runs a quick host-discovery sweep first,
then only deep-scans hosts that are actually online - far faster than probing every
address in a range.</div>
<div class="role"><b>Multi-tenant note:</b> a scan you start is tagged with <i>your</i>
tenant. Scoped users only ever see and re-run scans within their own tenant; admins see
all (§16).</div>

<h3>Active vs Passive scanning (v9)</h3>
<p>NetscanXi offers two acquisition modes:</p>
<table>
  <tr><th></th><th>Active Scan</th><th>Passive Scan</th></tr>
  <tr><td><b>How</b></td><td>Sends nmap probes (SYN, service/version, OS, NSE scripts) to targets.</td>
      <td><b>Sends no probe traffic.</b> Listens only: reads the ARP/neighbour cache and overhears mDNS / SSDP-UPnP self-announcements.</td></tr>
  <tr><td><b>Options</b></td><td>Full set of profile + selectable options.</td><td>None - one button, fixed output.</td></tr>
  <tr><td><b>Finds</b></td><td>IP, MAC, vendor, hostname, OS+accuracy, open ports, services/versions, software, vulnerabilities/CVEs, Docker, TLS, AD, compliance, risk score.</td>
      <td>IP, MAC, vendor, hostname, advertised services, low-confidence device type &amp; OS hint, first/last seen, asset ID.</td></tr>
  <tr><td><b>Does <u>not</u> find</b></td><td>—</td>
      <td>Open ports, service versions, OS accuracy, vulnerabilities/CVEs, TLS/AD/Docker/credential findings, risk score (shown as <code>n/a</code>).</td></tr>
  <tr><td><b>Use when</b></td><td>You need depth: ports, vulns, compliance.</td>
      <td>You need a zero-footprint inventory, or to discover quiet/sensitive devices without touching them.</td></tr>
</table>
<p>To run a passive scan, click <b>Passive Scan</b> in the controls bar. Passive assets
appear in the Assets table with a <span class="pill purple">Passive</span> badge and
<code>—</code> in the Ports/Vulns columns. When an <i>active</i> scan later runs against
the same device (matched by MAC), its full findings attach to the same asset ID.</p>
<div class="note"><b>No options for passive:</b> by design the passive scan has no
checkboxes - it returns exactly the asset attributes a passive observer can harvest, and
nothing that would require sending packets to the target.</div>

<!-- ============ 6 OPTIONS ============ -->
<h2 id="options">6. Scan Options &amp; Profiles</h2>
<h3>Profiles</h3>
<table>
  <tr><th>Profile</th><th>What it does</th><th>Speed</th></tr>
  <tr><td><b>Quick</b></td><td>Top 100 ports, light service detection, no vuln scripts.</td><td>Seconds</td></tr>
  <tr><td><b>Standard</b></td><td>Top 1000 ports + OS &amp; service detection.</td><td>Minutes</td></tr>
  <tr><td><b>Deep</b></td><td>Adds vulnerability NSE scripts for CVE detection.</td><td>Slower</td></tr>
</table>
<h3>Selectable options</h3>
<p>Independent of the profile, tick or untick any of these before scanning:</p>
<ul>
  <li><b>Ports</b> - scan ports at all (untick for discovery-only).</li>
  <li><b>Running services</b> - identify software/version behind each open port.</li>
  <li><b>OS detection</b> - fingerprint the operating system.</li>
  <li><b>Docker hosts</b> - probe Docker/container-runtime ports and the Docker API.</li>
  <li><b>Vulnerabilities</b> - run nmap's vuln scripts (slower, finds CVEs).</li>
  <li><b>Credential exposure</b> - <i>defensive</i> checks for cleartext logins, exposed
      services and weak TLS. Never brute-forces or captures credentials.</li>
  <li><b>AD / DC audit</b> - identify Domain Controllers and report directory hardening
      posture (defensive enumeration only; no password attacks).</li>
  <li><b>SSL/TLS certs</b> - inspect certificates for expiry and weak crypto.</li>
</ul>
<div class="note"><b>How it works:</b> your selections translate directly into the
underlying nmap command, so you only spend time on the checks you care about.</div>

<!-- ============ 7 ASSETS ============ -->
<h2 id="assets" class="pagebreak">7. Reading Asset Details &amp; Sorting/Filtering</h2>
<p>The asset table lists every live host. Click any <b>column header</b> to sort, use the
<b>filter box</b> to search by IP, hostname, OS, port, service or vulnerability, and click
any <b>row</b> to expand its full detail panel.</p>
<table>
  <tr><th>Column</th><th>Meaning</th></tr>
  <tr><td>Asset ID</td><td><b>(v9)</b> The device's stable 8-character ID, bound to its MAC address and reused across every scan.</td></tr>
  <tr><td>IP / Hostname</td><td>Address and resolved name. Passively-found assets carry a <span class="pill purple">Passive</span> badge here.</td></tr>
  <tr><td>Type</td><td>Guessed device type with a <span class="pill">🐳 Docker</span> badge when applicable. <b>(v9)</b> Click the ✎ pencil to correct a mis-identified type - the correction sticks to the asset on future scans.</td></tr>
  <tr><td>OS</td><td>Detected operating system with confidence %.</td></tr>
  <tr><td>Software</td><td>Lead application detected.</td></tr>
  <tr><td>Ports</td><td>Count of open ports.</td></tr>
  <tr><td>Risk</td><td>0-100 risk score (<span class="pill green">low</span>
      <span class="pill amber">med</span> <span class="pill red">high</span>). Shows <code>n/a</code> for passive-only assets.</td></tr>
  <tr><td>Vulns</td><td>Number of vulnerabilities found (<code>—</code> for passive assets).</td></tr>
</table>
<h3>Unique asset IDs &amp; correcting device type (v9)</h3>
<p>Each device gets a permanent <b>8-character alphanumeric asset ID</b> the first time
it's seen. The ID is keyed on the device's <b>MAC address</b> (or its IP when no MAC is
visible, e.g. routed hosts), so the same physical device is recognised on every
subsequent scan and its vulnerabilities are never double-counted.</p>
<p>If the scanner mislabels a device's <b>Type</b> (say it calls a NAS a “web server”),
click the <b>✎</b> next to the type, enter the correct value (e.g. <code>nas</code>,
<code>printer</code>, <code>camera</code>, <code>router</code>, <code>iot</code>) and save.
The override is stored against the asset ID and automatically re-applied whenever that
device is scanned again. Operators and admins can edit type; clearing the field reverts
to the scanner's guess.</p>
<p>The expanded panel shows an overview grid, the full vulnerability list, detected
software with CPE identifiers, a per-port breakdown, raw script output, a
<b>Re-scan</b> button, and per-host <b>Export</b> buttons (§12).</p>
<div class="tip"><b>Sorting &amp; filtering everywhere (v8):</b> the Software, Certificates
and Compliance tabs now have their own filter boxes and clickable sortable column
headers, and the Activity log is filterable too.</div>

<!-- ============ 8 VULNS ============ -->
<h2 id="vulns">8. Vulnerabilities, CVEs &amp; Mitigations</h2>
<p>When vulnerability scanning is enabled, each finding shows:</p>
<ul>
  <li>A <b>CVE code</b> linked to its full NVD entry.</li>
  <li>A <b>CVSS score</b>, colour-coded by severity.</li>
  <li>A <span class="pill">KEV</span> tag if it's in CISA's Known-Exploited catalog, and
      an <span class="pill">EXPLOIT</span> tag if a public exploit exists.</li>
  <li>A <b>🛠 Mitigation suggestion</b> - CISA's official remediation for KEV vulns, or
      tailored hardening advice otherwise.</li>
</ul>
<p>The <b>Top 10 Vulnerabilities</b> panel ranks findings network-wide by Known-Exploited
→ exploit-available → CVSS → number of affected hosts. Each entry shows the CVE id
(linked to NVD), CVSS score, KEV/EXPLOIT tags, the <b>full CVE description</b> and a
<b>&#128736; suggested mitigation</b> - the same detail now carried into every export.</p>
<div class="warn"><b>Treat findings as leads, not gospel.</b> nmap's vulnerability scripts
are heuristic; confirm against the vendor advisory before acting.</div>

<!-- ============ 9 TABS ============ -->
<h2 id="tabs">9. Software, Compliance, Certificates &amp; AD Tabs</h2>
<h3>Software inventory</h3>
<p>A flat, filterable, sortable list of every application/version detected across the
network, with its host, service and port.</p>
<h3>Compliance</h3>
<p>Each host is cross-referenced against eight frameworks - <b>PCI DSS, GDPR, ISO 27001,
SOC 2, HIPAA, Cyber Essentials, NIST CSF</b> and <b>NCSC CAF</b> - with pass/fail per
framework and a summary of at-risk hosts. Expand a row for the failing controls and
remediation. Filter by host or status.</p>
<p><b>New in Release 3:</b> the compliance engine now also maps each finding to
<b>NIST CSF</b> (Cybersecurity Framework) outcome categories - an internationally
recognised standard for private-sector enterprise buyers - and to the
<b>NCSC Cyber Assessment Framework (CAF)</b> objectives/principles, supporting UK
public-sector and operators-of-essential-services assurance requirements. Both appear
automatically in the dashboard summary, the per-host grid, the expandable control detail
and the PDF report.</p>
<h3>Certificates</h3>
<p>With <b>SSL/TLS certs</b> enabled, this tab lists discovered certificates with subject,
issuer, expiry date, days-left and a status (<span class="pill green">ok</span>
<span class="pill amber">expiring</span> <span class="pill red">expired/weak</span>).
Sort by days-left to find what to renew first.</p>
<h3>Active Directory</h3>
<p>With <b>AD / DC audit</b> enabled, detected Domain Controllers are listed with domain
and forest names and hardening findings (e.g. SMBv1 enabled, SMB signing not required,
LDAP without LDAPS).</p>
<div class="warn"><b>Defensive only.</b> The credential, AD and TLS checks never
brute-force, capture or guess credentials.</div>

<!-- ============ 10 DOCKER ============ -->
<h2 id="docker" class="pagebreak">10. Docker Host Detection</h2>
<p>NetscanXi flags hosts running Docker / a container runtime by combining open-port
signals (Docker API, Swarm, etcd, Kubernetes), service banners, and the
<code>docker-version</code> probe. Detected Docker hosts show a
<span class="pill">🐳 Docker</span> badge, a dashboard count, and a dedicated section
with engine version, ports and indicators.</p>
<div class="tip"><b>New in 10r1:</b> this network-level detection is now the
<i>entry point</i> to a much deeper view. With <b>Deep Docker scan</b> enabled,
NetscanXi pulls the container/image inventory from the Docker API, scans images
for CVEs and runs a CIS Docker audit. See <b>Part V</b> (§32-40) for the full
workflow.</div>
<div class="warn"><b>⚠ Exposed Docker API:</b> an open Docker API port (2375/2376/4243)
raises a warning - an exposed daemon can allow full host takeover. Restrict it
immediately.</div>

<!-- ============ 11 CHANGES ============ -->
<h2 id="changes">11. Change Detection &amp; Alerts</h2>
<p>Every scan is compared to the previous one <i>within the same tenant</i>. The
<b>Recent Changes</b> panel highlights new/gone devices, ports opening/closing, service
or version changes, new vulnerabilities (critical if Known-Exploited), and OS changes.
Notable changes can be pushed as <b>alerts</b> to Slack/Discord/generic webhooks or email
(§19).</p>

<!-- ============ 12 EXPORT ============ -->
<h2 id="export">12. Exporting Reports (Full &amp; Single-Host)</h2>
<h3>Whole-scan export</h3>
<p>From the controls bar:</p>
<ul>
  <li><b>Export CSV</b> - flat asset table (includes a Docker column, plus dedicated
      <i>CVE Descriptions</i> and <i>Mitigations</i> columns) for spreadsheets.</li>
  <li><b>Export JSON</b> - full structured data for other tools (every vulnerability
      carries its description and mitigation).</li>
  <li><b>Export PDF</b> - a branded report: executive summary, compliance overview, host
      inventory, TLS certs needing attention, Domain-Controller findings, and a
      <i>Vulnerability Detail</i> table listing each CVE with its description and
      suggested mitigation.</li>
</ul>
<div class="note"><b>CVE descriptions &amp; mitigations (v8):</b> all three export formats
now include, for every finding, the full CVE description and a recommended mitigation -
CISA's required action for known-exploited CVEs where available, otherwise tailored
service/product hardening advice.</div>
<div class="tip"><b>Scan type &amp; asset IDs on every report (v9):</b> CSV, JSON and PDF
exports clearly state whether the data is from a <b>Passive</b> or <b>Active</b> scan -
the PDF prints it prominently under the header, the CSV carries a leading
<code># Scan type: …</code> line plus a per-row <i>Scan Type</i> column, and the JSON
<code>scan.scan_type</code> field records it. Every export also includes each device's
<b>Asset ID</b> so findings can be tracked to the same physical device over time.</div>
<h3>Single-host export (v8)</h3>
<p>Expand any host and use its <b>Export: CSV / JSON / PDF</b> buttons to download a
focused report for just that host - overview, open ports/services, software and
vulnerabilities (each with its CVE description and mitigation). Ideal for handing one
machine's findings to its owner.</p>
<div class="note"><b>Scoped &amp; audited:</b> exports respect your tenant, and every
export is recorded in the activity log.</div>

<!-- ============ 13 SCHEDULE ============ -->
<h2 id="schedule">13. Scheduled Scans</h2>
<p>Click <b>⏱ Schedule</b> to manage recurring scans from the UI (operator+). For each
schedule set a name, target (blank = auto /24), profile, <b>scan type</b> (Active or
Passive), option toggles (credential exposure, AD/DC, SSL), and a cadence. Enable/disable,
<b>run now</b>, or delete any schedule. Schedules you create are tagged with your tenant.</p>
<h3>Day &amp; time scheduling (v9)</h3>
<p>You can now schedule by <b>day of week and clock time</b> instead of (or as well as) a
plain interval:</p>
<ul>
  <li><b>Run on days</b> - tick any combination of <b>Mon</b>–<b>Sun</b>.</li>
  <li><b>At time</b> - enter the <b>hour (0–23)</b> and <b>minute (0–59)</b> in local time.</li>
  <li><b>or every N minutes</b> - the classic interval, used only when no days are ticked.</li>
</ul>
<p>Example: tick <b>Mon</b>, <b>Wed</b>, <b>Fri</b> and set <b>02:30</b> to run a scan at
2:30 am every Monday, Wednesday and Friday. Choose <b>Passive</b> as the scan type for a
zero-footprint nightly inventory. The schedule list shows the next run time and the
Active/Passive badge. A global default interval can also be set via environment
variables (§19).</p>

<!-- ===================================================================== -->
<div class="part">
  <h2>Part III - Administration</h2>
  <p>For users with the <b>admin</b> role: accounts, tenants, the audit log, install and
     configuration.</p>
</div>

<!-- ============ 14 ROLES ============ -->
<h2 id="roles">14. Roles &amp; Permissions</h2>
<table>
  <tr><th>Role</th><th>Can do</th></tr>
  <tr><td><span class="pill red">admin</span></td><td>Everything: run/cancel scans,
      manage schedules, manage users &amp; tenants, view the activity log, enforce MFA.
      Sees data across <b>all</b> tenants.</td></tr>
  <tr><td><span class="pill amber">operator</span></td><td>Run, cancel and re-scan;
      manage schedules; export. Scoped to their own tenant.</td></tr>
  <tr><td><span class="pill green">viewer</span></td><td>Read-only: dashboard, all tabs,
      history and exports. Cannot start scans. Scoped to their own tenant.</td></tr>
</table>
<div class="note"><b>Safety rail:</b> the system refuses to delete or demote the
<b>last remaining admin</b>, so you can never lock yourself out.</div>

<!-- ============ 15 USERS ============ -->
<h2 id="users">15. User Administration</h2>
<p>Click <b>👥 User Admin</b> (admins only) to open the user-management modal.</p>
<ul>
  <li><b>Add a user</b> - username, password (≥ 8 chars), role, <b>tenant</b>, and an
      optional <b>Require MFA</b> toggle.</li>
  <li><b>Edit a username</b> inline (Release 2) - type a new name in the username field and
      press Enter / click away. Names are checked for uniqueness; renaming your own admin
      account keeps your session signed in.</li>
  <li><b>Set / reset a password</b> (Release 2) - click <b>🔑 set password</b> on a user's
      row and enter a new password (≥ 8 chars). Use this to recover a user who has
      <b>locked themselves out</b>; the reset applies immediately. Admins set passwords
      without needing the old one.</li>
  <li><b>Change role</b> inline from the dropdown.</li>
  <li><b>Change tenant</b> inline in the tenant field (v8).</li>
  <li><b>MFA controls</b> - force MFA on/off per user; <b>reset MFA</b> if someone loses
      their device (they re-enrol at next login). The list shows each user's MFA state and
      last-login time.</li>
  <li><b>Delete a user</b> with the ✕ button (never the last admin).</li>
</ul>
<div class="role"><b>Full editable access, by design-limit:</b> admins have editable control
over every account's <b>username</b> and <b>password</b>. Passwords are stored as one-way
salted hashes, so they can be <i>set/reset</i> but never <i>viewed</i> - not even by an
admin. This is intentional and protects users even from a compromised admin session.</div>
<div class="tip"><b>Bootstrapping:</b> on a fresh install you can create the first admin
from environment variables or the CLI (§18).</div>

<!-- ============ 16 TENANCY ============ -->
<h2 id="tenancy" class="pagebreak">16. Multi-Tenancy &amp; Data Separation</h2>
<p class="lead">NetscanXi supports <b>soft multi-tenancy</b>: one installation can serve
multiple teams/customers while keeping their scan data separated.</p>
<h3>How it works</h3>
<ul>
  <li>Every <b>user, scan and schedule</b> carries a <b>tenant</b> tag (default:
      <code>default</code>).</li>
  <li>A scan started by a user is tagged with that user's tenant; change-detection compares
      only against prior scans in the same tenant.</li>
  <li><b>Scoped users</b> (viewer/operator) see only their own tenant's scans, history,
      exports and running-scan status.</li>
  <li><b>Admins are unscoped</b> - they see and report across all tenants, and can filter
      the activity log by tenant.</li>
</ul>
<h3>Setting up tenants</h3>
<ol>
  <li>Decide on tenant names (e.g. <code>acme</code>, <code>contoso</code>,
      <code>home</code>). They're free-text tags - just be consistent.</li>
  <li>In <b>User Admin</b>, assign each user a tenant when creating them, or edit it
      inline. The tenant field auto-suggests existing tenants.</li>
  <li>Those users' scans and schedules are then automatically separated.</li>
</ol>
<div class="note"><b>"Soft" separation:</b> all data lives in one database with
tenant-scoped queries - not separate databases. It cleanly separates day-to-day
visibility but is not a hard cryptographic boundary; admins can always see everything.</div>
<div class="warn"><b>Existing data:</b> scans and users created before v8 are tagged
<code>default</code> automatically on upgrade. Re-tag users as needed; historical scans
keep their original tag.</div>

<!-- ============ 17 ACTIVITY ============ -->
<h2 id="activity">17. Activity &amp; Audit Log</h2>
<p>Click <b>📋 Activity</b> (admins only) to open the audit log. It records, with a
timestamp, the acting user, tenant and client IP:</p>
<table>
  <tr><th>Event</th><th>When it's logged</th></tr>
  <tr><td>🔓 login / ⎋ logout</td><td>Successful sign-in and sign-out (login/logout times).</td></tr>
  <tr><td>⛔ login failed</td><td>A bad username/password attempt.</td></tr>
  <tr><td>🔍 scan / 🔁 re-scan</td><td>A scan or single-host re-scan is queued.</td></tr>
  <tr><td>📤 export / 📄 host export</td><td>A whole-scan or single-host export.</td></tr>
  <tr><td>⏱ schedule run</td><td>A schedule is run on demand.</td></tr>
  <tr><td>➕ user added / 🏢 tenant change</td><td>User-administration actions.</td></tr>
  <tr><td>✏️ username change / 🔑 admin password reset</td><td>An admin renames a user or sets/resets their password (Release 2).</td></tr>
  <tr><td>🔑 password changed / ⛔ password change failed</td><td>A user changes their own password via Account Security (Release 2).</td></tr>
</table>
<ul>
  <li><b>Filter</b> by free text (user, action, detail, IP) or by <b>tenant</b> from the
      dropdown.</li>
  <li><b>Refresh</b> to pull the latest events (most recent first).</li>
</ul>
<div class="tip"><b>Use it for:</b> answering "who scanned what and when", spotting failed
sign-ins, and demonstrating access accountability for compliance.</div>

<!-- ============ 18 INSTALL ============ -->
<h2 id="install">18. Installation &amp; First-Run Setup</h2>
<h3>Option A - Docker (recommended)</h3>
<pre><code>cd netscan-xi/v8
docker compose up --build</code></pre>
<p>Open <code>http://localhost:5000</code> (or <code>http://&lt;host-ip&gt;:5000</code> from
the LAN). Data persists in <code>./data</code>.</p>
<div class="warn"><b>Linux only for real scanning.</b> The container uses host networking
plus <code>NET_ADMIN</code>/<code>NET_RAW</code> so nmap can see your physical LAN and do
SYN/OS detection. On Docker Desktop for Mac/Windows it runs in a VM and won't reach your
real network - use the native install there.</div>

<h3>Option B - Native install</h3>
<pre><code>sudo apt update &amp;&amp; sudo apt install -y nmap python3 python3-venv
cd netscan-xi/v8
chmod +x run.sh
sudo ./run.sh                 # http://localhost:5000
sudo ./run.sh 127.0.0.1 8080  # custom host/port</code></pre>
<div class="tip"><b>Why <code>sudo</code>?</b> OS detection (<code>-O</code>) and SYN
scanning (<code>-sS</code>) need root for raw socket access.</div>

<h3>Create the first admin</h3>
<p>On a fresh install, either set the bootstrap env vars before first start:</p>
<pre><code>NETSCAN_ADMIN_USER=admin
NETSCAN_ADMIN_PASSWORD=change-me-please</code></pre>
<p>...or create one from the CLI:</p>
<pre><code>python3 -m app.server seed-admin --username admin</code></pre>
<p>Once an admin exists, manage everyone else from <b>👥 User Admin</b>. For PDF export,
ensure <code>reportlab</code> is installed (it's in <code>requirements.txt</code>).</p>

<!-- ============ 19 CONFIG ============ -->
<h2 id="config" class="pagebreak">19. Configuration Reference</h2>
<p>All configuration is via environment variables - everything has a safe default.</p>
<table>
  <tr><th>Variable</th><th>Default</th><th>Purpose</th></tr>
  <tr><td><code>NETSCAN_ADMIN_USER</code></td><td><i>unset</i></td><td>Bootstrap first admin on a fresh install.</td></tr>
  <tr><td><code>NETSCAN_ADMIN_PASSWORD</code></td><td><i>unset</i></td><td>Password for the bootstrap admin.</td></tr>
  <tr><td><code>NETSCAN_SECRET</code></td><td>random</td><td>Flask session signing key - <b>set this</b> for stable logins.</td></tr>
  <tr><td><code>NETSCAN_PASSWORD</code></td><td><i>unset</i></td><td>Legacy single-password fallback (until accounts exist).</td></tr>
  <tr><td><code>NETSCAN_MFA_ISSUER</code></td><td>NetScan Xi</td><td>Issuer name shown in authenticator apps.</td></tr>
  <tr><td><code>NETSCAN_USE_NVD</code></td><td><code>0</code></td><td><code>1</code> to enrich CVEs via the NVD API.</td></tr>
  <tr><td><code>NETSCAN_SCHEDULE_MINUTES</code></td><td><code>0</code></td><td>Global recurring scan interval (0 = off).</td></tr>
  <tr><td><code>NETSCAN_SCHEDULE_PROFILE</code></td><td><code>standard</code></td><td>Profile for the global scheduled scan.</td></tr>
  <tr><td><code>NETSCAN_SCHEDULE_TARGET</code></td><td>auto</td><td>Target for the global scheduled scan.</td></tr>
  <tr><td><code>NETSCAN_WEBHOOK_URL</code></td><td><i>unset</i></td><td>Slack/Discord/generic webhook for alerts.</td></tr>
  <tr><td><code>NETSCAN_ALERT_MIN_SEV</code></td><td><code>warn</code></td><td>Minimum severity to alert on.</td></tr>
  <tr><td><code>NETSCAN_SMTP_*</code></td><td><i>unset</i></td><td>SMTP email alerting (host/port/user/pass/from/to).</td></tr>
  <tr><td><code>NETSCAN_DB</code></td><td><code>./data/netscan.db</code></td><td>SQLite database path.</td></tr>
</table>
<div class="note"><b>UI-managed schedules vs. the global schedule:</b> the env-var schedule
is a single built-in job; the <b>⏱ Schedule</b> modal lets you create as many tenant-tagged
schedules as you like.</div>

<!-- ============ 20 TIPS ============ -->
<h2 id="tips">20. Safety, Tips &amp; Troubleshooting</h2>
<div class="warn"><b>Only scan networks you own or are authorised to scan.</b> Port and
vulnerability scanning other people's networks may be illegal.</div>
<ul>
  <li><b>Secure the dashboard</b> - create accounts (or set <code>NETSCAN_PASSWORD</code>)
      and a stable <code>NETSCAN_SECRET</code> before exposing it beyond localhost; put it
      behind a reverse proxy with TLS for remote access.</li>
  <li><b>Enforce MFA</b> for admins and operators from User Admin.</li>
  <li><b>Empty results?</b> Run as root / with the right container capabilities; without
      them OS detection and SYN scans are skipped.</li>
  <li><b>Deep scans feel slow?</b> That's the vuln scripts - use Quick/Standard for fast
      discovery and reserve Deep (and the AD/SSL/creds toggles) for when you need them.</li>
  <li><b>Can't see another team's scans?</b> That's multi-tenancy working - only admins
      are unscoped (§16).</li>
  <li><b>PDF export returns an error?</b> Install <code>reportlab</code>
      (<code>pip install reportlab</code>).</li>
  <li><b>Theme</b> - your light/dark choice is saved in the browser and applied instantly.</li>
</ul>

<!-- ===================================================================== -->
<div class="part">
  <h2>Part IV - New in Version 9.1</h2>
  <p>The ten enhancements shipped in the 9.1 release: interactive analytics, finding
     lifecycle, bulk actions, a new admin role, global search, retention controls,
     patch-aware vulnerability assessment, trend history, service-desk integrations and
     a customisable dashboard.</p>
</div>

<!-- ============ 21 CHARTS ============ -->
<h2 id="charts">21. Interactive Dashboard Charts</h2>
<p>The dashboard presents four <b>equal-sized chart tiles</b>: <b>OS Distribution</b>,
<b>Vulnerability Severity</b>, <b>Network Risk &amp; Compliance</b> and <b>Regulatory
Compliance</b>. Together they give you an at-a-glance breakdown of what operating systems
are on your network, how findings spread across Critical / High / Medium / Low severity,
your overall risk and compliance posture, and pass/fail counts per regulatory framework.</p>
<p>Each tile is <b>customisable</b>. Use the <b>type selector</b> in a tile's header to
switch it between a <b>pie chart</b>, <b>horizontal bar graph</b> or <b>vertical bar
graph</b> (the Network Risk &amp; Compliance tile additionally offers a <b>historical
trend line</b>). <b>Drag the &#10303; handle</b> in a tile header to reorder the charts,
and <b>drag a tile's bottom-right corner</b> to resize it. Your chosen types, sizes and
order are <b>saved in your browser</b>, and <b>&#8634; Reset charts</b> restores the
defaults.</p>
<p>The OS and severity charts are not just pictures - they are filters. <b>Click a pie
slice or a legend entry</b> to instantly filter the Assets table to just that operating
system, or click a severity bar to show only assets carrying findings at that level. Click
the same element again to clear the filter. All charts are drawn as <b>inline SVG</b>, so
they render crisply at any size and <b>work fully offline</b> - no external chart library
or internet connection required.</p>
<div class="tip"><b>Combine with the table:</b> chart clicks set the same filter the
filter box uses, so you can click a slice and then refine further by typing in the Assets
filter.</div>

<!-- ============ 22 LIFECYCLE ============ -->
<h2 id="lifecycle">22. CVE Finding Lifecycle &amp; Status</h2>
<p>Every vulnerability can now be tracked through a lifecycle instead of simply reappearing
on each scan. Open a host's detail panel, find the CVE, and click <b>Set status</b> to mark
it as <b>Open</b>, <b>Remediated</b>, <b>Accepted Risk</b> or <b>False Positive</b>. You
can add an <b>optional note</b> (for example a change-ticket reference or the reason a risk
was accepted).</p>
<p>A status can be applied <b>per asset</b> or <b>tenant-wide</b> (so the same CVE is
treated consistently everywhere it appears in your tenant). Findings marked
<b>Remediated</b> or <b>False Positive</b> are <b>de-emphasised</b> in the host view and
<b>dropped from the active severity chart</b>, so your dashboard reflects work you've
actually done rather than noise. Because status is keyed to the stable asset ID, the
lifecycle decision <b>follows the asset across future scans</b> - re-scanning won't reset
your triage.</p>
<div class="note"><b>Accepted Risk vs Remediated:</b> Accepted-Risk findings remain
visible (they're a deliberate, documented decision) while Remediated and False-Positive
findings are filtered out of the active risk picture.</div>

<!-- ============ 23 MULTI-SELECT ============ -->
<h2 id="multiselect">23. Multi-Select Asset Table &amp; Bulk Actions</h2>
<p>The Assets table gains a <b>checkbox column</b> and a <b>select-all</b> checkbox in the
header, so you can act on several hosts at once. As soon as one or more rows are ticked, a
<b>bulk actions bar</b> appears with:</p>
<ul>
  <li><b>Export selected (CSV / JSON)</b> - download a focused report covering only the
      hosts you picked.</li>
  <li><b>Re-scan selected</b> - queue a fresh scan of just those hosts.</li>
</ul>
<p>Selection <b>respects the current filter</b>: if you've filtered the table (by typing in
the filter box or clicking a chart slice), <b>select-all</b> ticks only the rows currently
shown, so bulk actions apply to exactly the subset you're looking at.</p>

<!-- ============ 24 TENANT ADMIN ============ -->
<h2 id="tenantadmin">24. The Tenant Admin Role</h2>
<p>Version 9.1 introduces a new RBAC role - <b>tenant_admin</b> - that sits between
<b>operator</b> and <b>admin</b>. A tenant admin has <b>full admin powers within their own
tenant only</b>: they can manage that tenant's users, schedules, scans, integrations,
retention policy and activity log, without needing a global administrator.</p>
<p>Crucially, the boundary is strict. A tenant admin <b>can never act across tenants</b> and
<b>cannot create global admins</b> - they can only manage roles up to tenant_admin within
their own team. This lets you delegate day-to-day administration of a team to someone you
trust with that team's data, while keeping cross-tenant control reserved for global
admins.</p>
<div class="role"><b>Role hierarchy (9.1):</b>
<span class="pill green">viewer</span> &lt;
<span class="pill amber">operator</span> &lt;
<span class="pill purple">tenant_admin</span> &lt;
<span class="pill red">admin</span>. Each level includes everything below it; only the
global <b>admin</b> is unscoped across all tenants.</div>

<!-- ============ 25 SEARCH ============ -->
<h2 id="search">25. Global Search Bar</h2>
<p>A <b>global search bar</b> now lives in the top navigation. Start typing and it performs
a <b>live search</b> across your latest scan, covering:</p>
<ul>
  <li><b>Assets</b> - by asset ID, IP, hostname, OS, vendor or MAC address.</li>
  <li><b>CVEs</b> - by CVE id and by text in the description.</li>
  <li><b>Software</b> - applications and versions detected on hosts.</li>
</ul>
<p>Results appear in a drop-down as you type; <b>click any result to jump straight to that
asset</b> and open its detail. It's the fastest way to answer "where is host X?" or "which
machines are affected by this CVE?" without manually sorting the table. Search is scoped to
the data you're allowed to see.</p>

<!-- ============ 26 RETENTION ============ -->
<h2 id="retention">26. Data-Retention Policies</h2>
<p>The new <b>⚙ Admin</b> panel lets you control how long scan history is kept, so the
database doesn't grow forever. You can:</p>
<ul>
  <li><b>Delete scans older than N days</b>.</li>
  <li><b>Keep only the M most-recent scans</b>.</li>
  <li>Use either rule, or both together.</li>
  <li>Tick <b>auto-apply</b> so the policy runs automatically after every scan.</li>
  <li>Click <b>Save &amp; purge now</b> to apply the policy immediately.</li>
</ul>
<p>The <b>asset registry</b> (your stable asset IDs and per-asset history) and the
<b>audit log</b> are <b>always preserved</b> regardless of retention settings, so you never
lose accountability or device continuity. <b>Tenant admins</b> can manage and purge
<b>only their own tenant's</b> scans; global admins set policy across all tenants.</p>
<div class="warn"><b>Purging is permanent.</b> Deleted scans cannot be recovered - test
your N-days / M-scans values before enabling auto-apply.</div>

<!-- ============ 27 PATCH-AWARE ============ -->
<h2 id="patchaware">27. Patch-Aware Vulnerability Assessment</h2>
<p>A new <b>Patch-aware vulns</b> scan toggle enables version-aware vulnerability
assessment. When ticked it adds the <code>vulners</code> NSE script, and the scanner now
captures <b>patch / build / package-release tokens</b> (for example
<code>4ubuntu0.5</code>) into a <b>per-host patch-level inventory</b> rather than relying on
the distribution version alone.</p>
<p>Findings are tagged <b>"version-confirmed"</b> when the exact detected release proves the
host is vulnerable, versus <b>"heuristic"</b> when the match is only inferred. Mitigations
now <b>cite the precise detected release</b>, so advice points at the actual package on the
box. The result is markedly more accurate than distro-version-only assessment, with fewer
false positives for already-patched systems.</p>

<!-- ============ 28 TRENDS ============ -->
<h2 id="trends">28. Historical Trend Graphs</h2>
<p>Set the <b>Network Risk &amp; Compliance</b> chart tile to its <b>Trend (line)</b> view
to plot <b>historical trends</b> over time: your overall <b>network risk score</b> and your
<b>compliance posture (%)</b>, charted across your full scan history. This turns a
point-in-time snapshot into a visible direction of travel - are you getting more or less
secure? Switch the same tile to a pie or bar view whenever you just want the latest
values.</p>
<p>A <b>snapshot is recorded automatically after every scan</b>, so the trend builds up on
its own as you keep scanning. Use it to demonstrate progress after a remediation push, or
to spot a slow drift in posture before it becomes a problem.</p>

<!-- ============ 29 INTEGRATIONS ============ -->
<h2 id="integrations">29. Service-Desk Integrations</h2>
<p>NetscanXi can now raise tickets directly in your service desk. It ships native
integrations for <b>Jira</b>, <b>ServiceNow</b> and <b>Zendesk</b>. Configure them in the
new <b>🔗 Integrations</b> admin panel: enter the <b>base URL</b>, <b>authentication</b>
and the target <b>project / table / group</b>, then <b>test the connection</b> before
saving.</p>
<p>Once configured, open any CVE finding in the host detail view and click <b>Create
ticket</b> to file it in your chosen system - no copy-paste. Every ticket created is
<b>recorded for audit</b> in the activity log, so there's a clear trail from finding to
remediation task.</p>

<!-- ============ 30 CUSTOM DASHBOARD ============ -->
<h2 id="customdash">30. Customisable Dashboard</h2>
<p>You can now tailor the dashboard to how you work. The main components -
<b>Summary</b>, <b>Interactive Charts</b> and <b>Top Vulnerabilities</b> - can be
rearranged. Click <b>✎ Customise</b> to enter customise mode, where you can
<b>drag-reorder</b> components, <b>pin</b> one to the top, or <b>hide</b> ones you don't
use.</p>
<p>Within the <b>Interactive Charts</b> block, each chart tile is independently
customisable - change its <b>type</b> (pie / horizontal bars / vertical bars / trend),
<b>resize</b> it by dragging its corner, and <b>reorder</b> the tiles via their drag
handles (see &sect;21).</p>
<p>Click <b>↺ Reset layout</b> to restore the component defaults, or <b>↺ Reset
charts</b> for the chart tiles, at any time. Your layout <b>persists per user</b>, so each
person gets the dashboard arrangement they prefer the next time they sign in.</p>

<!-- ============ 31 API ============ -->
<h2 id="api91">31. API Additions in 9.1</h2>
<p>The 9.1 features are backed by new HTTP endpoints, useful if you automate NetscanXi or
build on top of it. All respect your role and tenant scope (see §14 and §24).</p>
<table>
  <tr><th>Endpoint</th><th>Purpose</th></tr>
  <tr><td><code>GET /api/dashboard</code></td><td>Summary data for the charts:
      <code>os_distribution</code>, <code>severity_distribution</code> and
      <code>lifecycle_counts</code> (§21, §22).</td></tr>
  <tr><td><code>POST/GET /api/cve/lifecycle</code></td><td>Set and read finding status
      (Open / Remediated / Accepted Risk / False Positive) with optional note (§22).</td></tr>
  <tr><td><code>GET /api/trends?days=</code></td><td>Historical risk-score and compliance
      snapshots over the requested window, e.g. <code>?days=90</code> (§28).</td></tr>
  <tr><td><code>GET /api/search?q=</code></td><td>Live global search across assets, CVEs and
      software (§25).</td></tr>
  <tr><td><code>GET/POST /api/settings/retention</code></td><td>Read and update the
      data-retention policy; updating can purge immediately (§26).</td></tr>
  <tr><td><code>/api/integrations*</code></td><td>Configure and test Jira / ServiceNow /
      Zendesk service-desk integrations (§29).</td></tr>
  <tr><td><code>/api/tickets</code></td><td>Create and list service-desk tickets raised from
      CVE findings (§29).</td></tr>
  <tr><td><code>GET/POST /api/dashboard/layout</code></td><td>Read and save the per-user
      dashboard layout (§30).</td></tr>
</table>
<div class="note"><b>Auth &amp; scope:</b> these endpoints use the same session/role checks
as the rest of the app; tenant-scoped users only see and modify data within their own
tenant.</div>

<!-- ===================================================================== -->
<div class="part pagebreak">
  <h2>Part V - New in Version 10r1 (Docker)</h2>
  <p>Deep Docker container scanning &amp; vulnerability assessment - look inside
     the Docker hosts NetscanXi finds.</p>
</div>

<h2 id="dk-intro">32. Deep Docker Scanning Overview</h2>
<p>Version 10r1 extends NetscanXi's Docker <i>detection</i> (§10) into deep,
   per-container and per-image visibility. When the <b>Deep Docker scan</b> option
   is enabled (it is on by default), for every detected Docker host NetscanXi:</p>
<ul>
  <li>connects to the <b>Docker Engine API</b> and pulls the container &amp; image
      inventory;</li>
  <li>scans each image for <b>CVEs</b> using a local scanner (Trivy or Grype);</li>
  <li>runs a <b>CIS Docker benchmark</b> misconfiguration audit;</li>
  <li>surfaces <b>registry</b>, <b>SBOM</b> and <b>orchestration</b> (Swarm/K8s)
      findings.</li>
</ul>
<div class="tip"><b>Graceful by design.</b> If the Docker API isn't reachable or
   no image scanner is installed, you still get the original network-level
   detection plus a clear note about what was unavailable. Nothing here runs an
   exploit or changes the target - the API access is read-only.</div>

<h2 id="dk-api">33. Authenticated Docker API Inventory</h2>
<p>NetscanXi talks to the Docker Engine API over plain HTTP (<code>2375</code>),
   TLS (<code>2376</code>, with optional client certificate), the legacy
   <code>4243</code>, or a local unix socket. From it you get:</p>
<ul>
  <li><b>Engine</b> - version, API version, storage driver, rootless vs root,
      live-restore, insecure registries.</li>
  <li><b>Containers</b> - name, image, state, published ports, and security
      flags: <b>privileged</b>, <b>docker.sock</b> mount, host network/PID,
      added capabilities, restart policy.</li>
  <li><b>Images</b> - tags, digests and size.</li>
</ul>
<div class="note"><b>mTLS to 2376:</b> set <code>NETSCAN_DOCKER_TLS_CA</code>,
   <code>NETSCAN_DOCKER_TLS_CERT</code> and <code>NETSCAN_DOCKER_TLS_KEY</code> to
   present a client certificate to TLS-protected daemons.</div>

<h2 id="dk-containers">34. Containers &amp; Images in the Host View</h2>
<p>Open any Docker host's detail panel. Below the existing Docker section you'll
   now see:</p>
<ul>
  <li>an <b>API status</b> line (connected / offline, endpoint, TLS);</li>
  <li>the <b>engine</b> summary;</li>
  <li>a <b>Containers</b> list - each row shows the image and risk badges
      (privileged, docker.sock, host-net, host-pid, +caps);</li>
  <li><b>Image Vulnerabilities</b> and the <b>CIS audit</b> (next sections).</li>
</ul>
<div class="note"><b>Nothing was removed.</b> All existing host views - ports,
   software, vulnerabilities, compliance, certificates, AD - are unchanged; the
   Docker detail is simply richer.</div>

<h2 id="dk-imgcve">35. Image Vulnerability Scanning (Trivy / Grype)</h2>
<p>Each discovered image is scanned for OS-package and language-dependency CVEs
   using a locally-installed scanner. The host view shows a <b>severity strip</b>
   (Critical/High/Medium/Low) and, per image, the CVE count and the top findings
   as chips. Container CVEs run through the same <b>CISA KEV</b> enrichment as
   host findings, so known-exploited issues are flagged (🔥) and sorted first.</p>
<div class="tip"><b>Install a scanner:</b> put <b>Trivy</b> (preferred) or
   <b>Grype</b> on the NetscanXi host's PATH. The bundled Docker image installs
   Trivy automatically. Without a scanner, NetscanXi still lists the images and
   tells you a scanner is needed for CVEs.</div>

<h2 id="dk-cis">36. CIS Docker Benchmark Audit</h2>
<p>NetscanXi audits each Docker host against high-signal CIS Docker controls and
   reports <span class="pill green">pass</span> /
   <span class="pill amber">warn</span> / <span class="pill red">fail</span> per
   check, including:</p>
<table>
  <tr><th>Check</th><th>Why it matters</th></tr>
  <tr><td>Docker API exposure</td><td>A remote API grants full control of the host.</td></tr>
  <tr><td>Daemon TLS</td><td>Plain-HTTP API has no authentication.</td></tr>
  <tr><td>Privileged container</td><td>Full host capabilities - a top escape risk.</td></tr>
  <tr><td>docker.sock mount</td><td>A container with the socket can control the host.</td></tr>
  <tr><td>Host network / PID</td><td>Removes container isolation.</td></tr>
  <tr><td>Insecure registry / :latest</td><td>Supply-chain &amp; reproducibility risks.</td></tr>
  <tr><td>Rootless / live-restore</td><td>Engine hardening posture.</td></tr>
</table>

<h2 id="dk-dash">37. The Docker Dashboard Panel</h2>
<p>A new <b>🐳 Docker &amp; Containers</b> panel appears on the dashboard whenever
   the latest scan found Docker hosts (it auto-hides otherwise). It shows tiles
   for docker hosts, running containers, images, image CVEs, critical image CVEs,
   privileged containers, <code>docker.sock</code> mounts and CIS failures. Like
   every dashboard component you can <b>pin</b>, <b>hide</b> or <b>drag</b> it.</p>

<h2 id="dk-drift">38. Container Drift &amp; Exports</h2>
<p><b>Change detection</b> now reports container/image drift between scans:
   new/removed containers, new images, a container becoming <b>privileged</b> or
   mounting <b>docker.sock</b> (flagged critical), and new known-exploited
   container CVEs.</p>
<p>Exports carry the new data: <b>CSV</b> gains Containers / Image CVEs / Image
   KEV / CIS-fail columns, <b>JSON</b> includes the full Docker block, and the
   <b>per-host PDF</b> gains a Docker container/image/CIS section.</p>

<h2 id="dk-howto" class="pagebreak">39. Step-by-Step: Running a Deep Docker Scan</h2>
<ol>
  <li>(Optional) install <b>Trivy</b> or <b>Grype</b> on the NetscanXi host for
      image CVE scanning.</li>
  <li>On the scan bar, leave <b>Docker hosts</b> and <b>Deep Docker scan</b>
      ticked (both default on).</li>
  <li>Run an <b>Active</b> scan of your range. NetscanXi detects Docker hosts,
      then pulls inventory, scans images and runs the CIS audit.</li>
  <li>Review the <b>Docker &amp; Containers</b> dashboard panel, then open a
      Docker host to see containers, image CVEs and the CIS audit.</li>
  <li>Triage: start with KEV + critical image CVEs, privileged containers and
      docker.sock mounts; export or raise tickets as needed.</li>
</ol>
<div class="warn"><b>Authorisation:</b> only scan hosts you own or are authorised
   to assess. Use read-only Docker API access (and TLS client certs where
   possible).</div>

<h2 id="dk-apiref">40. API &amp; Configuration Reference (10r1)</h2>
<table>
  <tr><th>Endpoint</th><th>Purpose</th></tr>
  <tr><td><code>GET /api/docker/capabilities</code></td><td>Reports whether the
      Docker API inventory and an image scanner (Trivy/Grype) are available.</td></tr>
  <tr><td><code>GET /api/dashboard</code></td><td>Now includes a
      <code>summary.docker_stats</code> rollup and the deep Docker block on each
      host.</td></tr>
</table>
<p><b>Scan option:</b> <code>docker_deep</code> (the “Deep Docker scan” toggle)
   enables/disables API inventory + image CVE + CIS audit per scan.</p>
<table>
  <tr><th>Environment variable</th><th>Effect</th></tr>
  <tr><td><code>NETSCAN_DOCKER_API=0</code></td><td>Disable authenticated API inventory.</td></tr>
  <tr><td><code>NETSCAN_DOCKER_IMAGE_SCAN=0</code></td><td>Disable image CVE scanning.</td></tr>
  <tr><td><code>NETSCAN_DOCKER_SCANNER</code></td><td><code>trivy</code> / <code>grype</code> / <code>auto</code>.</td></tr>
  <tr><td><code>NETSCAN_DOCKER_MAX_IMAGES</code></td><td>Cap images scanned per host (default 25).</td></tr>
  <tr><td><code>NETSCAN_DOCKER_TLS_CA|CERT|KEY</code></td><td>Client materials for mTLS to 2376.</td></tr>
</table>

<!-- ===================================================================== -->
<div class="part">
  <h2>Part VI - New in Version 13 (Patch and Remedy)</h2>
</div>

<h2 id="pa-intro">41. Patch and Remedy Overview</h2>
<p>Version 13 lets NetscanXi <b>act</b> on what it finds. The <b>Patch and Remedy</b>
tab (formerly the reserved "More" tab) applies <b>operating-system updates and
upgrades</b> over SSH, and can also update <b>Docker images</b>.</p>
<ul>
  <li>Patching is an <b>operator</b>-level action.</li>
  <li>It is <b>tenant-separated</b> &mdash; scoped users can only target their own
      tenant's assets.</li>
  <li><b>OS patching targets any scanned asset</b> (not only Docker hosts); the
      package manager (apt / dnf / yum / zypper / apk) is auto-detected over SSH.</li>
  <li>Windows OS patching (WinRM) is a future phase.</li>
</ul>

<h2 id="pa-run">42. Running a Patch (OS or Docker; Single / Group / All)</h2>
<ol>
  <li>Open the <b>Patch and Remedy</b> tab → <b>🔧 Patch and Remedy</b>.</li>
  <li>Choose a <b>Patch type</b>: <b>Operating system (SSH)</b> or
      <b>Docker images</b>.</li>
  <li>Pick a target: a <b>single asset</b>, an <b>asset group</b>, or
      <b>all assets in scope</b> from the latest scan.</li>
  <li><b>OS:</b> enter the <b>SSH username/password</b> (and sudo password if
      different) and port; optionally tick <b>Full distribution upgrade</b> or
      <b>Simulate only</b>. <b>Docker:</b> optionally enter <b>registry
      credentials</b> and tick <b>Recreate containers after pull</b>.</li>
  <li>Credentials are used for this run only and are <b>never stored or logged</b>.</li>
  <li>Click <b>Preview (dry run)</b> to see what would change &mdash; no side
      effects (OS preview doesn't contact SSH) &mdash; then <b>Patch now</b>.</li>
  <li>Review per-asset results, then open <b>Remediation Tracking</b>: an item is
      auto-created per asset and updated to <b>resolved</b> or <b>blocked</b>.</li>
</ol>
<div class="tip"><b>Per-asset remediation:</b> a multi-asset patch creates one
remediation item per targeted asset, so each asset's row reflects its own
outcome.</div>

<h2 id="pa-ref">43. Patch API, Safety &amp; Audit Reference</h2>
<table>
  <tr><th>Endpoint</th><th>Purpose</th></tr>
  <tr><td><code>POST /api/patch/os/plan</code></td><td>Dry run: list targeted
      assets + detected OS. No SSH, no side effects, no remediation items.</td></tr>
  <tr><td><code>POST /api/patch/os</code></td><td>OS patch the target(s) over SSH:
      auto-detect apt/dnf/yum/zypper/apk, update + upgrade, auto-create/update
      remediation, audit. Body: <code>mode</code>, <code>asset_id</code>/
      <code>group_id</code>, <code>ssh</code>
      {<code>username,password,port,sudo_password</code>},
      <code>dist_upgrade</code>, <code>simulate</code>.</td></tr>
  <tr><td><code>POST /api/patch/docker/plan</code></td><td>Dry run: which images
      would update on which Docker assets. No side effects.</td></tr>
  <tr><td><code>POST /api/patch/docker</code></td><td>Pull images (optional
      recreate), auto-create/update remediation, audit. Body: <code>mode</code>,
      <code>asset_id</code>/<code>group_id</code>, optional <code>registry</code>
      {<code>username,password,server</code>}, <code>recreate</code>.</td></tr>
</table>
<p><b>New module:</b> <code>app/patcher.py</code>; <b>new dependency:</b>
<code>paramiko</code> (SSH, imported lazily &mdash; degrades gracefully if absent).
<b>No new database tables</b> &mdash; patch runs reuse the Version 12
<code>remediation</code> table.</p>
<table>
  <tr><th>Safety property</th><th>Behaviour</th></tr>
  <tr><td>Credential storage</td><td><b>None.</b> SSH/sudo and registry
      credentials are used once, then discarded. Never in the DB, logs, or
      responses; the browser clears password fields on send.</td></tr>
  <tr><td>Audit</td><td>An <code>os_patch</code> / <code>docker_patch</code>
      activity entry records counts and target only (e.g.
      <code>mode=all targets=3 ok=2 simulate=False</code>).</td></tr>
  <tr><td>Access control</td><td>Requires the <b>operator</b> role; tenant-scoped
      targeting.</td></tr>
  <tr><td>Preview / simulate</td><td>Dry-run preview has no side effects;
      <b>Simulate only</b> runs the package manager in dry-run so nothing is
      changed on the host.</td></tr>
</table>
<div class="warn"><b>Change control:</b> OS patching performs <b>privileged remote
execution</b> and makes live changes to running systems. Patch only what you are
authorised to change; prefer the simulate/dry-run preview and a maintenance
window for production.</div>

<h2 id="pa-remediation">44. Remediation Tracking: Multi-Select Delete &amp; Comments</h2>
<p>The <b>Remediation Tracking</b> tab gains two Version 13 conveniences:</p>
<ul>
  <li><b>Multi-select &amp; bulk delete.</b> Tick the checkbox on any rows (or the
      header <b>select-all</b>), then click <b>Delete selected (n)</b> to remove
      them in one action. Deletion is tenant-scoped &mdash; you can only delete
      your own tenant's items &mdash; and also removes those items' comments.</li>
  <li><b>Comments thread.</b> Each item has an expandable <b>💬 comments</b>
      section (click the badge) for a running work-log. Comments record their
      author and timestamp; operators can add and delete them. The badge shows
      the current comment count.</li>
</ul>
<p><b>Endpoints:</b> <code>POST /api/remediation/bulk-delete</code>;
<code>GET/POST /api/remediation/&lt;id&gt;/comments</code>;
<code>DELETE /api/remediation/comments/&lt;id&gt;</code>. <b>New table:</b>
<code>remediation_comments</code> (auto-created on startup).</p>

<div class="note" style="margin-top:24px; text-align:center;">
  <b>NetscanXi Version 13</b> &nbsp;·&nbsp; Find the risk &mdash; then fix it.
  &nbsp;🔧
</div>

</body>
</html>