nsauditor-ai 0.2.32 → 0.2.33

package/README.md

@@ -17,6 +17,8 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
+**Capability-claim honesty pass, part 2 — the air-gapped-delivery class (CE 0.2.33 / Enterprise 0.32.8).** Paired with Enterprise 0.32.8, a **documentation-and-prose release** — no detection, routing, or compliance behaviour changes. 0.32.7 withdrew six phantom capability *flags*; an audit of the air-gapped-delivery claims found the same class one layer down, in prose, across **27 sites** (distinct lines) in the three published packages. **CE fix this cycle — `--out` with a version-named directory.** `--out .../ee-0.32.8` silently wrote artifacts to the *parent* directory: the file-vs-directory check keyed on "has an extension", and `path.parse('ee-0.32.8').ext` is `'.8'`. The same shape broke `v1.2.3` and `release-2026.07`. An extension now counts as file-like only if it starts with a letter, so version-named output directories work and `--out report.json` still resolves to its parent. Found by the pre-publish smoke gate running the documented command end-to-end. **CE docs change this cycle:** the ZDE section's *"Fully air-gappable. Every feature works without internet access"* is corrected to **"Air-gappable, once configured for it"** — scanning, analysis, license verification and evidence-pack generation all run with no outbound network access, and Enterprise adds offline CVE matching under `NSAUDITOR_OFFLINE_ONLY=1` (which emits an explicit coverage gap rather than a silent clean when the local store cannot answer), but a **default** scan still attempts NVD egress unless that variable is set, and the only other outbound paths — AI enrichment and the GRC push — are opt-in and off by default. The claim that Enterprise "includes offline NVD feeds" is **WITHDRAWN**: no feed data is delivered with the product, and populating the local store is the operator's. Held by a new mutation-proven guard (`tests/capability_claim_honesty.test.mjs`) that fails the build both if the absolute claim returns **and** if the honest qualifier is deleted. On the Enterprise side the same sweep found **five** rendered runtime strings — prose that reaches the assessor-facing evidence pack — making claims the code does not support. Plugin count UNCHANGED at 28; all seven coverage matrices UNCHANGED. See **[CHANGELOG.md](./CHANGELOG.md)** for the full per-release history.
+
 **Cross-framework routing + capability-claim honesty pass (CE 0.2.32 / Enterprise 0.32.7).** Paired with Enterprise 0.32.7, a **matrix-neutral** release. The network-scan analysis agents' findings now route in **all seven compliance frameworks** — a host serving cleartext or exposing SMB previously failed the SOC 2 report and read clean in HIPAA / NIST CSF / ISO 27001 / CIS v8 / PCI / GDPR off the *same scan*; that gap is closed (48 mapping rules across the seven framework files, a mutation-proven drift guard, all coverage matrices byte-identical). And a **capability-claim honesty pass** withdraws several Pro/Enterprise capabilities that were advertised without a shipping implementation. **CE code change this cycle:** the tier-capability map (`utils/capabilities.mjs`) drops six flags — `verificationEngine`, `brandedReports`, `usageMetering`, `dockerIsolation` (no implementation) and `zdePolicyEngine`, `enterpriseCTEM` (real cores ship + are claimed in prose; no distinct engine behind the name) — in lockstep with Enterprise and both licensing repos, so `nsauditor-ai license --capabilities` and every minted license now name only capabilities that ship. `resolveCapabilities(tier)` derives from tier and ignores the JWT capability array, so **issued licenses are unaffected**. Plugin count UNCHANGED at 28; all seven coverage matrices UNCHANGED. See **[CHANGELOG.md](./CHANGELOG.md)** for the full per-release history.
 
 **Network-scan false-negative closures on the analysis agents (CE 0.2.31 / Enterprise 0.32.6).** No CE code change this cycle — a paired bump for Enterprise 0.32.6, a **matrix-neutral** false-negative-hardening release on the EE analysis-agent (network-scan) path: **cleartext transport** is now flagged where before only weak-TLS-where-TLS-exists was — a service that should be encrypted but offers no TLS at all used to read clean (→ **SOC 2 CC6.7**); **SMB-alone** exposure is now its own **HIGH** finding rather than being silenced by an `SMB && RDP` conjunction — SMB without RDP is the higher-risk case (→ **CC6.6**); and **WinRM 5985/5986 · Elasticsearch 9300 · MSRPC 135 · a new aggregate open-port-count rule** are new exposure signals (→ **CC6.6**). Routed SOC 2-first with drift-detector coverage; **SOC 2 routing only this cycle — cross-framework mappings (HIPAA §164.312(e)(1) · CIS · NIST) deferred.** Plugin count UNCHANGED at 28; all seven coverage matrices UNCHANGED. See **[CHANGELOG.md](./CHANGELOG.md)** for the full per-release history.
