nsauditor-ai-agent-skill 0.2.33 → 0.2.34
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +48 -1
- package/README.md +6 -1
- package/SKILL.md +64 -176
- package/package.json +1 -1
- package/references/plugins.md +7 -7
- package/references/schemas.md +10 -4
- package/references/workflows.md +7 -5
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,53 @@ Release notes for **`nsauditor-ai-agent-skill`** — installable knowledge packa
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## 0.2.34 (2026-08-05) — Paired with EE 0.32.11 · a withdrawn capability, and SEVEN MCP tools that do not exist
|
|
8
|
+
|
|
9
|
+
### The tools that were never there
|
|
10
|
+
|
|
11
|
+
Found by Gate-3 prompt 6, in a live reply. Asked how to build a SOC 2 Type II evidence package, the assistant answered: *"`scan_compare` (Pro) gives risk-weighted deltas between runs, which is how you show a finding appeared, was remediated, and stayed closed."*
|
|
12
|
+
|
|
13
|
+
**`scan_compare` does not exist.** Measured against the live registry, SEVEN tools this package advertised return 0 entries in `TOOLS` and `undefined` from `toolHandlers`:
|
|
14
|
+
|
|
15
|
+
`risk_summary` · `scan_compare` · `save_finding` · `start_assessment` · `prioritize_risks` · `compliance_check` · `export_report`
|
|
16
|
+
|
|
17
|
+
The shipped set is exactly `scan_host`, `scan_cloud`, `get_findings`, `compliance_matrix`, `probe_service`, `get_vulnerabilities`, `list_plugins`.
|
|
18
|
+
|
|
19
|
+
**And the seven are not one class — a correction to this entry's first draft.** Four (`compliance_check`, `export_report`, `start_assessment`, `prioritize_risks`) have **no implementation anywhere**: `registerEnterpriseTools()` is an empty no-op. Three (`risk_summary`, `scan_compare`, `save_finding`) are **implemented but UNREACHABLE** — real handlers and real tests exist in EE's `PRO_MCP_TOOLS`, but `registerProTools()` has **zero non-test call sites**, so nothing ever registers them. Either way the skill must not advertise them, but the fixes differ: the first four need building or forgetting; the last three need WIRING, and are on the EE board as such.
|
|
20
|
+
|
|
21
|
+
`compliance_check` was the worst: it appeared **4 times in `SKILL.md` and 13 times across the package**, including a behavioural imperative — *"If unsure, run `compliance_check` and report what the pack says."* *(An earlier draft of this entry said "11 occurrences"; that figure was wrong and is corrected here — counted, not remembered.)* An agent loads this file into context and follows its imperatives, so an operator assembling the artifact an auditor SAMPLES was being routed at a tool that is not there. `export_report` promised "PDF, HTML" — the same phantom as the `pdfExport` capability flag EE withdrew this cycle, wearing a different name.
|
|
22
|
+
|
|
23
|
+
**The correction is not a deletion.** `compliance_check`'s row carried a great deal of accurate framework detail; what was wrong was the MECHANISM it hung on. Compliance is a **CLI** surface: `nsauditor-ai scan --host <target> --compliance <fw> --out <dir>` runs the compliance phase and writes the pack. `scan_cloud` maps findings to frameworks but never runs that phase, so **no MCP call produces a pack**. The detail is kept and re-attributed; use `compliance_matrix` to state COVERAGE and the CLI to produce EVIDENCE.
|
|
24
|
+
|
|
25
|
+
**`compliance_matrix` is now documented** — it shipped in CE 0.2.36 and this package had never mentioned it, which is the other direction of the same defect: a tool an agent is not told about is a tool it will not reach for.
|
|
26
|
+
|
|
27
|
+
### Why nothing caught it, and what now does
|
|
28
|
+
|
|
29
|
+
`gate:claims` sweeps for withdrawn capability WORDING. **A tool NAME matches no claim pattern** — it is a claim that exists only as an identifier, exactly like the withdrawn capability flags. EE now ships `tests/agent_skill_tool_surface.test.mjs`, which pins this package's advertised tool set against CE's live `TOOLS` **in both directions** (advertised-but-absent, and shipped-but-undocumented), fails rather than skips when the sibling repo is missing, and proves its own extractor on a probe. Both directions are mutation-proven.
|
|
30
|
+
|
|
31
|
+
> The sweep that first found this was itself too narrow — it enumerated the name prefixes already seen and so missed `start_assessment` and `prioritize_risks`. The guard therefore extracts the documentation STRUCTURALLY rather than grepping for tool-shaped words.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 0.2.34 — also: a withdrawn capability was still being taught, in the one repo no gate reached
|
|
36
|
+
|
|
37
|
+
**This is a correction release, and the reason it was needed matters more than the two lines it fixes.**
|
|
38
|
+
|
|
39
|
+
The Verification Engine was **withdrawn at EE 0.32.7**. This package went on presenting it as a shipped pipeline phase for four releases:
|
|
40
|
+
|
|
41
|
+
- `SKILL.md` showed WITHDRAWN Phase-4 text — *"For each finding: run SAFE non-destructive verification probe"* — as a phase that runs.
|
|
42
|
+
- `references/schemas.md` glossed `VERIFIED` with the WITHDRAWN wording *"Active safe probe confirmed the vulnerability."*
|
|
43
|
+
- A safety bullet asserted the WITHDRAWN claim *"All verification probes are safe read-only queries."*
|
|
44
|
+
- **The pricing table sold the WITHDRAWN "verification probes" as a Pro feature.**
|
|
45
|
+
|
|
46
|
+
All four are corrected. The status ENUM stays — the field and its risk-weighting scaffolding are real, which is why the schema documents them — but the gloss describing an active probe is WITHDRAWN, and every finding is now stated to be emitted `UNVERIFIED`. `Phase 4` remains in the diagram, labelled **planned, not shipped**, so the pipeline's shape stays legible without claiming the phase runs.
|
|
47
|
+
|
|
48
|
+
**Why nothing caught it.** The withdrawal was executed as a capability-FLAG removal plus README edits, so the *wording* was never patterned — and `gate:claims` sweeps web document roots while the honesty test is scoped to six hand-listed docs. This package is a third repo, published with every trio, outside both. It was found by a reader during the Gate-3 battery, not by any matcher.
|
|
49
|
+
|
|
50
|
+
**The durable fix, upstream:** EE 0.32.11 adds a `verification-engine` claim pattern and this repo is now swept by `gate:claims`. On its first run that pattern also found **two live unhedged claims on nsasoft.us**, including the homepage hero — so the gap was never only about this package.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
7
54
|
## 0.2.33 (2026-08-03) — Paired with EE 0.32.10 · no knowledge change, one honesty correction upstream
|
|
8
55
|
|
|
9
56
|
**No change to the skill's guidance, schemas, or plugin references.** Published in lockstep with Enterprise 0.32.10 and CE 0.2.35 so an agent installing the trio never mixes versions.
|
|
@@ -20,7 +67,7 @@ Paired EE 0.32.9 highlights: the evidence pack no longer carries internal roadma
|
|
|
20
67
|
|
|
21
68
|
## 0.2.31 (2026-07-28) — paired content bump for EE 0.32.8 (capability-claim honesty pass, part 2: the air-gapped-delivery class)
|
|
22
69
|
|
|
23
|
-
- **Two corrections in this package's own tier tables — both were overclaims this skill would otherwise teach an agent to repeat.** `SKILL.md` line 524 listed **"RFC 3161 timestamps"** unhedged among shipping Enterprise capabilities; RFC 3161 timestamping is *implemented but not yet wired to a flag*, so the row now says so explicitly and directs readers not to quote it as shipping. **SHA-256 chain-of-custody is the layer that ships.** Both `SKILL.md` and `README.md` also said **"air-gapped deployment"**, which implied a delivery mechanism that does not exist; both now say **"air-gapped operation (offline licensing + offline CVE matching under `NSAUDITOR_OFFLINE_ONLY=1`)"**.
|
|
70
|
+
- **Two corrections in this package's own tier tables — both were overclaims this skill would otherwise teach an agent to repeat.** `SKILL.md` line 524 listed **"RFC 3161 timestamps"** unhedged among shipping Enterprise capabilities; RFC 3161 timestamping is *implemented but not yet wired to a flag*, so the row now says so explicitly and directs readers not to quote it as shipping. **SHA-256 chain-of-custody is the layer that ships.** Both `SKILL.md` and `README.md` also said the now-WITHDRAWN **"air-gapped deployment"**, which implied a delivery mechanism that does not exist; both now say **"air-gapped operation (offline licensing + offline CVE matching under `NSAUDITOR_OFFLINE_ONLY=1`)"**.
|
|
24
71
|
- Version line updated to post-EE-0.32.8. Enterprise 0.32.8 is a documentation-and-prose release: **27 withdrawn-claim sites** (distinct lines) across the three published packages, each verified against the code — an arm64 image (the build forces `--platform linux/amd64`), offline-installable tarballs (an `npm pack` tarball still resolves its dependencies from a registry), monthly NVD feed bundles (nothing produces one), an air-gapped installation script (none exists in the tree), a `feed import` CLI command (`importFeed()` has zero non-test callers), and CE's absolute "every feature works without internet access". **Five of the sites were rendered runtime strings, not documentation** — coverage-gap rationales that render verbatim into the assessor-facing evidence pack and named a command that does not exist.
|
|
25
72
|
- No MCP tool, plugin, schema or workflow change. `references/plugins.md` UNCHANGED. Plugin count UNCHANGED at 28; all seven coverage matrices UNCHANGED.
|
|
26
73
|
|
package/README.md
CHANGED
|
@@ -98,12 +98,17 @@ This package provides **knowledge about** NSAuditor AI. To actually **run** scan
|
|
|
98
98
|
"nsauditor-ai": {
|
|
99
99
|
"command": "npx",
|
|
100
100
|
"args": ["-y", "nsauditor-ai-mcp"],
|
|
101
|
-
"env": { "NSA_ALLOW_ALL_HOSTS": "1" }
|
|
101
|
+
"env": { "NSA_ALLOW_ALL_HOSTS": "1", "NSA_MCP_AUTH_KEY": "<from: nsauditor-ai mcp install-key>" }
|
|
102
102
|
}
|
|
103
103
|
}
|
|
104
104
|
}
|
|
105
105
|
```
|
|
106
106
|
|
|
107
|
+
> ⚠️ **`NSA_MCP_AUTH_KEY` is REQUIRED — the server refuses to start without it.** Generate one with
|
|
108
|
+
> `nsauditor-ai mcp install-key`, then put the SAME value in the `env` block above. Without it the MCP
|
|
109
|
+
> server exits at startup and the client shows the tools as unavailable. (`NSA_MCP_AUTH_DISABLE=1`
|
|
110
|
+
> exists as an escape hatch and warns on stderr; it is not the recommended path.)
|
|
111
|
+
|
|
107
112
|
## Editions
|
|
108
113
|
|
|
109
114
|
| Edition | Price | Highlights |
|
package/SKILL.md
CHANGED
|
@@ -16,7 +16,9 @@ description: >
|
|
|
16
16
|
|
|
17
17
|
# NSAuditor AI — Agent Skill
|
|
18
18
|
|
|
19
|
-
> **Version:** 0.2.
|
|
19
|
+
> **Version:** 0.2.34 (post-EE-0.32.11 — **a correction release.** The Verification Engine was WITHDRAWN at EE 0.32.7; this package went on presenting it as a shipped Phase 4, glossing `VERIFIED` as probe-confirmed, and selling "verification probes" in the pricing table. All corrected — the status enum stays, the active-probe gloss goes, and findings are stated to be emitted UNVERIFIED. Upstream: `scan_cloud` summaries now surface the INFO tier and `deferredScope` boundaries; a new `compliance_matrix` MCP tool returns the shipped coverage matrix for any of the seven frameworks, derived at call time; `pdfExport` withdrawn and every capability now ships a description. Plugin catalog UNCHANGED at 28 EE / 55 overall; all seven matrices UNCHANGED.)
|
|
20
|
+
|
|
21
|
+
> **Prior:** 0.2.33 (post-EE-0.32.10 — no knowledge change.)
|
|
20
22
|
|
|
21
23
|
> **Prior:** 0.2.32 (post-EE-0.32.9 — the skill package's own provenance sweep.)
|
|
22
24
|
|
|
@@ -59,6 +61,26 @@ order (discovery → service probes → OS detection → result fusion).
|
|
|
59
61
|
|
|
60
62
|
---
|
|
61
63
|
|
|
64
|
+
#### `compliance_matrix`
|
|
65
|
+
Return the SHIPPED compliance coverage matrix for a framework — how many controls are Covered, Partial and
|
|
66
|
+
Out of scope, with the control ids and the per-group out-of-scope reasons.
|
|
67
|
+
|
|
68
|
+
| Parameter | Type | Required | Description |
|
|
69
|
+
|-----------|------|----------|-------------|
|
|
70
|
+
| `framework` | string | ❌ | `soc2` \| `hipaa` \| `nist-csf` \| `pci-dss` \| `iso-27001` \| `cis-v8` \| `gdpr` \| `all` (default) |
|
|
71
|
+
|
|
72
|
+
**ALWAYS call this before stating or tabulating any coverage matrix, and quote what it returns.** Do NOT derive a
|
|
73
|
+
matrix from the plugin inventory, from a scan result, or from documentation — coverage is a property of the shipped
|
|
74
|
+
framework maps, not of the plugin list, and a derived matrix will disagree with the customer's own report.
|
|
75
|
+
|
|
76
|
+
⚠️ `outOfScope` is the **flattened sub-criterion count**, not the number of out-of-scope groups: SOC 2 returns 37
|
|
77
|
+
ids across 11 groups. Publishing the group count yields a plausible-looking 10 / 4 / 11.
|
|
78
|
+
|
|
79
|
+
It **fails closed** — if the Enterprise pack is not installed or its data is unreadable it raises rather than
|
|
80
|
+
returning an empty matrix, because an empty matrix is what gets filled in with a guess.
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
62
84
|
#### `list_plugins`
|
|
63
85
|
List all available scanner plugins with metadata.
|
|
64
86
|
|
|
@@ -139,9 +161,6 @@ These tools return a license upgrade prompt on CE installations:
|
|
|
139
161
|
|
|
140
162
|
| Tool | Tier | Purpose |
|
|
141
163
|
|------|------|---------|
|
|
142
|
-
| `risk_summary` | Pro | Prioritized risk overview with severity breakdown |
|
|
143
|
-
| `scan_compare` | Pro | Diff two scan results with risk-weighted delta analysis |
|
|
144
|
-
| `save_finding` | Pro | Persist a validated finding to the finding queue |
|
|
145
164
|
| `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). |
|
|
146
165
|
| `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`. |
|
|
147
166
|
|
|
@@ -150,10 +169,11 @@ These tools return a license upgrade prompt on CE installations:
|
|
|
150
169
|
> **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.
|
|
151
170
|
|
|
152
171
|
> **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.
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
172
|
+
> **⚠️ COMPLIANCE IS A CLI SURFACE, NOT AN MCP TOOL.** There is no `compliance_check` tool and there never was — the evidence pack is produced by `nsauditor-ai scan --host <target> --compliance <fw> --out <dir>`, which runs the compliance PHASE and writes `scan_compliance_<framework>.{json,md,html}` plus its attestation and chain-of-custody sidecars. `scan_cloud` maps findings to frameworks but **never runs that phase**, so no MCP call produces a pack. Use `compliance_matrix` to state COVERAGE (what is covered / partial / out of scope); use the CLI to produce EVIDENCE.
|
|
173
|
+
>
|
|
174
|
+
> The framework detail below is accurate and worth keeping — it was attached to a tool name that does not exist:
|
|
175
|
+
>
|
|
176
|
+
> 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) + **GDPR Article 32 (Security of Processing)** (sub-measure-level; Regulation (EU) 2016/679; **Art. 32 infrastructure substrate only, NOT GDPR compliance**) gap analysis — all seven 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; **GDPR Article 32 EE 0.20.0**). Multi-framework via `--compliance all` (shorthand for all seven frameworks; EE 0.31.4) or `--compliance soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr` (any CSV subset; aliases `nist`/`pci`/`iso`/`cis`); an unknown token **fails fast** (no "Framework load failed" stub). The hepta-framework one-scan produces seven complete auditor-ready evidence packs. **CIS Controls v8**: 17 covered + 23 partial + 113 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). **GRC push (Enterprise, opt-in):** set `COMPLIANCE_GRC_PROVIDER=vanta` (or `drata` / `secureframe`) + `COMPLIANCE_GRC_TOKEN` to map the findings to the platform's evidence/test records and push them at scan time (ZDE-redacted egress; token never serialized; the Vanta·Drata·Secureframe connector trio is complete — Secureframe records model, live tenant validation in progress).
|
|
157
177
|
|
|
158
178
|
### Evidence gaps — never read one as a pass (post EE 0.32.9)
|
|
159
179
|
|
|
@@ -175,7 +195,7 @@ re-scan rather than reusing the old artifact.
|
|
|
175
195
|
### Cross-framework routing — cite the engine, do NOT freehand-map (post EE 0.32.7)
|
|
176
196
|
|
|
177
197
|
When a user asks which controls a finding maps to, **read it from the engine's compliance
|
|
178
|
-
pack (
|
|
198
|
+
pack (the `scan_compliance_<framework>.json` artifact the CLI writes) — do not infer
|
|
179
199
|
a mapping from general security knowledge.** The engine deliberately routes some findings
|
|
180
200
|
*narrowly*, and a plausible-looking freehand mapping will overclaim. The non-obvious
|
|
181
201
|
dispositions to know:
|
|
@@ -195,8 +215,8 @@ dispositions to know:
|
|
|
195
215
|
**confirmed** cleartext channel fails HIPAA §164.312(e)(1), ISO A.8.24, NIST PR.DS-02,
|
|
196
216
|
CIS 3.10, PCI 4.2.1 and GDPR Art. 32(1)(a) as well as SOC 2 CC6.7.
|
|
197
217
|
|
|
198
|
-
If unsure,
|
|
199
|
-
mapping the engine did not emit.
|
|
218
|
+
If unsure, say the pack is what decides it and offer to run the CLI — never assert a control
|
|
219
|
+
mapping the engine did not emit, and never claim an MCP call produced a pack.
|
|
200
220
|
|
|
201
221
|
---
|
|
202
222
|
|
|
@@ -220,173 +240,34 @@ Phase 3: INTELLIGENCE (Pro) CPE generation → NVD CVE lookup → Parallel ve
|
|
|
220
240
|
• Service Agent (CVE-specific targeted probes)
|
|
221
241
|
Output: Structured finding queue
|
|
222
242
|
↓
|
|
223
|
-
Phase 4: VERIFICATION
|
|
224
|
-
|
|
225
|
-
|
|
243
|
+
Phase 4: VERIFICATION PLANNED — NOT SHIPPED. The finding-status field and its
|
|
244
|
+
(planned, not shipped) risk-weighting scaffolding exist; the active safe probes
|
|
245
|
+
do not. Every finding today is emitted UNVERIFIED.
|
|
226
246
|
↓
|
|
227
247
|
Phase 5: SCORING (Pro/Ent) Risk scoring → Pro AI prompts → Compliance mapping
|
|
228
|
-
Output: Risk report + compliance report
|
|
248
|
+
Output: Risk report + compliance report (Markdown, HTML, JSON)
|
|
229
249
|
```
|
|
230
250
|
|
|
251
|
+
> **Phase 4 is a roadmap entry, kept in the diagram so the pipeline's shape is legible.** The
|
|
252
|
+
> Verification Engine was withdrawn as a capability claim at EE 0.32.7. Do not describe
|
|
253
|
+
> findings as probe-confirmed (it is WITHDRAWN, not merely unused), and do not tell an
|
|
254
|
+
> operator a finding was "verified" — see
|
|
255
|
+
> `references/schemas.md` § Finding Statuses.
|
|
256
|
+
|
|
231
257
|
---
|
|
232
258
|
|
|
233
|
-
## Plugin Reference (
|
|
234
|
-
|
|
235
|
-
See `references/plugins.md` for the complete catalog. Summary:
|
|
236
|
-
|
|
237
|
-
**Core (17):** Ping, SSH, Port Scanner, FTP, Host Up, HTTP Probe, SNMP, Result Concluder,
|
|
238
|
-
DNS, Webapp Detector, TLS, OpenSearch, OS Detector, NetBIOS/SMB, SUN RPC, WS-Discovery,
|
|
239
|
-
TCP SYN (Nmap wrapper)
|
|
240
|
-
|
|
241
|
-
**Discovery (6):** ARP, mDNS/Bonjour, UPnP/SSDP, DNS-SD, LLMNR, DB Scanner
|
|
242
|
-
|
|
243
|
-
**Pro (3):** TLS Certificate & Cipher Auditor, TRIBE v2 Probe, DNS Security Auditor
|
|
244
|
-
|
|
245
|
-
**Enterprise (18):** AWS Cloud Scanner (1020), GCP Cloud Scanner (1021), Azure Cloud
|
|
246
|
-
Scanner (1022), Zero Trust Checker (1023), AWS IAM Deep Auditor (1030), AWS CloudTrail
|
|
247
|
-
Operational Integrity (1040), AWS API Gateway Assurance (1050), AWS DynamoDB Audit
|
|
248
|
-
Integrity (1060), AWS KMS Auditor (1070), AWS Lambda Security Auditor (1080), AWS
|
|
249
|
-
Secrets Manager + SSM Parameter Store Auditor (1090), AWS CodePipeline + CodeBuild
|
|
250
|
-
Operational Integrity (1100), AWS IAM Effective Decrypt-Path Auditor (1110), AWS S3
|
|
251
|
-
Lifecycle + Cross-Region Replication Auditor (1120), AWS Backup Auditor (1130), AWS
|
|
252
|
-
RDS Auditor (1140 v3 — extended in EE 0.4.8 with database audit-logging; 7→10 dims:
|
|
253
|
-
+pgAudit / +CloudWatch Logs exports / +CloudWatch Logs retention; aurora-aware
|
|
254
|
-
log-path detection per reviewer fold), AWS SQS/SNS Auditor (1150 v2 —
|
|
255
|
-
extended in EE 0.5.1: 5 → 7 dims with CloudWatch alarm coverage on SQS
|
|
256
|
-
ApproximateAgeOfOldestMessage + SNS NumberOfNotificationsFailed; closes 1 CRITICAL
|
|
257
|
-
false-CLEAN class on empty-AlarmActions silent-PASS per review fold; first
|
|
258
|
-
plugin-1150 dim to cross an SDK boundary — SQS+SNS → CloudWatch), AWS EC2
|
|
259
|
-
SG Perimeter Auditor (1170 v2 — RESTRICTED_PORTS 23 ports per CIS AWS Foundations
|
|
260
|
-
v3.0), AWS VPC Endpoints / PrivateLink Auditor (1160 — NEW in EE 0.6.0; first plugin
|
|
261
|
-
to audit the PrivateLink isolation boundary; 4 dims: endpoint policy permissive
|
|
262
|
-
principals CC6.6, PrivateDNS enabled CC6.6, endpoint state A1.2+CC7.2, type substrate
|
|
263
|
-
Privacy+CC6.6), AWS ElastiCache Redis Auditor (1180 v2 — extended in EE 0.4.9:
|
|
264
|
-
kms:DescribeKey promotion + subnet route-table verifier; closes both v1 deferred items
|
|
265
|
-
+ -2; main-RT-inheritance false-NEGATIVE closure per a review fold
|
|
266
|
-
reviewer-fold), AWS SES Email Integrity Auditor (1190 v3 — extended in EE 0.5.0 +
|
|
267
|
-
consolidated in EE 0.5.2 + v3 extension in EE 0.5.3: DKIM CNAME DNS resolution + DMARC
|
|
268
|
-
TXT record parser + SES classic API parity + deferred-items sweep + DKIM public-key
|
|
269
|
-
fingerprint capture/pin + in-band DMARC alignment classifier; closes 1 CRITICAL
|
|
270
|
-
false-CLEAN class on DMARC pct=0 per review fold + 1 HIGH false-NEGATIVE class
|
|
271
|
-
on DMARC sp subdomain-policy override per review fold + new MEDIUM
|
|
272
|
-
ses-dkim-dns-partial-with-transients per v2.1 review fold + silent-loss-class
|
|
273
|
-
closure on SES classic API quota exhaustion via cause: "classic-sdk-quota-exhausted"
|
|
274
|
-
per v2.1 reviewer fold; first plugin in EE to depend on node:dns/promises
|
|
275
|
-
for live DNS cross-reference), AWS Inspector2 / GuardDuty Enablement Auditor (1200 v6 —
|
|
276
|
-
NEW in EE 0.6.1, extended through EE 0.6.6; first AWS-managed-threat-detection
|
|
277
|
-
substrate audit; bundles two services per the plugin 1150 precedent.
|
|
278
|
-
**v4 EE 0.6.4 reviewer-cleanup cycle** (closes 3 of 4 R2-deferred items from
|
|
279
|
-
): **EventBridge target verification** — new `_listEventBridgeRuleTargets`
|
|
280
|
-
helper with defensive NextToken pagination; per-rule target verification via
|
|
281
|
-
`events:ListTargetsByRule` (cap default 10 via `opts.targetVerificationRuleCap`;
|
|
282
|
-
opt-out via `opts.skipEventBridgeTargetVerification`); new MEDIUM verdict
|
|
283
|
-
`*-alerting-destination-targetless` for sink-less rules (zero Targets — substrate-
|
|
284
|
-
without-sink at the rule level). **multi-failedAccount surface** —
|
|
285
|
-
helper return-shape `{accountStatus, accessDenied, failedAccounts: array}`
|
|
286
|
-
(renamed plural; capped at AWS-documented 100); caller emits one LOW per failed
|
|
287
|
-
account with per-region emission cap 10 + rollup LOW. **trigger
|
|
288
|
-
uniformity** — GuardDuty alerting-destination trigger gates on `detector.Status
|
|
289
|
-
=== ENABLED` (matches Inspector2 enabled-only semantic). **5 v4 R1 folds**
|
|
290
|
-
(0 ): cap-skew classifier branch (LOW UNVERIFIABLE not
|
|
291
|
-
MEDIUM TARGETLESS when cap-exceeded rules could be the actual sink) +
|
|
292
|
-
consolidated `_listEventBridgeRuleTargets` pagination + JSDoc clarity +
|
|
293
|
-
multi-failedAccount per-region emission cap (10 + rollup) +
|
|
294
|
-
boundary tests + dead-target documented-limitation note.
|
|
295
|
-
**v3 EE 0.6.3 alerting-destination dim preserved**: EventBridge rule on source
|
|
296
|
-
`aws.guardduty`/`aws.inspector2` OR SecurityHub product subscription (boundary-
|
|
297
|
-
anchored `_shArnMatchesProduct` helper + strict `/aws/inspector2` constant per
|
|
298
|
-
v3 -1); verdict tiers PASS / MEDIUM SH-only / MEDIUM TARGETLESS (v4
|
|
299
|
-
added) / HIGH missing / LOW UNVERIFIABLE; new SDK deps `@aws-sdk/client-eventbridge`
|
|
300
|
-
+ `@aws-sdk/client-securityhub`. **v2 EE 0.6.2 preserved**: multi-region via
|
|
301
|
-
ec2:DescribeRegions + GuardDuty FindingPublishingFrequency check + Inspector2
|
|
302
|
-
baseline expansion (+lambdaCode +codeRepository). Operator opts: `regions[]` /
|
|
303
|
-
`skipMultiRegion` / `regionListCap` / `gdFrequencyPassFrequency` /
|
|
304
|
-
`skipAlertingDestination` / `skipEventBridgeTargetVerification` /
|
|
305
|
-
`targetVerificationRuleCap` / `skipTargetLivenessProbe` / `deadTargetProbeTimeoutMs`.
|
|
306
|
-
**v5 EE 0.6.5 closes the 0.6.4 documented limitation** via per-target
|
|
307
|
-
liveness probes for Lambda (`lambda:GetFunction` on full qualified ARN — alias/
|
|
308
|
-
version correctness verified server-side) + SNS (`sns:GetTopicAttributes`) +
|
|
309
|
-
SQS (`sqs:GetQueueUrl` + `GetQueueAttributes` — partition-aware via SDK URL
|
|
310
|
-
resolution; works on aws-cn / aws-us-gov / aws-iso). Companion-LOW emitted
|
|
311
|
-
alongside PASS when targets dead. Parallel probes via Promise.all + 2s default
|
|
312
|
-
timeout. One-retry on NotFound with 750ms backoff (eventual-consistency defense).
|
|
313
|
-
Case-insensitive NotFound matching per the AWS string-case normalisation discipline.
|
|
314
|
-
Sentinel observability — `targetVerificationReason` enum (AccessDenied /
|
|
315
|
-
SdkUnavailable / BeyondCap / SkippedByOpts) on rule shape. R-NIT
|
|
316
|
-
`SH_HUB_NOT_ENABLED_ERROR_NAMES` frozen Set. **v6 EE 0.6.6 closes the long
|
|
317
|
-
tail of unverifiable ARN shapes**: IAM role (`iam:GetRole` on path-stripped role
|
|
318
|
-
NAME; new SDK dep `@aws-sdk/client-iam`) + EventBridge API destination
|
|
319
|
-
(`events:DescribeApiDestination` reuses `_EventBridgeSdk`) + CloudWatch Logs
|
|
320
|
-
(`logs:DescribeLogGroups` with `logGroupNamePrefix` filter + exact-name
|
|
321
|
-
disambiguation guard so prefix-match siblings don't false-LIVE; new SDK dep
|
|
322
|
-
`@aws-sdk/client-cloudwatch-logs`). **Operator note (v6 -2)**:
|
|
323
|
-
`iam:GetRole` is a global API resolving per-partition; orchestrators wiring
|
|
324
|
-
`opts._iamClient` must construct a single global IAM client per-partition (NOT
|
|
325
|
-
per-region). **v6 review fold**: IAM `NoSuchEntityException` /
|
|
326
|
-
`NoSuchEntity` lifted into `_DEAD_TARGET_NOTFOUND_ERROR_NAMES` Set; bare
|
|
327
|
-
disjunction collapsed; eventual-consistency retry restored for IAM (the canonical
|
|
328
|
-
worst case — 9th cumulative recurrence of the emit-literal/set-drift class class).
|
|
329
|
-
**v6 review fold**: API destination ARN regex future-proofed against alias-only
|
|
330
|
-
ARN shapes. **v6.1 EE 0.6.7 closes the Logs probe retry-on-empty parity**:
|
|
331
|
-
`_retryOnNotFound` accepts an optional retry-on-result predicate; CWL Logs probe
|
|
332
|
-
fires retry when the response carries no exact-name match (covers both empty
|
|
333
|
-
and prefix-only-sibling responses). **Restructured to two-phase to cap total
|
|
334
|
-
network calls at 2 on compound paths** — Phase 1 = initial call + thrown-
|
|
335
|
-
NotFound retry; Phase 2 = result-based retry; phases are mutually exclusive
|
|
336
|
-
(per-call-site outer catch routes a second-call thrown error). Existing call
|
|
337
|
-
sites (Lambda / SNS / SQS / IAM / EventBridge API destination) pass only two
|
|
338
|
-
args; default `retryOnResultPredicate = null` cleanly skips Phase 2. Dim 5
|
|
339
|
-
org-scope still deferred to a future cycle. Total folds across all cycles:
|
|
340
|
-
6 v1 + 4 v2 + 4 v3 (1 ) + 5 v4 + 5 v5 + 4 v6 (0 ) + 1 v6.1
|
|
341
|
-
(0 / 0 ) = 29 R1 folds applied same-session.
|
|
342
|
-
|
|
343
|
-
**v5 also brings a cross-plugin contract change**: all 18 EE AWS plugins
|
|
344
|
-
(1020-1200) now thread `sessionToken` through their AWS-SDK credentials block,
|
|
345
|
-
unblocking AssumeRole-style auditor credentials uniformly across the catalog).
|
|
346
|
-
**EE plugin IDs use the disjoint 1000+ range** (per EE 0.3.9 renumbering) to avoid
|
|
347
|
-
CE collision. CE reserves 001-099.
|
|
348
|
-
|
|
349
|
-
**Plugin 1170 v3 (EE 0.6.6) SG→SG transitive chain reachability** — `aws-ec2-sg-perimeter-auditor` v3 extension. Pre-v3 each Security Group was audited in isolation; a SG with no direct public-CIDR ingress would emit the PASS-tier "no direct public-internet ingress CIDR rules" finding even if transitively reachable from the internet through a `UserIdGroupPairs` chain. v3 builds the SG-reference graph (`_buildSgReferenceGraph`), identifies public-CIDR roots (`_findPubliclyReachableSgs` — 0.0.0.0/0 / ::/0 ingress), and BFS-walks the graph (`_walkTransitiveReachability`) with cycle defense + depth cap (default 5, max 20) + per-target chain cap (default 10, max 100). 2-hop chains emit **HIGH**; 3+ hop chains emit **CRITICAL** (operator-blindness principle — deeper chains less likely to be noticed). Cross-VPC edges skipped (out-of-scope for v3 v1; INFO trailer). v3 v1 simplification: per-hop port-flow tracked but NOT intersected (`walkthroughRequired=true`). New operator opts: `skipTransitiveReachability` / `transitiveChainDepthCap` / `transitiveChainsPerTargetCap` / `transitiveChainSamplesPerFindingCap`. **v3 review fold**: BFS short-circuits enqueue past per-target cap (closes path-enumeration explosion on hub-and-spoke topologies — pre-fold the BFS kept cloning `path` and `visited` Sets and walking past the cap). **v3 review fold**: depth-cap-hit surfaced separately from per-target-cap (closes silent-deep-truncation false-CLEAN class). 3 new soc2.json mappings under CC6.6 (transitive HIGH + CRITICAL + INFO truncation). **v3.1 EE 0.6.7 closes the edge-dedup R2-deferred item**: `_buildSgReferenceGraph` now dedupes edges by `(sourceGroupId, targetGroupId)` with `ports` aggregated as array of `{protocol, fromPort, toPort}`. Pre-fold a real-world ALB-fronting-app SG with 3 ingress perms on different ports (80/443/8080) referencing the same source SG emitted 3 distinct edges A→B; the BFS treated each as a separate chain, inflating `chainCount` 2-5× and exhausting per-target chain caps on noise. Post-fold the BFS sees exactly 1 chain per distinct (source, target) pair. `isCrossVpc` aggregation is AND-semantic — if ANY contributing pair is same-VPC, the merged edge is same-VPC (per the conservative-classifier principle: walk possibly-same-VPC chains rather than silently skip). Classifier port-render accepts both v3.1 array shape and v3 single-object shape (back-compat). **v3.1 review fold**: arrival-order independence locked with 2 regression fixtures + JSDoc tightening. **v3.1 review fold**: partial-render contract on malformed port specs locked with 2 fixtures. **v3.1 review fold**: `_portKeys` scratch-lifetime documented (MUST NOT escape).
|
|
350
|
-
|
|
351
|
-
**EE SOC 2 substrate-evidence coverage (post-EE 0.10.0):** 10 covered controls (CC6.1 /
|
|
352
|
-
CC6.2 / CC6.6 / CC6.7 / CC6.8 / CC7.1 / CC7.2 / CC7.3 / C1.1 / C1.2) + 4 partial
|
|
353
|
-
(CC6.3 / CC8.1 / A1.2 / PI1.5) + 33 OOS for static substrate scanning. **SOC 2 matrix
|
|
354
|
-
UNCHANGED post-EE 0.10.0 — the NIST CSF 2.0 cycle is additive-only; no SOC 2 mappings
|
|
355
|
-
changed. NIST CSF 2.0 introduced as third Track 3 framework with its own 13/10/83
|
|
356
|
-
matrix across 106 of CSF 2.0 Core's 107 Subcategories; Govern function OOS-by-design
|
|
357
|
-
with GV.SC-04 partial as substrate-evidence exception; Respond function OOS-entirely;
|
|
358
|
-
Implementation Tiers 1-4 OOS as organizational-maturity claim.**
|
|
359
|
-
Coverage matrix is institutionally honest: substrate-evidence depth grows release-over-release
|
|
360
|
-
without the matrix being shifted (the matrix-shift requires net-new control coverage, not just
|
|
361
|
-
more evidence on already-covered controls).
|
|
362
|
-
|
|
363
|
-
**EE HIPAA §164.312 Technical Safeguards substrate-evidence coverage (NEW EE 0.9.0):**
|
|
364
|
-
7 covered sub-criteria (§164.312(a)(1) Access Control, (a)(2)(i) Unique User ID,
|
|
365
|
-
(a)(2)(iv) Encryption-at-rest, (b) Audit Controls, (d) Person/Entity Auth, (e)(1)
|
|
366
|
-
Transmission Security, (e)(2)(ii) Transmission Encryption) + 3 partial (§164.312(c)(1)
|
|
367
|
-
Integrity — ransomware-defense substrate via Logically Air-Gapped Backup Vault
|
|
368
|
-
cross-verification, (c)(2) Mechanism to Authenticate ePHI, (e)(2)(i) Transmission
|
|
369
|
-
Integrity Controls) + 45 OOS (2 within-§164.312 + entire §164.308 Administrative
|
|
370
|
-
Safeguards [31 specs: workforce training, BAAs, contingency planning, etc.] + entire
|
|
371
|
-
§164.310 Physical Safeguards [12 specs: facility access, workstation security, device
|
|
372
|
-
disposal]). The §164.308 + §164.310 OOS sets are *architecturally* OOS for any
|
|
373
|
-
infrastructure scanner — pair with HIPAA-focused GRC platforms (Drata HIPAA, Vanta HIPAA,
|
|
374
|
-
Compliancy Group, Tugboat Logic) for those families. HHS Required vs Addressable
|
|
375
|
-
discipline surfaced per control. **Zero BAA required** — Zero Data Exfiltration
|
|
376
|
-
architecture means ePHI never leaves customer infrastructure. Use `--compliance hipaa`,
|
|
377
|
-
`--compliance soc2,hipaa` (CSV; wired since EE 0.3.0), or `--compliance all` (all seven
|
|
378
|
-
frameworks; EE 0.31.4) for HIPAA-only, dual-, or full-framework evidence packs from a
|
|
379
|
-
single scan. 175 mappings inherited from soc2.json's grep-verified
|
|
380
|
-
pattern set with HIPAA-grounded rationales. New `data/compliance/hipaa.json`. New
|
|
381
|
-
`docs/hipaa-coverage.md`. **EE regression: 5890/5890 across 928 suites; 69-session
|
|
382
|
-
100% green streak preserved.** AWS-dogfood verified against operator's test account
|
|
383
|
-
(207 findings, per-framework citation map confirmed firing, ransomware-substrate
|
|
384
|
-
surfaces correctly).
|
|
385
|
-
|
|
386
|
-
Execution order: Discovery (100–150) → Service probes (200–400) → OS Detector (99000) →
|
|
387
|
-
Result Concluder (100000). Plugins with unmet requirements auto-skip.
|
|
259
|
+
## Plugin Reference (55 scanners — 27 Community + 28 Enterprise)
|
|
388
260
|
|
|
389
|
-
|
|
261
|
+
**`references/plugins.md` is the authoritative catalog.** The counts above are derived from the
|
|
262
|
+
shipped plugin files; verify any of them with `nsauditor-ai license --plugins`, which prints the
|
|
263
|
+
live total and marks each Enterprise plugin `✓ active` or `✗ requires: <tier>`.
|
|
264
|
+
|
|
265
|
+
The Community set groups roughly as service probes, host/network discovery, and intelligence /
|
|
266
|
+
meta plugins; three further plugins are Pro-gated (040 TLS Certificate & Cipher Auditor, 050
|
|
267
|
+
TRIBE v2 Probe, 060 DNS Security Auditor).
|
|
268
|
+
|
|
269
|
+
> A per-plugin list used to be duplicated here and drifted: it claimed **18** Enterprise plugins
|
|
270
|
+
> while enumerating **15**, against **28** on disk. One catalog, in `references/plugins.md`.
|
|
390
271
|
|
|
391
272
|
## Workflow Recipes
|
|
392
273
|
|
|
@@ -413,8 +294,8 @@ User wants to...
|
|
|
413
294
|
├── Detect debug leaks / CORS issues → probe_service with plugin 050 (Pro)
|
|
414
295
|
├── Scan a subnet → CLI with --parallel (not MCP)
|
|
415
296
|
├── Set up continuous monitoring → CLI with --watch (not MCP)
|
|
416
|
-
├──
|
|
417
|
-
└──
|
|
297
|
+
├── State framework COVERAGE → compliance_matrix (any tier)
|
|
298
|
+
└── Produce a compliance EVIDENCE PACK → CLI with --compliance (not MCP)
|
|
418
299
|
```
|
|
419
300
|
|
|
420
301
|
---
|
|
@@ -456,8 +337,9 @@ See `references/schemas.md` for complete structures:
|
|
|
456
337
|
4. **Scan Authorization:** ALWAYS confirm the user has authorization to scan the target.
|
|
457
338
|
Never scan hosts without explicit user instruction. Unauthorized scanning is illegal.
|
|
458
339
|
|
|
459
|
-
5. **Non-Destructive:**
|
|
460
|
-
|
|
340
|
+
5. **Non-Destructive:** every scanner probe is a read-only query — NSAuditor AI never
|
|
341
|
+
exploits vulnerabilities or modifies target systems. (Active *verification* probes are
|
|
342
|
+
Planned — not shipped; findings are emitted UNVERIFIED.)
|
|
461
343
|
|
|
462
344
|
---
|
|
463
345
|
|
|
@@ -524,6 +406,7 @@ claude mcp add nsauditor-ai -- npx nsauditor-ai-mcp
|
|
|
524
406
|
"args": ["-y", "nsauditor-ai-mcp"],
|
|
525
407
|
"env": {
|
|
526
408
|
"NSA_ALLOW_ALL_HOSTS": "1",
|
|
409
|
+
"NSA_MCP_AUTH_KEY": "<from: nsauditor-ai mcp install-key>",
|
|
527
410
|
"PLUGIN_TIMEOUT_MS": "5000"
|
|
528
411
|
}
|
|
529
412
|
}
|
|
@@ -531,6 +414,11 @@ claude mcp add nsauditor-ai -- npx nsauditor-ai-mcp
|
|
|
531
414
|
}
|
|
532
415
|
```
|
|
533
416
|
|
|
417
|
+
> ⚠️ **`NSA_MCP_AUTH_KEY` is REQUIRED — the server refuses to start without it.** Generate one with
|
|
418
|
+
> `nsauditor-ai mcp install-key`, then put the SAME value in the `env` block above. Without it the MCP
|
|
419
|
+
> server exits at startup and the client shows the tools as unavailable. (`NSA_MCP_AUTH_DISABLE=1`
|
|
420
|
+
> exists as an escape hatch and warns on stderr; it is not the recommended path.)
|
|
421
|
+
|
|
534
422
|
**Cursor / Windsurf / VS Code:**
|
|
535
423
|
Add to your MCP configuration with the same command/args pattern.
|
|
536
424
|
|
|
@@ -541,7 +429,7 @@ Add to your MCP configuration with the same command/args pattern.
|
|
|
541
429
|
| Edition | Price | Key Features |
|
|
542
430
|
|---------|-------|-------------|
|
|
543
431
|
| **Community** | Free / MIT | 27 plugins (service probes + host/network discovery + intelligence/meta), basic AI, CTEM, SARIF, scan history |
|
|
544
|
-
| **Pro** | $49/mo | + CVE matching,
|
|
432
|
+
| **Pro** | $49/mo | + CVE matching, risk scoring, analysis agents, Pro plugins (040 TLS / 050 TRIBE / 060 DNS) |
|
|
545
433
|
| **Enterprise** | $2k+/yr | + 28 cloud-substrate auditor plugins (1020-1222 range) covering AWS / GCP / Azure against seven frameworks (SOC 2 10 covered + 4 partial; HIPAA; NIST CSF 2.0; PCI DSS v4.0.1; ISO/IEC 27001:2022; CIS Controls v8; GDPR Art. 32 infrastructure substrate); Zero Trust; SOC 2 evidence-pack generation; SHA-256 chain-of-custody attestations (RFC 3161 timestamping is implemented but not yet wired to a flag — do not quote it as shipping); air-gapped operation (offline licensing + offline CVE matching under `NSAUDITOR_OFFLINE_ONLY=1`) |
|
|
546
434
|
|
|
547
435
|
→ [Pricing](https://www.nsauditor.com/ai/pricing/)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nsauditor-ai-agent-skill",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.34",
|
|
4
4
|
"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.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"nsauditor",
|
package/references/plugins.md
CHANGED
|
@@ -97,8 +97,8 @@ stealthier than the TCP connect scanner (003).
|
|
|
97
97
|
| 026 | ARP Scanner | ARP | Layer 2 MAC resolution, OUI vendor lookup, OS hints from vendor |
|
|
98
98
|
| 027 | mDNS/Bonjour Scanner | mDNS | Local Bonjour/mDNS service discovery, friendly device names |
|
|
99
99
|
| 028 | UPnP/SSDP Scanner | SSDP | UPnP device discovery via SSDP, description XML parsing |
|
|
100
|
-
|
|
|
101
|
-
|
|
|
100
|
+
| 018 | DNS-SD Service Scanner | DNS-SD | DNS-based Service Discovery announcements |
|
|
101
|
+
| 017 | LLMNR Scanner | LLMNR | Link-local Multicast Name Resolution (Windows networks) |
|
|
102
102
|
|
|
103
103
|
### Discovery Plugin Details
|
|
104
104
|
|
|
@@ -117,10 +117,10 @@ and IoT devices broadcasting on the LAN.
|
|
|
117
117
|
**028 — UPnP/SSDP Scanner:** Sends M-SEARCH multicast to discover UPnP devices.
|
|
118
118
|
Parses device description XML for manufacturer, model, firmware version.
|
|
119
119
|
|
|
120
|
-
**
|
|
120
|
+
**018 — DNS-SD Service Scanner:** DNS-based Service Discovery. Enumerates `_services._dns-sd._udp`
|
|
121
121
|
zone to find advertised services.
|
|
122
122
|
|
|
123
|
-
**
|
|
123
|
+
**017 — LLMNR Scanner:** Link-Local Multicast Name Resolution. Detects Windows hosts
|
|
124
124
|
responding to LLMNR queries (useful for Windows network enumeration and detecting
|
|
125
125
|
LLMNR poisoning risk).
|
|
126
126
|
|
|
@@ -159,9 +159,9 @@ listings, and default pages.
|
|
|
159
159
|
|
|
160
160
|
---
|
|
161
161
|
|
|
162
|
-
## Enterprise Plugins (
|
|
162
|
+
## Enterprise Plugins (28)
|
|
163
163
|
|
|
164
|
-
> **EE plugin ID range.** As of EE 0.3.9 (2026-05-12), all EE plugins use the disjoint **1000+ ID range** to avoid CE collision. The earlier 020/021/022/023/030/040/050/060 IDs were renumbered to 1020/1021/1022/1023/1030/1040/1050/1060. CE reserves 001-099. EE plugins audit AWS / GCP / Azure cloud substrate end-to-end against **
|
|
164
|
+
> **EE plugin ID range.** As of EE 0.3.9 (2026-05-12), all EE plugins use the disjoint **1000+ ID range** to avoid CE collision. The earlier 020/021/022/023/030/040/050/060 IDs were renumbered to 1020/1021/1022/1023/1030/1040/1050/1060. CE reserves 001-099. EE plugins audit AWS / GCP / Azure cloud substrate end-to-end against **all seven shipped compliance frameworks** — SOC 2, HIPAA §164.312, NIST CSF 2.0, PCI DSS v4.0.1, ISO/IEC 27001:2022, CIS Controls v8 and GDPR Article 32 (Art. 32 infrastructure substrate only, NOT GDPR compliance). **The authoritative enumeration, with each framework's citation level and ship version, is in `SKILL.md` — it is not repeated here.** Each plugin's findings route to every one of the seven via the framework-agnostic engine plus a per-framework control-citation map, so a report cites only its own framework's ids (SOC 2 `CC6.1`, HIPAA `§164.312(a)(1)`, NIST `PR.AA-01`, PCI `Req 1.2.1`, ISO `A.8.24`, CIS `4.4`, GDPR `Art.32(1)(b)`) — closing cross-framework citation leak across every ordered pair of the seven. Every plugin is enterprise-gated by the `cloudScanners` capability and runs against customer-supplied cloud credentials. Multi-framework workflow: `--compliance all` (all seven), or any CSV subset such as `--compliance soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr` — one scan produces a separate, complete auditor-ready evidence pack per framework requested. **Zero BAA required** for HIPAA — Zero Data Exfiltration architecture means ePHI never leaves customer infrastructure (and CHD never leaves for PCI DSS CDE-isolation threat models). **NIST CSF 2.0 Implementation Tiers 1-4** (Partial / Risk-Informed / Repeatable / Adaptive) are organizational-maturity claims explicitly OOS for infrastructure scanning — surfaced in renderer as cover-page Tiers OOS disclaimer section (markdown + HTML parity); pair with NIST-aware GRC platforms (Tugboat Logic, Drata NIST CSF, Vanta NIST CSF, AuditBoard). **PCI DSS v4.0.1 specifics**: sub-requirement-level mapping for QSA Report on Compliance workflow (MVP-67 density: 67 of ~250 sub-requirements. **For the current covered/partial/OOS triple, call `compliance_matrix` with `framework: "pci-dss"`** — it derives from the shipped framework map at call time. A figure typed here goes stale: this sentence carried `20 + 8 + 39` against a shipped `19 / 9 / 39`, the same stale triple that had already propagated to a public page once). **Req 12 Information Security Program OOS-by-design entirely** (Targeted Risk Analysis Req 12.3.1 + Customized Approach Documentation Req 12.3.2 + TPSP Responsibility Matrix Req 12.8.5 + IR personnel training Req 12.10.4 all Defined-only per Appendix E). **Req 5 anti-malware + Req 9 physical OOS-entirely** (endpoint EDR + facility-tier). **Req 3 stored CHD OOS-by-design at technical-control layer** pending operator CDE attestation via CDE Data Flow Diagram per Req 1.2.4 + Req 12.5.1. **Defined-vs-Customized Approach discipline per Appendix E** — 15 Defined-only sub-requirements enforced at schema layer. CAO text MVP-deferred to EE 0.11.1 patch. **Card-brand AOC enforcement priority view** (Visa CISP / Mastercard SDP / Amex DSOP / Discover DISC — the actual penalty mechanism). Pair with PCI-aware GRC platforms (Drata PCI, Vanta PCI, AuditBoard PCI module, OneTrust GRC).
|
|
165
165
|
|
|
166
166
|
| ID | Name | Tier | Purpose | SOC 2 Controls |
|
|
167
167
|
|----|------|------|---------|----------------|
|
|
@@ -192,7 +192,7 @@ listings, and default pages.
|
|
|
192
192
|
| 1210 | AWS EC2 Instance Auditor (**NEW EE 0.13.1** — first new plugin since 1200; plugin count 24 → 25; the AWS producer for CIS-Hardened-Image detection + EC2 instance-level + EBS-encryption coverage) | Enterprise | Audits EC2 instances (orthogonal to plugin 1170 which audits the SG perimeter policy). **Multi-region** via ec2:DescribeRegions (single-region fallback emits an evidence-gap). Dimensions: **IMDSv1 enabled** (CC6.1 — MEDIUM when an IAM instance profile is attached / LOW without; **IMDSv2 hop-limit > 1** re-opens container credential theft) + **EBS volume unencrypted** (C1.1 + CIS 3.11 — HIGH; resolves every attached BlockDeviceMappings volume via DescribeVolumes) + **account default-EBS-encryption disabled** (C1.1 preventive — GetEbsEncryptionByDefault) + **public-IP exposure** incl. secondary-ENI/EIP + IPv6 GUA (CC6.6 substrate, INFO) + **instance-store (ephemeral) volume** evidence-gap. **DIM 4 — AMI inventory** → result.cisImageInventory (the producer feed that makes CIS-Hardened-Image detection LIVE on Safeguards 4.1/4.2/4.6; Azure 1022 + GCP 1021 feed the same contract). Conservative classifier: LOW + evidenceGap on indeterminate metadata; AccessDenied → INFO + evidenceGap (never silent-PASS); terminated/shutting-down instances skipped. Survived 3 review rounds / 5 adversarial skill lenses (network-security-audit + CIS + IAM-effective-permissions + soc2-evidence + cloud-plugin-false-negatives). `@aws-sdk/client-ec2` reused. | CC6.1 / C1.1 / CC6.6 |
|
|
193
193
|
| 1220 | Azure Storage Account Data-Protection Auditor (**NEW EE 0.13.2** — Move C-2; **+2 dims EE 0.13.3** — Move C-2.1; plugin count 25 → 26; first dedicated Azure auditor beyond the multi-purpose 1022 scanner) | Enterprise | Audits the Azure Storage Account data-protection surface across **7 dims** — **orthogonal to plugin 1022** which owns the network-exposure dims (no double-emission; mirrors the AWS 1020 S3-scanner + 1120 S3-lifecycle two-plugin split). (1) **HTTPS-only transit** (`enableHttpsTrafficOnly` — HIGH on plaintext HTTP; CC6.7) + (2) **minimum TLS version** (< TLS1_2 → MEDIUM; CC6.7) + (3) **Shared Key authorization** (`allowSharedKeyAccess` — bypasses Azure AD identity; CC6.1; Azure field-default discipline: absent = ENABLED, never silent-PASS) + (4) **infrastructure (double) encryption** (`requireInfrastructureEncryption`; C1.1) + (5) **encryption key source incl. CMK reachability + rotation** (`encryption.keyVaultProperties` — keySource=Microsoft.Keyvault PASS only when the key is currently resolvable + auto-rotating; a disabled/revoked/version-pinned CMK degrades, not silent-PASS; C1.1) + (6) **blob recoverability** (soft-delete + versioning via the secondary `blobServices.getServiceProperties` path — A1.2; EE 0.13.3) + (7) **per-container anonymous public access** (account-toggle-aware via `blobContainers.list` — `publicAccess=Blob/Container` + allowBlobPublicAccess=true → HIGH effective exposure; C1.1; EE 0.13.3). Conservative classifier: indeterminate field / AccessDenied / secondary-path failure → evidence-gap (never silent-PASS); `for await` pagination. Single-subscription scope surfaced explicitly. Built + reviewed through the cloud-plugin-false-negatives lens. `@azure/arm-storage` + `@azure/identity`. | CC6.7 / CC6.1 / C1.1 / A1.2 |
|
|
194
194
|
| 1221 | Azure NSG Perimeter Auditor (**NEW EE 0.14.0** — Move C-2.2; **UDP lane EE 0.14.1**; plugin count 26 → 27; the Azure analog of AWS plugin 1170) | Enterprise | A CC6.6 network-segmentation perimeter auditor for Azure Network Security Groups — **non-overlapping-by-depth with plugin 1022's flat per-rule NSG lint** (no double-emission of a verdict; mirrors the AWS 1023-observed / 1170-declared two-plugin precedent). Evaluates each NSG's inbound rules in **Azure priority order** (first match wins; DenyAllInbound default): (1) **all-protocol (`*`) public Allow** — every port reachable from the public internet + (2) **public-source (`*`/`0.0.0.0/0`/`Internet`) to a restricted TCP port** (SSH/RDP/MSSQL/MySQL/Postgres/Redis/Memcached/MongoDB/Elasticsearch/CouchDB/SMB/WinRM/Oracle/Docker/Kubelet) + (3) **`::/0` IPv6-wildcard to a restricted port** (the dimension 1022's flat lint misses) + **(2u/3u) public-source / `::/0` to a restricted UDP service** (DNS/TFTP/rpcbind/NTP/NetBIOS/SNMP/CLDAP/IKE/Syslog/IPMI/OpenVPN/MSSQL-Monitor/SSDP/IPsec-NAT-T/Memcached — closes the public-UDP false negative, **EE 0.14.1**) + (4) **public→non-restricted port** INFO substrate + (5) **PASS substrate** when no public restricted exposure. **Attachment-aware severity** via the read-only `nsg.subnets[]`/`networkInterfaces[]` back-references — attached → CRITICAL (effective exposure); orphaned → MEDIUM (latent). Per-transport effective priority/deny-override resolution + port-range expansion + `0.0.0.0/1` split-range coverage + service-tag/ASG-source normalization (VirtualNetwork/AzureLoadBalancer/ASG = not public). Conservative classifier: denied/indeterminate listAll → evidence-gap; one malformed NSG degrades per-resource (never aborts the scan); `for await` pagination; single-subscription scope explicit. Built + reviewed through the cloud-plugin-false-negatives lens (EE 0.14.0 SHIP-WITH-FOLDS 2 LOW; EE 0.14.1 UDP lane SHIP-WITH-FOLDS 2 MED + 1 LOW, all folded). `@azure/arm-network` + `@azure/identity`. | CC6.6 |
|
|
195
|
-
| 1222 | Azure Key Vault Deep Auditor (**NEW EE 0.15.0** — Move C-2.3; plugin count 27 → 28; the third dedicated Azure auditor after 1220 storage + 1221 NSG; **hotfixed EE 0.15.1** — Dim-3 SDK-shape + Dim-4 inherited-admin severity re-tune) | Enterprise | The deep Key Vault auditor — the KV analog of how 1221 deepens 1022's flat NSG dim; **orthogonal to plugin 1022's vault-property dims** (purge/soft-delete/network-ACL/RBAC-mode) — no double-emission of a verdict. Enumerates each vault's **keys, role assignments, and diagnostic settings** across 4 dims: (1) key **auto-rotation policy** — keys with no `rotationPolicy` / no rotate-action → finding + (2) key **expiry** — keys with no `expires` (or already-expired), with epoch-s/ms/Date/string coercion (closes the ms-overflow false-clean) + (3) **diagnostic logging → Log Analytics** — vaults with no `AuditEvent`→workspace diagnostic setting; reads `@azure/arm-monitor`'s `diagnosticSettings.list()` correctly as an `await`-ed `{value:[]}` collection object (NOT a paged async-iterator — the EE 0.15.1 H-1 fix; pre-fix the dim always threw and degraded to a non-functional evidence-gap), soft-degrades to an evidence-gap if the SDK is absent + (4) **privileged-access depth** — RBAC `roleAssignments` (admin/data-plane/**scope-aware severity**: vault-scoped control-plane god roles + Key Vault Administrator at any scope → HIGH; inherited subscription/management-group-scope Owner/User-Access-Administrator → MEDIUM, inherited Contributor → LOW — the EE 0.15.1 H-2 re-tune that stops flagging the ubiquitous inherited-admin reality as HIGH on every RBAC vault) + legacy `accessPolicies` breadth (export + wide-crypto permissions). **Secret/cert expiry is a deliberate data-plane scope boundary** (explicit caveat — the control-plane mgmt API does not expose data-plane object expiry). Conservative classifier: indeterminate field / AccessDenied / arm-monitor absent → evidence-gap; one malformed vault degrades per-resource (never aborts the scan); single-subscription scope explicit. Findings route across all
|
|
195
|
+
| 1222 | Azure Key Vault Deep Auditor (**NEW EE 0.15.0** — Move C-2.3; plugin count 27 → 28; the third dedicated Azure auditor after 1220 storage + 1221 NSG; **hotfixed EE 0.15.1** — Dim-3 SDK-shape + Dim-4 inherited-admin severity re-tune) | Enterprise | The deep Key Vault auditor — the KV analog of how 1221 deepens 1022's flat NSG dim; **orthogonal to plugin 1022's vault-property dims** (purge/soft-delete/network-ACL/RBAC-mode) — no double-emission of a verdict. Enumerates each vault's **keys, role assignments, and diagnostic settings** across 4 dims: (1) key **auto-rotation policy** — keys with no `rotationPolicy` / no rotate-action → finding + (2) key **expiry** — keys with no `expires` (or already-expired), with epoch-s/ms/Date/string coercion (closes the ms-overflow false-clean) + (3) **diagnostic logging → Log Analytics** — vaults with no `AuditEvent`→workspace diagnostic setting; reads `@azure/arm-monitor`'s `diagnosticSettings.list()` correctly as an `await`-ed `{value:[]}` collection object (NOT a paged async-iterator — the EE 0.15.1 H-1 fix; pre-fix the dim always threw and degraded to a non-functional evidence-gap), soft-degrades to an evidence-gap if the SDK is absent + (4) **privileged-access depth** — RBAC `roleAssignments` (admin/data-plane/**scope-aware severity**: vault-scoped control-plane god roles + Key Vault Administrator at any scope → HIGH; inherited subscription/management-group-scope Owner/User-Access-Administrator → MEDIUM, inherited Contributor → LOW — the EE 0.15.1 H-2 re-tune that stops flagging the ubiquitous inherited-admin reality as HIGH on every RBAC vault) + legacy `accessPolicies` breadth (export + wide-crypto permissions). **Secret/cert expiry is a deliberate data-plane scope boundary** (explicit caveat — the control-plane mgmt API does not expose data-plane object expiry). Conservative classifier: indeterminate field / AccessDenied / arm-monitor absent → evidence-gap; one malformed vault degrades per-resource (never aborts the scan); single-subscription scope explicit. Findings route across all seven frameworks (SOC 2 CC6.3/C1.1/CC6.1/CC7.2 · HIPAA §164.312(a)(2)(iv)/(b)/(a)(1) · NIST CSF PR.DS-01/DE.CM-09/PR.AA-05 · PCI DSS 3.5.1/10.2.1/7.2.1 · ISO 27001 A.8.24/A.8.15/A.5.15+A.8.2 · CIS v8 3.11/8.2/5.4 · GDPR Art.32(1)(b)-confidentiality + Art.32(1)(b)-integrity) — all seven coverage matrices UNCHANGED. Built + reviewed through the cloud-plugin-false-negatives lens (SHIP-WITH-FOLDS 0C/3H/2M/4L; 4 folded). `@azure/arm-keyvault` + `@azure/arm-monitor` + `@azure/arm-authorization` + `@azure/identity`. | CC6.3 / C1.1 / CC6.1 / CC7.2 |
|
|
196
196
|
|
|
197
197
|
---
|
|
198
198
|
|
package/references/schemas.md
CHANGED
|
@@ -243,10 +243,16 @@ Structured finding format used across all tiers:
|
|
|
243
243
|
|
|
244
244
|
| Status | Meaning |
|
|
245
245
|
|--------|---------|
|
|
246
|
-
| `UNVERIFIED` | Detected
|
|
247
|
-
| `VERIFIED` |
|
|
248
|
-
| `POTENTIAL` |
|
|
249
|
-
| `FALSE_POSITIVE` |
|
|
246
|
+
| `UNVERIFIED` | Detected by a scanner. **This is the status every finding carries today** — see the WITHDRAWN note below. |
|
|
247
|
+
| `VERIFIED` | Reserved for the planned Verification Engine. No shipped code sets it. |
|
|
248
|
+
| `POTENTIAL` | Reserved for the planned Verification Engine. No shipped code sets it. |
|
|
249
|
+
| `FALSE_POSITIVE` | Set by an operator suppression, not by a probe. |
|
|
250
|
+
|
|
251
|
+
> **The Verification Engine is planned, not shipped** (withdrawn as a capability claim at EE
|
|
252
|
+
> 0.32.7). The status field and its risk-weighting scaffolding exist — which is why the enum
|
|
253
|
+
> is documented here — but the probe machinery that would populate `VERIFIED` / `POTENTIAL`
|
|
254
|
+
> is WITHDRAWN and does not ship. Read `UNVERIFIED` as "this is what the scanner detected", never as
|
|
255
|
+
> "this was tried and could not be confirmed".
|
|
250
256
|
|
|
251
257
|
---
|
|
252
258
|
|
package/references/workflows.md
CHANGED
|
@@ -244,7 +244,9 @@ Track security posture changes over time.
|
|
|
244
244
|
Step 1: scan_host({ host: "<target>" }) → baseline scan
|
|
245
245
|
Step 2: (time passes, changes made)
|
|
246
246
|
Step 3: scan_host({ host: "<target>" }) → follow-up scan
|
|
247
|
-
Step 4:
|
|
247
|
+
Step 4: compare the two scan outputs yourself — there is no compare TOOL. The CLI writes
|
|
248
|
+
each run to its own timestamped out-dir; diff the `scan_compliance_<fw>.json`
|
|
249
|
+
(or `scan_conclusion_raw.json`) files across runs.
|
|
248
250
|
|
|
249
251
|
Look for:
|
|
250
252
|
- New services (unexpected exposure)
|
|
@@ -268,10 +270,10 @@ User wants to...
|
|
|
268
270
|
├── Detect debug leaks / CORS issues → probe_service with plugin 050 (Pro)
|
|
269
271
|
├── Scan a subnet → CLI: --host CIDR --parallel N
|
|
270
272
|
├── Set up continuous monitoring → CLI: --watch --interval N
|
|
271
|
-
├── Compare two scans →
|
|
272
|
-
├──
|
|
273
|
-
├──
|
|
274
|
-
└── Generate formatted report
|
|
273
|
+
├── Compare two scans → CLI: diff the per-run out-dirs (no compare tool)
|
|
274
|
+
├── State framework COVERAGE → compliance_matrix (any tier)
|
|
275
|
+
├── Produce a compliance EVIDENCE PACK → CLI: --compliance <fw> --out <dir> (not MCP)
|
|
276
|
+
└── Generate a formatted report → CLI: --output-format sarif|csv|md (not MCP)
|
|
275
277
|
```
|
|
276
278
|
|
|
277
279
|
---
|