Finding Schema

Every engine on the platform — CSPM checks, CIEM, vulnerability, data security, CDR, and the rest of the 29 engines — emits findings normalized to one shared data model. This reference documents that model: the base finding item, the detail response with its compliance and remediation blocks, the list envelopes, the status lifecycle, and the severity scale. If you consume findings through the REST API or a webhook integration, this is the contract.

Where findings come from

Engines write findings into tenant-scoped engine databases during each scan run. The BFF gateway serves them through two shapes: compact list rows for tables (GET /api/v1/<engine>/findings) and a full detail document for the finding page (GET /api/v1/views/finding/{engine}/{id}).

Field naming is cloud-neutral by design, so one integration works across all 7 providers:

BaseFindingItem

BaseFindingItem is the required base for every per-finding list item, regardless of engine.

Credential fields never reach the API. credential_ref and credential_type are declared on the model but excluded from serialization, and a validator rejects any payload containing credential- or secret-material keys anywhere in its nested structure. This is enforced in the schema layer as defense in depth — not just in the UI.

Example finding

{
  "finding_id": "chk-4f9a2c31",
  "resource_uid": "arn:aws:s3:::billing-exports",
  "resource_type": "aws_s3_bucket",
  "provider": "aws",
  "region": "us-east-1",
  "severity": "critical",
  "status": "OPEN",
  "account_id": "123456789012",
  "scan_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_seen_at": "2026-06-28T04:12:09Z",
  "last_seen_at": "2026-07-19T04:10:44Z",
  "provider_metadata": {
    "bucket_policy_is_public": true,
    "block_public_access_enabled": false
  }
}

Severity levels

Five severity levels apply across all engines. Severity is assigned by the rule (for configuration findings) or computed (for vulnerabilities, where EPSS and CISA KEV feed prioritization).

Status lifecycle

Finding status is mutable through the console and the API. New findings open as OPEN; every transition is audit-logged.

Status is updated with a StatusUpdateRequest:

PATCH /api/v1/views/finding/{engine}/{id}/status

{
  "status": "SUPPRESSED",
  "note": "Public access is intentional - static website bucket, exception EX-142."
}

If a resource regresses after being RESOLVED — the misconfiguration comes back — the next scan reopens the finding as OPEN and preserves the original first_seen_at, so your mean-time-to-remediate metrics stay honest.

FindingDetailResponse

GET /api/v1/views/finding/{engine}/{id} returns the full detail document that powers the finding page's tabs. The engine path segment is one of: check, threat, iam, network-security, datasec, encryption, container-security, dbsec, ai-security, cdr, secops, attack-path, api-security.

FindingHeader

The header carries identity, rule metadata, taxonomy, and framework mappings. Detail responses use camelCase field names. Key fields:

ComplianceBlock

Maps the finding's rule to compliance controls across the 70+ supported frameworks.

RemediationBlock

RelatedFindingsBlock

Cross-engine findings on the same resource_uid, fetched with a bounded per-engine fan-out.

List envelopes

Three container shapes wrap findings in list and aggregate responses.

PaginatedList — every scrollable table:

SeverityCounts — KPI breakdowns:

ScanRunRef — lightweight scan-run metadata attached to results:

Next steps

• API Reference — authentication, pagination, and the endpoint map these schemas travel through
• CSPM — how the Check engine evaluates 10,000+ rules to produce configuration findings
• Integration Catalog — push these finding payloads to Jira, Slack, Splunk, or any webhook
• Data Retention — how long findings are stored and when they are deleted