nsauditor-ai 0.2.9 → 0.2.11

package/README.md

@@ -17,9 +17,12 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
-**Latest: CE 0.2.9 + Enterprise 0.19.4** (June 2026) — paired README-refresh bump (no Community Edition code change this cycle). **EE 0.19.4 "Routing-Integrity Hardening"** closes the routing false-clean class — a real finding (or a visible evidence-gap) that mapped to **zero** compliance controls while the verdict stayed green: a build-time **routing guard** (a complete-partition `nativeFrameworks` allowlist) so no marked gap routes nowhere + GuardDuty (1200) dedupe + class-O routing; a **deferred-scope unmark** across 8 plugins (a capability boundary is not an evidence-gap → the MCP "unverified" list shrinks); the 1160 AWS-default VPC-endpoint full-access policy down-rated **CRITICAL→MEDIUM** with cross-framework routing (PCI 1.4.1 / ISO A.8.22 / CIS 12.2 + SOC 2 CC6.6 / HIPAA 164.312(a)(1)); and 1150 SQS/SNS **alarm-independence** (alarm posture survives a `Get*Attributes` deny; all four `alarm-coverage-unverifiable` causes fail-close soc2{A1.2,CC7.2}+hipaa{164.312(b)}). **PCI DSS matrix shifts 20/8/39 → 19/9/39** (Req 7.2.2 covered→partial — an honest down-rate of a QSA-flagged overclaim, backed by 1030 over-privilege detection). Plugin count UNCHANGED at 28; the other five matrices UNCHANGED. **EE 0.19.4 requires CE 0.2.8+.**
+<!-- DRAFT pending operator legal review (GDPR-cycle scope-doctrine copy). Not yet published. -->
+**Latest: CE 0.2.11 + Enterprise 0.20.0** (June 2026) — paired content bump for the Enterprise **GDPR Article 32 (Security of Processing)** cycle, the **seventh** compliance framework. The Enterprise engine now substrate-evidences **GDPR Article 32 infrastructure substrate** — Art. 32 only, **not** GDPR compliance (GDPR is a 99-article legal regime; Art. 32 security-of-processing is the only article an infrastructure scanner can evidence). The CE-side change: the MCP `scan_cloud` tool description now lists GDPR Article 32 among the mapped frameworks, and the agent-skill teaches the 7th framework (scope doctrine · four-factor proportionality · the Art. 83(4) lower fine tier). No CE engine behavior change. Paired **EE 0.20.0** (the framework lives in the Enterprise engine; matrix 4 covered + 5 partial + 2 OOS across 11 Art. 32 sub-measure units) + agent-skill 0.2.11. **EE 0.20.0 requires CE 0.2.8+.** See [CHANGELOG.md](./CHANGELOG.md).
 
-**Prior: CE 0.2.8 + Enterprise 0.19.3** — real CE bump (MCP `scan_cloud` routing description + actionable gap-list visibility) paired with EE 0.19.3 "MCP affordance + class-O truncation sweep" (1080/1221/1180 + class-O sweep across 8 AWS auditors). See [CHANGELOG.md](./CHANGELOG.md).
+**Prior: CE 0.2.10 + Enterprise 0.19.4** — MCP affordance II: `scan_cloud` rolls up MEDIUM/LOW findings per provider by category + a NEW Enterprise-gated `get_findings` drill-down tool. See [CHANGELOG.md](./CHANGELOG.md).
+
+**Prior: CE 0.2.9 + Enterprise 0.19.4** — paired README-refresh pin for EE 0.19.4 "Routing-Integrity Hardening" (PCI matrix 20/8/39 → 19/9/39; no CE code change). 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

@@ -26,7 +26,7 @@ import { buildRegionIntent } from './utils/region_intent.mjs';
 import { getTierFromEnv, loadLicense } from './utils/license.mjs';
 import { resolveCapabilities } from './utils/capabilities.mjs';
 import { buildMarkdownReport } from './utils/report_md.mjs';
-import { summarizeCloudFindings, renderCloudFindingsMarkdown } from './utils/cloud_finding_summary.mjs';
+import { summarizeCloudFindings, renderCloudFindingsMarkdown, describeFinding, RESOURCE_KEYS } from './utils/cloud_finding_summary.mjs';
 import { authorizeMcpServerStartup, getMcpAuthKeyAge, getRotationWarningDays, reportMcpAuthSource } from './utils/mcp_auth.mjs';
 
 const _require = createRequire(import.meta.url);
