Setup Wizard

nat setup is a 7-phase interactive wizard that configures NAT from scratch. It detects your environment, asks a few questions, tests your exporter connection live, and writes a .natrc file — all in one command.

Run nat setup immediately after pip install nat-engine. It replaces manual .natrc editing for first-time configuration.

Quick start

pip install nat-engine
nat setup

That's it. The wizard guides you through every decision. When it finishes you can run nat scan straight away.

The 7 phases explained

Phase 1 — Environment Detection

NAT inspects your system before asking any questions:

Python version and OS
Whether Docker is available
Whether a .natrc already exists in the current directory or ~/.natrc

If an existing .natrc is found you are asked whether to overwrite it or exit.

Phase 2 — Deployment Mode

Choose how you want to run NAT:

Mode	Description
SaaS	Connect to app.nat-testing.io (opens in a new tab) — results sync to the cloud dashboard
Self-Hosted	Run the NAT server on your own infrastructure
CLI-only	Offline mode — results stay local, no server required

Phase 3 — API Spec / Ingestion Setup

Provide the API you want to test:

Spec path or URL — an OpenAPI 3.x / Swagger 2.x file on disk or a remote URL
Base URL — the API's root URL (e.g. https://api.example.com)
Auto-detection — if you skip the spec, NAT will attempt to auto-discover endpoints from the base URL

Phase 4 — API Authentication

Select how NAT should authenticate to your API:

Type	Details
Bearer token	Provide a static `Authorization: Bearer …` token
API key	Provide a header name and value
OAuth2	Provide token URL, client ID, secret, and scopes
None	No authentication (public APIs)

Phase 5 — Export Destination

Choose where NAT sends findings. NAT tests the connection live before writing the config.

Exporter	Description
GitHub Issues	Create issues in a GitHub repo
Jira	Create tickets in a Jira project
GitLab	Create issues in a GitLab project
Linear	Create issues in a Linear team
Azure DevOps	Create work items in an Azure DevOps project
Shortcut	Create stories in a Shortcut project
PagerDuty	Create incidents in PagerDuty
ServiceNow	Create incidents in ServiceNow
Webhook	POST findings to any HTTP endpoint
Sentry	Create events/issues in Sentry
Bugzilla	Create bugs in Bugzilla via REST API

See the Exporter Configuration guide for per-exporter credential details.

NAT calls test_connection() on the selected exporter before saving. If the connection fails, you are prompted to re-enter credentials or skip.

Phase 6 — Write Configuration

NAT generates a .natrc file in the current directory. Example output:

# .natrc — generated by nat setup
mode: saas
spec: ./openapi.yaml
base_url: https://api.example.com
auth:
  type: bearer
  token: "YOUR_TOKEN"
export: github
export_config:
  github_token: "ghp_..."
  github_repo: "your-org/your-repo"
export_min_severity: medium

⚠️

Run chmod 600 .natrc after setup to restrict file permissions — it may contain API tokens.

Phase 7 — Verify & First Run

NAT validates the generated config with nat doctor, then optionally runs an immediate scan so you can confirm everything works end-to-end.

Non-interactive mode (CI/CD)

Use --non-interactive to skip all prompts and read configuration entirely from environment variables:

nat setup --non-interactive

Core environment variables

Variable	Description
`NAT_MODE`	`saas`, `self-hosted`, or `cli-only`
`NAT_SPEC_PATH`	Path or URL to the OpenAPI spec
`NAT_BASE_URL`	API base URL
`NAT_AUTH_TOKEN`	Bearer token (if auth type is bearer)
`NAT_EXPORT`	Exporter name (e.g. `github`, `jira`, `webhook`)

Exporter-specific environment variables

Variable	Description
`NAT_GITHUB_TOKEN`	GitHub personal access token
`NAT_GITHUB_REPO`	Target repository (`owner/repo`)

CI/CD example

# GitHub Actions
- name: Configure NAT
  env:
    NAT_MODE: saas
    NAT_SPEC_PATH: ./openapi.yaml
    NAT_BASE_URL: https://staging.example.com
    NAT_AUTH_TOKEN: ${{ secrets.STAGING_TOKEN }}
    NAT_EXPORT: github
    NAT_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NAT_GITHUB_REPO: ${{ github.repository }}
  run: nat setup --non-interactive

`--demo` flag

Add --demo to automatically launch nat demo after setup completes:

nat setup --demo

Useful for immediately verifying the installation with a sandboxed example scan.

The `.natrc` file

nat setup writes .natrc in the current working directory. NAT also falls back to ~/.natrc for user-wide defaults.

# .natrc
mode: saas                   # saas | self-hosted | cli-only
spec: ./openapi.yaml         # path or URL to OpenAPI spec
base_url: https://api.example.com
auth:
  type: bearer               # bearer | api-key | oauth2 | none
  token: "YOUR_TOKEN"
export: github               # exporter name
export_config:
  github_token: "ghp_..."
  github_repo: "your-org/your-repo"
export_min_severity: medium  # info | low | medium | high | critical

Use nat doctor at any time to validate your .natrc and check connectivity to all configured services.

Supported exporters

Exporter	Key	Guide
GitHub Issues	`github`	Exporter Configuration
Jira	`jira`	Exporter Configuration
GitLab	`gitlab`	Exporter Configuration
Linear	`linear`	Exporter Configuration
Azure DevOps	`azure-devops`	Exporter Configuration
Shortcut	`shortcut`	Exporter Configuration
PagerDuty	`pagerduty`	Exporter Configuration
ServiceNow	`servicenow`	Exporter Configuration
Webhook	`webhook`	Exporter Configuration
Sentry	`sentry`	Exporter Configuration
Bugzilla	`bugzilla`	Exporter Configuration

Next steps

Your First Scan — run a real scan against your API
Exporter Configuration — detailed per-exporter credential setup
CLI Reference — full command and flag reference
Upgrade & Uninstall — keep NAT up to date or remove it cleanly

Was this helpful?

Quickstart API Quickstart