nsauditor-ai-agent-skill 0.2.41 → 0.2.42

package/CHANGELOG.md

@@ -4,6 +4,43 @@ Release notes for **`nsauditor-ai-agent-skill`** — installable knowledge packa
 
 ---
 
+## 0.2.42 (2026-08-19) — post-EE 0.39.0: teach `deferredScope` as a per-PLUGIN boundary, and correct a stale "not yet proven"
+
+**Requires CE >= 0.2.43 — UNCHANGED.** Enterprise 0.39.0 raises no floor.
+
+Enterprise 0.39.0 gives every GCP and Azure plugin a `details.deferredScope` declaration (1021, 1022,
+1024, 1025, 1220, 1221, 1222), joining the AWS plugins that already had one. The skill teaches four
+things about it, and each is a mis-teaching this package could otherwise ship:
+
+- A declaration is a **static capability boundary**, not an evidence gap and not a finding. It routes
+  to **zero** compliance controls by design. Report it as "not assessed".
+- It is emitted **even over an empty estate**, because "zero findings" is otherwise indistinguishable
+  from "assessed and clean".
+- ⚠️ **An empty or short list is NEVER a claim of full coverage.** Not every plugin declares its
+  boundaries, so the list bounds only what the DECLARING plugins state. This is stated as a per-plugin
+  invariant rather than a provider roster, deliberately: a roster sentence goes stale on the peer's
+  next release, and CE floats over a peer RANGE and cannot derive Enterprise's plugin set.
+- Two AWS declarations (1080, 1130) now emit **once per run** rather than once per region, so the count
+  no longer scales with the estate.
+
+Also taught: GCP impersonation now **refuses** an impersonated client that yields no Authorization
+header — by name, with the target principal — surfacing as `up:false` plus a warning that fires
+scanner-down synthesis. That refusal is the fail-closed design working and must not be taught as a
+regression; what it replaced was silent anonymous requests producing FALSE evidence gaps.
+
+### A correction this package owed, in the underclaim direction
+
+0.2.41 taught that pack signing was *"reachable, not yet proven"*. **True when written, false since
+2026-08-17**, when the published-bytes gate ran against the EE 0.38.0 registry bytes and passed. Every
+"not yet proven" clause about pack signing is corrected here. npm freezes this package's prose at
+publish time, so the correction needed its own release. The **scope** bound did not move and is the
+part to keep repeating: one framework's envelope and the artifacts it enumerates, an operator-held
+key, never a vendor attestation, never proof the scan ran.
+
+Plugin catalog UNCHANGED at 28 EE / 55 overall; all seven matrices UNCHANGED.
+
+---
+
 ## 0.2.41 (2026-08-17) — post-EE 0.38.0: the evidence pack can be signed
 
 **Requires CE >= 0.2.43** — both new verbs are routed from CE.

package/README.md

@@ -11,17 +11,24 @@ Works with **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **VS C
 
 ## Current release
 
-**0.2.41** — paired with **Enterprise 0.38.0 / Community 0.2.43**. Not yet proven: the two new pack-signing
-commands (`compliance sign-pack | verify-pack`) — reachable, **not yet** proven by the gate that runs
-against published bytes — and the exact scope of what a verified pack signature does and does not
-establish.
+**0.2.42** — paired with **Enterprise 0.39.0 / Community 0.2.44**. Coverage honesty: every GCP and Azure
+plugin now declares what it does NOT evaluate, so `deferredScope` must be taught as a **per-plugin static
+capability boundary** — not an evidence gap, not a finding, routing to zero compliance controls — and an
+empty or short list is **never** a claim of full coverage.
+
+⚠️ **Correcting this section's own prior text.** It called the sign-pack and verify-pack commands
+*"reachable, not yet proven"*, which was true when written and became false on 2026-08-17, when the
+published-bytes gate ran against the EE 0.38.0 registry bytes and passed. So the capability is now
+PROVEN for an operator-held key over one framework's envelope and the artifacts it enumerates, never
+a vendor attestation. That scope bound is permanent and did not move.
 
 ⚠️ **What the skill must teach accurately about THIS release, because it is the claim most easily
 overstated:** a verified signature proves the holder of a key asserted authorship of **one
 framework's** chain-of-custody envelope at a stated time, **relative to operator key custody**. It
 is never a vendor attestation, never proof the scan ran, and never proof the findings are true. It
 covers that envelope plus the four artifacts it enumerates — **not the directory and not the pack**;
-a seven-framework pack holds 74 files and no object in it enumerates the set. `verify-pack` also
+a seven-framework pack holds ten files per framework plus the scan-level output, and no object in
+it enumerates the set. `verify-pack` also
 recomputes every enumerated artifact hash against disk, so an edited report fails while the
 signature itself still reads VERIFIED. And exit **2** means the run could not measure — an unsigned
 pack, an unsupplied key or a registry member with no key material — which an agent must never
