Integrations

NAT connects to your existing tools at both ends of the pipeline — import API definitions in any format, and export findings to your issue tracker or alerting system automatically.

• Ingestors parse your API spec or test files and convert them into a normalized endpoint list that NAT can scan.
• Exporters take each finding above your configured severity threshold and create a work item, alert, or webhook payload in the target system.

Everything flows through a single command: nat pipeline --config pipeline.yaml.

Import Formats (Ingestors)

NAT supports 7 built-in ingestors. Choose whichever format your team already uses — NAT normalizes it into the same internal representation before scanning.

Format details

OpenAPI 3.x / Swagger 2.x — The most common format. NAT parses every path, operation, parameter, and schema from your spec and generates targeted test cases from them. Supports both local files and remote URLs.

Postman Collection — Export your Postman workspace collection as JSON and pass it directly to NAT. All requests, folders, and variable definitions are resolved into endpoint descriptors.

GraphQL Schema — Supply a .graphql SDL file, a .gql file, or a raw introspection JSON response. NAT maps every query, mutation, and type into testable endpoints for injection and auth-bypass checks.

HAR Archive — Record real traffic with your browser DevTools or a proxy (Burp, mitmproxy), export the .har file, and feed it to NAT. Captured requests become the test corpus — no spec authoring required.

Gherkin / BDD — If your team writes .feature files with Given / When / Then API scenarios, NAT can parse them directly. Each When step that makes an HTTP call becomes a testable endpoint.

cURL Commands — Paste your saved cURL one-liners into a .sh or .txt file and use it as a spec. Useful for ad-hoc scans when you don't have a formal spec.

BGSTM Test Plans — Native format for BGSTM-generated test plans. Pass the .bgstm.json file directly; NAT will use the embedded endpoint definitions and existing test intent metadata.

Quick start

pipeline.yaml snippet:

ingestor_name: openapi          # change to: postman | graphql | har | gherkin | curl | bgstm
source_path: ./openapi.yaml     # local path …
# source_url: https://api.example.com/openapi.json  # … or remote URL

CLI shortcut — skip the config file and pass a spec directly:

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

Replace --spec ./openapi.yaml with any supported file format; NAT auto-detects the ingestor from the file extension.

Export Destinations (Exporters)

NAT includes 9 built-in exporters. Once a scan finishes, findings are automatically pushed to every configured destination — no copy-paste required.

Exporter details

GitHub Issues — Creates one issue per finding with NAT's severity label, finding title, and remediation guidance. Supports deduplication so repeated scans don't create duplicate issues. The GITHUB_TOKEN available in GitHub Actions works out of the box.

Jira Cloud — Creates Jira issues via the REST API. Configure the project key, issue type, and component. Findings are mapped to Jira priority levels automatically.

GitLab Issues — Works with both GitLab.com and self-hosted instances. Findings can be marked confidential and assigned to specific users.

Linear — Creates Linear issues via the GraphQL API. Supports project, team, assignee, and label configuration.

Azure DevOps — Creates work items (Bug, Issue, Task) with area path and iteration path support for sprint planning.

Shortcut — Creates stories in a Shortcut project with configurable story type (bug, feature, chore), epic association, and labels.

PagerDuty — Triggers PagerDuty alerts for each finding, routing through your existing on-call escalation policies. Best combined with --export-min-severity critical to avoid alert fatigue.

ServiceNow — Creates ServiceNow incident records. Supports OAuth token and username/password authentication. The target table is configurable (incident, custom tables, etc.).

Generic Webhook — POSTs a JSON payload to any URL for each finding. Supports Authorization headers, HMAC-SHA256 request signing, custom headers, and batch mode (all findings in one request).

Quick start

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 \
  --export-min-severity medium

Swap github-issues for any other exporter_name from the table above, and replace the --export-config keys accordingly.

Compatibility Status