@@ -1008,7 +1010,7 @@ NSAuditor AI is built on a **Zero Data Exfiltration (ZDE)** architecture:
 - **No data processing.** Nsasoft US LLC never sees, stores, or processes your scan results.
 - **AI is opt-in.** External AI calls use your own API keys. Redaction runs locally first.
 - **License validation is offline.** JWT signature verified locally with an embedded public key.
-- **Fully air-gappable.** Every feature works without internet access (Enterprise includes offline NVD feeds).
+- **Air-gappable, once configured for it.** Scanning, analysis, license verification and evidence-pack generation all run with no outbound network access; Enterprise adds offline CVE matching from a local NVD store under `NSAUDITOR_OFFLINE_ONLY=1`, which emits an explicit coverage gap rather than a silent clean when the store cannot answer. Stated precisely because it matters operationally: a **default** scan still attempts NVD egress unless that variable is set, and the only other outbound paths — AI enrichment and the GRC push — are opt-in and off by default. Populating the local NVD store is the operator's; no feed data is delivered with the product.
 
 Nsasoft US LLC is not a data processor, data controller, or business associate under any data protection regulation. You own and control all data produced by NSAuditor AI.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

package/plugins/port_scanner.mjs

@@ -300,3 +300,75 @@ export default {
     };
   },
 };
+
+/* --------------------------- conclude adapter --------------------------- */
+
+/**
+ * services[] enumerates services FOUND, so only an OPEN port becomes a record.
+ * A refusal (RST) or a timeout is the absence of a service, and neither is lost:
+ * both stay in the conclusion's evidence[] stream and in this scan's own
+ * tcpClosed / tcpFiltered / udpNoResponse buckets.
+ *
+ * Measured, on a default sweep of localhost (50 ports from config/services.json):
+ * 41 refusals, 1 listener. Materializing refusals would put 42 rows into
+ * services[] to carry one bit of signal — and every consumer renders services
+ * unfiltered (report_md's table, export_csv's row-per-service, SARIF results,
+ * attack_map, and the scan_history baseline that deltas compare against).
+ */
+const MATERIALIZED_STATUSES = new Set(["open"]);
+
+/**
+ * Without this adapter, result_concluder falls through to fallbackRecord(),
+ * which keeps only `rows.find(Boolean)` — ONE record for the whole sweep. Since
+ * this plugin emits one row PER scanned port, that collapsed N open ports into
+ * the first-SCANNED port and dropped the rest before any consumer (CE reports,
+ * EE analysis agents) ever saw them. It also derived that survivor's status from
+ * the host-level `result.up`, so a filtered port was reported `open` whenever any
+ * other port on the host was open.
+ *
+ * `service` is deliberately the not-fingerprinted label, NOT a well-known-port
+ * name: a TCP connect proves a port answers, not which protocol speaks on it.
+ * Consumers that infer a protocol from the port number must do so themselves, at
+ * their own (lower) confidence tier — the EE crypto_agent, for one, rates a
+ * label-derived cleartext finding HIGH with certainty prose and a port-inferred
+ * one MEDIUM with an explicit "UNCONFIRMED" caveat. Emitting `'ftp'` for port 21
+ * here would silently promote every unfingerprinted listener into the confident
+ * tier. Identification is the job of the protocol probes, which are authoritative
+ * for their ports and overwrite these records on merge.
+ *
+ * @param {{host?: string, result?: object}} args
+ * @returns {Promise<object[]>} one ServiceRecord per affirmatively-observed port
+ */
+export async function conclude({ result } = {}) {
+  const rows = Array.isArray(result?.data) ? result.data : [];
+  const items = [];
+
+  for (const row of rows) {
+    const port = Number(row?.probe_port);
+    if (!Number.isInteger(port) || port <= 0) continue;
+
+    const status = String(row?.status || "");
+    if (!MATERIALIZED_STATUSES.has(status)) continue;
+
+    items.push({
+      port,
+      protocol: String(row?.probe_protocol || "tcp").toLowerCase(),
+      service: "unknown",
+      program: result?.program || "Unknown",
+      version: result?.version || "Unknown",
+      // From the ROW, never from the host-level result.up.
+      status,
+      info: row?.probe_info || null,
+      banner: row?.response_banner || null,
+      source: "port_scanner",
+      // The record's OWN probe row. The full sweep is already pushed to the
+      // conclusion's top-level evidence[]; repeating it on every record would be
+      // O(n^2) duplication of the same rows.
+      evidence: [row],
+      // A connect scan never outranks a protocol probe for the same port.
+      authoritative: false,
+    });
+  }
+
+  return items;
+}

