NATAegisFlow Beta Architecture
🛡️
Beta / Preview: NATAegisFlow is available for early adopters validating API security workflows. Interfaces, quotas, and supported stacks may change before general availability.
What it is
NATAegisFlow is a beta NAT module for orchestrating API security validation across discovery, contract checks, scan execution, and remediation follow-up. It helps teams connect their OpenAPI contract, NAT scan results, and troubleshooting workflow into one guided path.
Use it when you want a preview of NAT's managed security flow before rolling it out as a production gate.
Integration boundary
NATAegisFlow sits between the NAT app control plane and the scan execution APIs. NAT remains the source of truth for tenants, API keys, OpenAPI contracts, scan records, findings, and dashboard approvals. NATAegisFlow owns orchestration state for each beta run. That state records the approved contract revision, submitted scan request, collected evidence, and human approval decision for any enforcing gate.
| Boundary | NAT app owns | NATAegisFlow owns | Contract |
|---|---|---|---|
| Tenant and auth | Tenant lookup, quota, X-API-Key validation, dashboard session auth | Run-scoped access checks before orchestration | Scan API authentication |
| API contract | OpenAPI URL or uploaded spec metadata | Contract snapshot used by one flow run | OpenAPI / Swagger Reference |
| Run execution | POST /api/v1/scan, status polling, result storage | Idempotent orchestration, retries, approval checkpoints | Start a scan |
| Results | Findings, exports, dashboard history | Flow-level evidence bundle and approval state | Get scan results |
Sequence and data flow
Run data moves in one direction unless a user approves an enforcement checkpoint:
- NAT app resolves tenant, API key, contract, target URL, and optional auth profile.
- NATAegisFlow records a run envelope with contract revision, requested mode, and approval policy.
- NATAegisFlow submits the current Scan API request shape:
url, optionalspec_urlorspec_content, optionalauth, andoptionssuch asconcurrency,timeout, andfail_on. - NAT Scan API executes against the target API and stores status/results under the returned
scan_id. - NATAegisFlow polls results until
completedorfailed, then writes the flow-level outcome back to NAT for dashboard display and exports.
Contracts and auth
- API key boundary: All NAT Scan API calls use the tenant API key in
X-API-Key; NATAegisFlow does not introduce a separate public credential. - Target auth boundary: Target credentials stay in the NAT auth profile or scan request
authobject. Supported beta modes mirror the current Scan API request values:bearer,header,basic,oauth2, andnone. - Contract boundary: The OpenAPI contract is snapshotted for the run so later spec edits do not change the evidence behind an approval.
- Result contract: Flow status maps to Scan API status. A scan in progress remains
running; a successful evidence collection maps tocompleted; submission, polling, quota, or target failures map to a failed flow with a user-visible fallback.
Run and approval lifecycle
| State | Trigger | Owner | Expected next step |
|---|---|---|---|
draft | User or CI selects API, contract, auth, and run mode | NAT app | Validate required inputs |
awaiting_approval | Enforcement, deploy blocking, or remediation follow-up is requested | NAT app | Human approves or switches to advisory mode |
submitted | NATAegisFlow creates the Scan API request | NATAegisFlow | Store returned scan_id |
running | Scan API reports in-progress status | Scan API | Continue polling and show progress |
review_required | Findings meet or exceed fail_on, or beta confidence is low | NAT app | Human reviews findings and evidence |
approved | Human accepts result or approves release despite findings | NAT app | Export report or unblock downstream workflow |
blocked | Human rejects run, quota is exhausted, or scan fails closed in enforcement mode | NAT app | Keep existing release gate in place |
advisory_complete | Advisory-only run completes | NATAegisFlow | Display findings without blocking release |
Beta runs should default to advisory behavior unless a user explicitly enables enforcement and approves the pre-run checkpoint.
Failure modes and fallbacks
Detection behavior follows the documented Scan API error responses.
| Failure mode | Detection | Fallback behavior |
|---|---|---|
| Missing or invalid NAT API key | Scan API returns a documented authentication error response | Stop the flow, keep existing gates unchanged, and show API key setup guidance |
| Quota or concurrency limit | Scan API returns a documented quota or concurrency-limit response | Mark the flow blocked for enforcement runs; mark advisory runs inconclusive and retry later |
| Invalid contract or target URL | Scan API returns a documented invalid-request response, or contract parsing fails | Do not submit additional scans; ask the user to fix the OpenAPI source and rerun |
| Target auth rejected | Scan task evidence shows authentication failures or zero protected coverage | Fall back to unauthenticated/advisory findings only and require auth profile review |
| Scan timeout or target outage | Polling reaches timeout or scan status becomes failed | Preserve the failed scan_id, surface partial evidence when available, and keep prior release decision |
| Approval timeout | No human approval before the configured window expires | Advisory mode may continue; enforcement remains blocked until approval |
| Beta orchestrator unavailable | NATAegisFlow cannot create or update flow state | NAT app can still run the standard Scan API directly and display normal scan results |
Implementation and issue links
- Architecture tracking issue: bg-playground/nat-docs#114 (opens in a new tab)
- Documentation repository: bg-playground/nat-docs (opens in a new tab)
- Current API contract: OpenAPI / Swagger Reference
- Scan request and result schema: Scan API
- Pipeline entry point for beta runs: GitHub Action API and CI/CD integration guide
This page is reviewed against the current documented Scan API fields and authentication modes. If the beta runtime adds public endpoints, add those implementation repo or issue links here before promoting NATAegisFlow out of preview.
Who should use it
NATAegisFlow is best suited for:
- Security and platform teams piloting NAT as a standardized API security workflow
- API owners who already have an OpenAPI contract and want guided scan triage
- CI/CD maintainers testing a beta security gate before enforcing it broadly
- Early adopters who can tolerate preview limits and provide feedback
Beta limits
- Preview SLA only — do not use NATAegisFlow as the only production release blocker.
- Configuration may change — beta flags, response fields, and dashboard labels can change before GA.
- Limited tenant rollout — access may require your tenant to be allowlisted.
- Human review recommended — validate high-impact findings before taking automated action.
- No custom policy packs yet — use the standard NAT checks until policy-pack support is available.
Supported stack matrix
| Area | Supported | Experimental | Not yet supported |
|---|---|---|---|
| API contracts | OpenAPI 3.0 and 3.1 specs uploaded or referenced by URL | Partial Swagger 2.0 import after conversion | AsyncAPI and GraphQL schemas |
| Scan targets | Public HTTPS APIs and authenticated SaaS endpoints | Private APIs reachable from self-hosted runners | Isolated targets without a NAT runner |
| Authentication | API key, bearer token, and basic auth profiles | OAuth2 client credentials | Browser-only SSO and custom mTLS chains |
| Execution | On-demand scans from the dashboard or REST API | GitHub Actions and pipeline-triggered beta runs | Scheduled recurring NATAegisFlow campaigns |
| Results | NAT dashboard findings, JSON scan output, and remediation notes | PR comments and SARIF export with beta labels | Custom compliance evidence bundles |
| Environments | SaaS tenants on Free, Pro, Team, and Enterprise plans | Self-hosted control-plane pilots | Offline-only deployments |
Required setup links
🛡️ Positioning→⏱️ First 60 Minutes→🚀 Onboarding→🧪 Operational Setup→📄 API Contract→🔍 Scan API→🛠️ Troubleshooting→
Before enabling beta
- Complete API onboarding and confirm your API key works.
- If you are evaluating for the first time, complete the First 60 Minutes playbook with the recommended sample project.
- Validate that your OpenAPI contract reflects the deployed API surface.
- Run a standard scan through the Scan API and review the result format.
- Run the operational setup and troubleshooting checklist for local, Docker, dbt, auth, and failure-reporting pre-flights.
- Keep the onboarding troubleshooting guide handy for tenant, auth, and quota errors.
If your stack is listed as experimental or not yet supported, treat NATAegisFlow results as advisory and keep your existing security gates in place.
Was this helpful?