NSAuditor AI

Security Intelligence Without Data Exposure.

A modular, AI-assisted network security audit platform that scans, understands, prioritizes, and tracks vulnerabilities — without ever requiring your data to leave your infrastructure.

NSAuditor AI is the open-source core of a privacy-first security intelligence platform built by Nsasoft US LLC. It orchestrates 27 specialized scanning plugins against target hosts, fuses their results through an intelligent concluder, and optionally produces AI-powered vulnerability reports — all running entirely on your machine.

Zero Data Exfiltration by design. NSAuditor AI works fully offline. AI analysis, CVE correlation, and continuous monitoring all happen locally. External calls (to AI APIs, NVD, etc.) are opt-in and use your own API keys. We never see your scan data.

What's New

Latest: CE 0.2.11 + Enterprise 0.20.0 (June 2026) — paired content bump for the Enterprise GDPR Article 32 (Security of Processing) cycle, the seventh compliance framework. The Enterprise engine now substrate-evidences GDPR Article 32 infrastructure substrate — Art. 32 only, not GDPR compliance (GDPR is a 99-article legal regime; Art. 32 security-of-processing is the only article an infrastructure scanner can evidence). The CE-side change: the MCP scan_cloud tool description now lists GDPR Article 32 among the mapped frameworks, and the agent-skill teaches the 7th framework (scope doctrine · four-factor proportionality · the Art. 83(4) lower fine tier). No CE engine behavior change. Paired EE 0.20.0 (the framework lives in the Enterprise engine; matrix 4 covered + 5 partial + 2 OOS across 11 Art. 32 sub-measure units) + agent-skill 0.2.11. EE 0.20.0 requires CE 0.2.8+. See CHANGELOG.md.

Prior: CE 0.2.10 + Enterprise 0.19.4 — MCP affordance II: scan_cloud rolls up MEDIUM/LOW findings per provider by category + a NEW Enterprise-gated get_findings drill-down tool. See CHANGELOG.md.

Prior: CE 0.2.9 + Enterprise 0.19.4 — paired README-refresh pin for EE 0.19.4 "Routing-Integrity Hardening" (PCI matrix 20/8/39 → 19/9/39; no CE code change). See CHANGELOG.md.

→ Full release history: CHANGELOG.md → See a sample EE scan output: walk-through with synthetic Acme Corp AWS account (no signup required)

What It Does

Scan → Verify → Prioritize → Track → Act

• 27 scanner plugins probe networks across ICMP, TCP, UDP, HTTP, TLS, SNMP, DNS, SMB, RPC, mDNS, UPnP, WS-Discovery, MCP (Model Context Protocol), and more
• Smart result fusion — the Result Concluder merges all plugin outputs into a normalized view with OS detection, service fingerprinting, and evidence linking
• Structured finding format — all findings use a common schema with category, severity, evidence, and remediation — enabling consistent SARIF export and MCP integration
• AI-powered analysis — send redacted scan results to OpenAI or Claude (your keys, your choice) for vulnerability assessments and remediation guidance
• Verified vulnerabilities (Pro) — safe, non-destructive probes confirm findings are real, not just version-matched guesses. If it can't be verified, it's flagged as "potential" not "confirmed"
• Continuous monitoring (CTEM) — watch mode rescans on a schedule, diffs against previous results, and fires webhook alerts on changes
• MCP integration — expose scanning tools to AI assistants like Claude Code via Model Context Protocol
• CI/CD ready — SARIF output with --fail-on severity gating for pipeline integration

Editions

NSAuditor AI is available in three editions: Community (free, MIT-licensed, no restrictions), Pro ($49/mo), and Enterprise ($2k+/yr).

Why upgrade to Enterprise?

If you're heading into a SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS Controls v8, or GDPR Article 32 audit — or need to satisfy customer security questionnaires citing those frameworks, or an IG1 attestation for cyber-insurance renewal — Enterprise turns scan output into auditor-ready evidence packs that pass institutional scrutiny:

