Contract: Canonical Model (v0)¶
This contract defines the normalized entities, relationships, and required provenance fields that power Discovery and Access Explorer.
Entities (Nouns)¶
Principal¶
Represents a human or non-human actor.
Required fields: - canonical_id - type: human | nonhuman - display_name - status (active/inactive/unknown) - provenance (see below)
Account¶
System-specific identity record.
Required fields: - canonical_id - provider (aws|azure|cyberark_identity) - native_type (provider-specific label) - native_id (ARN/GUID/etc.) - display_name - cloud_account_boundary_id (if applicable) - provenance
Entitlement¶
Authorization construct (role/group/policy/permission set).
Required fields: - canonical_id - provider - native_type - native_id - display_name - cloud_account_boundary_id (if applicable) - provenance
Resource¶
Target accessed.
Required fields: - canonical_id - provider - native_type - native_id - display_name - cloud_account_boundary_id (if applicable) - provenance
Cloud Account Boundary¶
Provider container (AWS Account / Azure Subscription).
Required fields: - canonical_id - provider - native_id - display_name - provenance
Relationships (Verbs)¶
principal_represents_account¶
Principal ↔ Account Required fields: - from_principal_id - to_account_id - confidence (0-1 or low/med/high) - provenance
account_assigned_entitlement¶
Account -> Entitlement Required fields: - from_account_id - to_entitlement_id - provenance
entitlement_grants_resource¶
Entitlement -> Resource Required fields: - from_entitlement_id - to_resource_id - provenance
Optional relationship for providers supporting direct grants: - account_grants_resource (Account -> Resource)
Derived Concept: Access Path¶
Access Path is computed from relationships. Canonical display should show: Principal -> Account -> Entitlement -> Resource and a provenance panel for each hop.
Provenance (Required on every entity & relationship)¶
- source_system (aws|azure|cyberark_identity)
- source_object_id (native id)
- observed_at (timestamp)
- run_id (discovery run)
- confidence (required where any heuristic join occurs)
- evidence_ref (pointer to raw detail or source reference)