nsauditor-ai 0.2.7 → 0.2.8

package/README.md

@@ -17,9 +17,9 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
-**Latest: CE 0.2.7 + Enterprise 0.19.2** (June 2026) — paired pin for **EE 0.19.2** "Confirmed false-negative tail": six more gauntlet-confirmed Tier-B false-negatives across the Pro/Enterprise cloud auditors, each TDD'd and independently adversarially reviewed — Azure Key Vault legacy access-policy per-verb breadth (a 2-verb decrypt+unwrapKey envelope-decryption grant now flags) + two surfaced titlePattern anchor-drifts + drift-detector closure (1222); broad-but-not-full **public** GCP firewall source ranges → HIGH, RFC1918 discounted (1021); AWS KMS PendingDeletion keys now policy-audited — the deletion is reversible (1070); a CodePipeline sticky approval-latch — each production stage now needs its own gate (1100); GCP Storage bucket-enumeration truncation evidence-gap, class-O-routed (1024); and a CloudTrail data-events read-coverage caveat — WriteOnly drops S3 GetObject exfiltration events (1040). Plugin count UNCHANGED at 28; all six coverage matrices UNCHANGED; **CE has no code change (paired pin)**.
+**Latest: CE 0.2.8 + Enterprise 0.19.3** (June 2026) — a **real CE bump** (MCP affordance): the `scan_cloud` tool description now enumerates the actual service coverage (AWS S3 / IAM / KMS / CloudTrail / CodePipeline-CodeBuild SoD / Lambda / API GW / DynamoDB / RDS / SQS-SNS / Secrets / Backup / VPC endpoints / SG perimeter / ElastiCache / SES / GuardDuty; Azure Key Vault / Storage / NSG / RBAC; GCP firewall / storage / impersonation) + all 6 compliance frameworks, so AI agents route service-named audit asks to the scanner; the evidence-gap list lines are badge-coherent (lead with the GAP clause) and carry the first ACTIONABLE clause as a companion that now survives findings-cap eviction; internal compliance-routing tags are stripped at the presentation layer so gap lines spend their budget on substance. Paired **EE 0.19.3** "MCP affordance + class-O truncation sweep": inline-credential Lambda env-var names + the `AWS_LAMBDA_` exclusion-prefix evasion bypass closed (1080); truncation/AccessDenied evidence-gaps across 8 AWS auditors now fail-close their native controls in all six frameworks instead of routing to zero (class-O sweep incl. the 1110 P-16 grant-bypass); a new Azure NSG dimension flags restricted-port exposure to the tenant-rentable `AzureCloud` service tags (1221); public-subnet Redis replication groups no longer silently downgrade (1180). Plugin count UNCHANGED at 28; all six coverage matrices UNCHANGED. **EE 0.19.3 requires CE 0.2.8+.**
 