@@ -52,7 +59,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 (55 scanners with ports & protocols — 27 Community incl. 3 Pro + 28 Enterprise)
+│   └── plugins.md                    # Full plugin catalog (55 scanners with ports & protocols — 27 Community + 28 Enterprise)
 ├── examples/
 │   └── agent-interactions.md         # Example agent reasoning chains (9 scenarios)
 ├── package.json
@@ -109,7 +116,7 @@ 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** | 55 scanner plugins (27 Community incl. 3 Pro + 28 Enterprise) with protocols, ports, capabilities, and seven-framework (SOC 2 · HIPAA §164.312 · NIST CSF 2.0 · PCI DSS v4.0.1 · ISO/IEC 27001:2022 · CIS Controls v8 · GDPR Art. 32) substrate-evidence dimensions |
+| **Plugin awareness** | 55 scanner plugins (27 Community + 28 Enterprise) with protocols, ports, capabilities, and seven-framework (SOC 2 · HIPAA §164.312 · NIST CSF 2.0 · PCI DSS v4.0.1 · ISO/IEC 27001:2022 · CIS Controls v8 · GDPR Art. 32) substrate-evidence dimensions |
 | **Compliance frameworks** | **Seven 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) · GDPR Article 32 (sub-measure-level; **Art. 32 infrastructure substrate only, NOT GDPR compliance**). All seven via `--compliance all`, or any CSV subset via `--compliance soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr`. 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 |
@@ -149,7 +156,7 @@ This package provides **knowledge about** NSAuditor AI. To actually **run** scan
 | Edition | Price | Highlights |
 |---------|-------|-----------|
 | **Community** | Free / MIT | 27 plugins (service probes + host/network discovery + intelligence/meta), basic AI, SARIF, CTEM, scan history |
