How-To
Run a Security Audit

How to Run a Security Audit

A security audit is a comprehensive, scoped engagement that systematically evaluates your API's security posture. This guide walks through running a full audit with NAT.

⚠️

Only audit APIs you own or have explicit written authorization to test. Retain written evidence of this authorization.

Define the audit scope

Before scanning, document:

  • Target URL(s) — all API base URLs in scope
  • Authentication — credentials for all roles to be tested (admin, user, guest, etc.)
  • Excluded paths — endpoints that should not be tested (payment processing, email triggers, etc.)
  • Environment — always use a staging environment, not production

Prepare credentials for all tested roles

A thorough audit requires credentials representing each significant user role:

# Create test accounts for each role
# Minimum: one admin-level account, one standard user account
export ADMIN_TOKEN="eyJ..."
export USER_TOKEN="eyJ..."

Run the full audit scan

nat scan \
  --url https://staging.example.com \
  --spec ./openapi.yaml \
  --auth-type bearer \
  --token "$USER_TOKEN" \
  --secondary-token "$ADMIN_TOKEN" \
  --exclude "/api/v1/payments/*" \
  --exclude "POST:/api/v1/emails/send" \
  --concurrency 3 \
  --timeout 60 \
  --format html \
  --output ./audit-$(date +%Y%m%d).html

Check for unauthenticated access

Run an additional scan with no credentials to confirm that protected endpoints are properly secured:

nat scan \
  --url https://staging.example.com \
  --spec ./openapi.yaml \
  --auth-type none \
  --format json \
  --output ./audit-unauth.json \
  --fail-on info

Review findings by severity

nat report --open --scan-id latest

Work through findings in order:

  1. Critical — Stop and fix before any other work
  2. High — Fix before the next release
  3. Medium — Schedule for the next sprint
  4. Low — Backlog
  5. Informational — Track and review periodically

Export the report for stakeholders

# Executive summary (HTML)
nat report --format html --output ./audit-executive.html
 
# Full technical report (JSON for ticketing system import)
nat report --format json --output ./audit-technical.json
 
# SARIF for GitHub Security tab
nat report --format sarif --output ./audit.sarif

Track remediation

After your development team fixes the findings, re-run targeted scans to verify:

# Re-test only the endpoints with previous findings
nat scan \
  --url https://staging.example.com \
  --spec ./openapi.yaml \
  --auth-type bearer \
  --token "$USER_TOKEN" \
  --secondary-token "$ADMIN_TOKEN" \
  --include "/api/v1/users/*" \
  --format html \
  --output ./retest-$(date +%Y%m%d).html

Audit checklist

Before marking an audit complete, ensure:

  • All endpoints in the OpenAPI spec were covered
  • Unauthenticated scan was performed
  • At least two different user roles were tested
  • All critical and high findings are resolved or formally accepted
  • Remediation retest has been completed
  • Final report is archived and accessible

Next steps

Test a GraphQL APIRead Risk Reports