nsauditor-ai 0.2.8 → 0.2.10

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.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+.**
+**Latest: CE 0.2.10 + Enterprise 0.19.4** (June 2026) — a **real CE feature** (MCP affordance II): the `scan_cloud` summary now surfaces actionable findings that used to be invisible. MEDIUM/LOW findings **roll up per provider by category** (`MEDIUM (8) sqs-age-alarm-missing ×2 · sns-failure-alarm-missing ×2 · …`, count-descending, no-silent-cap) — so a Desktop agent can no longer narrate "the alarm dimension came back clean" over live monitoring findings. And a NEW Enterprise-gated **`get_findings`** tool drills the most recent scan's per-provider cache (filter by provider/plugin/severity/category, paginate, FULL untruncated text) — keyed by a `scanId` the summary footer carries, gated *before* any cache read (a CE/Pro caller gets the same 🔒 denial as `scan_cloud`). Plus collector fixes (all-clauses gap companion · boundary-safe truncation · walkthrough-vs-couldn't-read `gapKind`) and a `scan_cloud` description that steers agents away from raw cloud-provider MCPs. Paired **EE 0.19.4** (unchanged — peer `>=0.2.8` already satisfied) + agent-skill 0.2.10 (documents `get_findings`). **EE 0.19.4 requires CE 0.2.8+.**
 
-**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).
+**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 } 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, 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. 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 (same key
+    // priority as describeFinding's RESOURCE_KEYS) — avoids split-after-truncation
+    // ambiguity when describeFinding truncates into the ' — ' separator.
+    const FINDING_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'];
+    let res = '';
+    for (const k of FINDING_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.8",
+  "version": "0.2.10",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

package/utils/cloud_finding_summary.mjs

@@ -57,7 +57,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 +97,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 +111,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 +125,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 +149,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 +189,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 +202,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.