Pipeline Quickstart

Run a complete Ingest → Prioritize → Scan → Export → Learn pipeline in under 5 minutes using a single YAML config file.

If you just want to run a quick scan without export or spec ingestion, see the Quickstart or Your First Scan guides first.

What the pipeline does

The NAT orchestrator runs five phases automatically:

┌─────────────┐     ┌──────────────────────┐     ┌───────────────┐
│   Ingest    │ ──▶ │ Transform + Prioritize│ ──▶ │     Scan      │
│  (parse     │     │  (rank endpoints by   │     │  (OWASP tests │
│   spec)     │     │   belief-guided risk) │     │   vs live API)│
└─────────────┘     └──────────────────────┘     └───────┬───────┘
                                                          │
                    ┌─────────────┐     ┌────────────────▼───────┐
                    │    Learn    │ ◀── │        Export          │
                    │ (save scan  │     │  (send findings to     │
                    │  feedback)  │     │   GitHub, Jira, etc.)  │
                    └─────────────┘     └────────────────────────┘

Using nat pipeline instead of nat scan gives you:

Structured ingestion — parse any spec format (OpenAPI, Postman, GraphQL, HAR, Gherkin, cURL) into a normalized endpoint list
Belief-guided prioritization — NAT ranks endpoints by risk before scanning, so the most dangerous paths are tested first
Automatic export — findings are pushed directly to your issue tracker (GitHub Issues, Jira, Linear, GitLab, and more) without manual steps
Feedback loop — scan results are recorded to improve future prioritization

Prerequisites

NAT installed — pip install nat-engine (see Installation)
An API spec file or URL (or use the bundled examples/petstore-openapi.yaml)
A running API to scan (a staging environment works well)
(Optional) An issue tracker account for exporting findings

Option A: One-command pipeline (recommended)

Copy the pipeline config template

cp examples/pipeline.yaml pipeline.yaml

If you don't have the examples/ directory, download the template:

curl -O https://raw.githubusercontent.com/bg-playground/nat/main/examples/pipeline.yaml

Edit `pipeline.yaml`

Open pipeline.yaml and fill in your settings. The file has five main sections:

# pipeline.yaml
 
# 1. Ingest: where to load your API spec from
ingestor_name: openapi            # openapi | postman | har | graphql | gherkin | curl
source_path: ./openapi.yaml       # local file path …
# source_url: https://api.example.com/openapi.json  # … or remote URL
 
# 2. Scan: the live API to test
scan_config:
  base_url: https://api.example.com
  auth_token: "${API_TOKEN}"      # bearer token (or omit for public APIs)
  severity_threshold: medium      # skip findings below this level
  belief_guided: true             # enable prioritized scanning
  timeout: 30                     # per-request timeout in seconds
 
# 3. Export: where to send findings
exporter_config:
  exporter_name: github-issues    # see exporter table below
  token: "${GITHUB_TOKEN}"
  repo: myorg/myrepo
 
# 4. Prioritizer: belief score tuning (optional)
prioritizer_config:
  risk_report: true               # include risk report in output
 
# 5. LLM augmentation (optional — see section below)
llm_config:
  enabled: false

⚠️

Never hard-code secrets in pipeline.yaml. Use environment variable placeholders like "${GITHUB_TOKEN}" and export them in your shell before running the pipeline.

Run the pipeline

nat pipeline --config pipeline.yaml

NAT will print progress for each phase as it runs:

[NAT] Phase 1/5 — Ingest
[NAT]   Loaded openapi.yaml → 42 endpoints discovered
[NAT] Phase 2/5 — Prioritize
[NAT]   Ranked 42 endpoints by belief-guided risk score
[NAT] Phase 3/5 — Scan
[NAT]   [HIGH]  POST /api/v1/users — SQL Injection in 'email' parameter
[NAT]   [MED]   GET  /api/v1/orders/{id} — Broken Object Level Authorization
[NAT]   [LOW]   GET  /api/v1/products — Missing rate limiting
[NAT]   Scan complete: 3 findings in 00:01:47
[NAT] Phase 4/5 — Export
[NAT]   Exported 3 findings → github-issues (myorg/myrepo)
[NAT]   Created issues: #42, #43, #44
[NAT] Phase 5/5 — Learn
[NAT]   Feedback saved to ~/.nat/feedback/2024-01-15T10-30-00.json
[NAT] Pipeline complete ✓

Option B: Step-by-step CLI

For users who want to run each phase from the command line without a config file.

Step 1 — Ingest and scan

Run the security scanner with your spec file:

nat security-scan \
  --spec ./openapi.yaml \
  --base-url https://api.example.com

Step 2 — Add export

Append export flags to push findings to an issue tracker:

nat security-scan \
  --spec ./openapi.yaml \
  --base-url https://api.example.com \
  --export github-issues \
  --export-config token=$GITHUB_TOKEN \
  --export-config repo=myorg/myrepo

Step 3 — Enable belief-guided prioritization

