CI/CD Integration

Integrate NAT into your CI/CD pipeline to automatically scan your API on every pull request, deployment, or scheduled run.

GitHub Actions (recommended)

Use the official nat-action for zero-config GitHub Actions integration:

# .github/workflows/nat-scan.yml
name: API Security Scan
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
permissions:
  contents: read
  security-events: write
  pull-requests: write
 
jobs:
  nat-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Run NAT API Security Scan
        uses: nat-testing/nat-action@v1
        with:
          api-url: ${{ vars.STAGING_API_URL }}
          api-key: ${{ secrets.NAT_API_KEY }}
          spec: ./openapi.yaml
          fail-on: high
          output-format: sarif
          upload-sarif: true
          comment-on-pr: true

`nat-action` inputs

Input	Required	Description	Default
`api-url`	✅	Target API base URL	—
`api-key`	✅	NAT API key (use a secret)	—
`spec`		Path to OpenAPI/Swagger spec	Auto-discover
`auth-type`		`bearer`, `header`, `oauth2`, `none`	`none`
`token`		Auth token	—
`fail-on`		Severity level that fails the build	`high`
`output-format`		`html`, `json`, `sarif`	`sarif`
`output-file`		Report output path	`nat-results.sarif`
`exclude`		Comma-separated path patterns to exclude	—
`concurrency`		Parallel request count	`5`
`upload-sarif`		Auto-upload SARIF to GitHub Code Scanning	`false`
`comment-on-pr`		Post scan summary as PR comment	`false`
`max-findings`		Fail if total findings exceed this count	—

`nat-action` outputs

Output	Description
`scan-id`	Unique scan identifier
`finding-count`	Total findings count
`critical-count`	Critical severity count
`high-count`	High severity count
`report-url`	URL to full report in NAT dashboard
`sarif-file`	Path to SARIF output file
`summary-file`	Path to scan summary markdown file
`pr-comment-file`	Path to PR comment markdown file

SARIF upload to GitHub Code Scanning

The nat-action can automatically upload SARIF results to GitHub's Security tab using the upload-sarif input. When enabled, NAT handles the upload internally — no separate step required.

# .github/workflows/nat-scan.yml
name: API Security Scan
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
permissions:
  contents: read
  security-events: write
 
jobs:
  nat-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Run NAT API Security Scan
        uses: nat-testing/nat-action@v1
        with:
          api-url: ${{ vars.STAGING_API_URL }}
          api-key: ${{ secrets.NAT_API_KEY }}
          spec: ./openapi.yaml
          fail-on: high
          output-format: sarif
          upload-sarif: true

When upload-sarif: true is set, you no longer need the separate github/codeql-action/upload-sarif step. NAT handles the upload automatically and results appear in the Security → Code Scanning tab of your repository.

PR comment with scan summary

Set comment-on-pr: true to have NAT post a scan summary as a comment on every pull request. The comment includes the total finding count broken down by severity and a link to the full report.

permissions:
  contents: read
  pull-requests: write
 
jobs:
  nat-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Run NAT API Security Scan
        uses: nat-testing/nat-action@v1
        with:
          api-url: ${{ vars.STAGING_API_URL }}
          api-key: ${{ secrets.NAT_API_KEY }}
          spec: ./openapi.yaml
          fail-on: high
          comment-on-pr: true

⚠️

The pull-requests: write permission is required for PR comments. Ensure it is declared at the job or workflow level.

Quality gate configuration

Quality gates let you control exactly when a build should fail based on scan results.

Fail on severity level

Use --fail-on <level> to fail the build when findings at or above the specified severity are found:

- uses: nat-testing/nat-action@v1
  with:
    api-url: ${{ vars.STAGING_API_URL }}
    api-key: ${{ secrets.NAT_API_KEY }}
    fail-on: high          # fail on high or critical findings

Fail on finding count

Use max-findings to fail the build when the total number of findings exceeds a threshold:

- uses: nat-testing/nat-action@v1
  with:
    api-url: ${{ vars.STAGING_API_URL }}
    api-key: ${{ secrets.NAT_API_KEY }}
    fail-on: high
    max-findings: 10       # fail if more than 10 findings total

Quality gate strategies

Strategy	Input	When to use
Severity gate	`fail-on: critical`	Block only the most severe issues
Count gate	`max-findings: 0`	Zero-tolerance policy
Combined gate	`fail-on: high` + `max-findings: 5`	Balance signal and noise
Regression gate	`nat scan --diff <scan-id>`	Fail only on new findings

Other CI/CD platforms

# .gitlab-ci.yml
nat-security-scan:
  stage: test
  image: python:3.11
  script:
    - pip install nat-engine
    - nat scan
        --url "$STAGING_API_URL"
        --spec ./openapi.yaml
        --auth-type bearer
        --token "$API_TOKEN"
        --format sarif
        --output nat-results.sarif
        --fail-on high
  artifacts:
    reports:
      sast: nat-results.sarif
    paths:
      - nat-results.sarif
    when: always
  variables:
    NAT_API_KEY: $NAT_API_KEY

Scan on staging, not production

⚠️

Run CI/CD scans against a staging or test environment, not production. Active security scanning generates anomalous traffic and will trigger alerts, rate limits, or outages on production systems.

A typical pipeline pattern:

Deploy PR to a per-PR staging environment
Run NAT scan against the staging environment
Gate merge if high/critical findings are discovered
Merge to main → deploy to production (no scan needed)

Caching NAT in CI

Speed up pipelines by caching the NAT pip package:

# GitHub Actions
- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: nat-${{ runner.os }}-${{ hashFiles('**/requirements.txt') }}
 
- run: pip install nat-engine

Troubleshooting CI failures

See CI/CD Issues troubleshooting for common problems:

Authentication failures in CI
Target API not reachable from CI runner
Scan timing out
False positives causing build failures

Next steps

GitHub Action reference — full nat-action input/output reference
Integrate with GitHub Actions (how-to) — step-by-step setup
CI/CD Issues — troubleshoot CI scan failures

Was this helpful?

GitHub Action Zero-Config Setup (nat init)