nsauditor-ai-agent-skill 0.1.66 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ Release notes for **`nsauditor-ai-agent-skill`** — installable knowledge packa
 
 ---
 
+## 0.2.1 (2026-06-03) — Paired-release pin for EE 0.18.0 + CE 0.2.1 — GCP false-negative hardening
+
+Paired no-op bump (no standalone agent-skill content change beyond the SKILL.md version banner; SKILL.md body + `references/plugins.md` UNCHANGED). EE 0.18.0 closes five GCP false-negative defects at substrate depth on already-covered controls: **(1) plugin 1021 — AccessDenied evidence-gaps now route into `result.findings[]`** (16 single-owner anchors), so a denied GCP firewall / IAM / bucket enumeration FAILS its controls instead of reading CLEAN (was a compliance-layer false-CLEAN); **(2) plugin 1021 — project-IAM-public check now calls the correct client** — it had called `getIamPolicy` on `@google-cloud/compute`'s `ProjectsClient`, which has NO IAM methods, so the check ALWAYS threw live (`client.getIamPolicy is not a function`) and evidence-gapped → real project-IAM-public detection never fired (a pre-0.18.0 bug; the 1021 evidence-gap made it fail gracefully with no false-CLEAN, but the detection was dead); fixed to `@google-cloud/resource-manager`'s `ProjectsClient.getIamPolicy` (the client plugin 1025 already uses), live-validated under pure ADC; **(3) plugin 1025 — googleapis IAM-admin client now authenticates under pure ADC** — the `googleapis` REST client that powers 1025's Dim4-6 (custom-role inventory, SA-key custody, and the impersonation breadth-first-search where the K1/K2 paths below live) only set auth for the impersonation/key-file credential modes; in PURE Application-Default-Credentials it had NO auth set, and unlike the `@google-cloud` gax clients (storage / resource-manager) which auto-detect ADC, the `googleapis` library does NOT — so Dim4-6 returned AccessDenied even as project owner and never ran live (caught by the live Task 12 owner-ADC smoke). Fixed with an explicit scoped `GoogleAuth` for the pure-ADC path; pre-existing, same class as fix (2); **(4) plugin 1024 (GCP Cloud Storage) — NEW legacy-ACL public-exposure detection**, a bucket made public via a legacy ACL (`allUsers` / `allAuthenticatedUsers`) while Uniform Bucket-Level Access is disabled now scans the bucket ACL + a sampled object-ACL surface → CRITICAL / HIGH + evidence-gap (routed to SOC 2 CC6.6 / HIPAA §164.312(a)(1) / CIS Controls v8 3.3) instead of CLEAN; **(5) plugin 1025 (GCP IAM impersonation-BFS) completeness** — project-scope `roles/iam.serviceAccountKeyAdmin` (mint a long-lived key for ANY service account = offline impersonation) now fires the project-scope impersonation CRITICAL, and a service account privileged via an admin-equivalent CUSTOM role (`iam.serviceAccounts.actAs` etc.) is now marked admin in the impersonation graph so paths terminating there are detected instead of reading clean — both live-validated (K1 fired on a project-scope `serviceAccountKeyAdmin` binding; K2 fired on a custom-role-`actAs` SA reached via a `tokenCreator` edge). No skill-logic change. **Plugin count UNCHANGED at 28; all six coverage matrices UNCHANGED** (SOC 2 + HIPAA + NIST CSF 2.0 + PCI DSS v4.0.1 + ISO 27001:2022 + CIS Controls v8) — these are substrate-depth false-negative fixes on already-covered controls, NOT new controls. Live-validated under pure owner-ADC against a test-infra GCP project (1025-K1/K2 fired; 1025-adc Dim4-6 confirmed running; 1021 client read works with no false-clean under degraded auth); the 1024-C1 public-bucket + 1021 allUsers-binding findings could not be exercised live because the org enforces `publicAccessPrevention` + `allowedPolicyMemberDomains` (an environmental constraint, not a product gap) and remain unit-test + storage-enumeration-live proven.
+
+## 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

