nsauditor-ai-agent-skill 0.1.66 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,10 @@ Release notes for **`nsauditor-ai-agent-skill`** — installable knowledge packa
 
 ---
 
+## 0.2.0 (2026-06-01) — `scan_cloud` `regions` teaching (paired with EE 0.17.0 + CE 0.2.0)
+
+SKILL.md now teaches the `scan_cloud` `regions` argument: AWS region codes (e.g. `["us-east-1","eu-west-1"]`) or `["all"]`, with the divergent default (omit = the single server-configured `AWS_REGION`; omitting does NOT fan out). **Region-scope discipline — validated via live Claude Desktop runs + a RED→GREEN→REFACTOR subagent harness on a lighter model tier:** (1) **Default = single region** for any plain "audit my AWS account" / "quick check" / no-region request — do NOT fan out or batch; (2) **Honest scope reporting** — report the regions you actually PASSED, never claim "all regions / every region / across N regions" off GuardDuty's or Inspector's INTERNAL per-region enumeration, and never escalate a single-region or "quick" request into a multi-region scan; (3) **Full all-region coverage via discover-then-batch** (ONLY on an explicit all/every/whole-account/full-coverage request) — a single `["all"]` call usually exceeds the host's MCP tool-call timeout (e.g. Claude Desktop's ~60s) and returns nothing, so discover the enabled regions via a default scan then audit the remainder in small region-group batches until complete, counting the regions covered, and never report a timed-out or partial scan as full coverage. Paired with the EE 0.17.0 `--aws-region` feature + CE 0.2.0. Plugin count UNCHANGED (28); all six matrices UNCHANGED.
+
 ## 0.1.66 (2026-05-31) — Paired-release pin for EE 0.16.7 + CE 0.1.98 — EE CloudTrail (plugin 1040) multi-region hotfix: per-region DescribeTrails client now carries a short connect/request timeout + low maxAttempts (a dead/unreachable region fails in ~2s instead of hanging ~30s; region concurrency 6→12), and an errored region is recorded as an evidence-gap (regionsWithError) instead of throwing out of the whole enumeration → single-region fallback. Live: 233.7s → 14.2s, full multi-region, no fallback. Internal EE plugin change; no tool surface or agent-behavior change. Plugin count UNCHANGED (28); all six matrices UNCHANGED. Full regression 6814/6818 GREEN. SKILL.md/references unchanged.
 
 ## 0.1.65 (2026-05-31) — Paired-release pin for EE 0.16.6 + CE 0.1.97 — EE false-clean regression hotfix + two over-reporting folds (CloudTrail soft budget = 0.8×min(PLUGIN_TIMEOUT_MS, CLOUD_PLUGIN_TIMEOUT_MS) so it stays below the manager wall on BOTH the CLI and MCP scan paths — closes the 0.16.5 hard-cancel regression the published-build re-smoke caught; plugin 1110 no longer flags KMS grant-decrypt Pacu P-16 stealth paths on AWS-managed CMKs; compliance-engine PASS-tier substrate-evidence no longer counted as a violation). Internal EE engine/plugin change; no tool surface or agent-behavior change. Plugin count UNCHANGED (28); all six matrices UNCHANGED. Full regression 6808/6812 GREEN (zero new failures, zero verdict shifts). SKILL.md/references unchanged.

package/README.md

@@ -79,6 +79,7 @@ When an AI agent loads this skill, it gains:
 | **Security rules** | ZDE, SSRF protection, redaction, scan authorization requirements |
 | **Error handling** | License gates, SSRF blocks, timeout resolution, CPE format errors |
 | **Decision routing** | When to use scan_host vs probe_service vs CLI vs get_vulnerabilities |
+| **Cloud-region scoping** | The MCP `scan_cloud` `regions` argument — pass `["all"]` (or a region-code list like `["us-east-1","eu-west-1"]`) to audit every / specific AWS regions; **omit it to scan the server-configured `AWS_REGION`** (omitting does NOT fan out — pass `["all"]` explicitly for full coverage, mindful of the Desktop tool-call timeout). Mirrors the CE CLI `--aws-region <one\|csv\|all>` flag. |
 
 ## Prerequisites
 

package/SKILL.md

@@ -16,7 +16,7 @@ description: >
 
 # NSAuditor AI — Agent Skill
 
