NATAegisFlow Operational Setup and Troubleshooting

Use this guide when you are preparing a beta NATAegisFlow run, validating a local or Docker environment, or collecting diagnostics for the NAT team.

🛡️

NATAegisFlow is a beta workflow. Keep your existing release gates in place until a beta run completes and a human reviewer approves the result.

Local setup

Prepare an isolated NAT environment

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install nat-engine
nat setup

Export run inputs

export NAT_API_KEY="nat_pk_your_api_key_here"
export AEGISFLOW_TARGET_URL="https://api.example.com"
export AEGISFLOW_OPENAPI_SPEC="$(pwd)/openapi.yaml"
export AEGISFLOW_REPORT_DIR="$(pwd)/reports/aegisflow"
mkdir -p "$AEGISFLOW_REPORT_DIR"

Run pre-flight checks and a baseline scan

nat doctor --verbose
nat scan \
  --url "$AEGISFLOW_TARGET_URL" \
  --spec "$AEGISFLOW_OPENAPI_SPEC" \
  --output "$AEGISFLOW_REPORT_DIR/baseline.html" \
  --fail-on high

Use the successful scan ID, report path, and OpenAPI spec path when enabling the NATAegisFlow beta run from the dashboard or CI workflow.

Docker setup

Use Docker when you want a clean runtime that matches CI more closely.

export NAT_API_KEY="nat_pk_your_api_key_here"
export AEGISFLOW_TARGET_URL="https://api.example.com"
mkdir -p reports
 
docker run --rm \
  -e NAT_API_KEY \
  -v "$(pwd)/openapi.yaml:/workspace/openapi.yaml:ro" \
  -v "$(pwd)/reports:/reports" \
  natengine/nat:latest \
  nat scan \
    --url "$AEGISFLOW_TARGET_URL" \
    --spec /workspace/openapi.yaml \
    --output /reports/aegisflow-baseline.html \
    --fail-on high

For Docker Compose, keep beta inputs in .env and mount only the spec, reports directory, and any dbt artifacts needed for validation:

# docker-compose.yml
version: '3.8'
services:
  aegisflow-preflight:
    image: natengine/nat:latest
    environment:
      - NAT_API_KEY=${NAT_API_KEY}
      - AEGISFLOW_TARGET_URL=${AEGISFLOW_TARGET_URL}
      - AEGISFLOW_DBT_MANIFEST=/workspace/dbt/target/manifest.json
    volumes:
      - ./openapi.yaml:/workspace/openapi.yaml:ro
      - ./analytics/target:/workspace/dbt/target:ro
      - ./reports:/reports
    command: >
      nat scan
        --url ${AEGISFLOW_TARGET_URL}
        --spec /workspace/openapi.yaml
        --output /reports/aegisflow-baseline.html
        --fail-on high

docker compose run --rm aegisflow-preflight

dbt validation path

If your beta run uses dbt metadata for data contract context, validate the manifest before you start NATAegisFlow. The expected handoff artifact is target/manifest.json from the dbt project that owns the models under test.

cd analytics
python -m venv .venv
source .venv/bin/activate
# Skip this if you already upgraded pip during local setup.
pip install --upgrade pip
pip install dbt-core dbt-postgres
 
dbt deps
dbt debug --profiles-dir .
dbt parse --profiles-dir .
test -f target/manifest.json
python -m json.tool target/manifest.json >/dev/null

Set the manifest path that your beta workflow or support contact expects:

export AEGISFLOW_DBT_MANIFEST="$(pwd)/target/manifest.json"
ls -lh "$AEGISFLOW_DBT_MANIFEST"

Use the adapter package for your warehouse, such as dbt-snowflake, dbt-bigquery, dbt-redshift, or dbt-postgres. The example uses dbt-postgres only as a copy-and-paste starting point.

Common failures and fixes

Symptom	Likely cause	Fix
`manifest.json` is missing	`dbt parse` or `dbt build` has not run in the dbt project, or the beta workflow points at the wrong project directory	Run `dbt parse --profiles-dir .`, confirm `target/manifest.json` exists, then update `AEGISFLOW_DBT_MANIFEST` to the absolute path
`Could not find profile named ...`	dbt cannot find `profiles.yml`, or `DBT_PROFILES_DIR` points to the wrong directory	Run `dbt debug --profiles-dir /path/to/profiles`, export `DBT_PROFILES_DIR`, and retry `dbt parse`
Adapter import or credentials errors	The dbt adapter package is not installed, or warehouse credentials are not available in the shell/container	Install the matching adapter (`pip install dbt-snowflake`, `dbt-bigquery`, etc.) and pass credentials through environment variables or your secrets manager
`401` or `403` from NAT Scan API	`NAT_API_KEY` is missing, expired, or scoped to another tenant	Re-export `NAT_API_KEY`, confirm tenant access in the dashboard, then rerun `nat doctor --verbose`
Target API returns only unauthenticated coverage	Target credentials are missing, expired, or using the wrong auth type/header	Re-run the baseline scan with `--auth-type bearer --token "$TOKEN"` or follow the fixes in Auth Issues troubleshooting
Docker run cannot read spec or manifest	Volume mount path does not match the path passed to NAT or the beta workflow	Run `docker run --rm -v "$(pwd):/workspace" alpine ls -R /workspace` and update mounts to use container paths

Quick diagnostic checklist

Before reporting a beta failure, collect this output and redact secrets.

Note: The NAT CLI reads NAT_API_KEY automatically. Direct API probes must send the same key in the X-API-Key header.

pwd
python --version
pip freeze | grep -E '^(nat-engine|dbt-|dbt-core)='
nat doctor --verbose
printf 'NAT_API_KEY set: '; test -n "$NAT_API_KEY" && echo yes || echo no
printf 'OpenAPI spec: '; ls -lh "$AEGISFLOW_OPENAPI_SPEC"
printf 'dbt manifest: '; ls -lh "$AEGISFLOW_DBT_MANIFEST"
curl -sS -H "X-API-Key: $NAT_API_KEY" https://api.nat-testing.io/api/v1/health || true

If the failure only happens in Docker, also run:

docker version
docker run --rm \
  -e NAT_API_KEY \
  -v "$(pwd):/workspace:ro" \
  natengine/nat:latest \
  nat doctor --verbose

Report a failure

Open a NATAegisFlow failure report (opens in a new tab) and include:

The exact local, Docker, or CI command that failed
nat doctor --verbose output
dbt debug / parse output when a manifest or adapter is involved
Paths to the OpenAPI spec, dbt manifest, and generated reports
The scan ID or dashboard run link, if one was created

Never paste raw API keys, bearer tokens, database passwords, or warehouse credentials into the issue.

Was this helpful?

Beta Overview