Unified Risk Engine

The Unified Risk Engine (URE) is the orchestration layer at the heart of Ariftly. It coordinates multiple scan detectors, normalizes their findings into a shared schema, and produces a unified risk report.

Architecture

                    ┌────────────────────────────────┐
                    │       Ariftly Platform          │
                    │                                │
  Trigger ──────► │    Unified Risk Engine (URE)    │
  (API / CI / UI)  │                                │
                    │  ┌──────────┐  ┌───────────┐  │
                    │  │ Detector │  │ Detector  │  │
                    │  │ Runner   │  │ Runner    │  │
                    │  └────┬─────┘  └─────┬─────┘  │
                    │       │              │         │
                    │  ┌────▼──────────────▼─────┐  │
                    │  │   Result Normalizer      │  │
                    │  └────────────┬─────────────┘  │
                    │               │                │
                    │  ┌────────────▼─────────────┐  │
                    │  │    Risk Score Engine      │  │
                    │  └────────────┬─────────────┘  │
                    │               │                │
                    └───────────────┼────────────────┘
                                    │
                            Risk Report + Score

Key responsibilities

1. Detector orchestration

When a scan is triggered, the URE determines which detectors to run, launches them in parallel, and manages their lifecycle. Detectors are isolated — a failure in one does not affect others.

2. Result normalization

Each detector produces raw findings in its own format. The URE normalizes these into a canonical finding schema:

{
  "id": "finding_001",
  "detector": "accessibility",
  "severity": "high",
  "rule_id": "wcag-1-4-3",
  "title": "Insufficient color contrast",
  "description": "Text element has a contrast ratio of 2.1:1 (minimum 4.5:1 required)",
  "location": {
    "type": "dom_element",
    "selector": "button.cta-primary",
    "url": "https://myapp.example.com/home"
  },
  "remediation": "Increase the contrast ratio by adjusting the text or background color.",
  "references": ["https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum"]
}

3. Risk scoring

The URE aggregates all normalized findings and computes a risk score using a weighted formula that accounts for severity, category, and volume. See Risk Scoring for details.

4. Report generation

The final risk report contains:

• Overall risk score (0–100)
• Per-detector risk scores
• All normalized findings
• Remediation priorities
• Historical comparison (if previous scans exist)

Scan lifecycle

PENDING → RUNNING → COMPLETED
                  ↘ FAILED
                  ↘ CANCELLED

Status	Description
pending	Scan queued, not yet started
running	Detectors executing
completed	All detectors finished, report ready
failed	One or more detectors encountered a fatal error
cancelled	Scan was manually cancelled

Concurrency and isolation

• Detectors run in parallel within a scan for speed
• Each scan is isolated in its own execution environment
• Scans within the same project can also run concurrently (e.g., on different branches)
• Results from parallel scans do not interfere with each other

Extensibility

The URE is designed to be extended with new detectors over time. Each detector implements a standard interface:

1. Input: A target definition (URL, repo, API endpoint)
2. Output: A list of normalized findings + metadata

As new detectors are added to Ariftly, they plug directly into this framework with no changes required to the API or your integrations.