Nsauditor AI

NSAuditor AI — Agent Skill

Version: 0.1.10 · 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).

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.

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.

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

Common plugin IDs:

get_vulnerabilities (Pro license required)

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

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>:*:*:*:*:*:*:*

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:

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 or --compliance soc2,hipaa (CSV; wired since EE 0.3.0) for HIPAA-only or dual-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
├── 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

Plugin-Specific Timeouts

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

→ Pricing

Error Handling

MITRE ATT&CK Mapping

Findings are auto-tagged with MITRE techniques:

Output Formats