From your license key to your first audit report

A clean, linear getting-started path for new NSAuditor AI Enterprise customers: install → activate → configure → scan → read the results. Everything runs on your machine — no data leaves your network. This guide reflects the current shipped product, EE 0.17.0, including the new --aws-region multi-region scoping and the Claude Desktop / MCP workflow.

EE 0.17.0 LIVE on npm 28 enterprise plugins SOC 2 · HIPAA · NIST CSF 2.0 · PCI DSS · ISO 27001 · CIS v8 Zero data exfiltration

WHAT YOU RECEIVED IN YOUR PURCHASE EMAIL

After buying NSAuditor AI Enterprise from nsauditor.com/ai/enterprise, your confirmation email contains two things you'll need below:

• your Enterprise license key — enterprise_eyJhbGciOiJFUzI1NiIs...
• your npm access token — npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (read-only; @nsasoft/nsauditor-ai-ee is a private, restricted npm package).

The 10 steps

Install Node.js (LTS)
Authenticate with npm
Install the platform + Enterprise package
Activate your license
Configure AI & cloud credentials
Verify activation
Run your first Enterprise scan
Scope the AWS audit to regions
Use NSAuditor AI with Claude Desktop (MCP)
Read the results & troubleshoot

PREREQUISITE

0Install Node.js (LTS)

NSAuditor AI runs on Node.js 20 LTS or newer. Download the installer from the official Node.js Downloads page, choose the LTS build (not "Current" — LTS is the stable line), and run the installer that matches your OS (Windows .msi / macOS .pkg).

verify node

$ node --version   # v20.x or newer
$ npm --version

STEP 1 / NPM

1Authenticate with npm

@nsasoft/nsauditor-ai-ee is a private (restricted) package. Configure the read-token from your license email so npm can download it.

npm auth

# Global: set the auth token for the npm registry
$ npm config set //registry.npmjs.org/:_authToken npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Or, scoped to your home ~/.npmrc
$ echo "//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" >> ~/.npmrc

STEP 2 / INSTALL

2Install the platform + Enterprise package

Install all three packages: the free Community Edition runtime, the agent skill (for Claude Desktop / Claude Code), and the Enterprise package — your 28 cloud plugins and six compliance frameworks.

install the trio

$ npm install -g nsauditor-ai@latest \
                  nsauditor-ai-agent-skill@latest \
                  @nsasoft/nsauditor-ai-ee@latest

STEP 3 / LICENSE

3Activate your license

One command — no shell-rc edits. The CLI verifies the JWT signature before persisting, and stores the key in the macOS Keychain (or ~/.nsauditor/.env mode 0600 on Linux/Windows).

license install

$ nsauditor-ai license install enterprise_eyJhbGciOiJFUzI1NiIs...
✓ Enterprise license installed
  Stored at: macOS Keychain (service=nsauditor-ai)
  Org: you@example.com   Seats: 5
  Expires: 2027-04-04T...

CI/CD ALTERNATIVE

An environment variable also works and takes highest priority in the multi-source loader: export NSAUDITOR_LICENSE_KEY=enterprise_eyJ...

⚠ macOS RESET GOTCHA

If you ever hit a license_id_mismatch on macOS, clear both ~/.nsauditor/license-state.json and the Keychain entry NSAUDITOR_LICENSE_ID (Keychain wins on read). On Linux/Windows it is file-only.

STEP 4 / CONFIGURE

4Configure AI & cloud credentials

Create a dotenv file with your AI provider key and the cloud credentials for the account(s) you want to audit. Everything stays on your machine — nothing is sent to NSAuditor. Keep one .env per account (e.g. ~/envs/dev.env, ~/envs/prod.env) and select it per scan with --env (Step 6).

~/envs/prod.env

# ── AI provider (used for the optional AI analysis layer) ──
AI_ENABLED=true
AI_PROVIDER=claude                       # openai | claude | ollama
ANTHROPIC_API_KEY=sk-ant-...             # or keychain:ANTHROPIC_API_KEY on macOS — your key, stays local
ANTHROPIC_MODEL=claude-sonnet-4-20250514

