ahmido
6a5b8a3a11
Some checks failed
Main Confidence / confidence (push) Failing after 50s
## Summary - add a config-seeded canonical control catalog plus shared resolution primitives and Microsoft subject bindings - propagate canonical control references into findings-derived evidence snapshots and tenant review composition - add the feature spec artifacts and focused Pest coverage, plus the supporting workspace and Sail helper adjustments included in this branch ## Testing - cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Governance/CanonicalControlCatalogTest.php tests/Unit/Governance/CanonicalControlResolverTest.php tests/Feature/Governance/CanonicalControlResolutionIntegrationTest.php tests/Feature/Evidence/EvidenceSnapshotCanonicalControlReferenceTest.php tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php tests/Feature/PlatformRelocation/CommandModelSmokeTest.php - cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #272
133 lines
5.2 KiB
Markdown
133 lines
5.2 KiB
Markdown
# Data Model: Canonical Control Catalog Foundation
|
|
|
|
## Overview
|
|
|
|
The first slice introduces a product-seeded control catalog and a shared resolution contract. The catalog itself is not operator-managed persistence in v1; it is a bounded canonical registry consumed by existing governance domains.
|
|
|
|
## Entity: CanonicalControlDefinition
|
|
|
|
- **Purpose**: Represents one stable governance control objective independent of framework clauses, provider identifiers, or individual workload payloads.
|
|
- **Identity**:
|
|
- `control_key` — stable canonical slug, unique across the catalog
|
|
- **Core fields**:
|
|
- `name`
|
|
- `domain_key`
|
|
- `subdomain_key`
|
|
- `control_class`
|
|
- `summary`
|
|
- `operator_description`
|
|
- **Semantics fields**:
|
|
- `detectability_class`
|
|
- `evaluation_strategy`
|
|
- `evidence_archetypes[]`
|
|
- `artifact_suitability`
|
|
- `historical_status` — `active` or `retired`
|
|
- **Validation rules**:
|
|
- `control_key` must be stable, lowercase, and provider-neutral.
|
|
- `domain_key` and `subdomain_key` must point to canonical catalog taxonomy, not framework or provider namespaces.
|
|
- Each control must declare at least one evidence archetype.
|
|
- Each control must declare explicit suitability flags for baseline, drift, finding, exception, evidence, review, and report usage.
|
|
|
|
## Entity: MicrosoftSubjectBinding
|
|
|
|
- **Purpose**: Connects provider-owned Microsoft subjects, workloads, or signals to one canonical control without redefining the control.
|
|
- **Fields**:
|
|
- `control_key`
|
|
- `provider` — always `microsoft` in the first slice
|
|
- `subject_family_key`
|
|
- `workload`
|
|
- `signal_keys[]`
|
|
- `supported_contexts[]` — for example baseline, finding, evidence, exception, review, report
|
|
- `primary` — whether this binding is the default control for the declared context
|
|
- `notes`
|
|
- **Validation rules**:
|
|
- Every binding must reference an existing `control_key`.
|
|
- Provider-specific descriptors must not overwrite control-core terminology.
|
|
- More than one binding may point to the same control.
|
|
- Multiple controls may only claim the same binding context when the ambiguity is intentionally declared and handled.
|
|
|
|
## Entity: CanonicalControlResolutionResult
|
|
|
|
- **Purpose**: Shared response contract for downstream consumers.
|
|
- **Resolver matching rule**: provider, consumer context, and every supplied subject-family, workload, or signal discriminator combine conjunctively to narrow candidate bindings.
|
|
- **States**:
|
|
- `resolved`
|
|
- `unresolved`
|
|
- `ambiguous`
|
|
- **Fields when resolved**:
|
|
- `status` — always `resolved`
|
|
- `control` — full `CanonicalControlDefinition` payload containing:
|
|
- `control_key`
|
|
- `name`
|
|
- `domain_key`
|
|
- `subdomain_key`
|
|
- `control_class`
|
|
- `summary`
|
|
- `operator_description`
|
|
- `detectability_class`
|
|
- `evaluation_strategy`
|
|
- `evidence_archetypes[]`
|
|
- `artifact_suitability`
|
|
- `historical_status`
|
|
- **Fields when unresolved**:
|
|
- `reason_code` — stable failure vocabulary such as `missing_binding`, `unsupported_provider`, `unsupported_consumer_context`, or `insufficient_context`
|
|
- `binding_context`
|
|
- **Fields when ambiguous**:
|
|
- `reason_code` — stable failure vocabulary, including `ambiguous_binding`
|
|
- `candidate_control_keys[]`
|
|
- `binding_context`
|
|
- **Validation rules**:
|
|
- `resolved` returns exactly one canonical control.
|
|
- All supplied discriminator inputs must narrow resolution together; the resolver must not ignore a provided field to force a match.
|
|
- `ambiguous` returns no guessed winner.
|
|
- `unresolved` returns no local fallback label.
|
|
|
|
## Supporting Classifications
|
|
|
|
### DetectabilityClass
|
|
|
|
- `direct_technical`
|
|
- `indirect_technical`
|
|
- `workflow_attested`
|
|
- `external_evidence_only`
|
|
|
|
### EvaluationStrategy
|
|
|
|
- `state_evaluated`
|
|
- `signal_inferred`
|
|
- `workflow_confirmed`
|
|
- `externally_attested`
|
|
|
|
### EvidenceArchetype
|
|
|
|
- `configuration_snapshot`
|
|
- `execution_result`
|
|
- `policy_or_assignment_summary`
|
|
- `operator_attestation`
|
|
- `external_artifact_reference`
|
|
|
|
## Relationships
|
|
|
|
- One `CanonicalControlDefinition` has many `MicrosoftSubjectBinding` records.
|
|
- One `MicrosoftSubjectBinding` references exactly one canonical control.
|
|
- One governed subject or signal context may resolve to one control or to an explicit ambiguous set.
|
|
- Existing governance consumers remain the owners of their own records and read models; they do not become child entities of the canonical catalog.
|
|
|
|
## Lifecycle
|
|
|
|
### CanonicalControlDefinition lifecycle
|
|
|
|
- `active`: valid for new bindings and downstream use
|
|
- `retired`: historical references remain resolvable, but new adoption should stop unless explicitly allowed
|
|
|
|
### Resolution lifecycle
|
|
|
|
- `resolved`: downstream consumer may use canonical metadata directly
|
|
- `unresolved`: downstream consumer must surface or log explicit absence rather than invent local meaning
|
|
- `ambiguous`: downstream consumer must stop and preserve explicit ambiguity until the binding model is clarified
|
|
|
|
## Rollout Model
|
|
|
|
- The first slice keeps the catalog seeded in code and consumed through the resolver.
|
|
- Broad persistence of `canonical_control_key` on downstream entities is deferred.
|
|
- First-slice adoption is read-through and bounded to findings-derived evidence composition and tenant review composition. |