nsauditor-ai 0.2.49 → 0.2.51

package/README.md

@@ -7,7 +7,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)
-[![Tests](https://img.shields.io/badge/tests-1308%20passing-brightgreen.svg)](#tests)
+[![Tests](https://img.shields.io/badge/tests-1582%20passing-brightgreen.svg)](#tests)
 
 ---
 
@@ -17,6 +17,40 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
+**The Pro `report` subcommand, over a run record that states its own coverage (CE 0.2.51 / Enterprise 0.44.0).**
+`nsauditor-ai report --from <dir> --format executive|jira` turns a completed scan run into a
+client-facing deliverable — a self-contained, print-ready HTML report a consultant sends to their
+customer, or a Jira-importer CSV. Beneath it is a **per-run scan record**: written at run start,
+appended per host, finalized at the end, so the report's cover **states** what was covered — hosts
+requested, written and reachable, and the exploit-intelligence as-of dates read from the store's own
+metadata — instead of implying completeness. An incomplete run says so on the cover; `--allow-partial`
+renders it anyway with the caveat visible, never hidden. Two limits are shipped as text rather than
+left to be discovered: the **Jira import mapping has not been verified against a live Jira instance**,
+and a value-less `--from`/`--brand`/`--run`/`--out` is a **fatal error, not a silent default**. On the
+Enterprise side the same cycle stops reporting an S3 audit-trail gap on a bucket whose object-level
+reads and writes a CloudTrail data-event trail already records. See the
+[`report` command section](#report-command-pro) and the [CHANGELOG](./CHANGELOG.md).
+⚠️ **The Enterprise peer floor stays `>=0.2.49` — it is NOT raised to 0.2.51.** Raising it would charge
+every Enterprise operator an upgrade for a Community feature they may not want. The consequence is
+worth stating rather than discovering: an Enterprise 0.44.0 install resolves cleanly against Community
+0.2.49 or 0.2.50 and simply has **no `report` command**. Install Community 0.2.51 to get it.
+Every scan now also writes `scan_run_<runId>.json` at the root of `--out` — the record the report is
+built from. On the free tier these are pruned after a retention window; on Pro they are kept.
+
+**A provider badge you can trust, and an evidence gap that never tells an auditor what to type (CE 0.2.50 / Enterprise 0.43.0).**
+**No Community behaviour changed this cycle** — the version moves so the trio stays in lockstep, and **the Enterprise peer floor stays `>=0.2.49`** rather than being raised reflexively, because the
+one Community behaviour the Enterprise fix depends on already shipped there. What changed is on the
+Enterprise side and shows up in output a Community user also reads: an Enterprise scan whose cloud
+SDK failed to load used to report that provider as **audited**, because a plugin result carrying
+neither an error nor a skip flag falls through to `ran` in this package's plugin manager, and
+`auditedProviders` is derived from `ran`. Eighteen refusals across seventeen AWS and GCP plugins now
+carry their cause, so such a provider appears as `errored` and drops out of `auditedProviders`.
+Second: the compliance engine quotes a plugin's reason into the *"could not run"* sentence of every
+control that plugin evidences, and it used to quote the whole thrown message — so the SDK loaders'
+own `Install: npm install <pkg>@latest` reached the evidence-gap text of 7 SOC 2, 2 GDPR and 12 NIST
+SP 800-171 controls. **The report now states what was not evidenced; the operator channel states how
+to change it** — which matters most for air-gapped installs, where that instruction cannot be run.
+
 **Sovereign and air-gapped AWS partitions stop being mistaken for commercial (CE 0.2.49 / Enterprise 0.42.0).**
 This one DOES change CE behaviour, and Enterprise now requires it (`>=0.2.49`). `detectPartition`
 tested only `cn-` and `us-gov-` before falling through to `'aws'`, so every ISO and European
@@ -158,11 +192,12 @@ How Marketplace fulfillment works (ZDE and air-gap preserved — no runtime AWS
 | AI analysis (OpenAI, Claude, Ollama — your keys) | ✅ basic | ✅ enriched | ✅ enriched |
 | Structured findings + SARIF + CSV export | ✅ | ✅ | ✅ |
 | CTEM watch mode | ✅ basic | ✅ advanced | ✅ advanced |
-| **Pro features (vulnerability assessment)** | | | |
+| **Pro features** | | | |
 | CVE matching + MITRE ATT&CK mapping | — | ✅ | ✅ |
 | Risk scoring + prioritization | — | ✅ | ✅ |
 | Exploit intelligence — **CISA KEV** + **FIRST EPSS** joined onto the CVE matches, exploit-first ordering (a KEV-listed MEDIUM outranks an unexploited CRITICAL); stores are operator-populated — no feed data ships | — | ✅ | ✅ |
 | Parallel analysis agents | — | ✅ | ✅ |
+| **Client reporting** — `report --format executive` renders a completed run as a self-contained, print-ready HTML report with optional cover-page branding (`--brand`); `--format jira` writes a Jira-importer CSV. ⚠️ The Jira import mapping is done in Jira and has **not been verified against a live Jira instance**. | — | ✅ | ✅ |
 | **Enterprise — cloud scanning** | | | |
 | 29 enterprise plugins — 28 cloud (AWS / Azure / GCP) + 1 network-scan zero-trust check | — | — | ✅ |
 | Zero Trust assessment | — | — | ✅ |
@@ -747,6 +782,7 @@ nsauditor-ai validate
 nsauditor-ai feed bundle --from <dir-of-NVD-feeds> --out <bundle.json.gz> [--kev <f>] [--epss <f>]
 nsauditor-ai feed import --file <feed-or-bundle> [--cache-dir <d>] [--extras-dir <d>] [--append]   # the feeds you downloaded
 nsauditor-ai compliance <attest|suppress|review|renew|keygen|sign-pack|verify-pack>   (Enterprise)
+nsauditor-ai report --from <dir> --format executive|jira [--run <id>] [--brand <brand.json>] [--out <path>] [--allow-partial]   (Pro)
 nsauditor-ai mcp
 nsauditor-ai --help        (or -h, or `help`)
 nsauditor-ai --version     (or -v, or `version`)
@@ -840,6 +876,37 @@ HEALTHCHECK --interval=60s --timeout=5s --start-period=10s --retries=3 \
   CMD nsauditor-ai validate --json | grep -q '"overall": "ok"' || exit 1
 ```
 
+### `report` command (Pro)
+
+`nsauditor-ai report --from <dir> --format executive|jira` turns a completed scan run under `--from` into a client-facing deliverable — an HTML report a consultant sends to their customer, or a Jira-importer CSV.
+
+**What it reads.** A scan record keeps findings in more than one place, and the report reads all of them: each plugin's `result.findings` (an array, or a dict of categories as the DNS auditor emits), zero-trust dimension findings, per-port TLS issues, and the **finding queue** (`scan_finding_queue.json`) that carries the CVE/KEV/EPSS-enriched entries. `result.data` is deliberately NOT read — on a network scan it holds probe telemetry, not findings. The container inventory is enforced by a census: a container holding findings that no reader opens fails the build rather than rendering as a clean report.
+
+| Flag | Description | Default |
+|---|---|---|
+| `--from <dir>` | The scan `--out` directory holding the run's record and per-host evidence | *required* |
+| `--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 |
+| `--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` |
+
+A value-less `--from`/`--brand`/`--run`/`--out` (nothing after the flag, or a shell glob that swallowed the argument) is a fatal error, not a silent default.
+
+**Exit contract** — `0` a report was rendered · `1` fix the RUN (no run record under `--from`, or an
+incomplete run without `--allow-partial`) · `2` fix the REQUEST or its environment (an unknown or
+missing flag value, an unwritable `--out`, a `--brand` file that is refused).
+
+⚠️ `--brand` with `--format jira` is **refused**, not ignored: a Jira CSV has nowhere to put branding,
+and silently dropping a flag the caller passed is how a report goes out unbranded without anyone
+noticing.
+
+```bash
+nsauditor-ai report --from out/2026-08-26 --format executive --brand brand.json --out report.html
+nsauditor-ai report --from out/2026-08-26 --format jira
+```
+
 ---
 
 ## Configuration
@@ -1124,7 +1191,7 @@ No license key? Everything in this repository works perfectly without one. The C
 
 ## Tests
 
-Run all 1308 tests:
+Run all 1582 tests:
 
 ```bash
 npm test