Audit Lifecycle
The stages an audit passes through from submission to final report — queued, scanning, analyzing, summarizing, finalizing, complete.
Overview
When you submit a skill URL for auditing, Oathe processes it through a series of stages. Each stage performs a distinct operation — from cloning the repository to producing the final trust score. Understanding the lifecycle helps you track progress and troubleshoot issues.
Status Progression
| Stage | status Value | stage_label | What Happens |
|---|---|---|---|
| 1. Queued | queued | Waiting in queue | Audit is accepted and waiting for a worker |
| 2. Scanning | scanning | Installing and scanning | Skill is cloned, installed, and runtime behavior monitored |
| 3. Analyzing | analyzing | Applying threat patterns | 10 threat patterns are applied; AI behavioral analysis runs |
| 4. Summarizing | summarizing | Generating summary | Findings are compiled; dimension scores are calculated |
| 5. Finalizing | finalizing | Finalizing report | Trust score computed; verdict and recommendation assigned |
| 6. Complete | complete | Audit complete | Full report is available for retrieval |
| Failed | failed | Audit failed | An error occurred; error field contains details |
The status only moves forward. There is no mechanism to revert to a previous stage.
Stage Details
Queued
The audit has been accepted and assigned an audit_id. It is waiting for an available worker in the processing queue. Under normal load, this stage lasts less than 5 seconds. If the system is under heavy load, check the /health endpoint for the current queue_length.
Scanning
A worker picks up the audit. The skill repository is cloned at the specified commit or branch. The skill is installed in an isolated environment. Oathe monitors behavior during installation and initial execution.
Analyzing
The collected behavioral data is run through Oathe’s 10 threat patterns from the Open Threat Classification. Simultaneously, the AI behavioral model analyzes the runtime trace for patterns that static rules might miss. Findings are generated for each detected issue.
Summarizing
All findings are grouped by dimension. Dimension scores are calculated by subtracting each finding’s score_impact from 100. The audit summary text is generated.
Finalizing
The weighted trust score is computed from the six dimension scores. A verdict (SAFE, CAUTION, DANGEROUS, or MALICIOUS) and a recommendation are assigned based on the score thresholds. The final report object is assembled.
Complete
The audit is done. The full report is available at GET /api/audit/{audit_id}. This is a terminal state — the report does not change after this point.
Failed
Something went wrong during processing. Common causes include: the repository URL is unreachable, the skill has no valid entry point, or an internal timeout was exceeded. The error field in the response contains a human-readable message.
Typical Duration
Most audits complete in 30 to 90 seconds. Breakdown:
| Stage | Typical Duration |
|---|---|
| Queued | < 5 seconds |
| Scanning | 10 - 30 seconds |
| Analyzing | 10 - 30 seconds |
| Summarizing | 5 - 10 seconds |
| Finalizing | 2 - 5 seconds |
Complex skills with many tools or large dependency trees take longer in the scanning stage.
Tracking Progress
Polling
The simplest approach. Periodically request the audit status:
curl https://audit-engine.oathe.ai/api/audit/{audit_id}Check the status field. Poll every 3-5 seconds until the value is complete or failed.
WebSocket
For real-time updates, connect to the WebSocket endpoint:
wss://audit-engine.oathe.ai/ws/audit/{audit_id}The server pushes a message each time the status changes. The connection closes automatically when the audit reaches complete or failed.
Deduplication
If you submit a skill URL that was already audited at the same commit, Oathe returns the existing audit instead of running a new one. The response includes "deduplicated": true and the audit_id of the original audit.
To force a fresh audit, include "force_rescan": true in the POST body:
{
"skill_url": "https://github.com/your-org/your-skill",
"force_rescan": true
}The stage_label Field
The stage_label field provides a human-readable string suitable for display in a UI. It is always present in the response alongside status. Use status for programmatic logic and stage_label for user-facing messages.