• ☁️ 28 cloud plugins across AWS / Azure / GCP — find the configuration risks an auditor will flag, before they do (CloudTrail integrity, KMS custody, S3 Object Lock, IAM shadow-admin paths, GCP IAM impersonation chains, Azure RBAC sprawl, and more)
• 📋 7 compliance frameworks shipped — generate any combination from a single scan:
  • SOC 2 (AICPA TSC 2017) — 10 fully-covered + 4 partial controls
  • HIPAA Security Rule §164.312 — 7 covered + 3 partial Technical Safeguards; Zero BAA required (ePHI never leaves your infrastructure)
  • NIST CSF 2.0 Core (NIST CSWP 29, Feb 2024) — 13 covered + 10 partial Subcategories across 106 of CSF 2.0's 107 Subcategories; Subcategory-level mapping (auditor-canonical, not high-level Function/Category claims)
  • PCI DSS v4.0.1 (PCI SSC, June 2024 errata; v3.2.1 retired March 31, 2024) — 19 covered + 9 partial + 39 OOS sub-requirements across 67 of ~250 (MVP-67); sub-requirement-level mapping for QSA Report on Compliance workflow; Defined-vs-Customized Approach discipline per Appendix E (15 Defined-only sub-requirements enforced at schema layer); CHD Scope operator-attested via CDE Data Flow Diagram per Req 1.2.4; Card-brand AOC enforcement priority view (Visa CISP / Mastercard SDP / Amex DSOP / Discover DISC)
  • ISO/IEC 27001:2022 (ISO + IEC, Oct 2022; 2013 edition retired Oct 31, 2025) — 17 covered + 14 partial + 62 OOS across 93 Annex A controls (the complete Annex A universe); per-Annex-A-code mapping auditor-canonical for ISO/IEC 17021-1 certification body assessors; Statement of Applicability per Clause 6.1.3.d discipline + ISMS Clauses 4-10 OOS-by-design with 7 Major Nonconformity classes
  • CIS Critical Security Controls v8 (CIS, May 2021; v8.1 errata June 2024) — 17 covered + 22 partial + 114 OOS across 153 Safeguards / 18 Controls; per-Safeguard mapping with the Implementation Group cumulative discipline (IG1=56 cyber-insurance baseline / IG2 cumulative=130 / IG3 cumulative=153); no-certification-body attestation discipline (INPUT to your CSAT / CIS-CAT Pro self-attestation, never "CIS certified"); Cloud Companion Guide v8 shared-responsibility + CIS-Hardened-Image substrate-evidence credit (4.1/4.2/4.6)
  • GDPR Article 32 (Security of Processing) (Regulation (EU) 2016/679) — 4 covered + 5 partial + 2 OOS across 11 Art. 32 sub-measure units; GDPR Article 32 infrastructure substrate only — NOT GDPR compliance (GDPR is a 99-article legal regime; Art. 32 security-of-processing is the only article an infrastructure scanner can substrate-evidence; the rest is operator-side, out of scope by design). Four-factor proportionality (substrate for your "appropriate to the risk" determination, never an absolute pass/fail); personal-data-scope attestation (pair with your Art. 30 records of processing); Art. 83(4) lower fine tier (€10M/2%, not the €20M/4% headline tier); Art. 32(3)/Art. 42 cloud-provider certification-inheritance
• 🔐 Cryptographically signed evidence — SHA-256 chain-of-custody + RFC 3161 trusted timestamps + Ed25519 suppression signing. Non-repudiation, not just integrity. Auditors can verify offline.
• 🏛️ Zero Data Exfiltration architecture — your scan data never leaves your infrastructure. Air-gapped deployment supported. AI analysis happens locally (Ollama) or via your own API keys. Important for PCI DSS CDE-isolation threat models.
• 🔗 Native GRC platform integration — push evidence directly to Vanta (live; Drata + Secureframe planned). Idempotent retries, per-tenant token rotation, rate-limit handling, signed-envelope round-trip integrity.
• 🗄️ WORM evidence storage — S3 Object Lock COMPLIANCE-mode for SEC Rule 17a-4(f) / FINRA 4511 retention compliance
• 📊 SLA / MTTR tracking + recurring-scan attestation — the Type II operating-effectiveness evidence auditors actually demand (not just point-in-time snapshots)
• 🎯 11 adversarial-audit Claude Code skills authored per the Per-Framework Adversarial-Audit Skill Pairing institutional pattern — Phase-4 Compliance/GRC chain 8-of-8 COMPLETE for all shipped frameworks (SOC 2 + HIPAA + NIST CSF + PCI DSS + ISO 27001 + CIS Controls v8 + GDPR Article 32 + GRC connector)

→ See sample EE scan output — full evidence pack against synthetic Acme Corp AWS account (no signup required) → Buy NSAuditor AI Enterprise Edition — $2k / $5k / $10k+ per year for 5 / 25 / unlimited seats + custom SLA. Onboarding call included.

Feature comparison

This repository is the Community Edition — fully functional, MIT-licensed, no restrictions, no telemetry. Pro and Enterprise features ship via the @nsasoft/nsauditor-ai-ee package and install alongside the CE binary once licensed.

→ Get Pro or Enterprise →

Quick Start

# Install globally
npm install -g nsauditor-ai

# See all flags, subcommands, and worked examples
nsauditor-ai --help

# Configure (optional — scans work fully offline without AI)
cat > .env << 'EOF'
AI_ENABLED=true
AI_PROVIDER=ollama              # openai | claude | ollama
OLLAMA_MODEL=llama3             # For local AI (no API key needed)
# OPENAI_API_KEY=sk-...         # Or use OpenAI
# ANTHROPIC_API_KEY=sk-ant-...  # Or use Claude
OPENAI_REDACT=true
EOF

# Scan a host with all plugins
nsauditor-ai scan --host 192.168.1.1 --plugins all

# Scan a subnet in parallel
nsauditor-ai scan --host 192.168.1.0/24 --plugins all --parallel 10

# Start the MCP server for AI assistants
nsauditor-ai-mcp

Or run without installing:

npx nsauditor-ai scan --host 192.168.1.1 --plugins all

Or clone and run from source:

git clone https://github.com/nsasoft/nsauditor-ai.git
cd nsauditor-ai
npm install
node --env-file=.env cli.mjs scan --host 192.168.1.1 --plugins all

Results land in ./out/<host>_<timestamp>/:

Works on Node 20+ (tested on Node 22).

Plugins

Core Scanners

Discovery Plugins

