nsauditor-ai

name

nsauditor-ai

description

Use this skill whenever the user wants network security scanning, auditing, vulnerability assessment, host reconnaissance, or cloud-account security/compliance auditing with NSAuditor AI (via the nsauditor-ai MCP server: scan_host, scan_cloud, get_findings, probe_service, get_vulnerabilities, list_plugins). Triggers include 'scan', 'audit', 'vulnerability', 'CVE', 'network security', 'port scan', 'service detection', 'OS fingerprinting', 'penetration test', 'TLS/cipher audit', 'certificate check', 'DNS security', 'SPF/DKIM/DMARC/DNSSEC', 'SNMP/SMB/NetBIOS', 'CTEM', 'continuous monitoring', or 'audit my AWS/GCP/Azure account' / 'cloud compliance'. Also use it when the user asks to check if a host is up, enumerate services, find open ports, look up CVEs for a version, audit DNS records, or audit a cloud account — even if they don't say NSAuditor, as long as the nsauditor-ai MCP tools are available. Do NOT use for general coding, web development, or non-security topics.

NSAuditor AI — Agent Skill

Version: 0.2.25 (post-EE-0.32.2 — a matrix-neutral release: no new framework, no new plugins (still 28), all seven coverage matrices UNCHANGED. Two legs: (1) a new Secureframe GRC push connector completes the Vanta · Drata · Secureframe trio at the same early-access opt-in shape — set COMPLIANCE_GRC_PROVIDER=secureframe + COMPLIANCE_GRC_TOKEN and the compliance phase pushes structured control records to your Secureframe workspace evidence collection (records model like Drata — your Secureframe rules evaluate them; the connector carries the control status verbatim, it does NOT compute pass/fail; outbound, single-workspace, opt-in early-access; API shape published-assumed, live-tenant validation deferred to partner intake); and (2) the cross-framework foreign-token leak in the "Why this violates" rationales is closed — an internal Inherits from soc2.json CC6.1 note, bare foreign control-ids, cross-framework routing-maps, and a real-engine verified == QA-note no longer leak a foreign framework's name into a HIPAA / PCI / ISO / NIST / CIS / GDPR Report on Compliance (~300 rationales across all seven frameworks; pure-deletion, subsequence-invariant-proven, with a class-level guard; routing byte-neutral). Prior context — EE 0.32.1 cleaned internal engineering markers ([[wiki-links]], EE-RT work-codes, reviewer-codes, Rn-SEVERITY review-round IDs) out of the rationales + deeper Azure/AWS positive-substrate + a Vanta/Drata push-loop DRY refactor; EE 0.32.0 wired scan-time GRC push (Vanta) + shipped the Drata connector. Honest status: the three connectors are shipped + opt-in + extensively tested; live validation against production tenants in progress — early-access, single-workspace, not a multi-tenant sync. The seven frameworks: SOC 2 · HIPAA · NIST CSF 2.0 · PCI DSS v4.0.1 · ISO/IEC 27001:2022 · CIS Controls v8 · GDPR Article 32 — the last is Art. 32 infrastructure substrate ONLY, NOT GDPR compliance [Art. 32 is the only one of GDPR's 99 articles an infrastructure scanner can evidence; the rest is operator-side, out of scope by design], carrying four-factor proportionality + personal-data-scope attestation + the Art. 83(4) LOWER fine tier [€10M/2%, not the €20M/4% headline tier]. Paired CE 0.2.27 + EE 0.32.2) · Source: github.com/nsasoft/nsauditor-ai · npm: nsauditor-ai · License: MIT (CE)

NSAuditor AI is a modular, AI-assisted network security audit platform with 27+ scanner plugins, CVE matching, MITRE ATT&CK mapping, and Zero Data Exfiltration by design. This skill teaches you how to operate it via MCP tools and CLI.

---

MCP Tools Reference

NSAuditor AI exposes tools via Model Context Protocol (stdio transport). Available tools depend on the license tier (Community / Pro / Enterprise).

Community Edition Tools (always available)

scan_host

Run a full plugin scan against a target host. Executes ALL enabled plugins in priority order (discovery → service probes → OS detection → result fusion).

Parameter	Type	Required	Default	Description
host	string	✅	—	Target hostname or IP address
timeout	number	❌	30000	Per-plugin timeout in ms

Returns: { summary, host, services[], findings[] } — see references/schemas.md

