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.32.9 — an
internal-provenance strip (a compliance report is a document you hand your auditor,
and ours carried internal engineering identifiers in finding titles, on the attestation cover page and in the
chain-of-custody record — measured on a rebuilt three-cloud evidence pack, 686 unexplained internal-marker
occurrences went to 0 across 105 files, with a positive control in the same run
still detecting 3,572 benign matches so the zero is a measurement, not an absence of looking) and a
false-clean closure (a cloud that could not be scanned no longer reads as a clean
audit — see the upgrade notes in Step 2). It is matrix-neutral —
still 28 EE plugins, and all seven coverage matrices unchanged in both counts and control-id membership. The prior
release, EE 0.32.8 (2026-07-28), was a capability-claim honesty pass that checked 27 advertised claims across the three published packages against the code and withdrew them, five of them rendered runtime strings that print verbatim into the assessor-facing evidence pack. This guide covers the install path below, including
--aws-region
multi-region scoping and the Claude Desktop / MCP workflow.
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).
First, register to receive your license key. AWS bills you, but it doesn't hand us your email —
so after subscribing on the
AWS Marketplace listing,
go to nsauditor.com/ai/marketplace/register
and enter your email, your AWS account ID, and your Agreement ID (agmt-…, shown in
AWS Console → AWS Marketplace → Manage subscriptions). Your ES256-signed license key is then emailed to you.
(The Usage Instructions on the listing carry the same steps.)
Your delivery channel is the Docker container image, not npm — the emailed key comes with the
docker login / docker pull / docker run commands instead of an npm token,
and the image already bundles the full platform (CE + Enterprise package).
Skip steps 0–3 and 5 below — run the container with your key instead:
docker run --rm -e NSAUDITOR_LICENSE_KEY="enterprise_eyJ..." <image> license --status.
Steps 4 (cloud credentials — pass them as -e vars or a mounted --env file),
6–7 (your first scan and --aws-region scoping), and 9 (reading the results) apply identically
inside the container. Billing, renewal, and cancellation for Marketplace orders are managed in your
AWS account (see the EULA's AWS Marketplace Addendum) — your license key still verifies fully offline.
The 10 steps
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).
$ node --version # v20.x or newer $ npm --version
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.
# 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
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 seven compliance frameworks.
$ npm install -g nsauditor-ai@latest \ nsauditor-ai-agent-skill@latest \ @nsasoft/nsauditor-ai-ee@latest
1 · Re-check any suppression rule that matches the evidence-gap finding by title. EE 0.32.9 changed the title of the evidence-gap finding. A suppression rule written against the old text stops matching, so those findings resurface rather than stay hidden. That is the safe direction — nothing is silently suppressed — but the change itself is silent: no error, no warning, the rule simply goes inert. Re-point any rule keyed to the old wording.
2 · Re-scan; do not re-process a scan captured before 0.32.9. An archived scan taken on an earlier build was captured before the fail-closed evidence-gap behavior existed, so re-processing it cannot reconstruct what a cloud that failed to start would now disclose. The engine warns when it re-processes such a scan. Run the scan again against the live account instead of re-rendering the old capture.
Why it matters: before 0.32.9, when a cloud plugin could not start — its optional SDK absent, its credentials unusable — it refused to report, and that refusal evaporated one layer up. The compliance report came out byte-identical to one where the scanner ran and found nothing: ten controls read PASS, no violation, no warning. The dangerous shape is ordinary — AWS and GCP scan for real, Azure's SDK is absent, and the combined pack reads as a clean three-cloud audit. Now every in-scope control of a cloud that could not be scanned carries a fail-closed evidence gap. Expect gaps where you previously saw passes; that is the corrected reading.
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).
$ 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...
An environment variable also works and takes highest priority in the multi-source loader:
export NSAUDITOR_LICENSE_KEY=enterprise_eyJ...
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.
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).
# ── 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-6 # ── 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
NSAuditor AI performs read-only auditing — it reads configuration and metadata only and never needs create, write, modify, or delete permissions. Always supply read-only, least-privilege credentials for the account(s) you audit:
- AWS — attach the
ReadOnlyAccessorSecurityAuditmanaged policy - Azure — assign the built-in
Readerrole - GCP — grant
roles/viewer
Read-only scoping guarantees an audit cannot change your environment. Supplying credentials with write or other state-changing permissions is unnecessary and is entirely at your own risk. You are responsible for provisioning, scoping, rotating, and revoking these credentials — see EULA §5.5.
5Verify activation
$ nsauditor-ai license --status ✓ Enterprise license active | Org: you@example.com | Seats: 5 | Expires: 2027-04-04
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.
# Scan ALL THREE clouds in one run — comma-separated sentinels (CE 0.2.17+). # --plugins all auto-scopes each cloud to only its plugins; one out/ subfolder per cloud. $ nsauditor-ai scan --host aws,gcp,azure --env ~/envs/clouds.env --plugins all --compliance all --out out # …or one cloud at a time, 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,azurescans one or more clouds in a single run (comma-separated;--host awsfor just one). With--plugins alleach cloud auto-scopes to only its plugins (other clouds + non-cloud plugins are skipped and logged). Don't writeaws|gcp|azurewith pipe characters — your shell treats|as a pipe.--compliancetakes a CSV of any of the seven frameworks:soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr(gdpremits the GDPR Article 32 Security-of-Processing infrastructure substrate — Art. 32 only, not GDPR compliance).- Optional — push evidence to your GRC platform: set
COMPLIANCE_GRC_PROVIDER=vanta(ordrata/secureframe) +COMPLIANCE_GRC_TOKENand the scan maps its findings to your Vanta, Drata, or Secureframe workspace and pushes them at scan time — opt-in, early-access, Zero-Data-Exfiltration by default, token never serialized. See the GRC Connectors guide for the full setup. - A missing
--envfile is a hard error (fail-fast, never a silent skip). --out <dir>writes into the directory you name. In CE 0.2.34 a directory whose name contains a dot (e.g.--out out/ee-0.32.9) is correctly treated as a directory; earlier builds read the dot as a file extension and wrote the artifacts into the parent directory instead.
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).
# 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:
$ 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-regionflag ›AWS_REGION(shell /--envfile) › 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 allfor full coverage. -
›
Unknown region → fail fast
The explicit flag fails fast on an unrecognized region code (setNSA_AWS_REGION_ALLOW_UNKNOWN=1to permit a brand-new region); anAWS_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.
> 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.
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:
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
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-configuredAWS_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.
9Read the results & troubleshoot
-
✓
Evidence artifacts
Land under your--outdirectory, one timestamped folder per scan (e.g.aws_20260524_091331/), with the per-framework reports plus SHA-256 chain-of-custody sidecars. -
✓
Severities
Findings carryCRITICAL / 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. As of EE 0.32.9 this holds even when the plugin never started at all: if a cloud's optional SDK is absent or its credentials are unusable, every in-scope control of that cloud carries a fail-closed evidence gap instead of reading PASS. Always confirm the scan actually audited the account. -
✓
Region coverage
Check thescanScopeblock (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.