Pro/Enterprise Plugins (via @nsasoft/nsauditor-ai-ee)

28 enterprise plugins across AWS, GCP, and Azure substrate audits — all mapped to AICPA Trust Services Criteria 2017 (10 covered + 4 partial controls). EE plugins live in the disjoint 1000+ ID range; CE reserves 001-099. Once licensed, the EE package installs alongside the CE binary and discovers automatically.

→ Watch a sample scan run end-to-end — synthetic Acme Corp AWS account + home-office router. Real EE 0.6.7 output, no signup required. See the transitive SG chain reachability finding, the multi-region GuardDuty audit, the dnsmasq CVE detection, and what the signed evidence pack actually looks like.

→ Buy NSAuditor AI Enterprise Edition · $2k / $5k / $10k+ per year · 5 / 25 / unlimited seats · onboarding call included.

All EE plugins follow the same institutional plumbing pattern:

• Thread H _instrumentSdkClient wrap — per-API AccessDenied counter + ZDE structural guard (verb-prefix denylist regex blocks Get* / Retrieve* / Read* value-reading APIs at SDK boundary) + idempotency sentinel
• Throttle-retry — exponential-backoff retry on Throttling* / RequestLimitExceeded / TooManyRequestsException with per-command wall-clock budget
• Thread F conclude() field-selection allowlist — structured-data ZDE: only AWS-public-namespace identifiers + integer counts flow through to findings; customer policy content / key material / encrypted payloads NEVER propagate
• conservative_classifier_principle — emit INFO+evidenceGap with verification prompt when ARN-shape disambiguation needs a follow-up API call; vacuous PASS on partial substrate evidence is treated as the worst SOC 2 reporting outcome
• aws_string_case_normalization — trim + lowercase AWS-returned strings at SDK-helper boundary; protects against the 7+ recurrent classes of case-sensitivity fail-open (IAM Condition keys, Lambda runtimes, KMS aliases, Effect/Action discriminators, FULL_ADMIN sentinel, S3 region)

Running EE plugins (after nsauditor-ai license install <key>):

# Run a single EE plugin
nsauditor-ai scan --host aws --plugins 1130 --compliance soc2 --out evidence.json

# Run multiple EE plugins
nsauditor-ai scan --host aws --plugins 1030,1040,1070,1130 --compliance soc2

# Run all EE plugins (auto-discovered via plugin manager)
nsauditor-ai scan --host aws --plugins all --compliance soc2

# Tune plugin parameters (e.g., raise VPC-endpoint PAGE_CAP for large-fleet customers)
nsauditor-ai scan --host aws --plugins 1130 --plugin-opts '{"1130":{"vpcEndpointsPageCap":50}}'

Scoping the AWS audit to regions — --aws-region

By default an AWS audit runs against a single region (AWS_REGION, else us-east-1). The --aws-region <one|csv|all> flag controls which regions the regional plugins (security groups, EC2, RDS, KMS, Lambda, Secrets Manager, DynamoDB, CodePipeline/CodeBuild, Backup, SQS/SNS, VPC endpoints, ElastiCache, SES, Inspector/GuardDuty, CloudTrail) audit — each now audits every in-scope region, not just the configured one:

# A single region
nsauditor-ai scan --host aws --plugins all --compliance soc2 --aws-region us-east-1

# A comma-separated list of regions
nsauditor-ai scan --host aws --plugins all --compliance soc2 --aws-region us-east-1,eu-west-1,ap-southeast-2

# Every region enabled on the account (via DescribeRegions; static-list fallback on AccessDenied)
nsauditor-ai scan --host aws --plugins all --compliance soc2 --aws-region all

• Precedence: --aws-region flag › AWS_REGION (shell / --env file) › single-region default.
• Default (no flag, no AWS_REGION): scans one region and adds an informational "incomplete region coverage" note listing the enabled regions that were not scanned. It maps to no compliance control (a disclosure, not a finding — your posture is unchanged); pass --aws-region all for full coverage.
• Unknown region: the explicit flag fails fast on an unrecognized region code (set NSA_AWS_REGION_ALLOW_UNKNOWN=1 to permit a brand-new region); an AWS_REGION-derived value warns and proceeds.
• Global services (IAM, account-level S3 enumeration) are audited once regardless of --aws-region; the S3 auditors resolve each bucket's own region and skip + disclose buckets outside the scoped set (closing latent cross-region false-cleans).
• MCP scan_cloud (Claude Desktop / Claude Code): the same scoping is a regions argument — omit it to scan the server-configured AWS_REGION, or pass ["all"] (or a region-code list like ["us-east-1","eu-west-1"]) to fan out. Omitting does not fan out, so a single tool-call stays within Desktop's timeout.

The auditor evidence pack is emitted under out/ — cover-page Scope Attestation, SHA-256 chain-of-custody sidecars, RFC 3161 trusted-timestamps, suppression workflow, identity verification. EE is available at www.nsauditor.com/ai/pricing.

How Results Are Fused

The Result Concluder (plugin 008) merges all plugin outputs into a normalized structure:

1. Imports each plugin's conclude() adapter to get normalized ServiceRecord objects
2. Merges services by (protocol, port), preferring authoritative records
3. Selects OS — OS Detector result first, then high-signal hints (Windows services, HTTP tokens), finally TTL fallback
4. Produces a unified { summary, host, services, evidence } output
5. Enriches host details with names from mDNS, UPnP, NetBIOS; MAC + vendor from ARP

AI Analysis

NSAuditor AI supports three AI providers for vulnerability analysis. All providers work in all tiers — CE, Pro, and Enterprise. AI is optional; the platform is fully functional without it.

Providers: OpenAI (GPT-4o), Anthropic Claude (Sonnet/Opus), Ollama (fully local)

What changes by tier is the prompt content, not the provider:

• CE — basic scan-summary prompts (services, ports, versions detected). Local MITRE ATT&CK mapping via utils/attack_map.mjs: service-context-aware CVE→technique mapping (mapCveToAttack, mapServiceToAttack), plus a CWE→technique fallback (cweToMitre, cwesToMitre) covering ~30 common CWEs (auth, crypto, injection, memory safety, info disclosure, privilege escalation, web). The CWE fallback fires only when CVE-derived mapping returns no techniques — useful for findings annotated with evidence.cwe[] (per FindingSchema v0.1.13+) but no CVE context, such as agent-detected misconfigurations and compliance-flagged weaknesses
• Pro — intelligence-enriched prompts (CVE matches, MITRE techniques, risk scores, verification status injected into the prompt). Same API call, vastly better output
• Enterprise — Pro prompts + compliance context

Redaction: Before any data reaches an AI API, the redaction pipeline masks IP addresses, MAC addresses, serial numbers, and configurable confidential keywords. Admin RAW reports retain full detail for internal review.

# .env
AI_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-...        # Your key — never sent to Nsasoft
ANTHROPIC_MODEL=claude-sonnet-4-6
OPENAI_PROMPT_MODE=optimized
OPENAI_REDACT=true

For fully local AI (no external API calls), use Ollama:

AI_PROVIDER=ollama
OLLAMA_MODEL=llama3

Continuous Monitoring (CTEM)

Watch mode enables periodic rescanning with delta detection and webhook alerts:

nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
  --watch --interval 15 \
  --webhook-url https://hooks.example.com/security \
  --alert-severity high

• Scheduling with configurable intervals and concurrency control
• Delta detection — new, removed, and changed services highlighted between cycles
• Webhook alerts — JSON POST with retry (exponential backoff, no retry on 4xx)
• SSRF protection — private, loopback, and cloud metadata addresses blocked at the scan entry point and inside sendWebhook(). Set NSA_ALLOW_ALL_HOSTS=1 to scan RFC 1918 ranges (local network auditing)
• Scan history stored in .scan_history/ (JSONL format, 7-day retention in CE)

MCP Server

Heads-up on AI-client fabrication. Some MCP clients (notably Claude Desktop) can silently substitute AI-generated responses if a tools/call times out, instead of surfacing the failure. Every response from this server now ends with a ── Verified MCP call ── footer and a UUID. Run nsauditor-ai mcp verify-call <id> to confirm a response is genuine before acting on it. Full background and workflow: docs/mcp-verification.md. When in doubt, generate compliance evidence via the CLI (nsauditor-ai scan ...), which has no MCP client in the path.

Expose scanning capabilities to AI assistants via Model Context Protocol:

nsauditor-ai-mcp
# or
npx nsauditor-ai-mcp

CE Tools:

Pro Tools (requires license key + @nsasoft/nsauditor-ai-ee):

Enterprise Tools (requires Enterprise license):

scan_cloud runs the requested clouds' plugins concurrently (default up to 20 at once, 25s per-plugin timeout) so a full multi-service cloud audit completes within Claude Desktop's ~60s tool-call limit. Tune with CLOUD_SCAN_CONCURRENCY (default 20) and CLOUD_PLUGIN_TIMEOUT_MS (default 25000) in the server env. The network PLUGIN_TIMEOUT_MS still governs scan_host / network scans. Read the result's findingsSummary (per-provider severity counts + a CRITICAL/HIGH list) for the findings; audited:false / notes / pluginsRan:0 still mean a cloud was NOT audited (never a clean pass). Pass providers:["aws"] to audit only the cloud named.