package/plugins/tls_scanner.mjs

@@ -46,6 +46,45 @@ const DEFAULT_PORTS = {
   995: 'pop3s'
 };
 
+// ── crypto_agent producer contract ──────────────────────────────────────────
+// The EE crypto_agent (agents/crypto_agent.mjs) grades TLS quality off structured
+// fields on each service record. Before this producer leg no CE plugin set them,
+// so a real scan read clean over deprecated protocols / weak ciphers / expired /
+// self-signed certs. We emit only public handshake facts (versions, cipher names,
+// cert validity dates) — ZDE-safe, and only where a handshake was observed.
+const WEAK_TLS_PROTOCOLS = new Set(['TLSv1', 'TLSv1.1', 'SSLv3', 'SSLv2']);
+
+// Weak cipher name fragments — mirrors plugins/040_tls_cert_auditor.mjs.
+const WEAK_CIPHER_FRAGMENTS = ['RC4', '3DES', 'DES', 'NULL', 'EXPORT', 'ADH', 'AECDH', 'ANON', 'SEED', 'IDEA', 'CAMELLIA128'];
+
+// Cipher policy for the PROBE socket only (rationale at its use site in check()).
+// `eNULL` (no-encryption suites) is NOT part of OpenSSL's `ALL` by convention, so it must
+// be named explicitly or a server accepting NULL-SHA is undetectable. `aNULL` (anonymous,
+// ADH/AECDH) IS inside `ALL` at SECLEVEL=0 — we deliberately allow it so the suite can be
+// GRADED, then re-probe without it to recover certificate evidence, because an anonymous
+// handshake presents no certificate.
+const PROBE_CIPHERS = 'ALL:eNULL:@SECLEVEL=0';
+const PROBE_CIPHERS_AUTHENTICATED = 'ALL:eNULL:!aNULL:@SECLEVEL=0';
+
+function isWeakCipherName(name) {
+  const u = String(name || '').toUpperCase();
+  if (!u || u === 'UNKNOWN') return false;
+  return WEAK_CIPHER_FRAGMENTS.some((f) => u.includes(f));
+}
+
+// Self-signed iff the issuer DN equals the subject DN. A real self-signed leaf also
+// self-loops its issuerCertificate under getPeerCertificate(true); the DN-equality
+// check is the robust, stub-friendly signal (040 remains the deep cert auditor).
+// Keyed on CN|O|OU (Node omits absent DN fields) so an O-only / OU-only self-signed
+// cert — appliances, IoT, internal CAs, `openssl req -subj "/O=..."` — is caught,
+// not only CN-bearing DNs. Requires a non-empty DN so two empty DNs don't match.
+function isSelfSignedCert(cert) {
+  if (!cert || !cert.subject || !cert.issuer) return false;
+  const dnKey = (x) => `${x.CN || ''}|${x.O || ''}|${x.OU || ''}`;
+  const subjectDn = dnKey(cert.subject);
+  return subjectDn !== '||' && subjectDn === dnKey(cert.issuer);
+}
+
 function parseCsvEnv(name, fallback) {
   const v = process.env[name];
   if (!v) return fallback;
@@ -103,7 +142,7 @@ export default {
         hostname: hostname || null
       };
 
-      const check = (version) => new Promise((resolve) => {
+      const check = (version, cipherPolicy = PROBE_CIPHERS) => new Promise((resolve) => {
         let settled = false;
         const options = {
           host,
@@ -111,15 +150,27 @@ export default {
           servername: hostname,
           rejectUnauthorized: false,
           minVersion: version,
-          maxVersion: version
+          maxVersion: version,
+          // A scanner must be able to PROPOSE legacy suites, or it cannot discover them.
+          // Node 20+/OpenSSL 3 refuse to offer TLSv1/TLSv1.1 at the default security level
+          // and fail client-side before any packet: ERR_SSL_NO_PROTOCOLS_AVAILABLE
+          // (error:0A0000BF SSL routines:tls_setup_handshake). Without this, weakProtocols
+          // could NEVER populate against a real legacy server — the branch was dead in
+          // production while a stubbed unit test stayed green. @SECLEVEL=0 lowers only this
+          // probe's client policy (standard scanner practice — sslscan / testssl.sh do the
+          // same); it sends no data and does not weaken anything the operator runs.
+          // Guarded by tests/tls_scanner_real_tls_integration.test.mjs against a real server.
+          ciphers: cipherPolicy
         };
         const socket = tlsApi.connect(options, () => {
           if (settled) return;
           settled = true;
           const protocol = socket.getProtocol?.();
           const cipher = socket.getCipher?.();
+          let cert = null;
+          try { cert = socket.getPeerCertificate?.(true) || null; } catch { cert = null; }
           try { socket.end?.(); } catch {}
-          resolve({ success: true, protocol, cipher: cipher ? cipher.name : 'Unknown' });
+          resolve({ success: true, protocol, cipher: cipher ? cipher.name : 'Unknown', cert });
         });
         socket.setTimeout?.(timeoutMs);
         socket.on?.('timeout', () => {
@@ -135,12 +186,15 @@ export default {
         });
       });
 
+      let leafCert = null;
       for (const v of versions) {
         const res = await check(v);
         if (res.success) {
           const proto = res.protocol || v;
           result.supportedVersions.push(proto);
           result.ciphers[proto] = res.cipher;
+          // Keep the first observed leaf cert (all versions serve the same cert).
+          if (!leafCert && res.cert && res.cert.subject) leafCert = res.cert;
         }
         if (debug) {
           result.errors.push({ version: v, success: !!res.success, error: res.success ? 'none' : res.error });
@@ -150,6 +204,20 @@ export default {
       result.isTLSService = result.supportedVersions.length > 0;
       result.supportsOld = result.supportedVersions.some(v => v === 'TLSv1' || v === 'TLSv1.1');
 
+      // An anonymous (aNULL) suite presents NO certificate, so if the probe negotiated one
+      // the cert axes would go silent on exactly the worst-configured hosts — a false-clean
+      // on the two axes this producer exists to close. Re-probe ONCE excluding aNULL, purely
+      // to recover cert evidence; the weak-cipher grading from the first pass is retained.
+      // Costs an extra handshake only on the rare anonymous-capable server.
+      if (result.isTLSService && !leafCert) {
+        const known = result.supportedVersions[result.supportedVersions.length - 1];
+        const again = await check(known, PROBE_CIPHERS_AUTHENTICATED);
+        if (again.success && again.cert && again.cert.subject) leafCert = again.cert;
+      }
+      // Public cert facts only — the full cert stays in-process (ZDE).
+      result.certExpiry = leafCert?.valid_to || null;
+      result.certSelfSigned = isSelfSignedCert(leafCert);
+
       return result;
     }
 
@@ -177,7 +245,15 @@ export default {
         probe_port: r.port,
         probe_service: r.service,
         probe_info,
-        response_banner: JSON.stringify(bannerObj)
+        response_banner: JSON.stringify(bannerObj),
+        // Structured evidence for the crypto_agent producer contract (see conclude()).
+        tlsEvidence: {
+          tls: r.isTLSService,
+          supportedVersions: r.supportedVersions,
+          ciphers: r.ciphers,
+          certExpiry: r.certExpiry || null,
+          certSelfSigned: r.certSelfSigned === true
+        }
       };
     });
 
@@ -205,6 +281,31 @@ export async function conclude({ host, result }) {
     const info = r?.probe_info || null;
     const banner = r?.response_banner || null;
     const status = /TLS: /.test(String(info||'')) ? 'open' : 'closed';
+
+    // crypto_agent producer contract — attach the TLS-quality fields ONLY where a
+    // handshake was observed (status === 'open'), so the consumer's "encrypted
+    // wherever this fires" premise stays code-true.
+    const ev = r?.tlsEvidence || {};
+    let contract = {};
+    if (status === 'open') {
+      const supportedVersions = Array.isArray(ev.supportedVersions) ? ev.supportedVersions : [];
+      const weakProtocols = supportedVersions.filter((v) => WEAK_TLS_PROTOCOLS.has(v));
+      // weakCiphers reports the NEGOTIATED cipher per version (run() connects with
+      // node's default, strong client cipher list), so a non-empty value is a true
+      // positive but an empty value is NOT proof "no weak cipher is accepted" — the
+      // server may accept RC4/3DES that a default client never proposes. A forced
+      // per-cipher enumeration (like the per-version handshake) is the follow-up; the
+      // consumer only raises a finding on a non-empty value, so it never over-reads [].
+      const weakCiphers = [...new Set(Object.values(ev.ciphers || {}).filter(isWeakCipherName))];
+      contract = {
+        tls: true, // status === 'open' ⇒ a handshake was observed
+        weakProtocols,
+        weakCiphers,
+        certSelfSigned: ev.certSelfSigned === true,
+        ...(ev.certExpiry ? { certExpiry: ev.certExpiry } : {})
+      };
+    }
+
     items.push({
       port,
       protocol: 'tcp',
@@ -216,7 +317,8 @@ export async function conclude({ host, result }) {
       banner,
       source: 'tls-scanner',
       evidence: [r],
-      authoritative: true
+      authoritative: true,
+      ...contract
     });
   }
   return items;

package/utils/conclusion_utils.mjs

@@ -48,8 +48,39 @@ export function normalizeService(svc) {
   };
 }
 
+/**
+ * Liveness resolution for a merge. Authority governs IDENTITY (what the service
+ * IS — service/program/version/banner/contract fields); it must never govern
+ * LIVENESS (whether the port is open).
+ *
+ * A successful TCP connect is a direct observation: something is listening. A
+ * protocol probe that then fails to speak that protocol has learned about the
+ * SERVICE, not about the port — so its `closed`/`unknown` must not erase the
+ * observation. Measured before this guard existed: a real listener on 6379 that
+ * does not speak Redis was found `open` by port_scanner, overwritten to
+ * `unknown` by db_scanner's failed probe (authoritative:true), and the EE
+ * exposure_agent's HIGH "Database port 6379 open" finding went 1 -> 0. The same
+ * shape was confirmed on tls_scanner ('closed'), ssh_scanner (whose
+ * 'Connection closed before banner' matches statusFrom's /closed/ regex) and
+ * opensearch_scanner — a live, reachable port rendering as closed with zero
+ * findings, which in a compliance-evidence product is a false clean.
+ *
+ * Only DOWNGRADES are blocked: an affirmative `open` from either record wins,
+ * and otherwise the caller's own default (the `base` record) is preserved, so
+ * this changes nothing else about the existing precedence.
+ *
+ * @param {object} base  - the record whose status would have won before
+ * @param {object} other - the record it is merging with
+ * @returns {string} the resolved status
+ */
+function resolveLiveness(base, other) {
+  if (base?.status === 'open' || other?.status === 'open') return 'open';
+  return base?.status || 'unknown';
+}
+
 // Merge by protocol:port with basic authority precedence.
-// If 'authoritative' flag is true on a record, it wins over non-authoritative.
+// If 'authoritative' flag is true on a record, it wins over non-authoritative —
+// for identity. See resolveLiveness above for why status is handled separately.
 export function upsertService(services, next, { authoritative = false } = {}) {
   const key = keyOf(next);
   const i = services.findIndex(s => keyOf(s) === key);
@@ -60,7 +91,16 @@ export function upsertService(services, next, { authoritative = false } = {}) {
   const cur = services[i];
   // Authority precedence
   if (authoritative && !cur.__authoritative) {
-    services[i] = { ...cur, ...next, __authoritative: true };
+    services[i] = {
+      ...cur,
+      ...next,
+      status: resolveLiveness(next, cur),
+      // This branch alone used to drop the prior record's evidence, so the very
+      // probe that established the port was open left no trace on the merged
+      // record. The other two branches always concatenated.
+      evidence: (cur.evidence || []).concat(next.evidence || []),
+      __authoritative: true,
+    };
     return;
   }
   if (!authoritative && cur.__authoritative) {
@@ -71,6 +111,7 @@ export function upsertService(services, next, { authoritative = false } = {}) {
       version: cur.version || next.version || null,
       info: cur.info || next.info || null,
       banner: cur.banner || next.banner || null,
+      status: resolveLiveness(cur, next),
       evidence: (cur.evidence || []).concat(next.evidence || [])
     };
     return;
@@ -79,6 +120,7 @@ export function upsertService(services, next, { authoritative = false } = {}) {
   services[i] = {
     ...cur,
     ...next,
+    status: resolveLiveness(next, cur),
     evidence: (cur.evidence || []).concat(next.evidence || []),
     __authoritative: cur.__authoritative || authoritative
   };

package/utils/license.mjs

@@ -594,7 +594,13 @@ export async function loadLicense(keyStr, opts = {}) {
   // Explicit keyStr argument wins (preserves the existing behavior for
   // callers like the `license --status` subcommand which passes the env
   // var directly). When omitted, run the multi-source resolution chain.
-  let raw = keyStr ?? (await resolveLicenseKey());
+  // `opts` carries the same `_`-prefixed test seams resolveLicenseKey documents
+  // (_homeFileOverride, _keychainGet). They were reachable only by calling that
+  // function directly, so a test exercising the no-key path THROUGH loadLicense
+  // read the operator's real ~/.nsauditor/.env and Keychain — machine-dependent,
+  // and it made the "no key" case pass or fail depending on whose box ran it.
+  // No production caller passes a second argument, so threading is inert there.
+  let raw = keyStr ?? (await resolveLicenseKey(opts));
   if (!raw) return { valid: false, tier: 'ce', reason: 'no key provided' };
 
   // Thread K (CE 0.1.32): support `keychain:LABEL` indirection on the

package/utils/output_dir.mjs

@@ -37,9 +37,23 @@ export function resolveBaseOutDir() {
     process.env.SCAN_OUT_PATH || process.env.OPENAI_OUT_PATH || 'out'
   );
   const parsed = path.parse(raw);
-  // If env var pointed at a file (has an extension), use its parent dir.
-  // Otherwise treat the whole value as a directory.
-  return parsed.ext ? (parsed.dir || 'out') : (raw || 'out');
+  // If env var pointed at a FILE, use its parent dir; otherwise treat the whole
+  // value as a directory.
+  //
+  // ⚠️ "Has a dot" is NOT the same as "is a file", and reading it that way was a
+  // silent evidence-misplacement bug (found by the EE 0.32.8 pre-publish smoke
+  // gate). `path.parse('ee-0.32.8').ext` is `'.8'`, so `--out .../ee-0.32.8`
+  // resolved to `.../` and every artifact landed in the PARENT folder — exit 0,
+  // no warning, evidence scattered into a directory shared with other runs. It
+  // hit the naming convention this project uses for its own evidence archives,
+  // and the same shape breaks `v1.2.3` and `release-2026.07`.
+  //
+  // A file extension starts with a LETTER (`.json`, `.html`, `.csv`, `.sarif`).
+  // A trailing `.8` / `.07` / `.28` is a version or date component. Keying on the
+  // first character distinguishes them without guessing at a list of known
+  // extensions — and keeps the documented `--out report.json` affordance working.
+  const isFileExtension = /^\.[A-Za-z]/.test(parsed.ext);
+  return isFileExtension ? (parsed.dir || 'out') : (raw || 'out');
 }
 
 // (toCleanPath moved to utils/path_helpers.mjs in v0.1.20 — no _internals export needed.)