Example:

{ "host": "192.168.1.1", "timeout": 10000 }

Important:

• For RFC 1918 / private IPs, the MCP server must have NSA_ALLOW_ALL_HOSTS=1 set.
• The server blocks loopback (127.x, ::1), link-local (169.254.x, fe80:), and cloud metadata endpoints (169.254.169.254) — this is SSRF protection, not a bug.
• Plugins with unmet requirements auto-skip (e.g., SSH scanner skips if port 22 is closed).

---

list_plugins

List all available scanner plugins with metadata.

Parameter	Type	Required	Description
(none)	—	—	—

Returns: Array of { id, name, description, priority, protocols[], ports[], requirements }

When to use: Before a scan to understand available plugins, or to help the user select specific plugins for a targeted probe.

---

probe_service (Pro license required)

Run a single plugin against a specific host:port for deep-dive investigation.

Parameter	Type	Required	Description
host	string	✅	Target hostname or IP
pluginName	string	✅	Plugin name or numeric ID (e.g. "ssh_scanner" or "002")
port	number	✅	Target port number

Returns: Raw plugin output with full evidence for that specific service.

Common plugin IDs:

ID	Name	Best For
002	SSH Scanner	Banner, version, weak algorithms/ciphers
004	FTP Banner	FTP daemon identification, anonymous login
006	HTTP Probe	Server headers, tokens, vendor hints
007	SNMP Scanner	Device info via sysDescr, hardware/firmware
009	DNS Scanner	DNS server version (CHAOS query)
010	Webapp Detector	Technology stack fingerprinting (Wappalyzer)
011	TLS Scanner	TLS versions, cipher suites, deprecation
014	NetBIOS Scanner	SMB/NetBIOS enumeration, null sessions
040	TLS Cert & Cipher Auditor	Certificate chain, expiry, weak ciphers (Pro)
050	TRIBE v2 Probe	Debug leaks, stack traces, CORS misconfig (Pro)
060	DNS Security Auditor	SPF/DKIM/DMARC, DNSSEC, zone transfer (Pro)

---

get_vulnerabilities (Pro license required)

Look up known CVEs for a CPE string via the NVD 2.0 API.

Parameter	Type	Required	Description
cpe	string	✅	CPE 2.3 format (see CPE guide below)
maxResults	number	❌	Max CVE results to return

Returns: { cpe, totalResults, vulnerabilities[] } — each CVE includes ID, description, CVSS v3.1 score, severity, vector string, publication date.

CPE Construction Guide:

Format: cpe:2.3:a:<vendor>:<product>:<version>:*:*:*:*:*:*:*

Detected Program	Detected Version	CPE String
OpenSSH	8.9p1	cpe:2.3:a:openbsd:openssh:8.9p1:*:*:*:*:*:*:*
Apache httpd	2.4.54	cpe:2.3:a:apache:http_server:2.4.54:*:*:*:*:*:*:*
nginx	1.24.0	cpe:2.3:a:f5:nginx:1.24.0:*:*:*:*:*:*:*
OpenSSL	3.0.8	cpe:2.3:a:openssl:openssl:3.0.8:*:*:*:*:*:*:*
ISC BIND	9.18.12	cpe:2.3:a:isc:bind:9.18.12:*:*:*:*:*:*:*
vsftpd	3.0.5	cpe:2.3:a:beasts:vsftpd:3.0.5:*:*:*:*:*:*:*
Samba	4.17.5	cpe:2.3:a:samba:samba:4.17.5:*:*:*:*:*:*:*
Log4j	2.14.1	cpe:2.3:a:apache:log4j:2.14.1:*:*:*:*:*:*:*
MySQL	8.0.32	cpe:2.3:a:oracle:mysql:8.0.32:*:*:*:*:*:*:*
PostgreSQL	15.2	cpe:2.3:a:postgresql:postgresql:15.2:*:*:*:*:*:*:*

Tip: If vendor is ambiguous, search NVD with just the product name first.

---

Pro/Enterprise Tools (license gated)

These tools return a license upgrade prompt on CE installations:

Tool	Tier	Purpose
risk_summary	Pro	Prioritized risk overview with severity breakdown
scan_compare	Pro	Diff two scan results with risk-weighted delta analysis
save_finding	Pro	Persist a validated finding to the finding queue
scan_cloud	Enterprise	Audit one or more cloud accounts (AWS / GCP / Azure) for security & compliance posture using the server-configured credentials. No network host needed. Input: { providers?: ("aws"|"gcp"|"azure")[], 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.

Reporting scan_cloud region scope — never overstate coverage: Report the regions you ACTUALLY scanned, derived from the regions you passed — NOT from the findings. If you OMITTED regions, only the single server-default region (AWS_REGION) was scanned — say exactly that and add that the account's OTHER enabled regions were NOT covered (offer to re-run for all regions). Never escalate a single-region or "quick" request into a multi-region scan. Do NOT claim "all regions" / "every region" / "across N regions" just because GuardDuty or Inspector list per-region findings: those plugins enumerate every enabled region INTERNALLY regardless of scope, so their per-region findings are NOT evidence the other plugins ran outside the region(s) you passed.

Full all-region coverage — discover then batch (use ONLY when the user explicitly asked for all/every/whole-account/complete/full region coverage; NEVER for a plain or "quick" request — those stay single-region per the regions default above): a single regions:["all"] call usually exceeds the host's MCP tool-call timeout (e.g. Claude Desktop's) and returns nothing. Reliable pattern: (1) run a default scan (omit regions) — its GuardDuty/Inspector findings enumerate every enabled region, giving you the full list while auditing the default region; (2) scan the REMAINING regions in small batches (3–5 region codes per regions:[...] call) across successive calls until every enabled region is covered; (3) merge and report the TOTAL number of regions actually covered — count them, don't guess. If you try ["all"] and it times out, that result is INCOMPLETE — fall back to batching and continue until complete; never report a timed-out or partial scan as full coverage. | start_assessment | Enterprise | Multi-host orchestrated security assessment | | prioritize_risks | Enterprise | Cross-host risk prioritization and ranking | | compliance_check | Enterprise | SOC 2 (AICPA TSC 2017) + HIPAA (§164.312 Technical Safeguards) + NIST CSF 2.0 Core + PCI DSS v4.0.1 (sub-requirement-level for QSA RoC; PCI SSC June 2024 errata) + ISO/IEC 27001:2022 (per-Annex-A-code-level for ISO/IEC 17021-1 certification body assessors; ISO + IEC October 2022; 2013 edition retired October 31, 2025) + CIS Critical Security Controls v8 (per-Safeguard-level; Center for Internet Security May 2021, v8.1 errata June 2024) + 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). | | export_report | Enterprise | Formatted compliance/risk report (PDF, HTML) |

---

Five-Phase Pipeline Architecture

NSAuditor AI follows an institutional five-phase pipeline:

Phase 1: DISCOVERY (CE)        License → Plugin loading → PluginManager.run() → Concluder
                                Output: Fused scan with summary, OS, services[], evidence[]
                                        ↓
Phase 2: BASIC ANALYSIS (CE)   Redaction → MITRE mapping → AI analysis (any provider)
                                Output: Admin raw JSON/HTML + AI reports + scan history
                                        ↓
                                   [ License Gate: Pro required ]
                                        ↓
Phase 3: INTELLIGENCE (Pro)    CPE generation → NVD CVE lookup → Parallel verification agents:
                                  • Auth Agent (weak auth, default credentials)
                                  • Crypto Agent (TLS, ciphers, certificates)
                                  • Config Agent (misconfigs, debug exposure, CORS)
                                  • Service Agent (CVE-specific targeted probes)
                                Output: Structured finding queue
                                        ↓
Phase 4: VERIFICATION (Pro)    For each finding: run SAFE non-destructive verification probe
                                Classify: VERIFIED | POTENTIAL | FALSE_POSITIVE
                                Output: Verified finding queue with evidence
                                        ↓
Phase 5: SCORING (Pro/Ent)     Risk scoring → Pro AI prompts → Compliance mapping
                                Output: Risk report + compliance report + PDF

---

Plugin Reference (44+ Scanners)

See references/plugins.md for the complete catalog. Summary:

Core (17): Ping, SSH, Port Scanner, FTP, Host Up, HTTP Probe, SNMP, Result Concluder, DNS, Webapp Detector, TLS, OpenSearch, OS Detector, NetBIOS/SMB, SUN RPC, WS-Discovery, TCP SYN (Nmap wrapper)

Discovery (6): ARP, mDNS/Bonjour, UPnP/SSDP, DNS-SD, LLMNR, DB Scanner