Full all-region AWS coverage fits Desktop's limit automatically. When you ask for "all regions" / "full coverage", the agent scans the enabled regions in small region-group batches (each within the ~60s window) rather than one long regions:["all"] call — so it completes without timing out, and you do not raise any timeout for it. Keep CLOUD_PLUGIN_TIMEOUT_MS under Desktop's ~60s tool-call cap (default 25000; raise to ~45000 only for very large accounts — a higher per-plugin cap can let one plugin run past Desktop's wall and cause a hard timeout). For unbounded multi-region scans use the CLI (nsauditor-ai scan … --aws-region all), which has no MCP tool-call cap — there you can raise PLUGIN_TIMEOUT_MS (e.g. 90000) freely.

Security: SSRF protection on all host inputs (blocks RFC 1918, loopback, fc00::/7, cloud metadata), port validation (1–65535), CPE format enforcement, dependency injection for test isolation. Server-startup authentication is required — see next section.

Authentication (required)

The MCP server uses stdio transport, which means it runs as a child process of whatever client launches it. Without authentication, any process running as your user could spawn the server and use its tools — including the Pro/Enterprise tools that talk to AWS, generate compliance reports, and access your scan history. A per-operator shared-secret check at server startup closes this gap.

One-time setup (run once per machine after npm install -g nsauditor-ai):

nsauditor-ai mcp install-key

This generates a 256-bit auth key, stores it in the macOS Keychain (or ~/.nsauditor/.env mode 0600 on Linux/Windows), and prints the Claude Desktop config snippet for you to paste. The MCP server refuses to start unless the env-presented key matches the stored key (constant-time compare; mismatch produces an actionable error pointing at this command).

Inspect / verify:

nsauditor-ai mcp status                  # shows storage source WITHOUT printing the key
nsauditor-ai mcp print-key --confirm     # reveals the key (use sparingly; refuses non-TTY output)
nsauditor-ai mcp rotate-key --confirm    # generates a new key (invalidates old one immediately)

Why the Claude Desktop config snippet uses keychain: indirection on macOS: the printed snippet looks like "NSA_MCP_AUTH_KEY": "keychain:NSA_MCP_AUTH_KEY" rather than the literal key value. The MCP server resolves the placeholder from your Keychain at startup. Net effect: the secret never lands in ~/Library/Application Support/Claude/claude_desktop_config.json (which is mode 0644 by default — readable by other local users and any macOS app with Documents/Application Support entitlement). On Linux/Windows where there's no Keychain equivalent, the snippet uses the literal key with an explicit chmod 600 warning.

Threat model — what this defends, what it doesn't:

Linux note (/proc/<pid>/environ): on modern Linux, /proc/<pid>/environ is readable only by the process owner (the same user that spawned the MCP server). Other users on a multi-user system cannot read your MCP auth key from /proc under default kernel settings. The realistic remaining risks are:

• Container scenarios where multiple "users" share the same kernel UID (e.g., a Docker container running as root, with multiple processes inside) — the secret is visible to any process in the same UID namespace. Mitigation: run the MCP server in its own container / user.
• Audit/SIEM agents with broad read access (e.g., auditd configured to log child-process env). Mitigation: review your auditd rules; modern setups exclude env from logs by default.
• The legacy ps eww command on older POSIX systems (modern ps respects /proc permissions).

A shell-wrapper indirection script (read key from ~/.nsauditor/.env at exec time, pass to child) was considered for v1 but does NOT solve the underlying issue: the spawned MCP server still needs the key in its env to perform the auth check, so it appears in /proc/<server-pid>/environ regardless of how the parent process obtained it. v2 may add libsecret integration on Linux to mirror the macOS Keychain indirection model.

Rotation cadence: keys older than 90 days emit a soft warning at every server startup AND in nsauditor-ai mcp status output. SOC 2 CC6.1 / CC6.7 reviewers expect a credential-rotation cadence; rotate with nsauditor-ai mcp rotate-key --confirm and update Claude Desktop config with the new key.

Escape hatch for CI / dev (operator-acknowledged risk; emits a stderr warning every startup):

NSA_MCP_AUTH_DISABLE=1 nsauditor-ai-mcp

Claude Desktop Setup

First install the package globally:

npm install -g nsauditor-ai
nsauditor-ai mcp install-key   # required before MCP server will start

Then add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "nsauditor-ai": {
      "command": "nsauditor-ai-mcp",
      "env": {
        "NSA_MCP_AUTH_KEY": "keychain:NSA_MCP_AUTH_KEY",
        "NSA_ENV_FILE": "~/envs/prod-aws.env",
        "AI_PROVIDER": "claude",
        "ANTHROPIC_API_KEY": "keychain:ANTHROPIC_API_KEY"
      }
    }
  }
}

The exact NSA_MCP_AUTH_KEY value to paste is printed by nsauditor-ai mcp install-key — on macOS it's the keychain:NSA_MCP_AUTH_KEY placeholder shown above; on Linux/Windows it's the literal key value (and you should chmod 600 your config file).

• NSA_MCP_AUTH_KEY — required (see Authentication section above)
• NSA_ALLOW_ALL_HOSTS=1 — required to scan private/RFC 1918 addresses (e.g., 192.168.x.x)
• PLUGIN_TIMEOUT_MS=5000 — reduces per-plugin timeout to 5s so the full scan completes within Claude Desktop's 60s MCP limit
• CLOUD_SCAN_CONCURRENCY — max cloud plugins run at once by scan_cloud (default 20).
• CLOUD_PLUGIN_TIMEOUT_MS — per-plugin timeout for scan_cloud (default 25000; independent of the network PLUGIN_TIMEOUT_MS). Keep it under Desktop's ~60s tool-call cap (raise to ~45000 only for very large accounts); full all-region coverage is delivered by automatic region-batching, so it needs no timeout increase.
• AI_PROVIDER and API key — optional, enables AI-powered analysis of scan results

NSA_ENV_FILE — point the MCP server at an environment file

Instead of inlining every scan variable in the config above, set NSA_ENV_FILE to a dotenv file and keep the cloud credentials, CLOUD_PROVIDER, and scan tuning there. To scan a different account or cloud, change the one path (or swap the file) and restart Claude Desktop — no JSON editing.