@@ -73,7 +73,7 @@ function requireProCapability(toolName) {
   };
 }
 
-function requireEnterpriseCapability(toolName) {
+export function requireEnterpriseCapability(toolName) {
   if (_capabilities.enterpriseMCP) return null; // Enterprise: allow
   return {
     content: [{
@@ -84,6 +84,18 @@ function requireEnterpriseCapability(toolName) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Per-provider cloud-scan cache (Stage 2b). One slot per provider, last-writer-wins.
+// Populated ONLY by handleScanCloud, which runs behind the Enterprise dispatch gate.
+// ---------------------------------------------------------------------------
+
+const _cloudScanCache = new Map();   // provider -> { scanId, ts, args, results }
+let _scanIdCounter = 0;
+export function _nextScanId() { return `scan-${++_scanIdCounter}`; }
+export function _putCloudScan(provider, slot) { _cloudScanCache.set(provider, slot); }
+export function _getCloudScan(provider) { return _cloudScanCache.get(provider) || null; }
+export function _resetCloudScanCache() { _cloudScanCache.clear(); _scanIdCounter = 0; }
+
 // ---------------------------------------------------------------------------
 // Lazy singletons — initialised on first use, overridable for tests
 // ---------------------------------------------------------------------------
@@ -193,6 +205,9 @@ function appendCallSentinel(text, callId) {
 // Tool definitions (JSON Schema for input validation)
 // ---------------------------------------------------------------------------
 
+// Max findings per page — also referenced in the TOOLS inputSchema description below.
+const GET_FINDINGS_MAX_LIMIT = 20;   // ~500 chars/finding -> ~10KB page (Desktop 60s budget)
+
 // Exported for direct testing (the scan_cloud description is a routing surface —
 // tests pin its service-coverage enumeration + contract clauses).
 export const TOOLS = [
@@ -218,7 +233,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, 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.',
+      '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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -236,6 +251,20 @@ export const TOOLS = [
       required: [],
     },
   },
+  {
+    name: 'get_findings',
+    description:
+      'Drill into the findings of the MOST RECENT scan_cloud scan (per-provider, per-session cache — NOT live state; cleared when the MCP server restarts). Filter by provider/plugin/severity/category and paginate (cursor/limit). Returns full untruncated finding text. Requires an Enterprise license. Use the scanId from the scan_cloud summary footer; if you get a "re-run scan_cloud" error the cache was cleared or superseded.',
+    inputSchema: { type: 'object', properties: {
+      scanId: { type: 'string', description: 'scanId from the scan_cloud summary footer (optional; staleness guard).' },
+      provider: { type: 'string', enum: ['aws', 'gcp', 'azure'], description: 'Which provider slot to drill (required when multiple are cached).' },
+      plugin: { type: 'string', description: 'Filter to one plugin id, e.g. "1150".' },
+      severity: { type: 'string', description: 'Filter: CRITICAL|HIGH|MEDIUM|LOW|INFO.' },
+      category: { type: 'string', description: 'Filter to one details.category, e.g. "sqs-age-alarm-missing".' },
+      cursor: { type: 'string', description: 'Pagination cursor from a previous nextCursor.' },
+      limit: { type: 'number', description: `Page size (server-capped at ${GET_FINDINGS_MAX_LIMIT}).` },
+    } },
+  },
   {
     name: 'probe_service',
     description:
@@ -421,7 +450,8 @@ export async function handleScanCloud(args) {
   // empty for a cloud conclusion). Best-effort.
   let markdown = null;
   try {
-    markdown = renderCloudFindingsMarkdown(findingsSummary, providers);
+    markdown = renderCloudFindingsMarkdown(findingsSummary, providers,
+      { getFindingsAvailable: typeof toolHandlers.get_findings === 'function' });
   } catch { /* swallow — markdown is best-effort */ }
 
   // Anti-false-clean: a requested cloud is "audited" ONLY if >=1 of its plugins
@@ -445,6 +475,26 @@ export async function handleScanCloud(args) {
   // Honest count: completed audits, NOT error/skip envelopes.
   const pluginsRan = (output.manifest || []).filter((m) => m.status === 'ran').length;
 
+  // Mint ONE scanId for the whole call and write every scanned provider's slot so
+  // a follow-up get_findings call can drill into any individual provider from this
+  // scan (one-to-many: same scanId on every slot populated by this call).
+  const scanId = _nextScanId();
+  const ts = Date.now();
+  const byProvider = new Map();
+  for (const r of (output.results || [])) {
+    const prov = providerOf(r?.id ?? r?.result?.id);
+    if (!prov) continue;
+    if (!byProvider.has(prov)) byProvider.set(prov, []);
+    byProvider.get(prov).push(r);
+  }
+  for (const prov of providers) {
+    _putCloudScan(prov, { scanId, ts, args, results: byProvider.get(prov) || [] });
+  }
+
+  if (markdown != null && typeof toolHandlers.get_findings === 'function') {
+    markdown += `\n\n> _scanId: ${scanId} — drill any category via get_findings (provider="${providers[0]}")._`;
+  }
+
   return {
     providers,
     audited: auditedProviders.length > 0,
@@ -453,10 +503,48 @@ export async function handleScanCloud(args) {
     manifest: output.manifest ?? [],
     pluginsRan,
     markdown,
+    scanId,
     ...(notes.length ? { notes } : {}),
   };
 }
 
+export async function handleGetFindings(args = {}) {
+  const slots = ['aws', 'gcp', 'azure'].filter((p) => _getCloudScan(p));
+  let provider = args.provider && String(args.provider).toLowerCase();
+  if (!provider) {
+    if (slots.length === 1) provider = slots[0];
+    else if (slots.length === 0) return { error: 'No cloud scan is cached for this session — run scan_cloud first. (The cache is per-session and is cleared when the MCP server restarts.)' };
+    else return { error: `Multiple cached scans — pass provider (one of: ${slots.map((p) => `${p}:${_getCloudScan(p).scanId}`).join(', ')}).` };
+  }
+  const slot = _getCloudScan(provider);
+  if (!slot) return { error: `No cached scan for provider '${provider}' — run scan_cloud first (per-session cache, cleared on server restart).` };
+  if (args.scanId && args.scanId !== slot.scanId) return { error: `scanId '${args.scanId}' is no longer cached (displaced by ${slot.scanId}) — re-run scan_cloud.` };
+  let rows = [];
+  for (const r of (slot.results || [])) for (const f of (r?.result?.findings ?? r?.findings ?? [])) {
+    const sev = String(f?.severity || 'INFO').toUpperCase();
+    const cat = (f?.details && f.details.category) ? String(f.details.category) : `uncategorized(${String(r?.id ?? '')})`;
+    if (args.severity && sev !== String(args.severity).toUpperCase()) continue;
+    if (args.category && cat !== String(args.category)) continue;
+    if (args.plugin && String(r?.id) !== String(args.plugin)) continue;
+    // Extract the resource identifier directly from the finding object using the SAME
+    // key priority as describeFinding (the shared RESOURCE_KEYS imported from
+    // cloud_finding_summary.mjs) — avoids split-after-truncation ambiguity when
+    // describeFinding truncates into the ' — ' separator, and can never drift from it.
+    let res = '';
+    for (const k of RESOURCE_KEYS) { if (f && f[k]) { res = String(f[k]); break; } }
+    rows.push({ plugin: String(r?.id ?? ''), severity: sev, category: cat,
+      resource: res, region: f?.region || f?.details?.region || '',
+      text: Array.isArray(f?.issues) ? f.issues.join(' · ') : String(f?.title || f?.classification || '') });
+  }
+  const start = Number(args.cursor) || 0;
+  const limit = Math.min(Number(args.limit) || GET_FINDINGS_MAX_LIMIT, GET_FINDINGS_MAX_LIMIT);
+  const page = rows.slice(start, start + limit);
+  const out = { provider, scanId: slot.scanId, total: rows.length, findings: page };
+  if (Number(args.limit) > GET_FINDINGS_MAX_LIMIT) out.note = `limit capped server-side at ${GET_FINDINGS_MAX_LIMIT} (≈10KB/page).`;
+  if (start + limit < rows.length) out.nextCursor = String(start + limit);
+  return out;
+}
+
 export async function handleProbeService(args) {
   if (!args?.host || typeof args.host !== 'string') {
     throw new Error('Missing required parameter: host');
@@ -516,6 +604,7 @@ export async function handleListPlugins() {
 export const toolHandlers = {
   scan_host: handleScanHost,
   scan_cloud: handleScanCloud,
+  get_findings: handleGetFindings,
   probe_service: handleProbeService,
   get_vulnerabilities: handleGetVulnerabilities,
   list_plugins: handleListPlugins,
@@ -574,8 +663,8 @@ export function createServer() {
       }
     }
 
-    // Gate the Enterprise cloud-audit tool at the MCP dispatch layer.
-    if (name === 'scan_cloud') {
+    // Gate Enterprise cloud-audit tools at the MCP dispatch layer (gate-before-cache-read).
+    if (['scan_cloud', 'get_findings'].includes(name)) {
       const denied = requireEnterpriseCapability(name);
       if (denied) {
         return {

package/package.json

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

package/utils/cloud_finding_summary.mjs

@@ -9,7 +9,10 @@ const RANK = { CRITICAL: 5, HIGH: 4, MEDIUM: 3, LOW: 2, INFO: 1, PASS: 0 };
 // Resource-identifying keys, most-specific first so a precise label wins over the
 // generic resource/name/arn fallbacks. Grounded in the REAL EE plugin emissions
 // (S3 1020 emits `bucket`, Key Vault `vault`, DynamoDB `table`, KMS `key`, …).
-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'];
+// Exported as the SINGLE SOURCE OF TRUTH — get_findings (mcp_server.mjs) imports this
+// rather than re-declaring the list, so the two resource-extraction surfaces can never
+// drift on which key names a finding's resource.
+export 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
@@ -57,7 +60,7 @@ export function describeFinding(x, opts = {}) {
   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);
+  if (s) return s.length > 160 ? s.slice(0, 160).replace(/\s+\S*$/, '') + '…' : s;
   const sev = String(x.severity || x.level || '').toUpperCase();
   return sev ? sev + ' finding (no description)' : 'finding (no description)';
 }
@@ -97,7 +100,7 @@ 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 });
+    const bucket = (out[prov] ||= { counts: {}, findings: [], evidenceGaps: [], truncated: false, _rollup: { MEDIUM: new Map(), LOW: new Map() } });
     for (const x of found) {
       const sev = String(x?.severity || x?.level || 'INFO').toUpperCase();
       bucket.counts[sev] = (bucket.counts[sev] || 0) + 1;
@@ -111,10 +114,11 @@ export function summarizeCloudFindings(results, providerOf, cap = Number(process
         // 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' }) };
+        gapEntry.gapKind = (x.details.walkthroughRequired === true) ? 'walkthrough-required' : 'couldnt-read';
         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);
+        const actionableClauses = clauses.filter((i) => classifyClause(i) === 'actionable');
+        if (actionableClauses.length && clauses.some((i) => classifyClause(i) === 'gap')) {
+          gapEntry.action = actionableClauses.map((a) => a.replace(ROUTING_PREFIX_RE, '')).join(' · ').slice(0, 240);
         }
         // 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
@@ -124,6 +128,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)) {
+        const cat = (x && x.details && x.details.category)
+          ? String(x.details.category)
+          : `uncategorized(${String(r?.id ?? '')})`;
+        const m = bucket._rollup[sev];
+        m.set(cat, (m.get(cat) || 0) + 1);
+      }
     }
   }
   // Sort by severity (CRITICAL first) THEN truncate — so a CRITICAL is never evicted
@@ -141,6 +152,13 @@ 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)),
+    };
+    delete b._rollup;
   }
   return out;
 }
@@ -174,7 +192,7 @@ export function incompleteCoverageAdvisory(scanScope) {
 }
 
 /** Compact markdown from a summary. Named providers first, then any extras (e.g. 'unknown') so nothing is hidden. */
-export function renderCloudFindingsMarkdown(summary, providers) {
+export function renderCloudFindingsMarkdown(summary, providers, opts = {}) {
   const named = providers && providers.length ? providers.slice() : [];
   // Exclude the meta-key _incompleteCoverage from the provider rendering loop.
   const order = [...named, ...Object.keys(summary).filter((p) => !named.includes(p) && p !== '_incompleteCoverage')];
@@ -187,6 +205,14 @@ export function renderCloudFindingsMarkdown(summary, providers) {
     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._`);
+    const drill = opts.getFindingsAvailable ? ' — drill any category via get_findings' : '';
+    for (const tier of ['MEDIUM', 'LOW']) {
+      const rows = (b.rollup && b.rollup[tier]) || [];
+      if (!rows.length) continue;
+      const total = c[tier] || rows.reduce((n, rr) => n + rr.count, 0);
+      const body = rows.map((rr) => `${rr.category} ×${rr.count}`).join(' · ');
+      lines.push(`- **${tier} (${total})** ${body}${drill}`);
+    }
     lines.push('');
   }
   // Append the incomplete-coverage advisory (when present) as an informational note.