Root Cause Analysis

Root Cause Analysis (RCA) uses your configured LLM to automatically explain why a test failed or a security finding was detected — and what to do about it. Instead of reading raw request/response evidence, you get a plain-English diagnosis with suggested fixes.

How it works

When a scan completes, NAT automatically sends the evidence for high-severity findings to the configured LLM. The LLM returns:

• Root cause — a concise explanation of why the issue occurred
• Affected component — the endpoint, parameter, or code path most likely responsible
• Suggested fix — a concrete, actionable remediation step

For functional test failures, RCA explains assertion failures in terms of the expected vs. actual response and suggests what to check in your application code.

Automatic analysis

When an LLM provider is configured, RCA runs automatically for:

• Security scans — all critical and high severity findings
• Functional test failures — any scenario that fails one or more assertions
• Autonomous loop failures — task failures from the autonomous testing agent

You do not need to trigger RCA manually. The 🧠 Root Cause card appears inline on each affected finding in the dashboard as soon as analysis is complete.

On-demand analysis

Trigger RCA for a specific scan at any time — useful for older scans that completed before RCA was enabled, or when you want to re-analyze after updating your LLM provider.

API

POST /api/v1/scan/{scan_id}/analyze
X-API-Key: $NAT_API_KEY

Returns immediately with a job ID:

{
  "scan_id": "scan_01HXY3Z7KQNVJG84WDPT6BCS9",
  "job_id": "rca_job_01HY0Q5RCNM7KT3PWVX8FDB24",
  "status": "queued"
}

Analysis runs asynchronously. The dashboard updates automatically when results are ready, or poll the results endpoint.

Retrieve root cause results

GET /api/v1/scan/{scan_id}/root-causes
X-API-Key: $NAT_API_KEY

Response:

{
  "scan_id": "scan_01HXY3Z7KQNVJG84WDPT6BCS9",
  "analyzed_at": "2026-04-09T11:05:00Z",
  "findings": [
    {
      "finding_id": "finding_01HXY4A2BQR8NJD5XWMC6FTP0",
      "title": "Broken Object Level Authorization — GET /api/v1/users/{id}",
      "severity": "high",
      "root_cause": "The endpoint resolves the resource by the ID in the path without verifying that the requesting user owns or has permission to access that resource. Any authenticated user can substitute a different numeric ID to retrieve another user's data.",
      "affected_component": "GET /api/v1/users/{id} — authorization middleware",
      "suggested_fix": "Add an ownership check in the request handler: verify that `current_user.id == requested_id` (or that the user has an explicit permission grant) before returning the resource. Consider using a dedicated authorization library such as Pundit (Ruby) or Casbin (Go/Python) for policy enforcement."
    }
  ],
  "quota_applied": false,
  "findings_analyzed": 3,
  "findings_skipped": 0
}

When quota_applied is true, findings_skipped shows how many findings were not analyzed due to the Pro plan limit.

Dashboard

Root Cause cards appear inline on:

• Testing → Scans — failed test scenarios show a 🧠 Root Cause accordion beneath the assertion failure details
• Testing → Security — each critical or high finding shows a 🧠 Root Cause panel with the diagnosis and fix suggestion
• Insights → History — historical scan results include RCA if analysis was performed

Running on-demand from the dashboard

On any scan detail page, click Analyze Failures in the top-right action bar. This triggers POST /api/v1/scan/{scan_id}/analyze and updates the page in real time.

HTML and PDF reports

When RCA data is available, the exported HTML and PDF reports include a dedicated Root Cause Analysis section after the Findings table. Each analyzed finding shows:

• Finding title and severity
• Root cause paragraph
• Affected component
• Suggested fix

Findings not analyzed (due to quota or lack of LLM configuration) are listed separately with a note.

Feature availability

LLM provider configuration

Root Cause Analysis requires a configured LLM provider. Run nat doctor to verify your setup, or see LLM provider configuration for environment variable details.

If no LLM provider is configured, RCA is silently skipped and no Root Cause cards appear in the dashboard. A warning banner in Settings → Getting Started will prompt you to configure an LLM key.

Related

• LLM Test Plan Generator — generate test plans from an OpenAPI spec
• Natural Language Test Authoring — describe tests in plain English
• PDF Reports — export RCA results in PDF format
• Pricing & Plans — plan comparison and quotas