Pro (3): TLS Certificate & Cipher Auditor, TRIBE v2 Probe, DNS Security Auditor

Enterprise (18): AWS Cloud Scanner (1020), GCP Cloud Scanner (1021), Azure Cloud Scanner (1022), Zero Trust Checker (1023), AWS IAM Deep Auditor (1030), AWS CloudTrail Operational Integrity (1040), AWS API Gateway Assurance (1050), AWS DynamoDB Audit Integrity (1060), AWS KMS Auditor (1070), AWS Lambda Security Auditor (1080), AWS Secrets Manager + SSM Parameter Store Auditor (1090), AWS CodePipeline + CodeBuild Operational Integrity (1100), AWS IAM Effective Decrypt-Path Auditor (1110), AWS S3 Lifecycle + Cross-Region Replication Auditor (1120), AWS Backup Auditor (1130), AWS RDS Auditor (1140 v3 — extended in EE 0.4.8 with database audit-logging; 7→10 dims: +pgAudit / +CloudWatch Logs exports / +CloudWatch Logs retention; aurora-aware log-path detection per R-HIGH-1 reviewer-fold), AWS SQS/SNS Auditor (1150 v2 — extended in EE 0.5.1: 5 → 7 dims with CloudWatch alarm coverage on SQS ApproximateAgeOfOldestMessage + SNS NumberOfNotificationsFailed; closes 1 CRITICAL false-CLEAN class on empty-AlarmActions silent-PASS per R-CRITICAL fold; first plugin-1150 dim to cross an SDK boundary — SQS+SNS → CloudWatch), AWS EC2 SG Perimeter Auditor (1170 v2 — RESTRICTED_PORTS 23 ports per CIS AWS Foundations v3.0), AWS VPC Endpoints / PrivateLink Auditor (1160 — NEW in EE 0.6.0; first plugin to audit the PrivateLink isolation boundary; 4 dims: endpoint policy permissive principals CC6.6, PrivateDNS enabled CC6.6, endpoint state A1.2+CC7.2, type substrate Privacy+CC6.6), AWS ElastiCache Redis Auditor (1180 v2 — extended in EE 0.4.9: kms:DescribeKey promotion + subnet route-table verifier; closes both v1 deferred items R-MEDIUM-3 + R-LOW-2; main-RT-inheritance false-NEGATIVE closure per R-MEDIUM-2 reviewer-fold), AWS SES Email Integrity Auditor (1190 v3 — extended in EE 0.5.0 + consolidated in EE 0.5.2 + v3 extension in EE 0.5.3: DKIM CNAME DNS resolution + DMARC TXT record parser + SES classic API parity + deferred-items sweep + DKIM public-key fingerprint capture/pin + in-band DMARC alignment classifier; closes 1 CRITICAL false-CLEAN class on DMARC pct=0 per R-CRITICAL-1 fold + 1 HIGH false-NEGATIVE class on DMARC sp subdomain-policy override per R-HIGH-1 fold + new MEDIUM ses-dkim-dns-partial-with-transients per v2.1 R-MEDIUM-2 fold + silent-loss-class closure on SES classic API quota exhaustion via cause: "classic-sdk-quota-exhausted" per v2.1 R-HIGH-2 reviewer-fold; first plugin in EE to depend on node:dns/promises for live DNS cross-reference), AWS Inspector2 / GuardDuty Enablement Auditor (1200 v6 — NEW in EE 0.6.1, extended through EE 0.6.6; first AWS-managed-threat-detection substrate audit; bundles two services per the plugin 1150 precedent. v4 EE 0.6.4 reviewer-cleanup cycle (closes 3 of 4 R2-deferred items from EE-RT.20.2): R-HIGH-2 EventBridge target verification — new _listEventBridgeRuleTargets helper with defensive NextToken pagination; per-rule target verification via events:ListTargetsByRule (cap default 10 via opts.targetVerificationRuleCap; opt-out via opts.skipEventBridgeTargetVerification); new MEDIUM verdict *-alerting-destination-targetless for sink-less rules (zero Targets — substrate- without-sink at the rule level). R-MEDIUM-2 multi-failedAccount surface — helper return-shape {accountStatus, accessDenied, failedAccounts: array} (renamed plural; capped at AWS-documented 100); caller emits one LOW per failed account with per-region emission cap 10 + rollup LOW. R-LOW-2 trigger uniformity — GuardDuty alerting-destination trigger gates on detector.Status === ENABLED (matches Inspector2 enabled-only semantic). 5 v4 R1 folds (0 R-CRITICAL): R-HIGH-1 cap-skew classifier branch (LOW UNVERIFIABLE not MEDIUM TARGETLESS when cap-exceeded rules could be the actual sink) + R-HIGH consolidated _listEventBridgeRuleTargets pagination + JSDoc clarity + R-MEDIUM-1 multi-failedAccount per-region emission cap (10 + rollup) + R-MEDIUM-4 boundary tests + R-HIGH-2 dead-target documented-limitation note. v3 EE 0.6.3 alerting-destination dim preserved: EventBridge rule on source aws.guardduty/aws.inspector2 OR SecurityHub product subscription (boundary- anchored _shArnMatchesProduct helper + strict /aws/inspector2 constant per v3 R-CRITICAL-1); verdict tiers PASS / MEDIUM SH-only / MEDIUM TARGETLESS (v4 added) / HIGH missing / LOW UNVERIFIABLE; new SDK deps @aws-sdk/client-eventbridge

• @aws-sdk/client-securityhub. v2 EE 0.6.2 preserved: multi-region via ec2:DescribeRegions + GuardDuty FindingPublishingFrequency check + Inspector2 baseline expansion (+lambdaCode +codeRepository). Operator opts: regions[] / skipMultiRegion / regionListCap / gdFrequencyPassFrequency / skipAlertingDestination / skipEventBridgeTargetVerification / targetVerificationRuleCap / skipTargetLivenessProbe / deadTargetProbeTimeoutMs. v5 EE 0.6.5 closes the 0.6.4 R-HIGH-2 documented limitation via per-target liveness probes for Lambda (lambda:GetFunction on full qualified ARN — alias/ version correctness verified server-side) + SNS (sns:GetTopicAttributes) + SQS (sqs:GetQueueUrl + GetQueueAttributes — partition-aware via SDK URL resolution; works on aws-cn / aws-us-gov / aws-iso). Companion-LOW emitted alongside PASS when targets dead. Parallel probes via Promise.all + 2s default timeout. One-retry on NotFound with 750ms backoff (eventual-consistency defense). Case-insensitive NotFound matching per [[aws_string_case_normalization]]. Sentinel observability — targetVerificationReason enum (AccessDenied / SdkUnavailable / BeyondCap / SkippedByOpts) on rule shape. R-NIT SH_HUB_NOT_ENABLED_ERROR_NAMES frozen Set. v6 EE 0.6.6 closes the long tail of unverifiable ARN shapes: IAM role (iam:GetRole on path-stripped role NAME; new SDK dep @aws-sdk/client-iam) + EventBridge API destination (events:DescribeApiDestination reuses _EventBridgeSdk) + CloudWatch Logs (logs:DescribeLogGroups with logGroupNamePrefix filter + exact-name disambiguation guard so prefix-match siblings don't false-LIVE; new SDK dep @aws-sdk/client-cloudwatch-logs). Operator note (v6 R-MEDIUM-2): iam:GetRole is a global API resolving per-partition; orchestrators wiring opts._iamClient must construct a single global IAM client per-partition (NOT per-region). v6 R-MEDIUM-1 fold: IAM NoSuchEntityException / NoSuchEntity lifted into _DEAD_TARGET_NOTFOUND_ERROR_NAMES Set; bare disjunction collapsed; eventual-consistency retry restored for IAM (the canonical worst case — 9th cumulative recurrence of [[emit_literal_set_drift]] class). v6 R-LOW-2 fold: API destination ARN regex future-proofed against alias-only ARN shapes. v6.1 EE 0.6.7 closes the Logs probe retry-on-empty parity: _retryOnNotFound accepts an optional retry-on-result predicate; CWL Logs probe fires retry when the response carries no exact-name match (covers both empty and prefix-only-sibling responses). Restructured to two-phase to cap total network calls at 2 on compound paths — Phase 1 = initial call + thrown- NotFound retry; Phase 2 = result-based retry; phases are mutually exclusive (per-call-site outer catch routes a second-call thrown error). Existing call sites (Lambda / SNS / SQS / IAM / EventBridge API destination) pass only two args; default retryOnResultPredicate = null cleanly skips Phase 2. Dim 5 org-scope still deferred to a future cycle. Total folds across all cycles: 6 v1 + 4 v2 + 4 v3 (1 R-CRITICAL) + 5 v4 + 5 v5 + 4 v6 (0 R-CRITICAL) + 1 v6.1 (0 R-CRITICAL / 0 R-HIGH) = 29 R1 folds applied same-session.

v5 also brings a cross-plugin contract change: all 18 EE AWS plugins (1020-1200) now thread sessionToken through their AWS-SDK credentials block, unblocking AssumeRole-style auditor credentials uniformly across the catalog). EE plugin IDs use the disjoint 1000+ range (per EE 0.3.9 renumbering) to avoid CE collision. CE reserves 001-099.

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 R-HIGH-1 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 R-LOW-2 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 [[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 R-MEDIUM-1 fold: arrival-order independence locked with 2 regression fixtures + JSDoc tightening. v3.1 R-LOW-1 fold: partial-render contract on malformed port specs locked with 2 fixtures. v3.1 R-LOW-2 fold: _portKeys scratch-lifetime documented (MUST NOT escape).

EE SOC 2 substrate-evidence coverage (post-EE 0.10.0): 10 covered controls (CC6.1 / CC6.2 / CC6.6 / CC6.7 / CC6.8 / CC7.1 / CC7.2 / CC7.3 / C1.1 / C1.2) + 4 partial (CC6.3 / CC8.1 / A1.2 / PI1.5) + 33 OOS for static substrate scanning. SOC 2 matrix UNCHANGED post-EE 0.10.0 — the NIST CSF 2.0 cycle is additive-only; no SOC 2 mappings changed. NIST CSF 2.0 introduced as third Track 3 framework with its own 13/10/83 matrix across 106 of CSF 2.0 Core's 107 Subcategories; Govern function OOS-by-design with GV.SC-04 partial as substrate-evidence exception; Respond function OOS-entirely; Implementation Tiers 1-4 OOS as organizational-maturity claim. Coverage matrix is institutionally honest: substrate-evidence depth grows release-over-release without the matrix being shifted (the matrix-shift requires net-new control coverage, not just more evidence on already-covered controls).

EE HIPAA §164.312 Technical Safeguards substrate-evidence coverage (NEW EE 0.9.0): 7 covered sub-criteria (§164.312(a)(1) Access Control, (a)(2)(i) Unique User ID, (a)(2)(iv) Encryption-at-rest, (b) Audit Controls, (d) Person/Entity Auth, (e)(1) Transmission Security, (e)(2)(ii) Transmission Encryption) + 3 partial (§164.312(c)(1) Integrity — ransomware-defense substrate via Logically Air-Gapped Backup Vault cross-verification, (c)(2) Mechanism to Authenticate ePHI, (e)(2)(i) Transmission Integrity Controls) + 45 OOS (2 within-§164.312 + entire §164.308 Administrative Safeguards [31 specs: workforce training, BAAs, contingency planning, etc.] + entire §164.310 Physical Safeguards [12 specs: facility access, workstation security, device disposal]). The §164.308 + §164.310 OOS sets are architecturally OOS for any infrastructure scanner — pair with HIPAA-focused GRC platforms (Drata HIPAA, Vanta HIPAA, Compliancy Group, Tugboat Logic) for those families. HHS Required vs Addressable discipline surfaced per control. Zero BAA required — Zero Data Exfiltration architecture means ePHI never leaves customer infrastructure. Use --compliance hipaa, --compliance soc2,hipaa (CSV; wired since EE 0.3.0), or --compliance all (all seven frameworks; EE 0.31.4) for HIPAA-only, dual-, or full-framework evidence packs from a single scan. 175 mappings inherited from soc2.json's grep-verified pattern set with HIPAA-grounded rationales. New data/compliance/hipaa.json. New docs/hipaa-coverage.md. EE regression: 5890/5890 across 928 suites; 69-session 100% green streak preserved. AWS-dogfood verified against operator's test account (207 findings, per-framework citation map confirmed firing, ransomware-substrate surfaces correctly).

Execution order: Discovery (100–150) → Service probes (200–400) → OS Detector (99000) → Result Concluder (100000). Plugins with unmet requirements auto-skip.

---

Workflow Recipes

See references/workflows.md for detailed multi-step patterns:

1. Full Security Audit — list_plugins → scan_host → get_vulnerabilities per service
2. Targeted Service Investigation — probe_service(pluginId) → get_vulnerabilities
3. Subnet Discovery — CLI: nsauditor-ai scan --host <CIDR> --parallel 10
4. CI/CD Pipeline — SARIF output with --fail-on severity gating
5. Continuous Monitoring (CTEM) — --watch --interval <min> --webhook-url <url>
6. AI-Powered Report — Scan with AI provider (OpenAI/Claude/Ollama) + redaction

Decision Tree: Which Tool to Use

User wants to...
├── Scan a host comprehensively         → scan_host
├── Audit a cloud account (AWS/GCP/Azure) → scan_cloud (Enterprise)
├── Check a specific service/port       → probe_service (Pro)
├── Look up CVEs for software version   → get_vulnerabilities (Pro)
├── See available plugins               → list_plugins
├── Audit TLS certificates              → probe_service with plugin 040 (Pro)
├── Check DNS security (SPF/DKIM/DMARC) → probe_service with plugin 060 (Pro)
├── Detect debug leaks / CORS issues    → probe_service with plugin 050 (Pro)
├── Scan a subnet                       → CLI with --parallel (not MCP)
├── Set up continuous monitoring         → CLI with --watch (not MCP)
├── Compare two scans                   → scan_compare (Pro)
└── Generate compliance report          → compliance_check + export_report (Enterprise)

---

Data Schemas

See references/schemas.md for complete structures:

• Scan Result — { summary, host{os,mac,vendor,names}, services[], findings[] }
• ServiceRecord — { port, protocol, service, program, version, status, banner, evidence[] }
• Finding — { id, category, severity, title, evidence, remediation, cwe, mitre_attack[] }
• CVE Response — { cpe, totalResults, vulnerabilities[]{cve_id, cvss, severity} }
• Plugin Interface — { id, name, priority, run(), conclude(), requirements }
• SARIF Output — 2.1.0 format for CI/CD consumers

---

Security Constraints

CRITICAL — Always observe these constraints:

1. Zero Data Exfiltration (ZDE): NSAuditor AI NEVER sends scan data externally unless the user explicitly opts in to AI analysis with their own API keys. Nsasoft infrastructure never sees scan data. Never suggest workflows that violate this boundary.

2. SSRF Protection: The MCP server blocks loopback (127.x, ::1), link-local (169.254.x, fe80:), and cloud metadata endpoints. Set NSA_ALLOW_ALL_HOSTS=1 only for legitimate local network auditing. DNS rebinding is also blocked via pre-resolution.

3. AI Redaction: When AI analysis is enabled, the redaction pipeline scrubs:

   • Private IPv4 addresses → [REDACTED]
   • MAC addresses → [MAC]
   • Serial numbers → [REDACTED_HIDDEN]
   • Email addresses → [REDACTED_EMAIL]
   • Bearer tokens → [REDACTED_BEARER]
   • AWS keys → [REDACTED_AWS_KEY]
   • Configurable via CONFIDENTIAL_KEYWORDS env var

4. Scan Authorization: ALWAYS confirm the user has authorization to scan the target. Never scan hosts without explicit user instruction. Unauthorized scanning is illegal.

5. Non-Destructive: All verification probes are safe read-only queries. NSAuditor AI never exploits vulnerabilities or modifies target systems.

---

Configuration

Environment Variables

Variable	Default	Purpose
NSA_ALLOW_ALL_HOSTS	unset	Set to 1 to scan RFC 1918 private ranges
PLUGIN_TIMEOUT_MS	30000	Global per-plugin timeout
AI_ENABLED	false	Enable AI analysis
AI_PROVIDER	openai	openai · claude · ollama
OPENAI_API_KEY	—	OpenAI API key (or keychain:OPENAI_API_KEY)
ANTHROPIC_API_KEY	—	Claude/Anthropic API key
OPENAI_MODEL	gpt-4o-mini	OpenAI model name
ANTHROPIC_MODEL	claude-sonnet-4-20250514	Anthropic model name
OPENAI_REDACT	true	Redact PII before AI submission
CONFIDENTIAL_KEYWORDS	serial,password,token,secret	Comma-separated keys to scrub
NSAUDITOR_LICENSE_KEY	—	Pro/Enterprise JWT license key
COMPLIANCE_GRC_PROVIDER	—	Enterprise — opt-in scan-time GRC push: vanta, drata, or secureframe. Needs COMPLIANCE_GRC_TOKEN; optional COMPLIANCE_GRC_BASE_URL / COMPLIANCE_GRC_CONTROL_MAP / COMPLIANCE_GRC_REDACTION (off/hash/remove). Egress is ZDE-redacted; token never serialized. Live tenant validation in progress.
SCAN_OUT_PATH	out/	Output directory for scan results
SMB_NULL_SESSION	false	Allow SMB null session probe
ENABLE_SYN_SCAN	false	Enable Nmap TCP SYN scanning (requires root)

Plugin-Specific Timeouts

Variable	Default	Plugin
TLS_SCANNER_TIMEOUT_MS	8000	TLS Scanner
HTTP_PROBE_TIMEOUT_MS	6000	HTTP Probe
WEBAPP_DETECTOR_TIMEOUT_MS	6000	Webapp Detector
DNS_TIMEOUT_MS	800	DNS Scanner
OPENSEARCH_SCANNER_TIMEOUT_MS	6000	OpenSearch Scanner

---

Installation & Setup

# Install globally
npm install -g nsauditor-ai

# Start MCP server (stdio transport)
nsauditor-ai-mcp

# Or via npx (no global install)
npx nsauditor-ai-mcp

Agent Integration

Claude Code:

claude mcp add nsauditor-ai -- npx nsauditor-ai-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "nsauditor-ai": {
      "command": "npx",
      "args": ["-y", "nsauditor-ai-mcp"],
      "env": {
        "NSA_ALLOW_ALL_HOSTS": "1",
        "PLUGIN_TIMEOUT_MS": "5000"
      }
    }
  }
}

Cursor / Windsurf / VS Code: Add to your MCP configuration with the same command/args pattern.

---

Editions & Licensing

Edition	Price	Key Features
Community	Free / MIT	27 plugins (service probes + host/network discovery + intelligence/meta), basic AI, CTEM, SARIF, scan history
Pro	$49/mo	+ CVE matching, verification probes, risk scoring, Pro plugins (040 TLS / 050 TRIBE / 060 DNS)
Enterprise	$2k+/yr	+ 26 cloud-substrate auditor plugins (1020-1222 range) covering AWS / GCP / Azure against SOC 2 (10 covered + 4 partial controls); Zero Trust; SOC 2 evidence-pack generation; RFC 3161 timestamps; chain-of-custody attestations; air-gapped deployment

→ Pricing

---

Error Handling

Error	Cause	Resolution
SSRF block	Target is loopback/metadata/private	Set NSA_ALLOW_ALL_HOSTS=1 for local scanning
License gate (🔒)	Pro/Enterprise tool on CE	Upgrade license or use CE alternative
Plugin timeout	Network unreachable / slow target	Increase timeout param or PLUGIN_TIMEOUT_MS
No DNS banner	Provider blocks CHAOS/TXT queries	Expected; not all DNS servers expose version
CPE format error	Malformed CPE string	Use cpe:2.3:a:vendor:product:version:*:*:*:*:*:*:*
No services found	Host down or heavily firewalled	Try NSA_VERBOSE=true to debug; check connectivity
AI analysis failed	Bad API key or provider down	Check AI_PROVIDER and API key env vars

---

MITRE ATT&CK Mapping

Findings are auto-tagged with MITRE techniques:

Finding Type	Technique	ID
SSH vulnerability	Remote Services: SSH	T1021.004
SMB vulnerability	Remote Services: SMB	T1021.002
FTP anonymous login	Valid Accounts	T1078
DNS zone transfer	Gather Victim Network Info	T1590.002
SNMP default community	Network Sniffing	T1040
TLS weakness	Adversary-in-the-Middle	T1557
Debug/stack trace exposure	Gather Victim Host Info	T1592
Weak authentication	Brute Force	T1110

---

Output Formats

File	Format	Purpose
scan_conclusion_raw.json	JSON	Full unredacted scan data (admin)
scan_conclusion_raw.html	HTML	Admin dashboard with filters
scan_response_ai_payload.json	JSON	Redacted payload sent to AI
scan_response_ai.html	HTML	Styled report with CVE links, severity badges
scan_response_ai.txt	Markdown	AI vulnerability assessment (text)
SARIF	JSON	CI/CD integration (GitHub Advanced Security, Azure DevOps)
CSV	CSV	Tabular export of findings
JSONL	JSONL	Scan history for CTEM delta analysis