GitHub Action

The nat-testing/nat-action GitHub Action runs a NAT security scan as part of your CI/CD workflow. It integrates directly with your NAT Cloud account using an API key stored as a GitHub secret, and supports SARIF upload to GitHub Code Scanning and automatic PR comments.

Quick start

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

Setup

Sign up at app.nat-testing.io (opens in a new tab) and generate an API key from Settings → API Keys.
Add the key as a secret named NAT_API_KEY in your repository's Settings → Secrets and variables → Actions.
Add the workflow step shown above to your CI configuration.

Inputs reference

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

Outputs reference

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

Workflow examples

Minimal configuration — scan on every push to main:

name: NAT Security Scan
on:
  push:
    branches: [main]
 
permissions:
  contents: read
  security-events: write
 
jobs:
  nat-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nat-testing/nat-action@v1
        with:
          api-url: ${{ vars.STAGING_API_URL }}
          api-key: ${{ secrets.NAT_API_KEY }}

Permissions

Declare only the permissions your workflow needs:

Permission	Required for
`contents: read`	Checking out the repository
`security-events: write`	Uploading SARIF to GitHub Code Scanning (`upload-sarif: true`)
`pull-requests: write`	Posting a PR comment (`comment-on-pr: true`)

Troubleshooting

API key not set

Symptom: Error: NAT_API_KEY is not set

Fix: Add NAT_API_KEY as a repository secret in Settings → Secrets and variables → Actions, then reference it as ${{ secrets.NAT_API_KEY }} in the workflow.

Target API unreachable

Symptom: Error: connection refused or Error: timeout reaching <url>

Fix: Ensure the target API is running and reachable from GitHub-hosted runners. Use a staging environment URL rather than localhost. If your API is on a private network, use a self-hosted runner inside the same network.

SARIF upload fails

Symptom: Error: advanced-security is not enabled for this repository

Fix: GitHub Code Scanning requires GitHub Advanced Security. It is available on all public repositories and on GitHub Enterprise Cloud / GitHub Enterprise Server. Verify the security-events: write permission is declared on the job.