# ~/envs/prod-aws.env   (chmod 600 — this holds credentials)
CLOUD_PROVIDER=aws
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
NSA_ALLOW_ALL_HOSTS=1
PLUGIN_TIMEOUT_MS=5000

• The file is loaded at server startup; values in it override the same keys in the config env block.
• Fail-fast: if the path is missing or points at an AWS credentials/INI file, the server refuses to start (it will not silently fall back to ambient credentials and scan the wrong account). The error is written to the MCP server's stderr log.
• The file is the authoritative scan target: ambient provider credentials (e.g. an old account's AWS_* keys still in the config env block) that the file does not set are cleared, so a partial file can't silently scan a leftover account. Instance-role / ADC identity is untouched.
• NSA_MCP_AUTH_KEY and NSAUDITOR_LICENSE_KEY are resolved before the file and must stay inline (or in ~/.nsauditor/.env); if present in NSA_ENV_FILE they are ignored.

Claude Code Setup

nsauditor-ai mcp install-key   # required before MCP server will start
claude mcp add nsauditor-ai \
  --env NSA_MCP_AUTH_KEY=keychain:NSA_MCP_AUTH_KEY \
  -- npx nsauditor-ai-mcp

To target an environment via the file, add it as an env value:

claude mcp add nsauditor-ai \
  --env NSA_MCP_AUTH_KEY=keychain:NSA_MCP_AUTH_KEY \
  --env NSA_ENV_FILE=~/envs/prod-aws.env \
  -- npx nsauditor-ai-mcp

(On Linux/Windows, replace the keychain:NSA_MCP_AUTH_KEY placeholder with the literal key printed by install-key.)

Troubleshooting MCP authentication

"MCP authentication is not configured" at server startup → run nsauditor-ai mcp install-key. If you set NSA_MCP_AUTH_DISABLE=1 in CI by intent, that's fine — but check that you didn't forget it in your shell rc.

"NSA_MCP_AUTH_KEY env var is not set, but a key is configured in storage" → the server found a key in your Keychain (or ~/.nsauditor/.env) but the spawning client didn't pass NSA_MCP_AUTH_KEY in the env block. Update your Claude Desktop / Claude Code config to include the env value (use nsauditor-ai mcp install-key output as a reference snippet).

"NSA_MCP_AUTH_KEY env var does not match the key configured in storage" → most often means you ran nsauditor-ai mcp rotate-key --confirm but didn't update Claude Desktop config with the new key. Run nsauditor-ai mcp status to confirm storage source, then either re-paste the new key or use keychain:NSA_MCP_AUTH_KEY indirection (macOS only) so future rotations don't require a config change.

"MCP_AUTH uses keychain: indirection but the referenced Keychain entry could not be read" → typically a headless macOS / SSH-only CI runner where there's no GUI session to approve Keychain access. Replace the keychain: placeholder with the literal key value (or move auth to ~/.nsauditor/.env with mode 0600).

mcp status reports keychain-locked → distinct from unconfigured: the Keychain entry exists but the security daemon refused to unlock without a GUI prompt. Same workarounds as the previous error: approve a Keychain GUI prompt, replace keychain: indirection with the literal key, or move auth to ~/.nsauditor/.env.

mcp status shows ⚠ Created: ... — > 90d threshold → key is older than the 90-day rotation cadence. Run nsauditor-ai mcp rotate-key --confirm and update Claude Desktop config with the new key. Server emits the same warning to stderr at every startup.

Claude Desktop reports "Current tier: CE" despite nsauditor-ai license --status showing Enterprise → first run nsauditor-ai mcp tier to get the ground-truth tier the MCP server actually resolves at startup. If mcp tier reports enterprise but Claude Desktop's list_plugins says CE, the AI client is synthesizing the response without actually calling the tool — see docs/mcp-verification.md and verify any suspicious response with nsauditor-ai mcp verify-call <id>.

If mcp tier itself reports CE → genuine resolution failure. Inspect the license storage:

nsauditor-ai license --status
security find-generic-password -s nsauditor-ai -a NSAUDITOR_LICENSE_KEY -w 2>&1 | head -c 30

If license is in ~/.nsauditor/.env but not in Keychain on macOS, re-run nsauditor-ai mcp install-key — the auto-mirror writes the license to Keychain so Claude Desktop's child process can read it via the keychain: indirection.

Secure Credential Storage

Store API keys in the macOS Keychain instead of plaintext .env files:

# Store keys
nsauditor-ai security set ANTHROPIC_API_KEY
nsauditor-ai security set OPENAI_API_KEY

# List stored keys (masked)
nsauditor-ai security list

# Delete a key
nsauditor-ai security delete OPENAI_API_KEY

Then reference them with the keychain: prefix in .env or Claude Desktop config:

ANTHROPIC_API_KEY=keychain:ANTHROPIC_API_KEY

"env": {
  "ANTHROPIC_API_KEY": "keychain:ANTHROPIC_API_KEY"
}

The keychain: prefix works anywhere an API key is read — CLI, MCP server, or programmatic API.

CLI Reference

nsauditor-ai scan [options]
nsauditor-ai license install <KEY>
nsauditor-ai license <--status | --capabilities | --plugins>
nsauditor-ai security <set|delete|list|get> <KEY>
nsauditor-ai validate
nsauditor-ai --help        (or -h, or `help`)
nsauditor-ai --version     (or -v, or `version`)

Run nsauditor-ai --help (or -h, or just nsauditor-ai help) for a quick reference of subcommands, flags, env vars, and worked examples — works without a license key configured. --version / -v prints nsauditor-ai <version> and exits 0.

* Either --host or --host-file is required.

Host Formats

Examples

# Full scan with self-signed cert tolerance
nsauditor-ai scan --host 192.168.1.1 --plugins all --insecure-https

# Parallel subnet scan
nsauditor-ai scan --host 192.168.1.0/24 --plugins all --parallel 10

# Targeted scan: TLS + HTTP + DNS + OS detection
nsauditor-ai scan --host 192.168.1.8 --plugins 011,006,009,013,008

# SARIF output for CI/CD, fail on high+ findings
nsauditor-ai scan --host 10.0.0.5 --plugins all --output-format sarif --fail-on high

# Markdown report — paste straight into a GitHub issue, Slack thread, or chat
nsauditor-ai scan --host 10.0.0.5 --plugins all --output-format md

# Scan custom non-standard ports (e.g. an MCP server on 8090, dev service on 5000)
# Uses --ports to add to the default scan list — additive, not replacing
nsauditor-ai scan --host 192.168.1.28 --plugins all --ports 8090,5000/tcp

# Continuous monitoring with webhook alerts
nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
  --watch --interval 30 \
  --webhook-url https://hooks.example.com/alerts \
  --alert-severity high

# Hosts from file with 4 parallel scans
nsauditor-ai scan --host-file targets.txt --plugins all --parallel 4

Pre-flight validate command

nsauditor-ai validate runs a fast (<2s) environment check without scanning anything. Useful for CI/CD setups, Docker HEALTHCHECK probes, and first-time-user diagnosis. Each check returns a status; the overall exit code is 0 (all OK), 1 (warnings), or 2 (errors).

Checks: plugin discovery, license JWT validation (if key set), AI provider configuration, output-directory writability + free space, DNS resolution.

# Human-readable output
nsauditor-ai validate

# Machine-readable JSON for CI parsing
nsauditor-ai validate --json

Docker HEALTHCHECK example:

HEALTHCHECK --interval=60s --timeout=5s --start-period=10s --retries=3 \
  CMD nsauditor-ai validate --json | grep -q '"overall": "ok"' || exit 1

Configuration

Environment Variables (.env)

AI configuration:

AI_ENABLED=false                     # Set to true to enable AI analysis
AI_PROVIDER=openai                   # openai | claude | ollama
OPENAI_API_KEY=sk-...               # Your OpenAI key
OPENAI_MODEL=gpt-4o-mini
ANTHROPIC_API_KEY=sk-ant-...        # Your Claude key
ANTHROPIC_MODEL=claude-sonnet-4-6
OPENAI_PROMPT_MODE=optimized        # basic | pro | optimized
OPENAI_REDACT=true                  # Redact before sending to AI
CONFIDENTIAL_KEYWORDS=serial,password,token,secret

Plugin-specific:

TLS_SCANNER_TIMEOUT_MS=8000
TLS_SCANNER_VERSIONS=TLSv1,TLSv1.1,TLSv1.2,TLSv1.3
TLS_SCANNER_PORTS=443:https,465:smtps,563:nntps,993:imaps,995:pop3s
OPENSEARCH_SCANNER_TIMEOUT_MS=6000
OPENSEARCH_SCANNER_INSECURE_TLS=false
DNS_TIMEOUT_MS=800
HTTP_PROBE_TIMEOUT_MS=6000
WEBAPP_DETECTOR_TIMEOUT_MS=6000
SMB_NULL_SESSION=false
SMB_NULL_SESSION_TIMEOUT=5000
ENABLE_SYN_SCAN=false
SYN_SCAN_PORTS=
SYN_SCAN_TIMEOUT=30000
PING_FALLBACK=true
PING_FALLBACK_TIMEOUT=2000

Licensing (Pro/Enterprise):

NSAUDITOR_LICENSE_KEY=pro_eyJhbGci...   # Pro or Enterprise license key
NSAUDITOR_PLUGIN_PATH=                   # Additional plugin directories (colon-separated)

Security overrides:

NSA_ALLOW_ALL_HOSTS=1    # Allow scanning private/RFC 1918 ranges (local network auditing)
NSA_AI_TIMEOUT_MS=120000 # AI provider call timeout in ms (default: 120000 = 2 min)

Debug:

NSA_VERBOSE=true      # Verbose PluginManager logging
DEBUG_MODE=true       # Plugin-level debug output

Developing Plugins

NSAuditor AI uses a plug-and-play plugin system. Plugins are auto-discovered from ./plugins/ — no registration needed.

Plugin Interface

// plugins/0xx_my_scanner.mjs
export default {
  id: "0xx",
  name: "My Scanner",
  description: "What it probes",
  priority: 300,                    // Lower runs first; Concluder is 100000
  protocols: ["tcp"],
  ports: [1234],

  requirements: {                   // All optional
    host: "up",                     //   Skip if host unreachable
    tcp_open: [1234],               //   Skip if port not open
  },

  // requiredCapabilities: ["enterprise"],  // EE plugins only

  async run(host, port, opts = {}) {
    const { context } = opts;       // Shared state + OUI helpers
    return {
      up: true,
      program: "my-service",
      version: "1.0.0",
      data: [{
        probe_protocol: "tcp",
        probe_port: 1234,
        probe_info: "OK",
        response_banner: "my-service/1.0.0"
      }]
    };
  },

  // Adapter for Result Concluder
  conclude({ result, host }) {
    return [{
      port: 1234,
      protocol: "tcp",
      service: "my-service",
      program: result.program,
      version: result.version,
      status: "open",
      info: null,
      banner: result.data?.[0]?.response_banner || null,
      source: "my-scanner",
      evidence: result.data || [],
      authoritative: true
    }];
  },

  authoritativePorts: new Set(["tcp:1234"])
};

Plugin Tips

• Use env-driven timeouts for all network calls
• Always close sockets on all code paths with a small post-banner linger
• Keep probe_info and response_banner concise — full detail goes in evidence
• Use authoritativePorts to take precedence over other plugins for the same port
• Plugins can also be loaded from external npm packages via NSAUDITOR_PLUGIN_PATH

Pro & Enterprise Activation

After purchasing at nsauditor.com/ai/pricing, you'll receive an email with your license key and an npm install command. Two steps:

# 1. Install EE package (one-time, token included in email)
npm install -g @nsasoft/nsauditor-ai-ee --//registry.npmjs.org/:_authToken=npm_xxxxx

# 2. Set your license key
export NSAUDITOR_LICENSE_KEY=pro_eyJhbGci...

Verify:

nsauditor-ai license --status
# ✓ Pro license active | Expires: 2027-04-04

nsauditor-ai license --capabilities
# ✓ intelligenceEngine  ✓ riskScoring  ✓ proAI  ✓ advancedCTEM ...

License keys are delivered automatically via Stripe webhook — no manual processing. Subscription renewals generate a fresh key and email it to you before the current one expires.

No license key? Everything in this repository works perfectly without one. The CE is not crippled — it's a complete, production-ready security scanner.

→ Pricing · Enterprise contact

Tests

Run all 925+ tests:

npm test

Run a specific suite:

node --test tests/tls_scanner.test.mjs
node --test tests/port_scanner.test.mjs
node --test tests/result_concluder.test.mjs
node --test tests/os_detector.test.mjs
node --test tests/mcp_server.test.mjs
node --test tests/attack_map.test.mjs

Tests use Node.js built-in --test runner with the assert module — no external test framework. Each test is self-contained with inline fixtures and lightweight network stubs.

Troubleshooting

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick version:

1. Fork the repo and create a feature branch
2. Add a Signed-off-by line to your commits (git commit -s)
3. Include tests for any new or changed behavior
4. Submit a PR

All contributions to this repository are under the MIT license. For Enterprise Edition contributions, see the nsauditor-ai-ee repository which requires a signed IP Assignment Agreement.

What we won't accept: Code that phones home, transmits scan data externally, or weakens the Zero Data Exfiltration boundary.

Requesting or Contributing Plugins

Check ./plugins/ first. If a plugin doesn't exist:

• Request it: Open an issue with scope, target ports, protocols, and example banners
• Build it: Follow the plugin interface above, include tests, and update this README

Commonly requested plugins: RDP, VNC, SMTP/POP3/IMAP, MySQL/PostgreSQL/MSSQL/MongoDB/Redis, LDAP, RabbitMQ/Kafka/MQTT, SIP, NTP, Modbus/S7/DNP3/BACnet, WordPress/Jenkins/GitLab detectors.

Architecture

For the full technical architecture, see ARCHITECTURE.md.

Tech stack: Node.js 20+ · ES Modules (.mjs) · OpenAI + Anthropic SDKs · Node.js built-in test runner · MCP stdio transport

Design patterns: Factory (PluginManager.create) · Strategy (orchestrated/legacy execution) · Context (shared state) · Adapter (plugin conclude()) · Guard Clause (requirement gating) · Capability gating (CE/Pro/EE) · Semaphore (concurrency control) · Delta (scan history diff) · Boundary Guard (SSRF/injection protection) · Finding Queue (structured intermediate format) · Parallel Agents (concurrent specialized analysis) · Verification Probes (safe non-destructive confirmation)

Privacy & Security

NSAuditor AI is built on a Zero Data Exfiltration (ZDE) architecture:

• No telemetry. No analytics. No usage tracking. No phone-home.
• No data processing. Nsasoft US LLC never sees, stores, or processes your scan results.
• AI is opt-in. External AI calls use your own API keys. Redaction runs locally first.
• License validation is offline. JWT signature verified locally with an embedded public key.
• Fully air-gappable. Every feature works without internet access (Enterprise includes offline NVD feeds).

Nsasoft US LLC is not a data processor, data controller, or business associate under any data protection regulation. You own and control all data produced by NSAuditor AI.

License

MIT — see LICENSE for the full text.

© 2024-present Nsasoft US LLC. "NSAuditor" and "NSAuditor AI" are trademarks of Nsasoft US LLC.

The Pro and Enterprise features available via @nsasoft/nsauditor-ai-ee are licensed under a separate proprietary license. See www.nsauditor.com/ai/pricing for details.