nsauditor-ai 0.2.57 → 1.1.0

package/README.md

@@ -6,7 +6,7 @@ A modular, AI-assisted network security audit platform that scans, understands,
 
 [![npm](https://img.shields.io/npm/v/nsauditor-ai.svg)](https://www.npmjs.com/package/nsauditor-ai)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node.js 20+](https://img.shields.io/badge/node-20%2B-green.svg)](https://nodejs.org)
+[![Node.js 24.22.1+](https://img.shields.io/badge/node-24.22.1%2B-green.svg)](https://nodejs.org)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#tests)
 
 ---
@@ -17,22 +17,22 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
-**Latest: CE 0.2.57 + Enterprise 1.3.0 — *a finding on a port, region or producer a scan did not measure is not counted as fixed — two measured limits stated*.**
-The Pro/Enterprise `report --since` delta refuses two more ways a row could read as fixed without being fixed. A CVE
-or end-of-life row on a TCP port whose service the other scan reached but could not identify (a program and a version)
-is `port-not-measured`, never resolved or new. And from Enterprise 1.3.0 a scan that left out a plugin an analysis agent
-reads records it, so that agent's rows there are refused as `evidence-gap`. Each new, resolved and changed row now
-carries a **Basis** cell saying what the delta checked for that row. Two Enterprise agents changed identity at 1.3.0 —
-the exposure agent's titles no longer name the service, the service agent's no longer name the version — and both are
-declared in this release, so a row compared across the upgrade reads `identity-basis-changed`, never resolved or new.
-**Two measured limits:** a scan made before EE 1.3.0 could not record a plugin left out of it, so in a comparison with
-one, an agent's row that scan lacks is not refused — its Basis cell says so; and a scan that discovered ports with the
-Nmap plugin (024) alone records no port oracle, so an analysis agent's or the CVE mapper's row on a port it did not
-measure can read RESOLVED and count as closed in MTTR, and the control it failed can read PASS — include the port
-scanner (003). The release also carries this cycle's scanner, report and security fixes; the
-[CHANGELOG](./CHANGELOG.md) lists them. Plugin counts UNCHANGED at 27 Community + 29 Enterprise; every coverage matrix
-UNCHANGED; **Enterprise 1.3.0 requires this release** (`nsauditor-ai >= 0.2.57`). The free last-vs-current webhook
-alerting delta is untouched and stays free (see Continuous Monitoring below).
+**Latest: CE 1.1.0 + Enterprise 2.1.0 — *Node.js 24.22.1; scan_host stops at a time limit and names what it did not run; a saved response keeps its request beside it; a multi-entry cloud title says so; get_findings says what a scan holds*.**
+⚠️ **The supported runtime floor rises to Node.js 24.22.1** — the October 2026 Node.js security release for the 24
+line (`engines.node >=24.22.1`); npm only warns on an older runtime, so check `node --version`. Through the MCP server,
+`scan_host` stops at a total time limit by default (`SCAN_HOST_WALL_MS`, 50 s; `0` turns it off) and names the plugins it
+did not run; with `NSA_MCP_RESPONSE_DIR` set, each response is saved with its request beside it, and
+`nsauditor-ai mcp verify-call` checks both; a CRITICAL, HIGH or evidence-gap title in `scan_cloud` says when its finding
+holds more entries than it shows (` (+N more via get_findings)`); and a `get_findings` category filter that matches
+nothing returns the categories the scan does hold.
+Two limits from Enterprise 1.3.0 still hold in the Pro delta and Enterprise MTTR: a scan made before Enterprise 1.3.0
+could not record a plugin left out of it, so in a comparison with one an agent's row that scan lacks is not refused;
+and a scan that discovered ports with the Nmap plugin (024) alone records no port oracle, so an analysis agent's or the
+CVE mapper's row on a port it did not measure can read RESOLVED and count as closed in MTTR, and the control it failed
+can read PASS — include the port scanner (003).
+Plugin count UNCHANGED at 27 Community + 29 Enterprise; every coverage matrix UNCHANGED; Enterprise 2.1.0 pairs with this
+release, and its peer floor stays at `nsauditor-ai >= 1.0.0`. The free last-vs-current webhook alerting delta is
+untouched and stays free (see Continuous Monitoring below).
 
 For the full per-release history — every prior cycle, in detail — see [CHANGELOG.md](./CHANGELOG.md). This README keeps only the current release headline.
 
@@ -77,7 +77,7 @@ NSAuditor AI is available in three editions: Community (free, MIT-licensed, no r
 | Zero Trust assessment | — | — | ✅ |
 | **Enterprise — compliance (8 frameworks)** | | | |
 | SOC 2 (AICPA TSC 2017) — 10 covered + 4 partial controls | — | — | ✅ |
-| HIPAA Security Rule §164.312 — Zero BAA required | — | — | ✅ |
+| HIPAA Security Rule §164.312 — no BAA with Nsasoft required | — | — | ✅ |
 | NIST CSF 2.0 Core — Subcategory-level mapping (106 of 107 Subcategories) | — | — | ✅ |
 | PCI DSS v4.0.1 — Sub-requirement-level mapping for QSA RoC | — | — | ✅ |
 | ISO/IEC 27001:2022 — per-Annex-A-code mapping + SoA discipline (93 Annex A controls) | — | — | ✅ |
@@ -166,6 +166,7 @@ Results land in `./out/<host>_<timestamp>/` (two scans of one host whose plugin
 | `scan_conclusion_raw.json` | Full unredacted conclusion (admin reference) |
 | `scan_conclusion_raw.html` | Admin RAW HTML with filters and full detail |
 | `scan_response_ai_payload.json` | Redacted payload sent to AI |
+| `scan_response_ai_system_prompt.txt` | System prompt sent to AI, the Pro/Enterprise intelligence block included (from Community 1.0.0) |
 | `scan_response_ai.json` | Raw AI API response |
 | `scan_response_ai.txt` | AI conclusion (markdown) |
 | `scan_response_ai.html` | Styled HTML report with CVE links and badges |
@@ -173,7 +174,7 @@ Results land in `./out/<host>_<timestamp>/` (two scans of one host whose plugin
 | `scan_results.csv` | CSV — only with `--output-format csv` |
 | `scan_report.md` | GitHub-flavored Markdown report — only with `--output-format md` (or `markdown`) |
 
-> Works on Node 20+ (tested on Node 22).
+> Requires Node.js 24.22.1 or newer (tested on Node 24.22.1). npm only warns on an older runtime, so check `node --version` yourself.
 
 ---
 
@@ -199,7 +200,7 @@ found". A higher tier does not add tools; it unlocks the ones already in the lis
 
 | Tool | Purpose |
 |---|---|
-| `scan_host` | Run a full plugin scan against a host — service detection, OS fingerprint and the flags the service checks leave on each service record (weak SSH algorithms, SNMP community, weak TLS protocols / ciphers and a self-signed certificate, the MCP server checks; anonymous FTP login and zone transfer only when `FTP_CHECK_ANON` / `DNS_CHECK_AXFR` are set — both off by default). Its records also carry the HTTP probe's dangerous methods (006; `methodsTested` false means no Allow header was read — not tested, never "none"), SMB null sessions (014; only with `SMB_NULL_SESSION` set) and the TLS-certificate / debug-endpoint / DNS-security auditors' findings (040 / 050 / 060 — for a domain-name target the DNS-security audit lands on the 53/udp record when the scan found a 53/udp service, otherwise in the conclusion's evidence; for an IP-address target it declines, with its reason on the manifest and a NOT TESTED line in the markdown). Each opt-in check records whether it ran beside its result — `axfrTested` / `anonymousLoginTested` / `nullSessionTested` is `true` when measured, else the reason (`opt-in-off`, `no-domain`, `no-answer`) — and a null result is not tested, never "refused". It does NOT look up CVEs or run the analysis agents; with the Enterprise package the zero-trust assessment (1023) reaches it only as one score line in the evidence. So zero findings is not a clean verdict (use `get_vulnerabilities` per service CPE and `probe_service` for those plugins — both Pro — or the CLI scan with the Enterprise package and a Pro or Enterprise licence) |
+| `scan_host` | Run a full plugin scan against a host — service detection, OS fingerprint and the flags the service checks leave on each service record (weak SSH algorithms, SNMP community, weak TLS protocols / ciphers and a self-signed certificate, the MCP server checks; anonymous FTP login and zone transfer only when `FTP_CHECK_ANON` / `DNS_CHECK_AXFR` are set — both off by default). Its records also carry the HTTP probe's dangerous methods (006; `methodsTested` false means no Allow header was read — not tested, never "none"), SMB null sessions (014; only with `SMB_NULL_SESSION` set) and the TLS-certificate / debug-endpoint / DNS-security auditors' findings (040 / 050 / 060 — the DNS-security audit tries a zone transfer against the domain's nameservers only with `DNS_AUDIT_AXFR_CHECK` set, also off by default, and records what each nameserver answered; for a domain-name target the DNS-security audit lands on the 53/udp record when the scan found a 53/udp service, otherwise in the conclusion's evidence; for an IP-address target it declines, with its reason on the manifest and a NOT TESTED line in the markdown). Each of the three record-level opt-in checks records whether it ran beside its result — `axfrTested` / `anonymousLoginTested` / `nullSessionTested` is `true` when measured, else the reason (`opt-in-off`, `no-domain`, `no-answer`) — and a null result is not tested, never "refused". It does NOT look up CVEs or run the analysis agents; with the Enterprise package the zero-trust assessment (1023) reaches it only as one score line in the evidence. So zero findings is not a clean verdict (use `get_vulnerabilities` per service CPE and `probe_service` for those plugins — both Pro — or the CLI scan with the Enterprise package and a Pro or Enterprise licence) |
 | `list_plugins` | List available scanner plugins with their IDs, priorities and requirements |
 | `compliance_matrix` | Return the shipped coverage matrix for a framework — Covered / Partial / Out of scope, with the per-group out-of-scope reasons. **Needs the Enterprise pack installed**: the matrices are its data, so on a Community-only install this fails closed with an install instruction rather than returning an empty matrix (an empty matrix is what gets filled in with a guess) |
 
@@ -207,7 +208,7 @@ found". A higher tier does not add tools; it unlocks the ones already in the lis
 
 | Tool | Purpose |
 |---|---|
-| `probe_service` | Run one specific plugin against a single `host:port` |
+| `probe_service` | Run one specific plugin against a single `host:port` — a plugin with its own port set probes that set instead (the TLS scanner, 011: 443, 465, 563, 993 and 995), and the response's `probe` names the ports actually probed |
 | `get_vulnerabilities` | Look up known CVEs for a CPE (Common Platform Enumeration) string via the NVD API |
 
 **Unlocked by Enterprise:**
@@ -233,7 +234,7 @@ found". A higher tier does not add tools; it unlocks the ones already in the lis
 > has no MCP client in the path — there you can raise `PLUGIN_TIMEOUT_MS` (e.g. `90000`) freely. On the CLI a
 > plugin that declares its own budget already gets it; `PLUGIN_TIMEOUT_CEILING_MS` caps those.
 
-Security: SSRF protection on every host the MCP server is handed — the address it resolves to is checked (every answer), loopback, link-local and cloud-metadata addresses are always refused, and RFC 1918, CGNAT and fc00::/7 are refused unless `NSA_ALLOW_ALL_HOSTS` is set; a host the scanned target names — a redirect hop, a UPnP device's description URL — is checked the same way by the plugin that would follow it. A checked name is resolved again when it is scanned (no DNS pin). Port validation (1–65535), CPE format enforcement, dependency injection for test isolation. **Server-startup authentication is required** — see next section.
+Security: SSRF protection on every host the MCP server is handed — the address it resolves to is checked (every answer), loopback, link-local and cloud-metadata addresses are always refused, and RFC 1918, CGNAT and fc00::/7 are refused unless `NSA_ALLOW_ALL_HOSTS` is set; a redirect hop the scanned target names is checked the same way by the plugin that would follow it, and a UPnP device's description URL is fetched only when it names the very address that answered the discovery — so a device that answers from a link-local or loopback address (`169.254.x.x`, `127.0.0.1`) has its description fetched there. Since CE 1.0.0 a scan connects to the addresses its check resolved — the target's, and each redirect hop's — so a name that answers one address to the check and another when the scan connects (DNS rebinding) is not followed. Every answer is checked, and each connection the scan makes lands on one of the checked answers: an in-process connection may use any of them (Node tries them in turn), and the system tools a scan runs (`ping`, `nping`, `hping3`, `nmap`, `curl`, and `arp` for an address on a local network) are handed one — the first IPv4 answer when there is one. Limits: with `NODE_USE_ENV_PROXY` and a proxy configured, an HTTP request goes through the proxy by name and the proxy resolves it; and a request can reuse an idle connection the same process opened earlier to the same name, for as long as that connection stays idle in the pool — a few seconds by default; a server's Keep-Alive hint holds it longer. A `--webhook-url` alert does not share that pool: each alert opens its own connection to the address its check resolved, and closes it. And the address classifier does not recognise a NAT64 address (`64:ff9b::/96`) that embeds a blocked IPv4 address. One exception, off by default: with `DNS_AUDIT_AXFR_CHECK` set, the DNS-security audit (060) opens TCP/53 to each of the scanned domain's nameservers, at the first IPv4 address each nameserver's name resolves to — an address no host check resolved, so the audit classifies it itself before connecting: loopback, link-local, cloud-metadata and unspecified addresses are refused in every configuration, `NSA_ALLOW_ALL_HOSTS` included, and RFC 1918, CGNAT and fc00::/7 addresses unless `NSA_ALLOW_ALL_HOSTS` is set. It connects to the literal it classified, and a refused nameserver is recorded as not attempted, never graded. Port validation (1–65535), CPE format enforcement, dependency injection for test isolation. **Server-startup authentication is required** — see next section.
 
 ### Authentication (required)
 
@@ -320,13 +321,25 @@ The exact `NSA_MCP_AUTH_KEY` value to paste is printed by `nsauditor-ai mcp inst
 - `NSA_ALLOW_ALL_HOSTS=1` — required to scan private/RFC 1918 addresses (e.g., `192.168.x.x`); only `1`, `true`, `yes`
   or `on` turn it on. It admits private ranges only: loopback, link-local and cloud-metadata addresses stay refused over
   MCP whether they are written as an address in any spelling or reached through what a host name resolves to — every
-  answer is checked. The check does not pin the answer, so a name whose answer changes between the check and the scan
-  (DNS rebinding) is not caught
-- `FTP_CHECK_ANON=true` — lets the FTP check try an anonymous login (off by default; without it `scan_host` never reports anonymous FTP). `DNS_CHECK_AXFR=true` with `DNS_AXFR_DOMAIN=<zone>` — lets the DNS check try a zone transfer of that zone (off by default). `SMB_NULL_SESSION=true` — lets the NetBIOS check try an SMB null session (off by default). A check that is off, or that ran and could not complete (a timeout, a dropped connection), is recorded and reported as not tested with its reason — never as refused. The same variables govern the CLI scan.
-- `PLUGIN_TIMEOUT_MS=5000` — the per-plugin budget for `scan_host` and `probe_service` (default 30000), and it binds every plugin there, including one that declares a longer budget of its own. It bounds each PLUGIN, not the call: `scan_host` runs a host's plugins one after another, so the call takes roughly the sum of their times. On one router a `scan_host` call timed out in Claude Desktop on 2026-08-10 and one returned within 138 s on 2026-09-30, so neither outcome is promised: a call that times out returned no result — never read it as a clean host. On a real home gateway the plugins of one full scan took ~113 s between them at the default budget.
+  answer is checked. Since CE 1.0.0 the scan connects to the answers the check resolved, so a name whose answer changes
+  between the check and the scan (DNS rebinding) is not followed — the limits are in the Security note above
+- `FTP_CHECK_ANON=true` — lets the FTP check try an anonymous login (off by default; without it `scan_host` never reports anonymous FTP). `DNS_CHECK_AXFR=true` with `DNS_AXFR_DOMAIN=<zone>` — lets the DNS check try a zone transfer of that zone (off by default). `DNS_AUDIT_AXFR_CHECK=true` (or `1`, `yes`, `on`) — lets the DNS-security audit (060) try a zone transfer of the scanned domain against each of its nameservers (off by default; it connects to each nameserver's own address, which it classifies first — see the Security note above). `SMB_NULL_SESSION=true` — lets the NetBIOS check try an SMB null session (off by default). The FTP, DNS and NetBIOS checks, when off or when they ran and could not complete (a timeout, a dropped connection), are recorded and reported as not tested with their reason — never as refused; the DNS-security audit records what each nameserver answered (transferred the zone, answered without transferring it, refused, or no answer) and why a nameserver it did not ask was not asked. The two zone-transfer checks ask different hosts: the DNS check asks the scanned host, the DNS-security audit asks each of the domain's nameservers. When the scanned host is itself one of the domain's nameservers and `DNS_AXFR_DOMAIN` names that domain, a report carries a finding from each — two measurements of one exposure, not two exposures. The same variables govern the CLI scan.
+- `PLUGIN_TIMEOUT_MS=5000` — the per-plugin budget for `scan_host` and `probe_service` (default 30000), and it binds every plugin there, including one that declares a longer budget of its own. It bounds each PLUGIN, not the call: `scan_host` runs a host's plugins one after another, so the call takes roughly the sum of their times — on a real home gateway the plugins of one full scan took ~113 s between them at the default budget, and 54–122 s across five runs on another router. Without a call limit, on one router a `scan_host` call timed out in Claude Desktop on 2026-08-10 and one returned within 138 s on 2026-09-30. The call is bounded by `SCAN_HOST_WALL_MS` (below).
+- `SCAN_HOST_WALL_MS` — the time limit for the whole `scan_host` CALL (default 50000; `0` turns it off). Three walls, side by side: `PLUGIN_TIMEOUT_MS` bounds each network plugin, `CLOUD_PLUGIN_TIMEOUT_MS` each cloud plugin, and `SCAN_HOST_WALL_MS` the `scan_host` call. It exists because the CLIENT may end a tool call at a limit of its own, and a call it ends returns nothing at all — never read that as a clean host: on 2026-10-21 Claude Desktop 3.x ended both of two measured `scan_host` calls at about 60 s, whatever `MCP_TIMEOUT` said. With the limit, the call ends first, keeping 3 s for the summary and the response: a plugin still running at the limit is stopped, and the plugins after it are not started. Each reads `timeout` in `manifest`; the response's `callWall` lists them in the order they would have run (`notStarted`, `cutShort`, beside `limitMs` and `reached`, present on every call); and the response's `note` and the head of `markdown` say the scan is partial — not a clean result. **What it costs, measured:** the MCP Scanner (070) runs early, at priority 70, and on one home router that dropped its probes it took 44.6 s. With `PLUGIN_TIMEOUT_MS` at 45 s or more, it runs into the limit and the plugins after it in priority order are not started — on an Enterprise install the Zero Trust Assessment (1023), then the DNS-security audit (060) through to the TLS Scanner (011) and the TLS Certificate & Cipher Auditor (040), so the TLS and certificate checks are the first lost. At the 30 s default, 070 stops at its own 30 s and the seconds left go to the plugins after it, in that order. For a complete scan of such a host, run the CLI, or raise `SCAN_HOST_WALL_MS` in a client that does not cut the call.
 - `PLUGIN_TIMEOUT_CEILING_MS` — the upper bound on any plugin's DECLARED budget (default 120000). A few plugins declare their own budget because their cost grows with what they scan (the UPnP and MCP scanners here; several cloud auditors in Enterprise). On the CLI a declaration outranks `PLUGIN_TIMEOUT_MS`, so this is the setting that caps every plugin there. The MCP tools already bind declarations with their own limits.
 - `CLOUD_SCAN_CONCURRENCY` — max cloud plugins run at once by `scan_cloud` (default 20).
 - `CLOUD_PLUGIN_TIMEOUT_MS` — per-plugin timeout for `scan_cloud` (default 25000; independent of the network `PLUGIN_TIMEOUT_MS`). It bounds each plugin, not the call — see the all-region note above before raising it.
+- `NSA_MCP_RESPONSE_DIR` — off unless set. An **absolute** directory where the server saves each tool response,
+  exactly as it returned it, as `<call_id>.txt` (the directory is created `0700` if missing, each file `0600`, and an
+  existing file is never overwritten). It exists for `nsauditor-ai mcp verify-call <call_id> --response <file>`, which
+  needs the whole response: Claude Desktop shows long tool output truncated, and a truncated copy cannot be verified.
+  Beside each response the server saves its request as `<call_id>.request.json`: the tool's name and the call's own
+  arguments, verbatim (a `scan_host` host, `scan_cloud`'s providers and regions) — both files or neither, `0600`.
+  `verify-call <call_id> --response <file> --request <file>` checks both: the server logs a digest of each.
+  When the copies were saved, the response's receipt footer says so (it names the files, not the directory). The files
+  hold scan results and the targets you asked about — keep the directory private, and clear it yourself; nothing
+  removes them. It is a server setting, not a
+  scan target: set it in this `env` block (not in an `NSA_ENV_FILE` file), then fully quit and reopen Claude Desktop.
 - `AI_PROVIDER` and API key — optional, enables AI-powered analysis of scan results
 
 #### `NSA_ENV_FILE` — point the MCP server at an environment file
@@ -462,15 +475,20 @@ nsauditor-ai --version     (or -v, or `version`)
 | `--out <dir>` | Custom output directory — applies to the per-scan folder *and* to alternate-format files (SARIF/CSV/Markdown) | `out/` |
 | `--parallel <n>` | Concurrent host scans | `1` |
 | `--output-format <fmt>` | Additional output format: `sarif` (CI/CD) · `csv` (spreadsheet) · `md` or `markdown` (chat/PR/Slack quotable) | — |
-| `--fail-on <sev>` | Exit code 1 if any finding is ≥ severity (`critical\|high\|medium\|low\|info`). It reads the same findings the Markdown, SARIF and CSV reports count — one shared table grades them, one finding per item: anonymous FTP login, DNS zone transfer and MCP unauthenticated access or tool listing are critical; an SNMP default community, an expired certificate, an SMB null session, MCP cleartext transport and a deprecated MCP protocol are high; weak SSH algorithms, weak TLS protocols and negotiated ciphers, dangerous HTTP methods, a self-signed certificate and an exposed MCP Inspector are medium; the TLS-certificate (040), debug-endpoint (050) and DNS-security (060) audits grade each finding at its own severity, and 060 grades the scanned domain's SPF / DMARC / NS posture whether or not the host answered on 53/udp. **Since 1.3.0 it reads all of these — a pipeline that passed before may fail on findings that were always there.** Anonymous FTP login, zone transfer and the SMB null session are tested only when `FTP_CHECK_ANON=true` / `DNS_CHECK_AXFR=true` with `DNS_AXFR_DOMAIN` / `SMB_NULL_SESSION=true` are set; dangerous HTTP methods are read only where the HTTP probe read an Allow header; where it read none they are not tested, and that never trips the gate. Any concluded scan counts as info — so `--fail-on info` fails every scan that concludes. It does not read Enterprise's CVE rows or agent findings, so exit 0 is not a clean host; exit 2 for an unknown severity or no conclusion | — |
+| `--fail-on <sev>` | Exit code 1 if any finding is ≥ severity (`critical\|high\|medium\|low\|info`). A flag the CLI refuses, or a scan target its address guard refuses, exits 2 with one `[ERROR]` line, so exit 1 stays this verdict. It reads the same findings the Markdown, SARIF and CSV reports count — one shared table grades them, one finding per item: anonymous FTP login, DNS zone transfer and MCP unauthenticated access or tool listing are critical; an SNMP default community, an expired certificate, an SMB null session, MCP cleartext transport and a deprecated MCP protocol are high; weak SSH algorithms, weak TLS protocols and negotiated ciphers, dangerous HTTP methods, a self-signed certificate and an exposed MCP Inspector are medium; the TLS-certificate (040), debug-endpoint (050) and DNS-security (060) audits grade each finding at its own severity, and 060 grades the scanned domain's SPF / DMARC / NS posture (and, with `DNS_AUDIT_AXFR_CHECK` set, an open zone transfer) whether or not the host answered on 53/udp. **Since 1.3.0 it reads all of these — a pipeline that passed before may fail on findings that were always there.** Anonymous FTP login, zone transfer and the SMB null session are tested only when `FTP_CHECK_ANON=true` / `DNS_CHECK_AXFR=true` with `DNS_AXFR_DOMAIN` / `SMB_NULL_SESSION=true` are set (the DNS-security audit's own zone-transfer attempt only when `DNS_AUDIT_AXFR_CHECK` is set); dangerous HTTP methods are read only where the HTTP probe read an Allow header; where it read none they are not tested, and that never trips the gate. Any concluded scan counts as info — so `--fail-on info` fails every scan that concludes. It does not read Enterprise's CVE rows or agent findings, so exit 0 is not a clean host; exit 2 for an unknown severity or no conclusion | — |
 | `--insecure-https` | Accept self-signed TLS certificates | `false` |
 | `--watch` | CTEM continuous **alerting** loop — re-scan on `--interval`, compare each host with the previous cycle, webhook for a host whose scan changed and that carries a finding at or above `--alert-severity`; the first cycle sets the baseline and alerts nobody (see Continuous Monitoring). Not an evidence cadence: no retention, no cross-run aggregation, skips SARIF/CSV/Markdown + `--fail-on`, dies with the process. Scans each distinct host once per cycle (a one-shot `--host X,X` scans `X` twice). Use a scheduler for SOC 2 Type II history. | `false` |
 | `--interval <min>` | Rescan interval in minutes (requires `--watch`) | `60` |
 | `--webhook-url <url>` | Webhook URL for watch-mode alerts (see `--watch`) | — |
-| `--alert-severity <sev>` | Minimum severity for webhook alerts | `high` |
+| `--alert-severity <sev>` | Minimum severity for webhook alerts: `critical`, `high`, `medium`, `low` or `info`, in any case — any other value is refused | `high` |
 | `--alert-every-cycle` | Alert every host with a finding at or above `--alert-severity` on every watch cycle, the first included (default: only hosts whose scan changed since the previous cycle) | `false` |
+| `--alert-payload <mode>` | `full` — the watch alert as it has always been · `minimal` — drops the host, the service and the description: a count, and each finding's port, protocol and severity | `full` |
 | `--compliance <fw>` | Compliance framework to map findings into. Accepts CSV for multi-framework runs (e.g. `soc2`, `hipaa`, `nist-csf`, `pci-dss`, `iso-27001`, `cis-v8`, `gdpr`, `nist-800-171`, or any combination like `soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr,nist-800-171` — `all` expands to the same eight). **Enterprise license required.** Supported frameworks as of EE 0.40.0 — **eight**: `soc2` (AICPA TSC 2017) + `hipaa` (HIPAA Security Rule §164.312 Technical Safeguards) + `nist-csf` (NIST Cybersecurity Framework 2.0 Core, CSWP 29 Feb 2024) + `pci-dss` (PCI DSS v4.0.1, PCI SSC June 2024 errata) + `iso-27001` (ISO/IEC 27001:2022, ISO + IEC October 2022) + `cis-v8` (CIS Critical Security Controls v8, CIS May 2021 / v8.1 errata June 2024) + `gdpr` (GDPR Article 32 / Security of Processing, Regulation (EU) 2016/679 — Art. 32 infrastructure substrate, **not** GDPR compliance) + `nist-800-171` (NIST SP 800-171 Rev 2 — evidence substrate for **CMMC Level 2 preparation**, **not** a CMMC certification, **not** a FedRAMP authorization, and no MET/NOT MET determination or SPRS score). See `@nsasoft/nsauditor-ai-ee` README for per-framework coverage details. | — |
 | `--compliance-scope <path>` | Optional JSON file describing the assessment scope (passed to the compliance engine for cover-page attestation) | — |
+| `--notify-webhook <url>` | **Enterprise; one-shot scans with `--compliance` only, never `--watch`.** Posts the scan's drift (`scan_drift_<fw>.json`) when a control goes to fail or loses measurement, when a new violation is at or above `--notify-severity`, or when this run could not be compared with the previous one. Public `https` URLs only — anything else is refused with exit 2 | — |
+| `--notify-format <fmt>` | `generic` · `slack` · `teams` (a Teams Workflows webhook, which takes an Adaptive Card) | `generic` |
+| `--notify-severity <sev>` | Threshold for NEW violations only (`critical\|high\|medium\|low\|info`); a control going to fail or losing measurement always sends | `high` |
+| `--notify-payload <mode>` | `minimal` — framework, counts, control ids, severities and scanner ids; no hostname, resource name, account id or finding text · `full` adds them | `minimal` |
 | `--help`, `-h` | Print usage block (subcommands, flags, env vars, examples) and exit 0 | — |
 | `--version`, `-v` | Print `nsauditor-ai <version>` and exit 0 | — |
 
@@ -553,7 +571,7 @@ HEALTHCHECK --interval=60s --timeout=5s --start-period=10s --retries=3 \
 | `--format executive` | Self-contained, print-ready HTML report; no external network reference other than an `http(s)`/`mailto` `<a href>` | — |
 | `--format jira` | Jira-importer CSV (`Summary`/`Description`/`Priority`/`Labels`/`External ID`); the import mapping is done in Jira and has not been verified against a live Jira instance. **`pass`-tier records are EXCLUDED** — a Jira issue is a work item and a passing check is not work; every other tier is kept, INFO included, because INFO carries the evidence gaps and scope boundaries. Passing checks appear in the `executive` report under their own **PASS** tier. | — |
 | `--run <id>` | Report a specific run id instead of the newest one under `--from` | newest run |
-| `--since <runId\|prior>` | Compare the reported run with a baseline run under `--from`: `prior` is the run that started immediately before it, or name a run id. The `executive` report lists each new, resolved and changed finding, and each finding that could NOT be compared with its reason; stdout prints the counts, the changed and not-comparable rows and the limits; the `jira` CSV carries none of it. Each new, resolved and changed row carries a **Basis** cell saying what made it comparable: for a plugin's row, the host, plugin and scope present in both runs; for an Enterprise analysis agent's or the CVE mapper's row, that the run lacking it recorded no evidence gap from that producer covering it, and — for a CVE or end-of-life row on a TCP port — the measurement itself (the service identified, or the port closed). Where the run lacking an agent row predates EE 1.3.0, the cell says that run could not record an input plugin left out of the scan, so the row is not refused. When the baseline was made before Enterprise 1.3.0, keep `--plugins` identical between the two scans (see What's New). Every refusal exits 2: if the baseline was found but cannot support a comparison, the `executive` report is still written, states the refusal and lists no new, resolved or changed finding; if no baseline is found, if the reported run's own record fails verification, or with `--format jira`, nothing is written | — |
+| `--since <runId\|prior>` | Compare the reported run with a baseline run under `--from`: `prior` is the run that started immediately before it, or name a run id. The `executive` report lists each new, resolved and changed finding, and each finding that could NOT be compared with its reason; stdout prints the counts, the changed and not-comparable rows and the limits; the `jira` CSV carries none of it. Each new, resolved and changed row carries a **Basis** cell saying what made it comparable: for a plugin's row, the host, plugin and scope present in both runs; for an Enterprise analysis agent's or the CVE mapper's row, that the run lacking it recorded no evidence gap from that producer covering it, and — for a CVE or end-of-life row on a TCP port — the measurement itself (the service identified, or the port closed). When the TLS scanner (011) could not complete a handshake on a port the port scanner saw open, its row names the transport error (`ECONNRESET`, `ETIMEDOUT`, …) and Enterprise records the port as not measured, so an earlier TLS finding there is not comparable — except when another port of the same scan completed a TLS handshake: then the failed port is not read, and such a finding can read as resolved (a stated limit). Where the run lacking an agent row predates EE 1.3.0, the cell says that run could not record an input plugin left out of the scan, so the row is not refused. When the baseline was made before Enterprise 1.3.0, keep `--plugins` identical between the two scans (see What's New). Every refusal exits 2: if the baseline was found but cannot support a comparison, the `executive` report is still written, states the refusal and lists no new, resolved or changed finding; if no baseline is found, if the reported run's own record fails verification, or with `--format jira`, nothing is written | — |
 | `--brand <brand.json>` | Cover-page branding (company name, prepared-by, contact, logo) — `--format executive` only | unbranded |
 | `--out <path>` | Write to this path instead of `report_<runId>.<ext>` beside the run record | `report_<runId>.<ext>` |
 | `--allow-partial` | Render even if some requested hosts were never written, or the run never recorded completion — the caveat is stated on the cover, never hidden | `false` |
@@ -677,7 +695,7 @@ No license key? Everything in this repository works perfectly without one. The C
 | 024 | TCP SYN Scanner | TCP (Nmap) | SYN half-open scan via Nmap wrapper (optional) |
 | 040 | TLS Certificate & Cipher Auditor | TCP:443+ | Cert expiry, chain integrity, hostname mismatch, weak ciphers, deprecated protocols, key strength |
 | 050 | TRIBE v2 Neural API Security Probe | TCP/HTTP:8080 | Debug leak detection, stack traces in errors, header security, CORS misconfiguration, unauthenticated routes |
-| 060 | DNS Security Auditor | DNS/UDP:53 | SPF/DKIM/DMARC, dangling CNAMEs, DNSSEC, NS delegation, zone transfer exposure, MX security, CAA records |
+| 060 | DNS Security Auditor | DNS/UDP:53 | SPF/DKIM/DMARC, dangling CNAMEs, DNSSEC, NS delegation, zone transfer exposure (opt-in: `DNS_AUDIT_AXFR_CHECK`), MX security, CAA records |
 | 070 | MCP Scanner | TCP/HTTP+SSE | Detects MCP (Model Context Protocol) servers on candidate ports (1967, 3000, 3005, 5173, 6274, 6277, 8000, 8090). Audits for cleartext transport (HTTP not HTTPS), missing/anonymous auth, anonymous tool enumeration, deprecated protocol versions, and Inspector exposure on non-loopback. Maps findings to CWE/OWASP/MITRE per the FindingSchema. STDIO-transport MCP servers are out of scope (no network port). |
 
 ### Discovery Plugins
@@ -705,7 +723,7 @@ See [Pro & Enterprise Activation](#pro--enterprise-activation) to install a lice
 
 Every compliance scan already produces a GRC-ready JSON evidence artifact. The **GRC connectors** take the next step: they map each NSAuditor compliance finding to your GRC platform's own evidence/test records and **push them at scan time** — so your Vanta, Drata, or Secureframe workspace reflects the latest cloud posture without a manual export/import round-trip.
 
-**Opt-in, and Zero-Data-Exfiltration by default.** The push is off unless you set the environment variables below. When it runs, finding text and target identifiers go to your platform as written unless you set `COMPLIANCE_GRC_REDACTION` to `hash` or `remove` (redaction is off by default); the persisted audit log stores a body **fingerprint** (never the raw payload), and your API token is never written to any artifact. Nothing leaves your infrastructure that you didn't opt into.
+**Opt-in, and Zero-Data-Exfiltration by default.** The push is off unless you set the environment variables below. When it runs, finding text and target identifiers go to your platform as written unless you set `COMPLIANCE_GRC_REDACTION` to `hash` or `remove` (redaction is off by default); the persisted audit log stores a body **fingerprint** (never the raw payload), and your API token is never written to any artifact. The push sends only what you opted into, and nothing goes to Nsasoft.
 
 ```bash
 # Enable the scan-time push (Enterprise)
@@ -744,7 +762,7 @@ The Result Concluder (plugin 008) merges all plugin outputs into a normalized st
 
 NSAuditor AI supports three AI providers for vulnerability analysis. **All providers work in all tiers** — CE, Pro, and Enterprise. AI is optional; the platform is fully functional without it.
 
-**Providers:** OpenAI (GPT-4o), Anthropic Claude (Sonnet/Opus), Ollama (fully local)
+**Providers:** OpenAI (default model `gpt-6-luna` from Community 1.0.0; set `OPENAI_MODEL` for another), Anthropic Claude (Sonnet/Opus), Ollama (fully local). Setup, exactly what is sent and what is written: [docs/openai.md](./docs/openai.md).
 
 **What changes by tier is the prompt content, not the provider:**
 
@@ -752,7 +770,7 @@ NSAuditor AI supports three AI providers for vulnerability analysis. **All provi
 - **Pro** — intelligence-enriched prompts (CVE matches, MITRE ATT&CK technique annotations, composite risk scores injected into the prompt). Same API call, better-grounded output
 - **Enterprise** — Pro prompts + compliance context
 
-**Redaction:** On by default (`OPENAI_REDACT=false` turns it off), the redaction pipeline masks IP addresses, MAC addresses, serial numbers, and configurable confidential keywords before the payload reaches an AI API. Admin RAW reports retain full detail for internal review.
+**Redaction:** On by default (`OPENAI_REDACT=false` turns it off). Before the scan payload reaches an AI API it masks the scanned host, IPv4 addresses (private ones in service and evidence text), colon-separated MAC addresses, full-form IPv6 addresses, serial numbers, a scanned service's Set-Cookie values, and any field named in `CONFIDENTIAL_KEYWORDS`. From Community 1.0.0 it also masks AWS account IDs found in ARNs and AWS URLs, everywhere they occur and inside resource names (the names are kept), and any other 12-digit number under a neutral label (0.2.57 and earlier send both). **It does not mask** cloud resource names, AWS access-key IDs, hostnames, e-mail addresses and certificate subjects in service text, compressed IPv6 addresses, or dash- and dot-form MAC addresses (measured 2026-10-11) — inspect `scan_response_ai_payload.json` before using the AI step on production data. On Pro and Enterprise the intelligence block travels in the system prompt, which the redactor does not see and the payload file does not record; [docs/openai.md](./docs/openai.md) has the details. Admin RAW reports retain full detail for internal review.
 
 ```ini
 # .env
@@ -786,7 +804,8 @@ nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
 - **Scheduling** with configurable intervals and concurrency control
 - **Change detection** — each host's scan is compared with that host's previous line in `scan_history.jsonl` and printed as a `[ScanHistory]` line: new, removed and changed services, the findings delta, and — since 1.3.0 — each service-check finding that appeared, cleared or was first observed, and each one that could not be compared, with the reason (a check that did not run this time is never read as cleared). The first scan after upgrading says the service checks were not compared, because the earlier line did not record them
 - **Webhook alerts** — a JSON POST, retried up to twice 1 s apart on a 5xx or network error, not on a 4xx. Each cycle is compared with the one before, host by host, and printed as an `=== Delta Report ===`. A host has CHANGED when a service appeared, went or changed, its finding count moved or could not be compared, a service check appeared, cleared or could not be compared, or the two cycles could not be compared at all. An alert is posted for each changed host carrying a finding at or above `--alert-severity` — one detail per finding with its own grade, from the table `--fail-on` reads (at `info`, every finding counts; a host with none gets no alert). The first cycle establishes the baseline and does not alert, whatever it finds; `--alert-every-cycle` alerts every host carrying such a finding on every cycle, the first included. A host whose scan failed is reported on stdout and does not alert in this release.
-- **SSRF protection** — private, loopback, and cloud metadata addresses blocked at the scan entry point and inside `sendWebhook()`, and at every host a scanned target names: the webapp detector re-checks each redirect hop (at most 5) and sends your `HTTP_EXTRA_HEADERS` only to the origin you named, the UPnP scanner fetches a device description only from the device that answered, and the OpenSearch scanner does not follow redirects. `NSA_ALLOW_ALL_HOSTS=1` lifts the scan-entry guard for local network auditing — on the CLI the whole guard, loopback and metadata included; over MCP, the private-range check only, so loopback, link-local and metadata stay refused — and never the webhook guard
+- **What watch alerts cover** — `--watch` alerts cover network-scan findings; cloud-plugin findings and compliance control status do not alert — use the drift file and its notification on a scheduled one-shot scan (Enterprise: `--notify-webhook`). `--alert-payload minimal` drops the host, the service and the description from each alert; `full` stays the default. The start-up line names the webhook's host and never its URL: a Slack or Teams webhook URL carries its own credential
+- **SSRF protection** — private, loopback, and cloud metadata addresses blocked at the scan entry point and inside `sendWebhook()`, which connects to the address its own check resolved, so a webhook name that answers differently between the check and the connect is not followed (with `NODE_USE_ENV_PROXY` and a proxy configured, Node sends the webhook through that proxy by name and the proxy resolves it — the pin then covers only the hop to the proxy; since CE 1.0.0 a scanned host and each redirect hop are pinned the same way — see the MCP security note), and at every host a scanned target names: the webapp detector re-checks and pins each redirect hop (at most 5) and sends your `HTTP_EXTRA_HEADERS` only to the origin you named, the UPnP scanner fetches a device description only from the device that answered, and the OpenSearch scanner does not follow redirects — the one exception is the DNS-security audit's zone-transfer attempt, off by default (see the MCP security note). `NSA_ALLOW_ALL_HOSTS=1` lifts the scan-entry guard for local network auditing — on the CLI the whole guard, loopback and metadata included; over MCP, the private-range check only, so loopback, link-local and metadata stay refused — and never the webhook guard
 - **Scan history** stored in `scan_history.jsonl` in the output directory (`--out`, default `out/`; 7-day retention in CE)
 
 ---
@@ -937,7 +956,7 @@ Commonly requested plugins: RDP, VNC, SMTP/POP3/IMAP, MySQL/PostgreSQL/MSSQL/Mon
 
 For the full technical architecture, see [ARCHITECTURE.md](docs/architecture.md).
 
-**Tech stack:** Node.js 20+ · ES Modules (.mjs) · OpenAI + Anthropic SDKs · Node.js built-in test runner · MCP stdio transport
+**Tech stack:** Node.js 24.22.1+ · ES Modules (.mjs) · OpenAI + Anthropic SDKs · Node.js built-in test runner · MCP stdio transport
 
 **Design patterns:** Factory (PluginManager.create) · Strategy (orchestrated/legacy execution) · Context (shared state) · Adapter (plugin conclude()) · Guard Clause (requirement gating) · Capability gating (CE/Pro/EE) · Semaphore (concurrency control) · Delta (scan history diff) · Boundary Guard (SSRF/injection protection) · Finding Queue (structured intermediate format) · Parallel Agents (concurrent specialized analysis)
 

package/bin/nsauditor-ai.mjs

@@ -1,3 +1,5 @@
 #!/usr/bin/env node
-import { main } from '../cli.mjs';
-main().catch((err) => { console.error(err?.stack || err); process.exit(1); });
+// The command npm installs. It imports main(), so cli.mjs is never the entry point here: a rejection goes to cli.mjs's
+// own exitOnMainRejection, the one copy of the exit-code mapping (a flag refusal exits 2; anything else exits 1).
+import { main, exitOnMainRejection } from '../cli.mjs';
+main().catch((err) => exitOnMainRejection(err));