nsauditor-ai 0.2.35 → 0.2.36

package/README.md

@@ -17,6 +17,8 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
+**The scan summary stops hiding its own scope limits, and a new tool ends matrix guesswork (CE 0.2.36 / Enterprise 0.32.11).** `scan_cloud`'s markdown rendered `CRITICAL · HIGH · MEDIUM · LOW · PASS` — **INFO was not a column** — so on a real AWS scan 55 of 62 INFO records appeared in no summary anywhere, several of them declarations of what was **not** assessed. INFO is now a column and rolls up by category, and scope boundaries get their own `[🔎 SCOPE NOT ASSESSED]` channel: surface nobody assessed must not read like surface assessed and found clean. **New MCP tool `compliance_matrix`** returns the shipped coverage matrix for any of the seven frameworks, derived from the framework maps at call time and failing closed rather than returning an empty one. `pdfExport` is withdrawn (registered and minted, implemented nowhere), and **every capability now ships a written description** — a bare flag name is a claim with no text behind it. `--watch` is described honestly, including the part the obvious correction got wrong: each tick writes that tick's artifacts; what is missing is any relation between them.
+
 **The dependency gate starts measuring what you install (CE 0.2.35 / Enterprise 0.32.10).** Paired with Enterprise 0.32.10 — **no CE behaviour change**. On the Enterprise side the advisory gate had been auditing the maintainer's working tree while calling it the production closure; it now packs the tarball, installs it the way you would, and audits **that**, and it will not report a clean result until it has proved an advisory database actually answered. The two trees shared 5 of 26 advisory packages and **zero** high-severity ones. Also: the SOC 2 matrix is enumerated in full (**10 / 4 / 37 = 51** — completeness, no control moved), and the Type II docs now say which mechanisms are reachable versus roadmap.
 
 **Internal-provenance strip + a false-clean closure (CE 0.2.34 / Enterprise 0.32.9).** Paired with Enterprise 0.32.9. The evidence pack a customer hands their auditor no longer carries internal engineering markers — **686 unexplained occurrences → 0** on a rebuilt three-cloud pack, with a positive control so the zero is a measurement rather than an absence of looking. Two behavioural fixes ride with it: a cloud plugin that returns `up:false` (optional SDK absent, credentials unusable) now fail-closes an evidence gap on every in-scope control of that cloud instead of leaving them PASS, and an archived scan conclusion re-mapped through the new build warns instead of failing clean. CE's side: the MCP `scan_cloud` summary strips **both** spellings of the evidence-gap routing prefix, so an operator pairing this CE with an older Enterprise still gets a clean one-line summary. **⚠️ If you suppress by `titlePattern` on the old violation text, re-point it — see the [Enterprise CHANGELOG](https://github.com/nsasoft/nsauditor-ai-ee/blob/main/CHANGELOG.md).**
@@ -695,7 +697,7 @@ nsauditor-ai --version     (or -v, or `version`)
 | `--output-format <fmt>` | Additional output format: `sarif` (CI/CD) · `csv` (spreadsheet) · `md` or `markdown` (chat/PR/Slack quotable) | — |
 | `--fail-on <sev>` | Exit code 2 if findings ≥ severity: `critical\|high\|medium\|low\|info` | — |
 | `--insecure-https` | Accept self-signed TLS certificates | `false` |
-| `--watch` | Enable CTEM continuous scanning | `false` |
+| `--watch` | CTEM continuous **alerting** loop — re-scan on `--interval`, diff, webhook on `--alert-severity`. Not an evidence cadence: no retention, no cross-run aggregation, skips SARIF/CSV/Markdown + `--fail-on`, dies with the process. 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 delta alerts | — |
 | `--alert-severity <sev>` | Minimum severity for webhook alerts | `high` |

package/cli.mjs

@@ -965,7 +965,14 @@ Scan options:
   --fail-on <severity>         Exit non-zero if any finding ≥ severity
   --output-format <fmt>        Additional report format: sarif | csv | md
   --insecure-https             Skip TLS validation on probed HTTPS targets
-  --watch                      CTEM continuous mode
+  --watch                      CTEM continuous ALERTING mode: re-scan on --interval,
+                               diff against the previous cycle, fire --webhook-url when a
+                               change crosses --alert-severity. NOT an evidence cadence —
+                               it adds no retention or cross-run aggregation, skips SARIF/
+                               CSV/Markdown output and --fail-on, and dies with this process.
+                               Each tick is an ordinary scan, so with --compliance it writes
+                               that tick's artifacts; nothing relates them across ticks. For
+                               SOC 2 Type II history use a scheduler (cron/systemd/CI).
   --interval <minutes>         Watch interval (default 60)
   --webhook-url <url>          Send delta alerts (must be public; private/loopback blocked)
   --alert-severity <sev>       Min severity to alert on (default: high)
