nsauditor-ai-agent-skill 0.2.53 → 0.2.55

package/README.md

@@ -13,7 +13,11 @@ Works with **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **VS C
 
 ## Current release
 
-**0.2.53** — paired with **Enterprise 1.1.0 / Community 0.2.55**. ⚠️ **A floor bump: requires Community >= 0.2.55** (it was >= 0.2.49 — Enterprise 1.1.0 calls code that first ships in Community 0.2.55). The skill now INSTALLS itself: `npx nsauditor-ai-agent-skill install` copies it into `~/.claude/skills/` for Claude Code, and `npx nsauditor-ai-agent-skill build-zip --out ~/Desktop` builds the Claude Desktop upload zip. Claude Code users can instead add it as a plugin marketplace — `/plugin marketplace add nsasoft/nsauditor-ai-agent-skill`. ⚠️ A marketplace reaches **Claude Code only**; Claude Desktop accepts skills only as an uploaded zip, and skills do not sync between surfaces. Knowledge updated for the Pro cross-run delta (`report --since`) that ships in Community 0.2.55.
+**0.2.55** (2026-10-07) — paired with **Enterprise 1.3.0 / Community 0.2.57**. ⚠️ **A floor bump: requires Community >= 0.2.57** (it was >= 0.2.56 — Enterprise 1.3.0 imports names that first ship in Community 0.2.57; below it Enterprise's core does not load while its plugins still do — on Community 0.2.56 as on 0.2.55 — so the scan skips its intelligence, analysis-agent and compliance stages: Community 0.2.56 names that on stderr, and 0.2.55 or older says nothing, the shape measured for Enterprise 1.2.0 and 1.3.0). New in this release's teaching: the not-comparable bucket also catches a CVE-mapper or service-agent row on a TCP port whose service the other run could not identify, and an analysis agent's or the CVE mapper's row when a plugin it reads was left out of a scan; after a CVE lookup that failed, the controls the prior CVE rows failed are now held failed; the exposure and service agents' titles moved, so their rows read `identity-basis-changed` across the upgrade; the DNS-posture audit (060) declines an IP-address target; the TLS certificate audit (040) grades an IP target's DNS-only name mismatch LOW and reads IP SANs; and two measured limits — a scan made before Enterprise 1.3.0 could not record a plugin left out of it, so in a comparison with one an agent's row that scan lacks is not refused; and a scan that discovered ports with the Nmap plugin (024) alone records no port oracle, so an analysis agent's or the CVE mapper's row on a port it did not measure can read RESOLVED and count as closed in MTTR, and the control it failed can read PASS — include the port scanner (003). See [CHANGELOG.md](https://github.com/nsasoft/nsauditor-ai-agent-skill/blob/main/CHANGELOG.md).
+
+**Prior: 0.2.54** (2026-10-04) — paired with **Enterprise 1.2.0 / Community 0.2.56**. ⚠️ **A floor bump: requires Community >= 0.2.56** (Enterprise 1.2.0 imports names that first ship in Community 0.2.56). Its teaching — the not-comparable cases, the compliance hold on a prior finding, how a failed Enterprise load surfaces — is carried forward above; of its two measured limits, 0.2.55 teaches the first closed and the second narrowed.
+
+**Prior: 0.2.53** — paired with **Enterprise 1.1.0 / Community 0.2.55**. ⚠️ **A floor bump: requires Community >= 0.2.55** (it was >= 0.2.49 — Enterprise 1.1.0 calls code that first ships in Community 0.2.55). The skill now INSTALLS itself: `npx nsauditor-ai-agent-skill install` copies it into `~/.claude/skills/` for Claude Code, and `npx nsauditor-ai-agent-skill build-zip --out ~/Desktop` builds the Claude Desktop upload zip. Claude Code users can instead add it as a plugin marketplace — `/plugin marketplace add nsasoft/nsauditor-ai-agent-skill`. ⚠️ A marketplace reaches **Claude Code only**; Claude Desktop accepts skills only as an uploaded zip, and skills do not sync between surfaces. Knowledge updated for the Pro cross-run delta (`report --since`) that ships in Community 0.2.55.
 
 **Prior: 0.2.52** — paired with **Enterprise 1.0.0 / Community 0.2.54** (Community is a README-only release). ⚠️ **NOT a floor bump: Community stays >= 0.2.49.** Plugin enumeration unchanged at 29 Enterprise plugins; all eight coverage matrices unchanged. New in this release's teaching: `Findings analyzed` counts findings rather than issues, so a 1.0.0 pack reads a SMALLER number than a 0.46.0 pack over the same estate and that is the correction — the new `report.summary.findingsReceived` / `findingsRouted` fields let an agent check `findingsRouted ≤ findingCount ≤ findingsReceived` from the pack alone; an Azure RBAC assignment at the root scope (`/`) is named as such; PCI DSS `11.5.2` is critical-file change detection (the payment-page controls are `11.6.1` and `6.4.3`). No tool surface changed. The evidence contract in Enterprise's `docs/contract-v1.md` is binding from EE 1.0.0. See [CHANGELOG.md](https://github.com/nsasoft/nsauditor-ai-agent-skill/blob/main/CHANGELOG.md).
 
@@ -109,6 +113,10 @@ nsauditor-ai-agent-skill/
 │   └── plugins.md                    # Full plugin catalog (56 scanners with ports & protocols — 27 Community + 29 Enterprise)
 ├── examples/
 │   └── agent-interactions.md         # Example agent reasoning chains (9 scenarios)
+├── bin/
+│   └── nsauditor-ai-agent-skill.mjs  # `install` (Claude Code) and `build-zip` (Claude Desktop)
+├── scripts/                          # the Desktop zip builder and its frontmatter check
+├── .claude-plugin/                   # plugin-marketplace manifests (Claude Code only)
 ├── package.json
 ├── README.md
 └── LICENSE
@@ -119,19 +127,18 @@ nsauditor-ai-agent-skill/
 ### Claude Code
 
 ```bash
-# Option 1: Install globally and copy
-npm install -g nsauditor-ai-agent-skill
-cp -r $(npm root -g)/nsauditor-ai-agent-skill ~/.claude/skills/nsauditor-ai
+# Into ~/.claude/skills/nsauditor-ai — creates the folder, or overwrites SKILL.md and references/ in an older copy
+npx nsauditor-ai-agent-skill@latest install
 
-# Option 2: Copy into your project
-cp -r nsauditor-ai-agent-skill .claude/skills/nsauditor-ai
+# Or into one project: .claude/skills/nsauditor-ai
+npx nsauditor-ai-agent-skill@latest install --dest .claude/skills
 ```
 
-Claude Code auto-discovers skills in `.claude/skills/`.
+Keep `@latest` (or name a version): a bare `npx nsauditor-ai-agent-skill` runs a copy already installed in the project or globally whenever one exists, whatever its version. `install` overwrites only the files this version ships; it deletes nothing. Copying the package by hand with `cp -r` fails when `~/.claude/skills` does not exist yet, and over an existing `nsauditor-ai` folder it nests the new copy inside it and leaves the old `SKILL.md` in place — delete the old folder first. Claude Code auto-discovers skills in `.claude/skills/`.
 
 ### Claude Desktop
 
-Build the upload zip with `npx nsauditor-ai-agent-skill build-zip --out ~/Desktop`, then upload that `nsauditor-ai-skill-<version>.zip` in Claude Desktop's Settings (skills). Upload the zip, never `SKILL.md` alone: SKILL.md is under half of the skill, and its links to the reference files would point at nothing. Fully quit and relaunch Desktop after replacing a skill.
+Build the upload zip with `npx nsauditor-ai-agent-skill@latest build-zip --out ~/Desktop`, then upload that `nsauditor-ai-skill-<version>.zip` in Claude Desktop's Settings (skills). Upload the zip, never `SKILL.md` alone: SKILL.md is under half of the skill, and its links to the reference files would point at nothing. Fully quit and relaunch Desktop after replacing a skill.
 
 ### Cursor
 
@@ -148,9 +155,8 @@ Add `SKILL.md` to `.github/copilot-instructions.md` or your workspace's Copilot
 ### Generic / Custom Agents
 
 ```bash
-npm install nsauditor-ai-agent-skill
-# Copy into wherever your agent loads skills/context from
-cp -r node_modules/nsauditor-ai-agent-skill /path/to/agent/skills/nsauditor-ai
+# Copies SKILL.md and references/ into /path/to/agent/skills/nsauditor-ai
+npx nsauditor-ai-agent-skill@latest install --dest /path/to/agent/skills
 ```
 
 ## What the Agent Learns
@@ -175,23 +181,27 @@ When an AI agent loads this skill, it gains:
 This package provides **knowledge about** NSAuditor AI. To actually **run** scans:
 
 1. **Install NSAuditor AI:** `npm install -g nsauditor-ai`
-2. **Start MCP server:** `nsauditor-ai-mcp` (or configure in your agent's MCP settings)
+2. **Start MCP server:** your agent starts `nsauditor-ai-mcp` (a stdio server) itself, from the settings in step 3;
+   run it by hand only with `NSA_MCP_AUTH_KEY` set (see the warning below)
 3. **Add MCP to your agent:**
    ```bash
    # Claude Code
-   claude mcp add nsauditor-ai -- npx nsauditor-ai-mcp
+   nsauditor-ai mcp install-key
+   claude mcp add nsauditor-ai --env NSA_MCP_AUTH_KEY=<from: nsauditor-ai mcp install-key> -- nsauditor-ai-mcp
 
-   # Claude Desktop (claude_desktop_config.json)
+   # Claude Desktop (claude_desktop_config.json): paste the block `install-key` prints, which names
+   # node and the server script by absolute path, and add NSA_ALLOW_ALL_HOSTS to its env
    {
      "mcpServers": {
        "nsauditor-ai": {
-         "command": "npx",
-         "args": ["-y", "nsauditor-ai-mcp"],
+         "command": "<from: nsauditor-ai mcp install-key — the absolute path to node>",
+         "args": ["<from: nsauditor-ai mcp install-key — the absolute path to bin/nsauditor-ai-mcp.mjs>"],
          "env": { "NSA_ALLOW_ALL_HOSTS": "1", "NSA_MCP_AUTH_KEY": "<from: nsauditor-ai mcp install-key>" }
        }
      }
    }
    ```
+   `NSA_ALLOW_ALL_HOSTS: "1"` lets Claude scan your own network — private addresses such as `192.168.x.x` or `10.x.x.x`. It admits private ranges only (RFC 1918, CGNAT `100.64/10`, `fc00::/7`): the server still refuses loopback, link-local and cloud-metadata addresses in any spelling, whether written as the host or returned for a host name — every answer is checked. Only `1`, `true`, `yes` or `on` turn it on. The check does not pin the answer, so a name whose answer changes between the check and the scan (DNS rebinding) is not caught. `install-key` does not print it, so add it yourself, and remove it if you only scan public hosts.
 
 > ⚠️ **`NSA_MCP_AUTH_KEY` is REQUIRED — the server refuses to start without it.** Generate one with
 > `nsauditor-ai mcp install-key`, then put the SAME value in the `env` block above. Without it the MCP