-**Prior: CE 0.2.6 + Enterprise 0.19.1** — paired pin for EE 0.19.1 "Confirmed false-negative batch" (7 cloud plugins hardened: 1030/1150/1130/1120/1080/1025/1160). See [CHANGELOG.md](./CHANGELOG.md).
+**Prior: CE 0.2.7 + Enterprise 0.19.2** — paired pin for EE 0.19.2 "Confirmed false-negative tail" (6 more silent misses closed: 1222/1021/1070/1100/1024/1040). See [CHANGELOG.md](./CHANGELOG.md).
 
 → Full release history: **[CHANGELOG.md](./CHANGELOG.md)**
 → See a sample EE scan output: **[walk-through with synthetic Acme Corp AWS account](https://www.nsauditor.com/ai/docs/sample-scan/)** (no signup required)

package/mcp_server.mjs

@@ -193,7 +193,9 @@ function appendCallSentinel(text, callId) {
 // Tool definitions (JSON Schema for input validation)
 // ---------------------------------------------------------------------------
 
-const TOOLS = [
+// Exported for direct testing (the scan_cloud description is a routing surface —
+// tests pin its service-coverage enumeration + contract clauses).
+export const TOOLS = [
   {
     name: 'scan_host',
     description:
@@ -216,7 +218,7 @@ 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. 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.',
+      '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, and CIS v8 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.',
     inputSchema: {
       type: 'object',
       properties: {

package/package.json

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

package/utils/cloud_finding_summary.mjs

@@ -12,15 +12,50 @@ const RANK = { CRITICAL: 5, HIGH: 4, MEDIUM: 3, LOW: 2, INFO: 1, PASS: 0 };
 const RESOURCE_KEYS = ['userName', 'bucket', 'bucketName', 'function', 'functionName', 'table', 'tableName', 'instanceId', 'group', 'groupId', 'key', 'keyId', 'vault', 'vaultName', 'pipeline', 'topic', 'queue', 'projectId', 'domain', 'secretName', 'roleName', 'accountName', 'resource', 'resourceId', 'name', 'arn'];
 const REASON_KEYS = ['classification', 'title', 'message', 'reason', 'finding', 'detail'];
 const UNKNOWN_PROVIDER = 'unknown';
+// Scan-coverage gap prose — an EXACT 1:1 mirror of the EE evidence-gap anchor
+// (nsauditor-ai-ee utils/evidence_gap_contract.mjs EVIDENCE_GAP_ANCHOR; an EE meta-test
+// drift-pins source equality). Used ONLY to order clauses WITHIN one finding — a rollup
+// mixing a gap clause with an actionable clause (e.g. Key Vault key-enum gap +
+// over-privilege broad-grant) must put each clause on its proper channel. NEVER used to
+// classify findings — that is the details.evidenceGap marker's job.
+export const GAP_CLAUSE_RE =
+  /evidence[ -]?gap|\bUNVERIFIED\b|posture[^.]{0,60}\bunverified\b|posture[^.]{0,40}\bindeterminate\b|\bindeterminate,\s*manual verification|could not (?:be )?(?:read|verified?|verify|enumerated?|enumerate|complete[d]?|parse[d]?|determine[d]?|retrieve[d]?|scoped?)|did not complete|not a clean result|scan coverage is partial|provenance is partial|failed to (?:fetch|list|retrieve)|\bnot assessed\b|manual verification required/i;
+// Substrate-evidence PASS prose (1220/1222 push these into the same issues[] as
+// violations) — informational; never a lead clause while any alternative exists.
+const PASS_CLAUSE_RE = /substrate evidence:/i;
+// EE compliance-routing tag (e.g. 'EE-RT.1.2 multi-region-enumeration-incomplete: ')
+// leading many gap emissions — anchor plumbing for the EE framework JSONs, not
+// operator prose. Stripped at THIS presentation layer only (routing matches the
+// RAW issue strings EE-side) so the 160-char slice spends its budget on substance.
+const ROUTING_PREFIX_RE = /^EE-RT\.[\dx.]+ [a-z][a-z-]*: /;
+
+function classifyClause(s) {
+  if (PASS_CLAUSE_RE.test(s)) return 'pass';
+  if (GAP_CLAUSE_RE.test(s)) return 'gap';
+  return 'actionable';
+}
+
+// Lead-clause pick: actionable > gap > pass by default; the evidence-gap list flips to
+// gap > actionable > pass so the [⚠ EVIDENCE GAP] badge always badges a GAP clause,
+// never a verified fact. Falls back to issues[0] (never empty).
+function pickClause(issues, prefer) {
+  const order = prefer === 'gap' ? ['gap', 'actionable', 'pass'] : ['actionable', 'gap', 'pass'];
+  for (const cls of order) {
+    const hit = issues.find((i) => i && classifyClause(String(i)) === cls);
+    if (hit !== undefined) return String(hit);
+  }
+  return String(issues[0]);
+}
 
 /** Robust one-line descriptor from any plugin finding shape. Never empty, never a raw object dump. */
-export function describeFinding(x) {
+export function describeFinding(x, opts = {}) {
   if (!x || typeof x !== 'object') return String(x ?? '').slice(0, 160);
   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 = String(x.issues[0]);
+  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.slice(0, 160);
   const sev = String(x.severity || x.level || '').toUpperCase();
@@ -66,11 +101,28 @@ export function summarizeCloudFindings(results, providerOf, cap = Number(process
     for (const x of found) {
       const sev = String(x?.severity || x?.level || 'INFO').toUpperCase();
       bucket.counts[sev] = (bucket.counts[sev] || 0) + 1;
+      let findingEntry = null;
       if (sev === 'CRITICAL' || sev === 'HIGH') {
-        bucket.findings.push({ severity: sev, plugin: String(r?.id ?? ''), title: describeFinding(x) });
+        findingEntry = { severity: sev, plugin: String(r?.id ?? ''), title: describeFinding(x) };
+        bucket.findings.push(findingEntry);
       }
       if (x && typeof x === 'object' && x.details && x.details.evidenceGap === true) {
-        bucket.evidenceGaps.push({ severity: sev, plugin: String(r?.id ?? ''), title: describeFinding(x) });
+        // Lead with the GAP clause (the badge says "unverified" — badging a verified
+        // fact is incoherent); carry the first actionable clause as a companion so a
+        // mixed rollup's actionable content still reaches the caller (review fold D3).
+        const gapEntry = { severity: sev, plugin: String(r?.id ?? ''), title: describeFinding(x, { prefer: 'gap' }) };
+        const clauses = Array.isArray(x.issues) ? x.issues.filter(Boolean).map(String) : [];
+        const actionable = clauses.find((i) => classifyClause(i) === 'actionable');
+        if (actionable && clauses.some((i) => classifyClause(i) === 'gap')) {
+          gapEntry.action = actionable.replace(ROUTING_PREFIX_RE, '').slice(0, 160);
+        }
+        // For CRITICAL/HIGH the actionable clause is normally itemized in the findings
+        // list above, so the companion would duplicate it — but the findings list is
+        // capped AFTER this loop, and an evicted entry would lose its actionable clause
+        // everywhere. Keep a ref; the post-cap pass below drops the companion only when
+        // the findings-list entry actually survived (0.19.3 batch-review fold).
+        if (findingEntry) gapEntry._findingRef = findingEntry;
+        bucket.evidenceGaps.push(gapEntry);
       }
     }
   }
@@ -82,6 +134,13 @@ export function summarizeCloudFindings(results, providerOf, cap = Number(process
     b.findings.sort((a, c) => (RANK[c.severity] || 0) - (RANK[a.severity] || 0));
     if (b.findings.length > cap) { b.truncated = true; b.findings = b.findings.slice(0, cap); }
     if (b.evidenceGaps.length > cap) { b.evidenceGapsTruncated = true; b.evidenceGaps = b.evidenceGaps.slice(0, cap); }
+    const kept = new Set(b.findings);
+    for (const g of b.evidenceGaps) {
+      if (g._findingRef) {
+        if (kept.has(g._findingRef)) delete g.action; // itemized above — avoid the D3 duplicate
+        delete g._findingRef; // internal ref must never reach the MCP payload
+      }
+    }
   }
   return out;
 }
@@ -126,7 +185,7 @@ export function renderCloudFindingsMarkdown(summary, providers) {
     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`);
     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}`);
+    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._`);
     lines.push('');
   }