nsauditor-ai 0.2.50 → 0.2.52

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,36 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
+**Latest: CE 0.2.52 + Enterprise 0.45.0 — the Enterprise NTP clock attestation is WITHDRAWN.** The probe
+is deleted: it validated any reply of at least 48 bytes with a non-null transmit timestamp and nothing
+else — no mode byte, no stratum, no originate echo — so over unauthenticated UDP a datagram of the right
+shape produced a false clean reading, and it measured the SCANNER's own clock rather than your estate.
+It had never been reachable from any shipped entry point.
+RFC 3161 trusted timestamping is untouched, opt-in, and is the capability that answers the question —
+off unless you configure a Time-Stamp Authority, and an outbound call to a third party when you do. On the Community side this cycle changes no behaviour: the
+withdrawn-claim guard over `license --capabilities` descriptions learns the wording the product actually
+published, so the class cannot recur silently here. See [CHANGELOG.md](./CHANGELOG.md).
+
+**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
@@ -120,7 +150,7 @@ Scan → Analyze → Prioritize → Track → Act
 - **Smart result fusion** — the Result Concluder merges all plugin outputs into a normalized view with OS detection, service fingerprinting, and evidence linking
 - **Structured finding format** — all findings use a common schema with category, severity, evidence, and remediation — enabling consistent SARIF export and MCP integration
 - **AI-powered analysis** — send redacted scan results to OpenAI or Claude (your keys, your choice) for vulnerability assessments and remediation guidance
-- **Risk-scored prioritization (Pro)** — findings carry a composite risk score (CVSS weighted by verification status, with an uplift for initial-access techniques) and a status field, and an operator suppression workflow (accepted-risk / false-positive with expiry) keeps triaged findings out of the report until they expire
+- **Risk-scored prioritization (Pro/Enterprise)** — findings carry a composite risk score (CVSS weighted by verification status, with an uplift for initial-access techniques) and a status field, and an operator suppression workflow (accepted-risk / false-positive with expiry) keeps triaged findings out of the report until they expire
 - **Continuous monitoring (CTEM)** — watch mode rescans on a schedule, diffs against previous results, and fires webhook alerts on changes
 - **MCP integration** — expose scanning tools to AI assistants like Claude Code via Model Context Protocol
 - **CI/CD ready** — SARIF output with `--fail-on` severity gating for pipeline integration
@@ -172,11 +202,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 | — | — | ✅ |
@@ -761,6 +792,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/Enterprise)
 nsauditor-ai mcp
 nsauditor-ai --help        (or -h, or `help`)
 nsauditor-ai --version     (or -v, or `version`)
@@ -854,6 +886,82 @@ HEALTHCHECK --interval=60s --timeout=5s --start-period=10s --retries=3 \
   CMD nsauditor-ai validate --json | grep -q '"overall": "ok"' || exit 1
 ```
 
+### `report` command (Pro/Enterprise)
+
+`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
+```
+
+#### The `brand.json` file
+
+`--brand` takes a small JSON object. Every field is optional; omit the file entirely and the report
+renders unbranded with the default title.
+
+```json
+{
+  "title": "Q3 External Perimeter Review",
+  "companyName": "Acme Manufacturing GmbH",
+  "preparedBy": "J. Rivera, Security Consulting LLC",
+  "contact": "security@example.com",
+  "logoPath": "acme-logo.png"
+}
+```
+
+| field | type | default | notes |
+|---|---|---|---|
+| `title` | string | `Network Scan Report` | Replaces the report's headline. |
+| `companyName` | string | *(empty)* | The client the report is prepared **for**. |
+| `preparedBy` | string | *(empty)* | The consultant or firm preparing it. |
+| `contact` | string | *(empty)* | Free text — an address, an email, a phone number. |
+| `logoPath` | string | *(none)* | A **local** PNG or JPEG, resolved relative to the brand file's own directory. Embedded into the HTML as a data URI. |
+
+**`logoPath` is deliberately restrictive, and each refusal protects the report's core promise —
+that it opens with no external network reference of any kind:**
+
+- **A URL is refused and never fetched.** A remote logo is egress at render time and a tracking
+  pixel every time your client opens the file.
+- **A UNC share (`\\host\share\...`) is refused** for the same reason: it is a network reference.
+- **SVG is refused.** SVG is markup and can carry a script, which would break the report's
+  no-script guarantee from inside the image. Use PNG or JPEG.
+- **The path must stay inside the brand file's own directory** — `../` escapes are refused, checked
+  both as typed and again after symlinks are resolved.
+- **2 MB maximum**, and the format is detected by **magic bytes, not by file extension** — renaming
+  `logo.svg` to `logo.png` does not get it past the check.
+- **An empty string is read as "no logo"**, the same as omitting the key, so a generated
+  `brand.json` that emits `""` is not an error.
+
+A brand file that cannot be read, is not valid JSON, is not a JSON object, or whose `logoPath` is
+refused is a **fatal error** — the report is not written. A flag you passed is never silently
+dropped, because that is how a report goes out unbranded without anyone noticing.
+
+⚠️ `--brand` applies to `--format executive` only. Passing it with `--format jira` is **refused**,
+not ignored: a CSV has nowhere to put a cover page.
+
 ---
 
 ## Configuration
@@ -1138,7 +1246,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