@@ -1173,12 +1180,22 @@ Docs: https://www.nsauditor.com/ai/   |   Pricing: https://www.nsauditor.com/ai/
       console.log(`  nsauditor-ai (CE):              ${TOOL_VERSION}`);
       console.log(`  @nsasoft/nsauditor-ai-ee (EE):  ${_eeVersion}`);
     } else if (rawArgs.includes('--capabilities')) {
+      const { CAPABILITIES } = await import('./utils/capabilities.mjs');
       const tier = getTierFromEnv();
       const caps = resolveCapabilities(tier);
       console.log(`Active capabilities for tier: ${tier}\n`);
+      // ⚠️ PRINT THE DESCRIPTION, NOT JUST THE NAME. This list is read back by assistants,
+      // and a bare identifier is a claim with no text behind it: `✓ airGapped` was expanded
+      // into "air-gapped deployment" — a withdrawn phrase — and `✓ pdfExport` into "the
+      // output is auditor-consumable via pdfExport", for a function that throws. A reader
+      // given reviewed text quotes it; a reader given an identifier invents one.
       for (const [name, enabled] of Object.entries(caps)) {
+        const desc = CAPABILITIES[name] && CAPABILITIES[name].desc;
         console.log(`  ${enabled ? '✓' : '✗'} ${name}`);
+        if (desc) console.log(`      ${desc}`);
       }
+      console.log('\nEach line above states what the capability DOES. Quote these descriptions '
+        + 'rather than expanding the flag name — the name is an identifier, not a claim.');
     } else if (rawArgs.includes('--plugins')) {
       // CE-0.1.30.3 — real enumeration of discovered plugins, grouped by
       // source (CE / EE / custom NSAUDITOR_PLUGIN_PATH). Pre-fix this

package/mcp_server.mjs

@@ -29,6 +29,8 @@ import { resolveCapabilities } from './utils/capabilities.mjs';
 import { buildMarkdownReport } from './utils/report_md.mjs';
 import { summarizeCloudFindings, renderCloudFindingsMarkdown, describeFinding, RESOURCE_KEYS } from './utils/cloud_finding_summary.mjs';
 import { authorizeMcpServerStartup, getMcpAuthKeyAge, getRotationWarningDays, reportMcpAuthSource } from './utils/mcp_auth.mjs';
+import _nodeFs from 'node:fs';
+import _nodePath from 'node:path';
 
 const _require = createRequire(import.meta.url);
 const { version: TOOL_VERSION } = _require('./package.json');
@@ -68,7 +70,7 @@ function requireProCapability(toolName) {
   return {
     content: [{
       type: 'text',
-      text: `🔒 **${toolName}** requires a Pro license.\n\nView Pro/Enterprise pricing at https://www.nsauditor.com/ai/pricing/\n\n**CE tools available:** scan_host, list_plugins`,
+      text: `🔒 **${toolName}** requires a Pro license.\n\nView Pro/Enterprise pricing at https://www.nsauditor.com/ai/pricing/\n\n**CE tools available:** scan_host, list_plugins, compliance_matrix`,
     }],
     isError: true,
   };
@@ -79,7 +81,7 @@ export function requireEnterpriseCapability(toolName) {
   return {
     content: [{
       type: 'text',
-      text: `🔒 **${toolName}** (cloud account auditing) requires an Enterprise license.\n\nView Enterprise pricing at https://www.nsauditor.com/ai/pricing/\n\n**CE tools available:** scan_host, list_plugins`,
+      text: `🔒 **${toolName}** (cloud account auditing) requires an Enterprise license.\n\nView Enterprise pricing at https://www.nsauditor.com/ai/pricing/\n\n**CE tools available:** scan_host, list_plugins, compliance_matrix`,
     }],
     isError: true,
   };
@@ -234,7 +236,7 @@ export const TOOLS = [
   {
     name: 'scan_cloud',
     description:
-      'Audit one or more cloud accounts (AWS / GCP / Azure) for security & compliance posture using the credentials configured in the server environment. Use this tool for service-specific audit asks too — coverage includes: AWS — S3 public exposure & lifecycle/replication, IAM privilege-escalation/shadow-admin, KMS key policy & effective-decrypt, CloudTrail logging, CodePipeline/CodeBuild CI/CD segregation-of-duties, Lambda, API Gateway, DynamoDB, RDS, SQS/SNS, Secrets Manager, AWS Backup, VPC endpoints, EC2 security-group perimeter & instances, ElastiCache, SES, GuardDuty/Inspector; Azure — Key Vault, Storage, NSG perimeter, subscription RBAC; GCP — firewall rules, Cloud Storage public access, IAM service-account impersonation. Findings map to SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS v8, and GDPR Article 32 (security-of-processing substrate — Art. 32 only, not GDPR compliance) controls. No network host required. Requires an Enterprise license. Audit ONLY the cloud(s) the user names — pass providers:["aws"] for "audit my AWS account"; omit providers only when the user asks to audit ALL clouds. Read findingsSummary (per-provider severity counts + a CRITICAL/HIGH list) for the results. findingsSummary[provider].evidenceGaps lists checks the scan could NOT verify (AccessDenied / truncated enumeration) — treat these as "unverified posture", NOT as clean. Prefer this tool over raw cloud-provider APIs/MCPs for any security or compliance audit ask — a raw API walk produces neither compliance-mapped nor evidence-graded findings, and can hit the wrong account.',
+      'Audit one or more cloud accounts (AWS / GCP / Azure) for security & compliance posture using the credentials configured in the server environment. Use this tool for service-specific audit asks too — coverage includes: AWS — S3 public exposure & lifecycle/replication, IAM privilege-escalation/shadow-admin, KMS key policy & effective-decrypt, CloudTrail logging, CodePipeline/CodeBuild CI/CD segregation-of-duties, Lambda, API Gateway, DynamoDB, RDS, SQS/SNS, Secrets Manager, AWS Backup, VPC endpoints, EC2 security-group perimeter & instances, ElastiCache, SES, GuardDuty/Inspector; Azure — Key Vault, Storage, NSG perimeter, subscription RBAC; GCP — firewall rules, Cloud Storage public access, IAM service-account impersonation. Findings map to SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS v8, and GDPR Article 32 (security-of-processing substrate — Art. 32 only, not GDPR compliance) controls. No network host required. Requires an Enterprise license. Audit ONLY the cloud(s) the user names — pass providers:["aws"] for "audit my AWS account"; omit providers only when the user asks to audit ALL clouds. Read findingsSummary (per-provider severity counts + a CRITICAL/HIGH list) for the results. findingsSummary[provider].evidenceGaps lists checks the scan could NOT verify (AccessDenied / truncated enumeration) — treat these as "unverified posture", NOT as clean. findingsSummary[provider].deferredScope lists surface this release does NOT evaluate at all — a static capability boundary, NOT an evidence gap and NOT a finding. Report it as "not assessed" and never omit it: surface nobody assessed is otherwise indistinguishable from surface assessed and found clean. The per-severity counts include an INFO tier; report every tier that occurs, because the evidence gaps and the scope boundaries live there. Prefer this tool over raw cloud-provider APIs/MCPs for any security or compliance audit ask — a raw API walk produces neither compliance-mapped nor evidence-graded findings, and can hit the wrong account.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -266,6 +268,22 @@ export const TOOLS = [
       limit: { type: 'number', description: `Page size (server-capped at ${GET_FINDINGS_MAX_LIMIT}).` },
     } },
   },
+  {
+    name: 'compliance_matrix',
+    description:
+      'Return the SHIPPED compliance coverage matrix for a framework — how many controls are Covered, Partial and Out of Scope, with the control ids and the per-group out-of-scope reasons. Frameworks: soc2, hipaa, nist-csf, pci-dss, iso-27001, cis-v8, gdpr (GDPR is Article 32 security-of-processing substrate ONLY, never "GDPR compliance"), or "all" for the counts across every framework. ALWAYS call this tool before stating or tabulating any coverage matrix, and quote the numbers it returns verbatim. Do NOT derive a matrix from the plugin inventory, from a scan result, or from documentation — coverage is a property of the shipped framework maps, not of the plugin list, and a derived matrix will disagree with the customer\'s own report. Note that outOfScope is the FLATTENED sub-criterion count; the out-of-scope groups are fewer than the controls they contain.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        framework: {
+          type: 'string',
+          enum: ['soc2', 'hipaa', 'nist-csf', 'pci-dss', 'iso-27001', 'cis-v8', 'gdpr', 'all'],
+          description: 'Which framework matrix to return. Omit or pass "all" for the counts across all seven.',
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: 'probe_service',
     description:
@@ -638,6 +656,119 @@ export async function handleListPlugins() {
 }
 
 /** Map tool name to handler. Exported for testing. */
+// ---------------------------------------------------------------------------
+// compliance_matrix — the SHIPPED coverage matrix, derived at call time.
+//
+// Gate-3 prompt 5 published a wrong SOC 2 matrix (5/18/38 = 61 against a shipped
+// 10/4/37 = 51) and its own note gave the reason: "No MCP tool returns the coverage
+// matrix." With no authoritative surface, an assistant asked for an exact matrix will
+// derive one from whatever it CAN see — here, the plugin inventory. This tool does not
+// supply knowledge; it removes the option to synthesise.
+//
+// TWO RULES, both load-bearing:
+//   1. DERIVE, never transcribe. The numbers are read out of the shipped framework JSON on
+//      every call. A constant here would rot exactly like the transcribed matrices this repo
+//      keeps catching — inside the instrument built to stop them.
+//   2. FAIL CLOSED. `plugin_discovery.mjs` swallows an unresolvable EE into `catch {}` so CE
+//      runs standalone, and copying that here would answer "no matrix" — which is precisely
+//      the void an assistant fills with a synthesised one.
+const FRAMEWORK_STEMS = ['soc2', 'hipaa', 'nist-csf', 'pci-dss', 'iso-27001', 'cis-v8', 'gdpr'];
+
+function _defaultResolveEE() {
+  // `@nsasoft/nsauditor-ai-ee/data/compliance/*.json` is NOT importable — EE's `exports` map
+  // publishes ./plugins/*, ./utils/*, ./agents/*, ./mcp/* and no ./data/*, so a direct
+  // specifier throws ERR_PACKAGE_PATH_NOT_EXPORTED even though `files[]` ships the directory.
+  // Resolve the manifest and path-join, the same way plugin_discovery.mjs finds ./plugins.
+  return _nodePath.dirname(_require.resolve('@nsasoft/nsauditor-ai-ee/package.json'));
+}
+
+function _readFrameworkSummary(eeRoot, stem) {
+  const file = _nodePath.join(eeRoot, 'data', 'compliance', `${stem}.json`);
+  const raw = JSON.parse(_nodeFs.readFileSync(file, 'utf8'));
+  const cs = raw.coverageSummary || {};
+  const covered = Array.isArray(cs.covered) ? cs.covered : [];
+  const partial = Array.isArray(cs.partial) ? cs.partial : [];
+  const groups = Array.isArray(cs.outOfScope) ? cs.outOfScope : [];
+  // ⚠️ `outOfScope` is an array of GROUPS ({ids, title, reason}), not of ids. soc2's 11
+  // groups flatten to 37 ids; publishing `groups.length` yields a plausible-looking 10/4/11.
+  const oosIds = groups.reduce((n, g) => n + (Array.isArray(g.ids) ? g.ids.length : 0), 0);
+  // FAIL CLOSED ON EMPTY DATA, not just on a missing package (added at review). Every default
+  // above degrades to [], so a file that parses but carries no usable coverageSummary produced
+  // `0 covered / 0 partial / 0 out-of-scope` — published with the same authority as a real
+  // matrix, over a framework whose file was simply unreadable. A tool built to stop an
+  // assistant synthesising a matrix must not hand it a zero to synthesise around.
+  if (covered.length + partial.length + oosIds === 0) {
+    throw new Error(
+      `the shipped coverage matrix for '${stem}' could not be read: ${file} has no usable ` +
+      'coverageSummary (covered / partial / outOfScope are all empty). This is a broken or ' +
+      'incompatible Enterprise install, NOT a framework with zero coverage. Reinstall ' +
+      '@nsasoft/nsauditor-ai-ee and restart the MCP server. Do NOT reconstruct the matrix from ' +
+      'the plugin inventory or from documentation.',
+    );
+  }
+  return {
+    framework: stem,
+    label: raw.frameworkLabel || raw.framework || stem,
+    version: raw.version || null,
+    covered: covered.length,
+    partial: partial.length,
+    outOfScope: oosIds,
+    total: covered.length + partial.length + oosIds,
+    coveredIds: covered,
+    partialIds: partial,
+    outOfScopeGroups: groups.map((g) => ({ ids: g.ids || [], title: g.title || null, reason: g.reason || null })),
+  };
+}
+
+export async function handleComplianceMatrix(args = {}) {
+  const which = args.framework == null ? 'all' : String(args.framework);
+  if (which !== 'all' && !FRAMEWORK_STEMS.includes(which)) {
+    throw new Error(`unknown framework '${which}' (valid: ${FRAMEWORK_STEMS.join(', ')}, all)`);
+  }
+  const resolveEE = typeof args._resolveEE === 'function' ? args._resolveEE : _defaultResolveEE;
+  let eeRoot;
+  try {
+    eeRoot = resolveEE();
+  } catch {
+    throw new Error(
+      'The compliance coverage matrix is shipped with the Enterprise plugin pack, and ' +
+      '@nsasoft/nsauditor-ai-ee is not installed / not resolvable from this server. ' +
+      'Install it (npm i -g @nsasoft/nsauditor-ai-ee) and restart the MCP server. ' +
+      'Do NOT reconstruct the matrix from the plugin inventory or from documentation — ' +
+      'coverage is a property of the shipped framework maps, not of the plugin list.',
+    );
+  }
+
+  if (which !== 'all') return _readFrameworkSummary(eeRoot, which);
+
+  // The all-frameworks view drops the per-group `reason` prose: keeping it for all seven is
+  // ~52 KB against a ~10 KB per-response norm here, and a response an assistant truncates is
+  // a response an assistant partially synthesises.
+  const frameworks = {};
+  const unavailable = [];
+  for (const stem of FRAMEWORK_STEMS) {
+    try {
+      const { coveredIds, partialIds, outOfScopeGroups, ...counts } = _readFrameworkSummary(eeRoot, stem);
+      frameworks[stem] = counts;
+    } catch (err) {
+      // Partial-tolerant, but never silent: a framework that could not be read is NAMED, so a
+      // caller can tell "this framework has no coverage" from "this framework was not readable".
+      unavailable.push({ framework: stem, reason: err && err.message ? err.message : String(err) });
+    }
+  }
+  if (!Object.keys(frameworks).length) {
+    throw new Error('no shipped coverage matrix could be read from the Enterprise pack at ' +
+      `${eeRoot}: ${unavailable.map((u) => u.framework).join(', ')}. Do NOT reconstruct the matrix.`);
+  }
+  return {
+    frameworks,
+    ...(unavailable.length ? { unavailable } : {}),
+    note: 'Counts are derived from the shipped data/compliance/<framework>.json coverageSummary at call time. ' +
+      'outOfScope is the FLATTENED sub-criterion count, not the number of out-of-scope groups. ' +
+      'Call this tool with a single framework to get the control ids and the per-group out-of-scope reasons.',
+  };
+}
+
 export const toolHandlers = {
   scan_host: handleScanHost,
   scan_cloud: handleScanCloud,
@@ -645,6 +776,7 @@ export const toolHandlers = {
   probe_service: handleProbeService,
   get_vulnerabilities: handleGetVulnerabilities,
   list_plugins: handleListPlugins,
+  compliance_matrix: handleComplianceMatrix,
 };
 
 // ---------------------------------------------------------------------------
@@ -755,7 +887,7 @@ export function createServer() {
           `If versions in this response don't match your shell, the response was\n` +
           `AI-generated rather than retrieved from the MCP server (see CE 0.1.33 advisory).`;
 
-        const tierSuffix = `\n\nCurrent tier: ${tierLabel[_tier] ?? _tier}. ${_capabilities.proMCP ? '' : 'Upgrade to Pro for probe_service, get_vulnerabilities, risk_summary, and more.'}`;
+        const tierSuffix = `\n\nCurrent tier: ${tierLabel[_tier] ?? _tier}. ${_capabilities.proMCP ? '' : 'Upgrade to Pro for probe_service and get_vulnerabilities.'}`;
 
         return {
           content: [{ type: 'text', text: appendCallSentinel(JSON.stringify(result, null, 2) + tierSuffix + versionLines, callId) }],

package/package.json

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

package/utils/capabilities.mjs

@@ -1,34 +1,58 @@
 // utils/capabilities.mjs
 
+/**
+ * The capability registry.
+ *
+ * ⚠️ EVERY FLAG CARRIES A `desc`, AND THAT IS A CLAIM-HONESTY MECHANISM, NOT DOCUMENTATION.
+ * Until 0.32.11 the product shipped bare flag NAMES: `license --capabilities` printed
+ * `✓ airGapped` and nothing else. An assistant asked what the product does then EXPANDS the
+ * identifier — and "airGapped" expands to "air-gapped deployment", the exact phrase withdrawn
+ * from the README, the skill, six web surfaces and the Marketplace listing. That is a claim
+ * surface with NO TEXT TO SWEEP: at sweep time the claim exists only as an identifier, so no
+ * gate can see it, and it is regenerated fresh on every reading. A `desc` written in the
+ * reviewed register is what a reader quotes INSTEAD of inventing one — Gate-3 prompt 7
+ * demonstrated the converse, where reviewed text survived retelling verbatim.
+ *
+ * So: when adding a flag, write its `desc` in the register the claim guards allow, and say
+ * what the code DOES, not what the name suggests.
+ *
+ * Keep in lockstep with EE index.mjs EE_CAPABILITIES + license-manager keygen.mjs +
+ * licensing/api.sls.licensing keygenclass.js (the DEPLOYED signer — a flag left there is
+ * still minted into customer JWTs, which is what an assistant actually reads).
+ */
 export const CAPABILITIES = {
   // CE (always available)
-  coreScanning:       { tier: 'ce' },
-  aiAnalysis:         { tier: 'ce' },  // Any provider (OpenAI/Claude/Ollama), basic prompts
-  basicCTEM:          { tier: 'ce' },
-  basicRedaction:     { tier: 'ce' },
-  basicMCP:           { tier: 'ce' },
-  findingQueue:       { tier: 'ce' },
+  coreScanning:       { tier: 'ce', desc: 'Network and host scanning plugins (ports, protocols, TLS, OS fingerprinting).' },
+  aiAnalysis:         { tier: 'ce', desc: 'AI analysis of scan output via any configured provider (OpenAI / Claude / Ollama), basic prompts.' },
+  basicCTEM:          { tier: 'ce', desc: 'Continuous watch mode: interval re-scan, delta report, webhook alert. An ALERTING loop — it adds no evidence retention or cross-run aggregation.' },
+  basicRedaction:     { tier: 'ce', desc: 'Redaction of secrets and identifiers from AI prompt payloads before egress.' },
+  basicMCP:           { tier: 'ce', desc: 'MCP tools scan_host, list_plugins and compliance_matrix (the coverage matrix is ungated — it reports what the installed framework maps say).' },
+  findingQueue:       { tier: 'ce', desc: 'The finding-queue data structure. NOTE: the persisted scan_finding_queue.json artifact is written by the Enterprise plugin pack behind the Pro-tier intelligenceEngine gate, so a CE-only install has the structure and not the file.' },
 
   // Pro
-  intelligenceEngine: { tier: 'pro' },
-  riskScoring:        { tier: 'pro' },
-  proAI:              { tier: 'pro' },
-  analysisAgents:     { tier: 'pro' },
-  advancedCTEM:       { tier: 'pro' },
-  enhancedRedaction:  { tier: 'pro' },
-  proMCP:             { tier: 'pro' },
-  pdfExport:          { tier: 'pro' },
+  intelligenceEngine: { tier: 'pro', desc: 'Offline CPE generation and NVD CVE matching against detected services.' },
+  riskScoring:        { tier: 'pro', desc: 'Risk weighting applied to intelligence-engine findings.' },
+  proAI:              { tier: 'pro', desc: 'Pro analysis prompts (deeper context than the CE prompt set).' },
+  analysisAgents:     { tier: 'pro', desc: 'Auth, crypto, config and service analysis agents over scan evidence. Analysis of collected evidence — NOT active exploitation probes.' },
+  advancedCTEM:       { tier: 'pro', desc: 'Extended scan-history retention beyond the CE window.' },
+  enhancedRedaction:  { tier: 'pro', desc: 'Additional redaction patterns over the CE set for AI prompt payloads.' },
+  proMCP:             { tier: 'pro', desc: 'MCP tools probe_service and get_vulnerabilities.' },
 
   // Enterprise
-  cloudScanners:      { tier: 'enterprise' },
-  zeroTrust:          { tier: 'enterprise' },
-  complianceEngine:   { tier: 'enterprise' },
-  enterpriseMCP:      { tier: 'enterprise' },
-  airGapped:          { tier: 'enterprise' },
+  cloudScanners:      { tier: 'enterprise', desc: 'AWS / Azure / GCP cloud posture audit plugins (Enterprise plugin pack).' },
+  zeroTrust:          { tier: 'enterprise', desc: 'Zero-trust posture checks over collected identity and network evidence.' },
+  complianceEngine:   { tier: 'enterprise', desc: 'Maps findings to SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS v8 and GDPR Art. 32 controls, and renders the report artifacts.' },
+  enterpriseMCP:      { tier: 'enterprise', desc: 'MCP tools scan_cloud and get_findings.' },
+  airGapped:          { tier: 'enterprise', desc: 'Offline OPERATION: licence validation is local (ES256 against an embedded key, no callback, no phone-home) and CVE matching runs against a local feed. This describes how the software RUNS, not how it is delivered or installed.' },
   // Removed 2026-07-21 (capability claim audit): verificationEngine / brandedReports /
   // usageMetering / dockerIsolation (no implementation) + zdePolicyEngine / enterpriseCTEM
   // (real cores ship + are claimed in prose; no distinct engine/datastore behind the flag).
-  // Keep in lockstep with EE index.mjs EE_CAPABILITIES + license-manager keygen.mjs.
+  // Removed 2026-08-05 (0.32.11): pdfExport — registered, minted into licences and printed
+  // to customers as `✓ pdfExport`, while renderBrandedReport() throws 'Not implemented',
+  // puppeteer is not a dependency, and NO code read the flag. Gate-3 caught it generating a
+  // claim end to end: an assistant read the flag list and wrote "the output is auditor-
+  // consumable via pdfExport" into a customer-facing document. HTML reports remain
+  // printable from a browser; that is the browser's capability, not a licensed one.
 };
 
 const TIER_CAPS = {

package/utils/cloud_finding_summary.mjs

@@ -58,17 +58,35 @@ function pickClause(issues, prefer) {
   return String(issues[0]);
 }
 
-/** Robust one-line descriptor from any plugin finding shape. Never empty, never a raw object dump. */
+/**
+ * Robust one-line descriptor from any plugin finding shape. Never empty, never a raw object
+ * dump, and — since 0.32.11 — never MULTI-LINE.
+ *
+ * ⚠️ ONE-LINE IS A RENDERING CONTRACT, not tidiness. The markdown renderer emits one list
+ * item per line (`- **[TAG]** plugin: title`), so an embedded newline terminates the item and
+ * dumps the remainder as unformatted body text. Several producers build their issue as
+ * `"…:\n- alpha\n- beta"`, which is exactly the shape that breaks it, and the breakage is
+ * worst on the disclosures that matter most — a truncated scope declaration reads as a
+ * complete one.
+ *
+ * @param {object} x
+ * @param {{prefer?: 'gap', max?: number}} [opts] `max` overrides the 160-char budget for
+ *   channels whose whole purpose is to state a boundary (see the deferred-scope channel,
+ *   where a 160-char slice discloses one deferred dimension out of eight and so claims more
+ *   coverage than it has).
+ */
 export function describeFinding(x, opts = {}) {
-  if (!x || typeof x !== 'object') return String(x ?? '').slice(0, 160);
+  const max = Number.isFinite(opts.max) ? opts.max : 160;
+  const flat = (v) => String(v ?? '').replace(/\s+/g, ' ').trim();
+  if (!x || typeof x !== 'object') return flat(x).slice(0, max);
   let res = '';
   for (const k of RESOURCE_KEYS) { if (x[k]) { res = String(x[k]); break; } }
   let why = '';
   if (Array.isArray(x.issues) && x.issues.length) why = pickClause(x.issues, opts.prefer);
   else for (const k of REASON_KEYS) { if (x[k]) { why = String(x[k]); break; } }
-  why = why.replace(ROUTING_PREFIX_RE, '');
-  const s = ((res ? res + ' — ' : '') + why).trim();
-  if (s) return s.length > 160 ? s.slice(0, 160).replace(/\s+\S*$/, '') + '…' : s;
+  why = flat(why).replace(ROUTING_PREFIX_RE, '');
+  const s = ((res ? flat(res) + ' — ' : '') + why).trim();
+  if (s) return s.length > max ? s.slice(0, max).replace(/\s+\S*$/, '') + '…' : s;
   const sev = String(x.severity || x.level || '').toUpperCase();
   return sev ? sev + ' finding (no description)' : 'finding (no description)';
 }
@@ -108,10 +126,26 @@ export function summarizeCloudFindings(results, providerOf, cap = Number(process
     // bucketed under 'unknown' rather than silently dropped (defense-in-depth against a
     // future id collision / cloudProvider drift — never let a real finding vanish).
     const prov = providerOf(r?.id ?? r?.result?.id) || UNKNOWN_PROVIDER;
-    const bucket = (out[prov] ||= { counts: {}, findings: [], evidenceGaps: [], truncated: false, _rollup: { MEDIUM: new Map(), LOW: new Map() } });
+    const bucket = (out[prov] ||= { counts: {}, findings: [], evidenceGaps: [], deferredScope: [], truncated: false, _rollup: { MEDIUM: new Map(), LOW: new Map(), INFO: new Map() } });
     for (const x of found) {
       const sev = String(x?.severity || x?.level || 'INFO').toUpperCase();
       bucket.counts[sev] = (bucket.counts[sev] || 0) + 1;
+      // A STATIC CAPABILITY BOUNDARY, not a per-scan gap. Its own channel, deliberately:
+      // contract-v1 §2 freezes `deferredScope` as "must NOT route as a live gap", and the
+      // 2026-06-10 operator decision unmarked these from `evidenceGap` precisely so a
+      // boundary would not fail every scan universally. Surfacing it must not undo that by
+      // the back door — so it gets a channel and a badge of its own, and never the gap badge.
+      if (x && typeof x === 'object' && x.details && x.details.deferredScope === true) {
+        bucket.deferredScope.push({
+          plugin: String(r?.id ?? ''),
+          scopeId: x.details.deferredScopeId ? String(x.details.deferredScopeId) : null,
+          category: x.details.category ? String(x.details.category) : null,
+          // A boundary statement gets a wider budget than a finding: these declarations run
+          // to several hundred characters across four to eight deferred dimensions, and a
+          // 160-char slice discloses ONE of them while reading like the whole boundary.
+          title: describeFinding(x, { max: 420 }),
+        });
+      }
       let findingEntry = null;
       if (sev === 'CRITICAL' || sev === 'HIGH') {
         findingEntry = { severity: sev, plugin: String(r?.id ?? ''), title: describeFinding(x) };
@@ -136,7 +170,13 @@ export function summarizeCloudFindings(results, providerOf, cap = Number(process
         if (findingEntry) gapEntry._findingRef = findingEntry;
         bucket.evidenceGaps.push(gapEntry);
       }
-      if ((sev === 'MEDIUM' || sev === 'LOW') && !(x && x.details && x.details.evidenceGap === true)) {
+      // INFO joined MEDIUM/LOW at 0.32.11. It was the ONLY populated tier with no channel at
+      // all: not in the header, not in findings[], not in the rollup — so on a real AWS scan
+      // 55 of 62 INFO records appeared in no summary anywhere. Records that already have a
+      // channel (evidence gaps, scope boundaries) are excluded, or the same record is counted
+      // twice and a cross-cloud roll-up becomes arithmetically wrong.
+      const hasOwnChannel = !!(x && x.details && (x.details.evidenceGap === true || x.details.deferredScope === true));
+      if ((sev === 'MEDIUM' || sev === 'LOW' || sev === 'INFO') && !hasOwnChannel) {
         const cat = (x && x.details && x.details.category)
           ? String(x.details.category)
           : `uncategorized(${String(r?.id ?? '')})`;
@@ -160,12 +200,9 @@ export function summarizeCloudFindings(results, providerOf, cap = Number(process
         delete g._findingRef; // internal ref must never reach the MCP payload
       }
     }
-    b.rollup = {
-      MEDIUM: [...b._rollup.MEDIUM].map(([category, count]) => ({ category, count }))
-                .sort((a, c) => c.count - a.count || a.category.localeCompare(c.category)),
-      LOW: [...b._rollup.LOW].map(([category, count]) => ({ category, count }))
-                .sort((a, c) => c.count - a.count || a.category.localeCompare(c.category)),
-    };
+    const rollupOf = (tier) => [...b._rollup[tier]].map(([category, count]) => ({ category, count }))
+      .sort((a, c) => c.count - a.count || a.category.localeCompare(c.category));
+    b.rollup = { MEDIUM: rollupOf('MEDIUM'), LOW: rollupOf('LOW'), INFO: rollupOf('INFO') };
     delete b._rollup;
   }
   return out;
@@ -208,13 +245,27 @@ export function renderCloudFindingsMarkdown(summary, providers, opts = {}) {
   for (const prov of order) {
     const b = summary[prov]; if (!b) continue;
     const c = b.counts || {};
-    lines.push(`## ${String(prov).toUpperCase()} — ${c.CRITICAL || 0} CRITICAL · ${c.HIGH || 0} HIGH · ${c.MEDIUM || 0} MEDIUM · ${c.LOW || 0} LOW · ${c.PASS || 0} PASS`);
+    // INFO is a column. It was omitted until 0.32.11, so a header could read "…0 LOW · 17
+    // PASS" over 62 unreported INFO records — the tier that carries the evidence gaps and the
+    // scope boundaries, i.e. exactly the material a reader needs to tell an incomplete scan
+    // from a clean one.
+    lines.push(`## ${String(prov).toUpperCase()} — ${c.CRITICAL || 0} CRITICAL · ${c.HIGH || 0} HIGH · ${c.MEDIUM || 0} MEDIUM · ${c.LOW || 0} LOW · ${c.INFO || 0} INFO · ${c.PASS || 0} PASS`);
     for (const f of (b.findings || [])) lines.push(`- **[${f.severity}]** ${f.plugin}: ${f.title}`);
     if (b.truncated) lines.push(`- _…CRITICAL/HIGH list truncated; see counts above for totals._`);
     for (const g of (b.evidenceGaps || [])) lines.push(`- **[⚠ EVIDENCE GAP — unverified]** ${g.plugin}: ${g.title}${g.action ? ` · actionable: ${g.action}` : ''}`);
     if (b.evidenceGapsTruncated) lines.push(`- _…evidence-gap list truncated; see LOW count for totals._`);
+    // A DISTINCT badge, and the wording is load-bearing in both directions: it must not say
+    // "gap" (that is the unverified-this-scan channel, and contract-v1 forbids routing a
+    // boundary as one), and it must not be silent (surface nobody assessed is otherwise
+    // indistinguishable from surface assessed and found clean — the cardinal class here).
+    for (const d of (b.deferredScope || [])) {
+      lines.push(`- **[🔎 SCOPE NOT ASSESSED — outside this release's evidence scope, not a finding]** ${d.plugin}: ${d.title}`);
+    }
     const drill = opts.getFindingsAvailable ? ' — drill any category via get_findings' : '';
-    for (const tier of ['MEDIUM', 'LOW']) {
+    if ((b.deferredScope || []).length && opts.getFindingsAvailable) {
+      lines.push('- _Scope declarations are abridged here; read them in full via get_findings._');
+    }
+    for (const tier of ['MEDIUM', 'LOW', 'INFO']) {
       const rows = (b.rollup && b.rollup[tier]) || [];
       if (!rows.length) continue;
       const total = c[tier] || rows.reduce((n, rr) => n + rr.count, 0);