# ── Which cloud(s) this file audits ──
CLOUD_PROVIDER=aws,gcp,azure

# ── AWS ──
AWS_ACCOUNT_ID=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1

# ── Azure ──
AZURE_CLIENT_ID=
AZURE_CLIENT_SECRET=
AZURE_TENANT_ID=
AZURE_SUBSCRIPTION_ID=

# ── GCP (Application Default Credentials) ──
GOOGLE_CLOUD_NUMBER=
GOOGLE_CLOUD_PROJECT_ID=
GOOGLE_APPLICATION_CREDENTIALS=/Users/myuser/.config/gcloud/application_default_credentials.json
GOOGLE_IMPERSONATE_SERVICE_ACCOUNT=your@project-id

STEP 5 / VERIFY

5Verify activation

license status

$ nsauditor-ai license --status
✓ Enterprise license active | Org: you@example.com | Seats: 5 | Expires: 2027-04-04

STEP 6 / FIRST SCAN

6Run your first Enterprise scan

The headline use case is a cloud audit: point NSAuditor at a cloud account and get one evidence pack mapped across the compliance frameworks you ask for.

cloud audit recipes

# One dotenv file per account (credentials load for THIS scan only)
$ nsauditor-ai scan --host aws --env ~/envs/dev.env     --plugins all --compliance soc2 --out out/aws-dev
$ nsauditor-ai scan --host aws --env ~/envs/prod.env    --plugins all --compliance soc2 --out out/aws-prod

# Or a named profile from ~/.aws/credentials (no .env needed)
$ nsauditor-ai scan --host aws --aws-profile prod --plugins all --compliance soc2 --out out/aws-prod

# GCP / Azure per-account via --env (key-file path / service-principal vars live in the file)
$ nsauditor-ai scan --host gcp   --env ~/envs/gcp-prod.env   --plugins 1021 --compliance soc2,cis-v8 --out out/gcp-prod
$ nsauditor-ai scan --host azure --env ~/envs/azure-prod.env --plugins 1022 --compliance soc2        --out out/azure-prod

--host aws|gcp|azure + --plugins all auto-scopes to only that cloud's plugins (sentinel-host auto-scoping); other clouds are skipped and logged.
--compliance takes a CSV of any of the six frameworks: soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8.
A missing --env file is a hard error (fail-fast, never a silent skip).

A directory listing of the signed audit-evidence output files NSAuditor AI EE writes per scan — per-framework reports plus RFC 3161 timestamps and SHA-256 chain-of-custody sidecars. — A sample of the audit-evidence output files a scan produces.

STEP 7 / NEW IN EE 0.17.0

7Scope the AWS audit to regions — `--aws-region`

By default an AWS scan covers a single region (AWS_REGION, else us-east-1). The --aws-region <one|csv|all> flag controls which regions the regional auditors cover — and each now audits every in-scope region, with genuine per-region fan-out (security groups, EC2, RDS, KMS, Lambda, Secrets Manager, DynamoDB, CodePipeline/CodeBuild, Backup, SQS/SNS, VPC endpoints, ElastiCache, SES, Inspector/GuardDuty, and CloudTrail).

--aws-region <one|csv|all>

# 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 (DescribeRegions; static-list fallback on AccessDenied)
$ nsauditor-ai scan --host aws --plugins all --compliance soc2 --aws-region all

What a scoped run looks like, end to end:

per-region fan-out

$ nsauditor-ai scan --host aws --plugins all --compliance soc2 \
    --aws-region us-east-1,eu-west-1,ap-southeast-2 --out out/aws-prod

[region] scope = flag-list · 3 regions requested → resolving…
[region] scanning us-east-1, eu-west-1, ap-southeast-2  (regional plugins fan out per-region)
[plugin] AWS EC2 SG Perimeter Auditor (1170) ......... 3 regions · 5 findings
[plugin] AWS RDS Auditor (1140) ...................... 3 regions · 2 findings
[plugin] AWS IAM Deep Auditor (1030) ................. global · audited once
[plugin] AWS S3 Security Auditor (1020) .............. per-bucket region resolved · 6 findings
✓ scanScope: regionsScanned=[us-east-1, eu-west-1, ap-southeast-2]  regionsWithError=[]

