| 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:
- Full Security Audit — list_plugins → scan_host → get_vulnerabilities per service
- Targeted Service Investigation — probe_service(pluginId) → get_vulnerabilities
- Subnet Discovery — CLI:
nsauditor-ai scan --host <CIDR> --parallel 10
- CI/CD Pipeline — SARIF output with
--fail-on severity gating
- Continuous Monitoring (CTEM) —
--watch --interval <min> --webhook-url <url>
- 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:
-
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.
-
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.
-
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
-
Scan Authorization: ALWAYS confirm the user has authorization to scan the target.
Never scan hosts without explicit user instruction. Unauthorized scanning is illegal.
-
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
npm install -g nsauditor-ai
nsauditor-ai-mcp
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 |