Integration compatibility is tracked in the NAT compatibility matrix. Each entry includes supported authentication methods, known quirks with workarounds, and verified configuration examples.

Exporter Compatibility

{
  "organization": "myco",
  "project": "API Security",
  "pat": "$AZDO_PAT",
  "work_item_type": "Bug"
}

{
  "base_url": "https://bugs.myco.com",
  "product": "Platform",
  "component": "Security",
  "api_key": "$BUGZILLA_API_KEY"
}

{
  "url": "https://hooks.myco.com/nat-findings",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer $WEBHOOK_TOKEN"
  },
  "signing_secret": "$WEBHOOK_HMAC_SECRET",
  "batch_mode": true
}

{
  "token": "$GITHUB_TOKEN",
  "repo": "myorg/security-backlog",
  "labels": [
    "nat",
    "security"
  ]
}

{
  "base_url": "https://gitlab.com",
  "project_id": "123456",
  "private_token": "$GITLAB_TOKEN",
  "confidential": true
}

{
  "base_url": "https://myco.atlassian.net",
  "project_key": "NAT",
  "email": "ci-bot@myco.com",
  "api_token": "$JIRA_API_TOKEN",
  "issue_type": "Bug"
}

{
  "api_key": "$LINEAR_API_KEY",
  "team_id": "ENG",
  "project_id": "security-hardening"
}

{
  "routing_key": "$PAGERDUTY_ROUTING_KEY",
  "dedup_key_prefix": "nat-prod",
  "severity_map": {
    "critical": "critical",
    "high": "error",
    "medium": "warning"
  }
}

{
  "organization": "myco",
  "project": "api-security",
  "auth_token": "$SENTRY_AUTH_TOKEN",
  "environment": "production"
}

{
  "instance_url": "https://myco.service-now.com",
  "table": "incident",
  "oauth_token": "$SERVICENOW_OAUTH_TOKEN"
}

{
  "token": "$SHORTCUT_TOKEN",
  "project_id": "5001",
  "story_type": "bug"
}

Ingestor Compatibility

{
  "source_path": "./schema.graphql",
  "max_depth": 8
}

{
  "proto_path": "./proto",
  "import_paths": [
    "./proto",
    "./third_party/proto"
  ]
}

{
  "source_path": "./captures/app.har",
  "dedupe_requests": true,
  "strip_cookies": true
}

{
  "source_path": "./openapi.yaml",
  "resolve_remote_refs": true
}

{
  "source_path": "./postman/collection.json",
  "environment_path": "./postman/env.json",
  "resolve_variables": true
}

{
  "source_path": "./swagger.json",
  "auto_convert_to_openapi3": true
}

{
  "source_path": "./contracts/service.wsdl",
  "flatten_imports": true
}

Pipeline overview

The nat pipeline command runs the full Ingest → Prioritize → Scan → Export → Learn loop in a single command:

nat pipeline --config pipeline.yaml

┌─────────────┐     ┌──────────────────────┐     ┌───────────────┐
│   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 running each step manually gives you structured ingestion, belief-guided prioritization, automatic export, and a feedback loop that improves future runs — all configured in a single YAML file.

See the Pipeline Quickstart for a complete step-by-step guide.

Custom integrations

Both ingestors and exporters are pluggable. You can write your own by extending the base classes:

• Custom ingestor — extend BaseIngestor and implement the ingest() method. Load your plugin with --ingestors-dir ./ingestors.
• Custom exporter — extend BaseExporter and implement export_finding() (and optionally test_connection()). Load your plugin with --exporters-dir ./exporters.

# Load a custom exporter from a local directory
nat security-scan --spec ./openapi.yaml --base-url https://api.example.com \
  --export my-custom-exporter \
  --exporters-dir ./exporters
 
# Load a custom ingestor from a local directory
nat pipeline --config pipeline.yaml \
  --ingestors-dir ./ingestors

See the Custom Check Plugins guide for patterns on writing and registering plugins.

Next steps