›
Precedence
--aws-region flag › AWS_REGION (shell / --env file) › single-region default.
›
No flag and no AWS_REGION
One region is scanned and the report adds an informational "incomplete region coverage" advisory listing the enabled regions that were not scanned. It maps to no compliance control — a disclosure, not a finding, so your posture is unchanged. Pass --aws-region all for full coverage.
›
Unknown region → fail fast
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 audited once
IAM and account-level S3 enumeration run 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.

ℹ️ THE INCOMPLETE-COVERAGE ADVISORY

> Incomplete region coverage — 16 enabled region(s) not scanned (eu-west-1, ap-south-1, …). Re-run with --aws-region all (or set AWS_REGION) for full coverage.

STEP 8 / CLAUDE DESKTOP

8Use NSAuditor AI with Claude Desktop (MCP)

Run audits conversationally from Claude Desktop — "Audit my AWS account" — via the MCP server bundled with the package.

1 · Add the skill

In Claude Desktop go to Customize → Skills, click +, choose Create skill → Upload a skill, and upload SKILL.md from the @nsasoft/nsauditor-ai-ee package (SKILL.md on GitHub).

2 · Configure Claude Desktop environment variables

macOS example, using Keychain references:

Claude Desktop · MCP server env

NSA_ENV_FILE=~/envs/dev.env
MCP_TIMEOUT=180000
AI_PROVIDER=claude
ANTHROPIC_API_KEY=keychain:ANTHROPIC_API_KEY
NSA_ALLOW_ALL_HOSTS=1
PLUGIN_TIMEOUT_MS=90000
CLOUD_PLUGIN_TIMEOUT_MS=45000
NSA_MCP_AUTH_KEY=keychain:NSA_MCP_AUTH_KEY
NSAUDITOR_LICENSE_KEY=keychain:NSAUDITOR_LICENSE_KEY

⚠ TIMEOUT TUNING

Claude Desktop enforces a hard ~60s per-tool-call limit that MCP_TIMEOUT does not extend (that knob only governs server startup). Keep CLOUD_PLUGIN_TIMEOUT_MS under ~60s (e.g. 45000) so a slow plugin returns partial-with-disclosure rather than a hard timeout.

3 · Ask Claude to audit

Say "Audit my AWS account" (one cloud) or "Audit my AWS and Azure accounts" (several). For region scoping, the MCP scan_cloud tool takes the same scope as a regions argument:

Omit regions → audits only the server-configured AWS_REGION (one region; a single tool-call stays within Desktop's timeout). This is the default for a plain "audit my AWS account".
Name regions → pass exactly those (e.g. ["us-east-1","eu-west-1"]).
"All regions / every region / full coverage" → the agent discovers then batches: it scans the enabled regions in small groups across successive calls (each well within the ~60s limit) and reports the total number actually covered — rather than one long ["all"] call that could time out. You do not need to raise any timeout for this.

A snippet of a Claude Desktop response after asking it to audit an AWS account — surfacing per-severity finding counts and the audited region scope. — A snippet from a Claude Desktop AWS-account audit response.

STEP 9 / READ THE RESULTS

9Read the results & troubleshoot

✓
Evidence artifacts
Land under your --out directory, one timestamped folder per scan (e.g. aws_20260524_091331/), with the per-framework reports plus RFC 3161 trusted timestamps and SHA-256 chain-of-custody sidecars.
✓
Severities
Findings carry CRITICAL / HIGH / MEDIUM / LOW / INFO; the summary rolls them up per provider.
✓
"0 findings" is NOT automatically a clean pass
If a cloud could not be audited (no creds, plugin errored, region truncated), the report says so explicitly — it never reports a silent clean. Always confirm the scan actually audited the account.
✓
Region coverage
Check the scanScope block (and the incomplete-coverage advisory) to confirm which regions were actually scanned. Don't infer "all regions" from GuardDuty/Inspector findings — those enumerate regions internally regardless of scope.