OpenAPI Audit

nat audit validates your OpenAPI spec before you scan, catching issues that would reduce scan coverage or cause errors during the security testing phase.

Quick use: nat audit --spec ./openapi.yaml — validate your spec in seconds and get a structured report of issues, warnings, and suggestions.

What it checks

nat audit runs a suite of checks across six categories:

Category	What's checked
Descriptions	Missing `description` fields on endpoints, parameters, and schemas
Error responses	Endpoints missing `4xx`/`5xx` response definitions
Authentication	Endpoints without a `security` requirement (that appear to require auth)
Deprecated endpoints	Operations marked `deprecated: true` still present in the spec
Schema consistency	Mismatched types, `$ref` resolution failures, enum/format inconsistencies
Examples	Missing `example` or `examples` on request/response bodies

Usage

nat audit --spec <path> [flags]

Flags

Flag	Description
`--spec <path>`	Path to the OpenAPI spec file (YAML or JSON). Required.
`--strict`	Fail (exit code 1) on warnings, not just errors
`--format <fmt>`	Output format: `text` (default), `json`, `markdown`
`--fix`	Auto-fix common issues: adds placeholder descriptions, standard error responses
`--output <path>`	Write audit results to a file instead of stdout

Severity levels

Each finding from nat audit has one of three severity levels:

Level	Meaning	Exit code impact
Error	Will cause scan failures or significantly reduce coverage	Always fails (`exit 1`)
Warning	May affect scan coverage or result accuracy	Fails only with `--strict`
Info	Best practice suggestion — no impact on scanning	Never fails

Example output

Running nat audit --spec ./openapi.yaml on a typical project:

NAT OpenAPI Audit — ./openapi.yaml
OpenAPI 3.1.0 · 24 paths · 67 operations

Errors (2)
──────────────────────────────────────────────────────
[E001] Missing authentication requirement
  POST /admin/users — no security scheme defined
  Fix: Add a securityRequirement or global security block

[E002] Unresolvable $ref
  GET /orders/{id} → response 200 → $ref '#/components/schemas/OrderDetail'
  Schema 'OrderDetail' not found in components.schemas
  Fix: Define the schema or correct the $ref path

Warnings (5)
──────────────────────────────────────────────────────
[W001] Missing error responses (3 endpoints)
  GET /products — no 404 response defined
  POST /payments — no 402 or 422 response defined
  DELETE /users/{id} — no 403 response defined

[W002] Deprecated endpoints still present (2)
  GET /v1/users — deprecated since v1.3
  POST /v1/auth/token — deprecated since v1.4

Info (8)
──────────────────────────────────────────────────────
[I001] Missing descriptions (6 parameters)
  GET /search → query param 'q' has no description
  POST /users → body field 'metadata' has no description
  ... and 4 more

[I002] Missing examples (2 request bodies)
  POST /orders → request body has no example
  PUT /users/{id} → request body has no example

──────────────────────────────────────────────────────
Summary: 2 errors, 5 warnings, 8 info
Result: FAIL (errors present)

JSON output

Use --format json for machine-readable results:

nat audit --spec ./openapi.yaml --format json --output audit-results.json

{
  "spec": "./openapi.yaml",
  "openapi_version": "3.1.0",
  "paths": 24,
  "operations": 67,
  "summary": {
    "errors": 2,
    "warnings": 5,
    "info": 8
  },
  "result": "fail",
  "findings": [
    {
      "id": "E001",
      "severity": "error",
      "category": "authentication",
      "message": "Missing authentication requirement",
      "location": "POST /admin/users",
      "fix": "Add a securityRequirement or global security block"
    }
  ]
}

Auto-fix common issues

The --fix flag automatically resolves a subset of common issues in place:

nat audit --spec ./openapi.yaml --fix

What --fix can repair automatically:

Issue	Auto-fix
Missing parameter descriptions	Adds `"No description provided."` placeholder
Missing standard error responses	Adds `400`, `401`, `500` response stubs
Missing request body examples	Generates an example from the schema definition

What --fix cannot repair (requires manual intervention):

Unresolvable $ref — the schema definition is missing and must be written manually
Missing authentication requirements — security model decisions require human review
Deprecated endpoint removal — API versioning strategy varies by project

⚠️

--fix modifies your spec file in place. Commit your spec to version control before running --fix so you can review the diff.

Integration with `nat scan`

nat scan runs a lightweight audit automatically before every scan. This quick pre-check catches critical spec errors that would prevent scanning from completing.

For a thorough, actionable audit report — especially before a first scan or spec update — run nat audit separately:

Audit first

nat audit --spec ./openapi.yaml --strict

Fix any errors and review warnings before scanning.

Then scan

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

With a clean spec, scan coverage is maximized and results are more accurate.

CI/CD integration

Add nat audit as a step before nat scan in your pipeline to catch spec issues early:

# .github/workflows/nat-scan.yml
- name: Audit OpenAPI spec
  run: nat audit --spec ./openapi.yaml --format json --output audit-results.json --strict
 
- name: Run NAT security scan
  run: nat scan --url ${{ vars.STAGING_API_URL }} --spec ./openapi.yaml --fail-on high

Troubleshooting

Problem	Fix
`nat audit` exits with error on a valid spec	Run with `--format json` to get structured output and check the `findings` array for the specific error
`--fix` changes more than expected	Review the diff with `git diff` and revert any changes that don't look right
`nat audit` is very slow on a large spec	Use `--format json --output results.json` to write results to disk and inspect offline
`$ref` errors on a valid spec	Ensure relative paths in `$ref` are correct relative to the spec file location

Was this helpful?

Notifications Scan Comparison