GitHub Action Reference

The bg-playground/nat-action GitHub Action runs a NAT security scan as part of your CI/CD workflow.

Usage

- uses: bg-playground/nat-action@v1
  with:
    api-url: https://api.example.com
    api-key: ${{ secrets.NAT_API_KEY }}

Inputs

Required inputs

Input	Description
`api-url`	The base URL of the API to scan
`api-key`	Your NAT API key. Store this in a GitHub secret — never hard-code it.

Discovery inputs

Input	Description	Default
`spec`	Path to an OpenAPI 3.x or Swagger 2.x spec file (local path or URL)	Auto-discover
`graphql`	Enable GraphQL testing mode (`true` / `false`)	`false`
`graphql-endpoint`	GraphQL endpoint path	`/graphql`
`graphql-schema`	Path to GraphQL schema file	Auto-introspect
`depth`	Endpoint discovery crawl depth	`3`
`include`	Comma-separated path patterns to include	All
`exclude`	Comma-separated path patterns to exclude	None

Authentication inputs

Input	Description	Default
`auth-type`	Authentication method: `bearer`, `header`, `basic`, `oauth2`, `none`	`none`
`token`	Bearer token value	—
`secondary-token`	Second user token for BOLA testing	—
`header`	Custom header in `Name: Value` format (repeatable)	—
`username`	Username for Basic auth	—
`password`	Password for Basic auth	—
`oauth2-token-url`	OAuth2 token endpoint URL	—
`oauth2-client-id`	OAuth2 client ID	—
`oauth2-client-secret`	OAuth2 client secret	—
`oauth2-scope`	OAuth2 scopes (space-separated)	—
`oauth2-grant-type`	OAuth2 grant type: `client_credentials`, `password`	`client_credentials`

Execution inputs

Input	Description	Default
`concurrency`	Parallel request count	`5`
`timeout`	Per-request timeout in seconds	`30`
`rate-limit`	Maximum requests per second	Unlimited
`max-requests`	Hard cap on total requests	Unlimited

Output inputs

Input	Description	Default
`fail-on`	Severity level that fails the workflow step: `critical`, `high`, `medium`, `low`, `info`	`high`
`output-format`	Report format: `html`, `json`, `sarif`	`sarif`
`output-file`	Output report file path	`nat-results.sarif`

Check customization inputs

Input	Description
`profile`	Built-in check profile name: `owasp-api-top10`, `minimal`, `pci-dss`, `hipaa`
`disable-checks`	Comma-separated check IDs to disable
`enable-checks`	Comma-separated check IDs to enable

Outputs

Output	Description
`scan-id`	Unique identifier for this scan
`finding-count`	Total number of findings
`critical-count`	Number of critical severity findings
`high-count`	Number of high severity findings
`medium-count`	Number of medium severity findings
`low-count`	Number of low severity findings
`risk-score`	Aggregate risk score (0–100)
`report-url`	URL to the full report in the NAT dashboard
`report-file`	Path to the local report file

Examples

Basic scan with SARIF upload

- uses: bg-playground/nat-action@v1
  with:
    api-url: ${{ vars.STAGING_API_URL }}
    api-key: ${{ secrets.NAT_API_KEY }}
    spec: ./openapi.yaml
    auth-type: bearer
    token: ${{ secrets.API_TOKEN }}
 
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: nat-results.sarif

OAuth2 authentication

- uses: bg-playground/nat-action@v1
  with:
    api-url: https://api.example.com
    api-key: ${{ secrets.NAT_API_KEY }}
    auth-type: oauth2
    oauth2-token-url: https://auth.example.com/oauth/token
    oauth2-client-id: ${{ secrets.OAUTH2_CLIENT_ID }}
    oauth2-client-secret: ${{ secrets.OAUTH2_CLIENT_SECRET }}
    oauth2-scope: "read write"

Fail only on critical findings

- uses: bg-playground/nat-action@v1
  with:
    api-url: ${{ vars.STAGING_API_URL }}
    api-key: ${{ secrets.NAT_API_KEY }}
    fail-on: critical

Custom check profile

- uses: bg-playground/nat-action@v1
  with:
    api-url: ${{ vars.STAGING_API_URL }}
    api-key: ${{ secrets.NAT_API_KEY }}
    profile: owasp-api-top10
    disable-checks: tls-issues,security-misconfiguration

Use outputs in subsequent steps

- uses: bg-playground/nat-action@v1
  id: nat
  with:
    api-url: ${{ vars.STAGING_API_URL }}
    api-key: ${{ secrets.NAT_API_KEY }}
 
- name: Comment findings on PR
  if: github.event_name == 'pull_request'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `**NAT Security Scan**: ${{ steps.nat.outputs.finding-count }} findings ` +
              `(Risk score: ${{ steps.nat.outputs.risk-score }}/100)\n` +
              `[View report](${{ steps.nat.outputs.report-url }})`
      })

Permissions

The action requires security-events: write permission to upload SARIF results:

permissions:
  security-events: write
  contents: read

Version pinning

Pin to a specific version for reproducible builds:

- uses: bg-playground/nat-action@v1.2.0

Next steps

CI/CD Integration guide — other CI/CD platforms
Integrate with GitHub Actions (how-to) — step-by-step setup
CI/CD Issues — troubleshoot workflow failures

REST API Reference Common Issues