-> **Version:** 0.1.10 · **Source:** [github.com/nsasoft/nsauditor-ai](https://github.com/nsasoft/nsauditor-ai) · **npm:** `nsauditor-ai` · **License:** MIT (CE)
+> **Version:** 0.2.0 · **Source:** [github.com/nsasoft/nsauditor-ai](https://github.com/nsasoft/nsauditor-ai) · **npm:** `nsauditor-ai` · **License:** MIT (CE)
 
 NSAuditor AI is a modular, AI-assisted network security audit platform with 27+ scanner
 plugins, CVE matching, MITRE ATT&CK mapping, and Zero Data Exfiltration by design. This
@@ -138,9 +138,13 @@ These tools return a license upgrade prompt on CE installations:
 | `risk_summary` | Pro | Prioritized risk overview with severity breakdown |
 | `scan_compare` | Pro | Diff two scan results with risk-weighted delta analysis |
 | `save_finding` | Pro | Persist a validated finding to the finding queue |
-| `scan_cloud` | Enterprise | Audit one or more cloud accounts (AWS / GCP / Azure) for security & compliance posture using the server-configured credentials. No network host needed. Input: `{ providers?: ("aws"\|"gcp"\|"azure")[] }` — **pass only the cloud(s) the user names** (`providers:["aws"]` for "audit my AWS account"); omit `providers` only when the user asks to audit ALL clouds. Use this (not `scan_host`) when the user asks to "audit my AWS account", "audit my AWS and Azure accounts", or "check my cloud compliance". CE/Pro callers get an upgrade message. |
+| `scan_cloud` | Enterprise | Audit one or more cloud accounts (AWS / GCP / Azure) for security & compliance posture using the server-configured credentials. No network host needed. Input: `{ providers?: ("aws"\|"gcp"\|"azure")[], regions?: string[] }` — **pass only the cloud(s) the user names** (`providers:["aws"]` for "audit my AWS account"); omit `providers` only when the user asks to audit ALL clouds. Use this (not `scan_host`) when the user asks to "audit my AWS account", "audit my AWS and Azure accounts", or "check my cloud compliance". CE/Pro callers get an upgrade message. **`regions` (AWS only)** — AWS region codes (e.g. `["us-east-1","eu-west-1"]`) or `["all"]`. **Default — single region (MOST requests):** a plain "audit my AWS account", a "quick check", or any request that names no region AND does not explicitly ask for all/every/whole-account/complete/full coverage → **OMIT `regions`** (audits ONLY the server-configured `AWS_REGION`, one region; do NOT fan out or batch). Omitting does NOT scan all regions. **Specific regions:** when the user names region(s), pass exactly those. **All regions — ONLY on an explicit "all regions / every region / whole account / full coverage" request:** use the discover-then-batch approach in the region-scope note below — do NOT pass a single `["all"]` call and rely on it (it fans every regional plugin across all enabled regions and usually EXCEEDS the host's MCP tool-call timeout, e.g. Claude Desktop's, returning nothing). Unknown region codes are rejected before the scan runs (the WHOLE call fails — fix the region and re-call; never silently drop it). |
 
 > **Interpreting `scan_cloud` results — never report a false clean:** read **`findingsSummary`** for the findings — it maps each provider to `counts` (per-severity totals) and a `findings` list of the CRITICAL/HIGH items (`{severity, plugin, title}`); report those. A cloud was effectively audited only if it appears in `auditedProviders`. If the result has `audited: false`, any `notes` entries, or `pluginsRan: 0`, the cloud was **NOT** audited (no plugins, missing credentials, or skipped) — report the gap explicitly; an empty result is **not** a clean pass. Do not infer "clean" from an empty `findingsSummary` when the cloud is not in `auditedProviders`.
+
+> **Reporting `scan_cloud` region scope — never overstate coverage:** Report the regions you ACTUALLY scanned, derived from the `regions` you **passed** — NOT from the findings. If you OMITTED `regions`, only the single server-default region (`AWS_REGION`) was scanned — say exactly that and add that the account's OTHER enabled regions were NOT covered (offer to re-run for all regions). **Never escalate a single-region or "quick" request into a multi-region scan.** Do NOT claim "all regions" / "every region" / "across N regions" just because GuardDuty or Inspector list per-region findings: those plugins enumerate every enabled region INTERNALLY regardless of scope, so their per-region findings are NOT evidence the other plugins ran outside the region(s) you passed.
+
+> **Full all-region coverage — discover then batch** (use ONLY when the user explicitly asked for all/every/whole-account/complete/full region coverage; NEVER for a plain or "quick" request — those stay single-region per the `regions` default above): a single `regions:["all"]` call usually exceeds the host's MCP tool-call timeout (e.g. Claude Desktop's) and returns nothing. Reliable pattern: (1) run a default scan (omit `regions`) — its GuardDuty/Inspector findings enumerate every enabled region, giving you the full list while auditing the default region; (2) scan the REMAINING regions in small batches (3–5 region codes per `regions:[...]` call) across successive calls until every enabled region is covered; (3) merge and report the TOTAL number of regions actually covered — **count** them, don't guess. If you try `["all"]` and it times out, that result is INCOMPLETE — fall back to batching and continue until complete; never report a timed-out or partial scan as full coverage.
 | `start_assessment` | Enterprise | Multi-host orchestrated security assessment |
 | `prioritize_risks` | Enterprise | Cross-host risk prioritization and ranking |
 | `compliance_check` | Enterprise | SOC 2 (AICPA TSC 2017) + HIPAA (§164.312 Technical Safeguards) + NIST CSF 2.0 Core + PCI DSS v4.0.1 (sub-requirement-level for QSA RoC; PCI SSC June 2024 errata) + ISO/IEC 27001:2022 (per-Annex-A-code-level for ISO/IEC 17021-1 certification body assessors; ISO + IEC October 2022; 2013 edition retired October 31, 2025) + **CIS Critical Security Controls v8** (per-Safeguard-level; Center for Internet Security May 2021, v8.1 errata June 2024) gap analysis — all six shipped (SOC 2 EE 0.3.x; HIPAA EE 0.9.0; NIST CSF 2.0 EE 0.10.0; PCI DSS v4.0.1 EE 0.11.0; ISO/IEC 27001:2022 EE 0.12.0; **CIS Controls v8 EE 0.13.0**). Multi-framework via `--compliance soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8` (any CSV subset; hexa-framework one-scan produces six complete auditor-ready evidence packs). **CIS Controls v8**: 17 covered + 22 partial + 114 OOS across 153 Safeguards / 18 Controls. **Implementation Group cumulative discipline** — IG1=56 (cyber-insurance baseline; ~50-70% of mid-market policies require IG1 attestation), IG2 cumulative=130, IG3 cumulative=153; smallest-IG-membership tagging (NEVER report IG2 as 74-of-74 in isolation). **No-certification-body attestation discipline** — engine output is INPUT to CSAT / CIS-CAT Pro self-attestation OR a SOC 2 auditor cross-validating CIS scope, never "CIS certified." Cloud Companion Guide v8 shared-responsibility + CIS-Hardened-Image substrate-evidence credit (Safeguards 4.1/4.2/4.6) + 5 Security Functions (NOT 6 — no Govern) + 6 Asset Types + MS-ISAC/EI-ISAC/H-ISAC sector baselines + v7.1-to-v8 cross-reference. CIS Safeguard examples: `3.3` Data Access Control Lists, `5.4` Restrict Administrator Privileges, `6.3` MFA for Externally-Exposed Applications, `8.2` Collect Audit Logs, `11.4` Isolated Recovery Data Instance. ISO 27001 Annex A code examples: `A.5.15` Access control, `A.5.23` NEW 2022 Cloud services, `A.8.5` Secure authentication, `A.8.9` NEW 2022 Configuration management, `A.8.16` NEW 2022 Monitoring activities, `A.8.24` Use of cryptography. Statement of Applicability per Clause 6.1.3.d discipline + ISMS Clauses 4-10 OOS-by-design framing (7 Major Nonconformity classes — absence of internal audit per Clause 9.2 or management review per Clause 9.3 = auto-fail Stage 2) + 5-attribute taxonomy NEW in 2022 (controlType / informationSecurityProperties / cybersecurityConcepts [5 categories, NOT 6 like NIST CSF 2.0] / operationalCapabilities / securityDomains) + 2013-to-2022 transition discipline. Pair with ISO-aware GRC (Drata ISO 27001 / Vanta ISO 27001 / AuditBoard / OneTrust ISMS / Secureframe ISO 27001) for SoA workflow + internal audit + management review. PCI DSS sub-requirement examples: `Req 1.2.1` NSC config standards, `Req 8.4.1` MFA on non-console admin, `Req 10.2.1` audit logs enabled, `Req 11.3.1` quarterly internal vuln scans. Defined-vs-Customized Approach discipline per Appendix E (15 Defined-only sub-requirements enforced at schema layer; CHD Scope operator-attested via CDE DFD per Req 1.2.4; card-brand AOC enforcement view — Visa CISP / Mastercard SDP / Amex DSOP / Discover DISC). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai-agent-skill",
-  "version": "0.1.66",
+  "version": "0.2.0",
   "description": "AI Agent Skill for NSAuditor AI — gives any AI coding agent built-in knowledge of NSAuditor's MCP tools, schemas, plugins, and security audit workflows.",
   "keywords": [
     "nsauditor",