Add --belief-guided to rank endpoints by risk before scanning:

nat security-scan \
  --spec ./openapi.yaml \
  --base-url https://api.example.com \
  --export github-issues \
  --export-config token=$GITHUB_TOKEN \
  --export-config repo=myorg/myrepo \
  --belief-guided

NAT will show an additional prioritization step before scanning begins:

[NAT] Prioritizing 42 endpoints by risk score...
[NAT]   High-risk:   8 endpoints
[NAT]   Medium-risk: 19 endpoints
[NAT]   Low-risk:    15 endpoints
[NAT] Starting scan (high-risk endpoints first)...

Supported input formats

Format	`ingestor_name`	File extension
OpenAPI 3.x / Swagger 2.x	`openapi`	`.yaml`, `.json`
Postman Collection	`postman`	`.json`
GraphQL Schema	`graphql`	`.graphql`, `.gql`
HAR Archive	`har`	`.har`
Gherkin	`gherkin`	`.feature`
cURL commands	`curl`	`.sh`, `.txt`

ingestor_name: openapi
source_path: ./openapi.yaml
# Or load from a URL:
# source_url: https://api.example.com/openapi.json

Supported exporters

Exporter	`exporter_name`	Required keys
GitHub Issues	`github-issues`	`token`, `repo`
Jira	`jira`	`base_url`, `project_key`, `email`, `api_token`
GitLab	`gitlab`	`gitlab_url`, `project_id`, `private_token`
Linear	`linear`	`api_key`, `team_id`
Azure DevOps	`azure-devops`	`organization`, `project`, `token`
Shortcut	`shortcut`	`api_token`, `project_id`
PagerDuty	`pagerduty`	`routing_key`
ServiceNow	`servicenow`	`instance_url`, `username`, `password`
Webhook	`webhook`	`url`

See the Exporter Configuration guide for all required and optional keys for each exporter.

LLM augmentation (optional)

Enable LLM-generated edge cases to get deeper coverage of each endpoint. NAT will use the LLM to generate additional test inputs beyond its built-in checks:

llm_config:
  enabled: true
  provider: openai          # openai | anthropic | local
  model: gpt-4o-mini
  api_key: "${OPENAI_API_KEY}"
  priority_threshold: 0.7   # only augment endpoints with risk score ≥ 0.7
  n_cases: 5                # additional test cases per endpoint

LLM augmentation increases scan depth but also increases scan time and API cost. Start with priority_threshold: 0.7 and n_cases: 3 for a good balance.

Expected output

A full pipeline run produces output like this:

$ nat pipeline --config pipeline.yaml

[NAT] Loading pipeline config from pipeline.yaml
[NAT] ─────────────────────────────────────────
[NAT] Phase 1/5 — Ingest (openapi)
[NAT]   Source: ./openapi.yaml
[NAT]   Discovered 42 endpoints across 8 resource groups
[NAT]   Parsed 156 test intents

[NAT] Phase 2/5 — Transform + Prioritize
[NAT]   Ranked 42 endpoints by belief-guided risk score
[NAT]   Risk distribution: 8 high / 19 medium / 15 low

[NAT] Phase 3/5 — Scan
[NAT]   Target: https://api.example.com
[NAT]   Running OWASP checks (belief-guided order)...
[HIGH]  POST /api/v1/users — SQL Injection in 'email' parameter
          CWE-89 | Risk: 92/100
[HIGH]  DELETE /api/v1/users/{id} — Broken Object Level Authorization
          CWE-639 | Risk: 88/100
[MED]   GET  /api/v1/orders/{id} — Missing authentication check
          CWE-306 | Risk: 61/100
[LOW]   GET  /api/v1/products — Missing rate limiting
          CWE-770 | Risk: 28/100
[NAT]   Scan complete: 4 findings in 00:02:33

[NAT] Phase 4/5 — Export (github-issues)
[NAT]   Exporting 4 findings to myorg/myrepo...
[NAT]   ✓ Issue #42 created: [HIGH] SQL Injection in POST /api/v1/users
[NAT]   ✓ Issue #43 created: [HIGH] BOLA in DELETE /api/v1/users/{id}
[NAT]   ✓ Issue #44 created: [MED] Missing auth in GET /api/v1/orders/{id}
[NAT]   ✓ Issue #45 created: [LOW] Missing rate limit in GET /api/v1/products

[NAT] Phase 5/5 — Learn
[NAT]   Feedback saved → ~/.nat/feedback/2024-01-15T10-30-00.json

[NAT] ─────────────────────────────────────────
[NAT] Pipeline complete ✓  (total time: 00:02:41)
[NAT] 4 findings exported to github-issues
[NAT] Risk report saved → ./nat-risk-report.json

Next steps

Exporter Configuration — detailed config for all 9 exporters
Security Scanning — deep dive into scan checks and configuration
CLI Reference — full command reference for nat pipeline and nat security-scan
CI/CD Integration — run the pipeline automatically on every PR

Was this helpful?

Functional Testing Quickstart Installation