@@ -17,7 +17,7 @@ nsauditor-ai-agent-skill/
 ├── references/
 │   ├── workflows.md                  # Multi-step workflow recipes (full audit, CI/CD, CTEM)
 │   ├── schemas.md                    # Complete data structures (scan results, CVEs, findings)
-│   └── plugins.md                    # Full plugin catalog (50 scanners with ports & protocols — 17 core + 6 discovery + 3 pro + 24 enterprise)
+│   └── plugins.md                    # Full plugin catalog (55 scanners with ports & protocols — 27 Community incl. 3 Pro + 28 Enterprise)
 ├── examples/
 │   └── agent-interactions.md         # Example agent reasoning chains (9 scenarios)
 ├── package.json
@@ -74,11 +74,12 @@ When an AI agent loads this skill, it gains:
 | **Workflow patterns** | Multi-step chains: scan → CVE lookup → remediation report |
 | **Schema knowledge** | Complete data structures for parsing and presenting results |
 | **CPE construction** | How to map detected services to NVD vulnerability lookups |
-| **Plugin awareness** | 50 scanner plugins (23 CE + 3 Pro + 24 Enterprise) with protocols, ports, capabilities, and SOC 2 + HIPAA §164.312 substrate-evidence dimensions |
-| **Compliance frameworks** | SOC 2 (AICPA TSC 2017 — 10 covered + 4 partial controls) AND **HIPAA Security Rule §164.312 Technical Safeguards (NEW EE 0.9.0 — 7 covered + 3 partial + 45 OOS; HHS Required/Addressable discipline per control)**. Multi-framework dual-publish via `--compliance soc2,hipaa`. Zero BAA required for HIPAA — ePHI never leaves customer infrastructure. |
+| **Plugin awareness** | 55 scanner plugins (27 Community incl. 3 Pro + 28 Enterprise) with protocols, ports, capabilities, and six-framework (SOC 2 · HIPAA §164.312 · NIST CSF 2.0 · PCI DSS v4.0.1 · ISO/IEC 27001:2022 · CIS Controls v8) substrate-evidence dimensions |
+| **Compliance frameworks** | **Six frameworks, one scan** — SOC 2 (AICPA TSC 2017) · HIPAA Security Rule §164.312 Technical Safeguards (HHS Required/Addressable discipline per control) · NIST CSF 2.0 (Subcategory-level) · PCI DSS v4.0.1 (QSA RoC sub-requirement-level) · ISO/IEC 27001:2022 (per-Annex-A-code, SoA discipline) · CIS Controls v8 (per-Safeguard; Implementation Group IG1/IG2/IG3 cumulative discipline). Any CSV subset via `--compliance soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8`. Zero BAA required for HIPAA — ePHI never leaves customer infrastructure. |
 | **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
 
@@ -109,7 +110,7 @@ This package provides **knowledge about** NSAuditor AI. To actually **run** scan
 |---------|-------|-----------|
 | **Community** | Free / MIT | 27 plugins (service probes + host/network discovery + intelligence/meta), basic AI, SARIF, CTEM, scan history |
 | **Pro** | $49/mo | + CVE matching, verification probes, risk scoring, 3 Pro plugins (040 TLS / 050 TRIBE / 060 DNS) |
-| **Enterprise** | $2k+/yr | + 26 cloud-substrate auditor plugins (1020-1222 range; AWS / GCP / Azure SOC 2 evidence-pack), Zero Trust, RFC 3161 timestamps, chain-of-custody attestations, air-gapped deployment |
+| **Enterprise** | $2k+/yr | + 28 cloud-substrate auditor plugins (1020-1222 range; AWS / Azure / GCP six-framework evidence-pack — SOC 2 / HIPAA / NIST CSF 2.0 / PCI DSS v4.0.1 / ISO 27001:2022 / CIS Controls v8), Zero Trust, RFC 3161 timestamps, chain-of-custody attestations, air-gapped deployment |
 
 → [Pricing](https://www.nsauditor.com/ai/pricing/)
 

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.1 (post-EE 0.18.0 — GCP false-negative hardening) · **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.1",
   "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",