-| **Pro** | $49/mo | + CVE matching, risk scoring, 3 Pro plugins (040 TLS / 050 TRIBE / 060 DNS) |
+| **Pro** | $49/mo | + CVE matching, risk scoring, and intelligence-enriched AI prompts (CVE + MITRE ATT&CK context injected) |
 | **Enterprise** | $2k+/yr | + 28 enterprise plugins (1020-1222 range) — 27 cloud-substrate auditors across AWS / Azure / GCP plus `1023 Zero Trust Assessment`, which scores zero-trust posture from a NETWORK-host scan and does not run on a cloud pass, seven-framework evidence-pack (SOC 2 / HIPAA / NIST CSF 2.0 / PCI DSS v4.0.1 / ISO 27001:2022 / CIS Controls v8 / GDPR Art. 32), SHA-256 chain-of-custody attestations, the suppression-approval CLI with opt-in Ed25519 signing (reachable from EE 0.35.0, proven 0.36.0, verified per approver holding key material), air-gapped operation (offline licensing + offline CVE matching) |
 
 → [Pricing](https://www.nsauditor.com/ai/pricing/)

package/SKILL.md

@@ -16,7 +16,9 @@ description: >
 
 # NSAuditor AI — Agent Skill
 
-> **Version:** 0.2.41 (post-EE-0.38.0 · **requires CE ≥ 0.2.43**) — the pack-signing release, reachable and **not yet** proven by the published-bytes gate. `compliance sign-pack` signs a chain-of-custody envelope with an operator-held Ed25519 key (reachable, **not yet** proven); `compliance verify-pack` establishes authorship AND recomputes every enumerated artifact hash against disk. A verified signature proves the holder of a key asserted authorship of ONE framework's envelope, relative to operator key custody — never a vendor attestation, never proof the scan ran. It covers that envelope and its four artifacts, not the pack. Exit 2 means the run could not measure and is never a failure.
+> **Version:** 0.2.42 (post-EE-0.39.0 · **requires CE ≥ 0.2.43**, UNCHANGED) — the coverage-honesty release. ⚠️ **Teach `deferredScope` as a per-PLUGIN declaration, never as a provider or coverage inventory.** Every GCP and Azure plugin now declares what it does NOT evaluate (1021, 1022, 1024, 1025, 1220, 1221, 1222), joining the AWS plugins that already did — 8 to 12 static boundaries each, emitted at `run()` scope on the audited path **including over an empty estate**, because "zero findings" is otherwise indistinguishable from "assessed and clean". A declaration is a **static capability boundary**: it is NOT an evidence gap and NOT a finding, it routes to ZERO compliance controls by design, and it must be reported as "not assessed". ⚠️ **An empty or short `deferredScope` is NEVER a claim of full coverage** — not every plugin declares its boundaries, so the list bounds only what the DECLARING plugins state. Never tell a user that an empty list means everything was assessed. Two AWS declarations (1080 Lambda, 1130 Backup) are now emitted ONCE PER RUN rather than once per region, so a fleet reads nine once-per-run disclosures — a count that no longer scales with the estate. And **GCP impersonation now REFUSES rather than degrading**: an impersonated client that yields no Authorization header fails loudly by name with the target principal, surfacing as `up:false` plus a warning that fires scanner-down synthesis. ⚠️ Teach that refusal as a PASS of the fail-closed design, never as a regression — the alternative it replaced was silent anonymous requests reporting FALSE evidence gaps. Plugin catalog UNCHANGED at 28 EE / 55 overall; all seven matrices UNCHANGED.
+>
+> **Prior:** 0.2.41 (post-EE-0.38.0 · **requires CE ≥ 0.2.43**) — the sign-pack / verify-pack release. ⚠️ **This entry described those commands as "reachable and not yet proven" when written, and that is now STALE in the underclaim direction.** The published-bytes gate RAN against the EE 0.38.0 registry bytes on 2026-08-17 and PASSED, so the capability is PROVEN for an operator-held key over one framework's envelope and the artifacts it enumerates, never a vendor attestation. What has not changed, and never will, is that scope. `compliance sign-pack` signs a chain-of-custody envelope with an operator-held Ed25519 key; `compliance verify-pack` establishes authorship AND recomputes every enumerated artifact hash against disk. A verified signature proves the holder of a key asserted authorship of ONE framework's envelope, relative to operator key custody — never a vendor attestation, never proof the scan ran. It covers that envelope and its four artifacts, not the pack. Exit 2 means the run could not measure and is never a failure.
 >
 > **Prior:** 0.2.40 (post-EE-0.37.0 · **requires CE ≥ 0.2.42**) — the air-gap feed release. `feed bundle` and `feed import` let NVD feed files downloaded on a connected host be merged into one archive, hand-carried, and imported into the offline store on an isolated host — delivered as a **restricted** distribution rather than a public `npm install`, and amd64 only. ⚠️ Teach these precisely: **`feed bundle` bundles the FEEDS YOU DOWNLOADED, never "your database"** — the offline store is a lossy derivation of an NVD feed and cannot be turned back into one, so never describe this as a store export or a backup. **No KEV or EPSS data ships with the product**; `--kev` / `--epss` carry the operator's own downloads from CISA and FIRST, and `--extras-dir` places them on import and prints the environment lines to set. **A bundle is integrity-checked, NOT authenticated** — the recorded SHA-256 detects alteration in transit but cannot establish authorship, because it travels inside the archive it covers; never describe an imported bundle as trusted or verified-as-genuine. **Import skips about a quarter of a real NVD year file by design** (withdrawn CVEs, entries with no CPE match data) — that is not data loss, while malformed records are a different signal meaning re-download. The air-gap delivery claims are EARNED BACK at this release, every one of them as a **restricted** distribution and **amd64 only** — the offline installation tarball is restricted, the install script is restricted, the feed-import CLI moves the feeds you downloaded, and air-gapped deployment is restricted and amd64 only — because the artifacts exist and the delivery gate passes on the built bytes. Teach them WITH their conditions, which are part of the claim and not footnotes: the bundle is a **restricted** distribution rather than a public `npm install`, and it is **amd64** only. **arm64 images remain WITHDRAWN** — never describe an arm64 enclave as supported.
 >
@@ -176,7 +178,7 @@ These tools return a license upgrade prompt on CE installations:
 | `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). |
 | `get_findings` | Enterprise | Drill into the findings of the MOST RECENT `scan_cloud` scan — a per-provider, **per-session** cache (NOT live state; cleared when the MCP server restarts). Input: `{ scanId?, provider?, plugin?, severity?, category?, cursor?, limit? }`. Use it AFTER `scan_cloud` when the summary's **category rollup** shows a category you want to expand to specific resources, or when you need the FULL untruncated text of a finding. Pass the **`scanId` from the `scan_cloud` summary footer** + the `provider`; filter by `category`/`severity`/`plugin`; paginate with `cursor`/`limit` (server-capped at 20 — follow `nextCursor`). If you get a **"re-run scan_cloud"** error the cache was cleared or superseded — **re-run `scan_cloud`, do NOT retry `get_findings`**. CE/Pro callers get the same upgrade message as `scan_cloud`. |
 
-> **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`. **Beyond CRITICAL/HIGH, `findingsSummary[provider].rollup` lists the MEDIUM + LOW findings grouped by `category` with counts (count-descending) — these are actionable too: a category like `sqs-age-alarm-missing` or `*-public` is a real gap, not noise, and reporting only CRITICAL/HIGH while the rollup is non-empty is itself a false clean. To enumerate the specific resources behind a rollup category, or to read a finding's full untruncated text, call `get_findings` with the `scanId` from the summary footer + the `category`.**
+> **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`. **Beyond CRITICAL/HIGH, `findingsSummary[provider].rollup` groups the remaining findings by `category` with counts (count-descending) across **MEDIUM, LOW *and* INFO** — and the INFO tier is not optional reading, because that is where the evidence gaps and the deferred-scope boundaries live. ⚠️ This sentence said "MEDIUM + LOW" until EE 0.39.0, which was FALSE against the summariser's own three rollup buckets, and false in the direction that hides the tier a reader most needs. Report every tier that occurs; these are actionable too: a category like `sqs-age-alarm-missing` or `*-public` is a real gap, not noise, and reporting only CRITICAL/HIGH while the rollup is non-empty is itself a false clean. To enumerate the specific resources behind a rollup category, or to read a finding's full untruncated text, call `get_findings` with the `scanId` from the summary footer + the `category`.**
 
 > **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.
 
@@ -204,6 +206,36 @@ If a scan predates EE 0.32.9, its gap findings lead with a retired prefix that n
 anchor matches, so they route to no control — the engine detects this and warns. Advise a
 re-scan rather than reusing the old artifact.
 
+### Deferred scope — a declared boundary is neither a gap nor a finding (post EE 0.39.0)
+
+`findingsSummary[provider].deferredScope` lists surface this release does **not evaluate at all**.
+It is a **static capability boundary**, and all three of the following are load-bearing:
+
+- **It is NOT an evidence gap.** A gap means the scanner tried to read something and could not
+  (AccessDenied, truncated enumeration) — fixable with permissions. A deferred-scope entry means no
+  code was ever written to look. Never merge the two lists, and never suggest granting permissions
+  to close one.
+- **It is NOT a finding.** It routes to **ZERO** compliance controls by design, carries no severity
+  judgement about the estate, and must never be reported under "issues found" or counted as a
+  failure. Report it as **"not assessed"**.
+- **It is emitted even over an EMPTY estate**, deliberately: an account with no resources yields
+  zero findings whether or not anything was examined, so the declaration is the only thing that
+  tells those two apart.
+
+⚠️ **AN EMPTY OR SHORT `deferredScope` IS NEVER A CLAIM OF FULL COVERAGE.** Not every plugin
+declares its boundaries, so the list bounds only what the **declaring** plugins state — it is not a
+coverage inventory. Where the list is empty or short, say plainly that boundaries are declared
+per-plugin and this is not an inventory. **Never tell a user that an empty list means everything was
+assessed.** State this as a per-plugin invariant, never as a provider roster: a roster sentence goes
+stale on the next Enterprise release, which is exactly why the CE tool description stopped carrying
+one at CE 0.2.44.
+
+Since EE 0.39.0 all three clouds declare: AWS through nine emitters, Azure through four (1022, 1220,
+1221, 1222) and GCP through three (1021, 1024, 1025). Before that release only AWS declared, and the
+asymmetry was itself the hazard — **one provider disclosing is what makes another's silence read as
+completeness.** The AWS declarations are also now emitted once per RUN rather than once per region,
+so the count no longer scales with the estate and no entry is region-stamped.
+
 ### Cross-framework routing — cite the engine, do NOT freehand-map (post EE 0.32.7)
 
 When a user asks which controls a finding maps to, **read it from the engine's compliance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai-agent-skill",
-  "version": "0.2.41",
+  "version": "0.2.42",
   "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",
@@ -48,7 +48,7 @@
     "examples/"
   ],
   "peerDependencies": {
-    "nsauditor-ai": ">=0.1.40"
+    "nsauditor-ai": ">=0.2.43"
   },
   "peerDependenciesMeta": {
     "nsauditor-ai": {

package/references/plugins.md

@@ -126,7 +126,13 @@ LLMNR poisoning risk).
 
 ---
 
-## Pro Plugins (3)
+## Local-Surface Plugins (1)
+
+| ID | Name | Protocol | Purpose |
+|----|------|----------|---------|
+| 070 | MCP Scanner | local | Detects Model Context Protocol servers reachable from the host and audits their exposure. Community tier; requires host: up. |
+
+## Deep-Audit Plugins (3) — Community tier
 
 | ID | Name | Ports | Purpose |
 |----|------|-------|---------|
@@ -134,7 +140,7 @@ LLMNR poisoning risk).
 | 050 | TRIBE v2 Probe | 80, 443 | Detect debug info leaks, stack traces, verbose errors, CORS misconfig |
 | 060 | DNS Security Auditor | 53 | SPF/DKIM/DMARC validation, DNSSEC, zone transfer, MX security, CAA |
 
-### Pro Plugin Details
+### Deep-Audit Plugin Details
 
 **040 — TLS Certificate & Cipher Auditor:** Goes beyond the basic TLS Scanner (011)
 with full certificate chain validation, expiration warnings, and a comprehensive weak