ahmido
75ebade345
## Summary Implements Spec 284 for provider-neutral artifact source taxonomy. - add shared artifact source descriptor, resolver, taxonomy, and provider-detail support - update findings, evidence snapshots, stored reports, inventory items, and tenant review surfaces to disclose descriptor-first artifact summaries - add bounded Pest unit, feature, guard, and browser coverage for the taxonomy slice - include the completed Spec 284 package artifacts under `specs/284-provider-neutral-artifact-source-taxonomy/` ## Notes - branch: `284-provider-neutral-artifact-source-taxonomy` - commit: `bf8d59e0` - this PR was created as part of the requested commit/push/PR flow against `platform-dev` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #343
619 lines
17 KiB
YAML
619 lines
17 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Provider-neutral Artifact Source Taxonomy Logical Contract
|
|
version: 0.1.0
|
|
description: >-
|
|
Logical GET surfaces and descriptor-first view models for the bounded 284
|
|
artifact-source taxonomy slice.
|
|
paths:
|
|
/logical/findings:
|
|
get:
|
|
summary: List findings with descriptor-first artifact summaries
|
|
operationId: listFindingsWithArtifactSourceDescriptor
|
|
responses:
|
|
'200':
|
|
description: Finding list page view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FindingListPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/findings/{findingId}:
|
|
get:
|
|
summary: View one finding with descriptor-first artifact summary
|
|
operationId: viewFindingWithArtifactSourceDescriptor
|
|
parameters:
|
|
- name: findingId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Finding detail view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FindingPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/evidence-snapshots:
|
|
get:
|
|
summary: List evidence snapshots with descriptor-first summaries
|
|
operationId: listEvidenceSnapshotsWithArtifactSourceDescriptor
|
|
responses:
|
|
'200':
|
|
description: Evidence snapshot list page view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EvidenceSnapshotListPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/evidence-snapshots/{snapshotId}:
|
|
get:
|
|
summary: View one evidence snapshot with descriptor-first item summaries
|
|
operationId: viewEvidenceSnapshotWithArtifactSourceDescriptor
|
|
parameters:
|
|
- name: snapshotId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Evidence snapshot detail view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EvidenceSnapshotPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/stored-reports:
|
|
get:
|
|
summary: List stored reports with descriptor-first summaries
|
|
operationId: listStoredReportsWithArtifactSourceDescriptor
|
|
responses:
|
|
'200':
|
|
description: Stored report list page view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StoredReportListPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/stored-reports/{reportId}:
|
|
get:
|
|
summary: View one stored report with descriptor-first summary
|
|
operationId: viewStoredReportWithArtifactSourceDescriptor
|
|
parameters:
|
|
- name: reportId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Stored report detail view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StoredReportPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/inventory-items:
|
|
get:
|
|
summary: List inventory items with descriptor-first summaries
|
|
operationId: listInventoryItemsWithArtifactSourceDescriptor
|
|
responses:
|
|
'200':
|
|
description: Inventory item list page view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/InventoryItemListPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/inventory-items/{inventoryItemId}:
|
|
get:
|
|
summary: View one inventory item with canonical and provider type split
|
|
operationId: viewInventoryItemWithArtifactSourceDescriptor
|
|
parameters:
|
|
- name: inventoryItemId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Inventory item detail view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/InventoryItemPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/tenant-reviews:
|
|
get:
|
|
summary: List tenant reviews with primary descriptor summaries
|
|
operationId: listTenantReviewsWithArtifactSourceDescriptor
|
|
responses:
|
|
'200':
|
|
description: Tenant review list page view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TenantReviewListPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
/logical/tenant-reviews/{reviewId}:
|
|
get:
|
|
summary: View one tenant review with descriptor-first artifact sections
|
|
operationId: viewTenantReviewWithArtifactSourceSections
|
|
parameters:
|
|
- name: reviewId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Tenant review detail view model
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TenantReviewPage'
|
|
'403':
|
|
$ref: '#/components/responses/ForbiddenResponse'
|
|
'404':
|
|
$ref: '#/components/responses/NotFoundResponse'
|
|
components:
|
|
responses:
|
|
ForbiddenResponse:
|
|
description: In-scope actor missing the required capability for the surface.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemResponse'
|
|
NotFoundResponse:
|
|
description: Workspace or managed-environment context is missing or out of scope for the actor.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProblemResponse'
|
|
schemas:
|
|
ProblemResponse:
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
message:
|
|
type: string
|
|
code:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
ArtifactSourceDescriptor:
|
|
type: object
|
|
required:
|
|
- workspace_id
|
|
- tenant_id
|
|
- source_family
|
|
- source_kind
|
|
- provider_key
|
|
- managed_environment_id
|
|
- source_target_kind
|
|
properties:
|
|
workspace_id:
|
|
type: integer
|
|
description: Derived workspace scope anchor for the artifact.
|
|
tenant_id:
|
|
type: integer
|
|
description: Derived tenant scope anchor for the artifact.
|
|
source_family:
|
|
type: string
|
|
enum:
|
|
- finding
|
|
- stored_report
|
|
- evidence_snapshot
|
|
- inventory
|
|
- operation_run
|
|
source_kind:
|
|
type: string
|
|
enum:
|
|
- model_summary
|
|
- stored_report
|
|
- operation_rollup
|
|
- inventory_projection
|
|
provider_key:
|
|
type: string
|
|
description: Current repo truth emits `microsoft` only.
|
|
provider_connection_id:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
managed_environment_id:
|
|
type: integer
|
|
description: Required managed-environment anchor inside the derived workspace and tenant scope.
|
|
source_target_kind:
|
|
type: string
|
|
enum:
|
|
- managed_environment
|
|
- governed_subject
|
|
- provider_connection
|
|
- operation_run
|
|
source_target_identifier:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
detector_key:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
description: >-
|
|
Standardized field only. 284 does not define a closed detector
|
|
catalog.
|
|
control_key:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
package_run_id:
|
|
type:
|
|
- integer
|
|
- 'null'
|
|
description: Optional future package hook. Remains null in current runtime.
|
|
InventoryTypeDescriptor:
|
|
type: object
|
|
required:
|
|
- canonical_type
|
|
- provider_object_type
|
|
- provider_display_type
|
|
properties:
|
|
canonical_type:
|
|
type: string
|
|
provider_object_type:
|
|
type: string
|
|
provider_display_type:
|
|
type: string
|
|
legacy_policy_type:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
ArtifactProviderDetail:
|
|
type: object
|
|
properties:
|
|
legacy_finding_type:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
legacy_report_type:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
legacy_policy_type:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
provider_object_type:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
provider_display_type:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
detector_detail:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
CanonicalControlSummary:
|
|
type: object
|
|
required:
|
|
- control_key
|
|
properties:
|
|
control_key:
|
|
type: string
|
|
label:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
status:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
FreshnessSummary:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Existing freshness or timing metadata carried through descriptor-first summaries.
|
|
FindingArtifactSummary:
|
|
type: object
|
|
required:
|
|
- id
|
|
- title
|
|
- severity
|
|
- status
|
|
- source_descriptor
|
|
properties:
|
|
id:
|
|
type: integer
|
|
title:
|
|
type: string
|
|
severity:
|
|
type: string
|
|
status:
|
|
type: string
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
provider_detail:
|
|
$ref: '#/components/schemas/ArtifactProviderDetail'
|
|
control_summary:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/CanonicalControlSummary'
|
|
- type: 'null'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
FindingListPage:
|
|
type: object
|
|
required:
|
|
- items
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FindingArtifactSummary'
|
|
FindingPage:
|
|
type: object
|
|
required:
|
|
- finding
|
|
properties:
|
|
finding:
|
|
$ref: '#/components/schemas/FindingArtifactSummary'
|
|
EvidenceSnapshotListEntry:
|
|
type: object
|
|
required:
|
|
- id
|
|
- managed_environment_id
|
|
- source_descriptor
|
|
properties:
|
|
id:
|
|
type: integer
|
|
managed_environment_id:
|
|
type: integer
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
control_summary:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/CanonicalControlSummary'
|
|
- type: 'null'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
EvidenceSnapshotListPage:
|
|
type: object
|
|
required:
|
|
- items
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EvidenceSnapshotListEntry'
|
|
EvidenceSnapshotItemViewModel:
|
|
type: object
|
|
required:
|
|
- dimension_key
|
|
- state
|
|
- source_descriptor
|
|
properties:
|
|
dimension_key:
|
|
type: string
|
|
state:
|
|
type: string
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
provider_detail:
|
|
$ref: '#/components/schemas/ArtifactProviderDetail'
|
|
control_summary:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/CanonicalControlSummary'
|
|
- type: 'null'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
EvidenceSnapshotPage:
|
|
type: object
|
|
required:
|
|
- id
|
|
- managed_environment_id
|
|
- items
|
|
properties:
|
|
id:
|
|
type: integer
|
|
managed_environment_id:
|
|
type: integer
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EvidenceSnapshotItemViewModel'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
StoredReportPage:
|
|
type: object
|
|
required:
|
|
- id
|
|
- summary
|
|
- source_descriptor
|
|
properties:
|
|
id:
|
|
type: integer
|
|
summary:
|
|
type: string
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
provider_detail:
|
|
$ref: '#/components/schemas/ArtifactProviderDetail'
|
|
control_summary:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/CanonicalControlSummary'
|
|
- type: 'null'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
StoredReportListEntry:
|
|
type: object
|
|
required:
|
|
- id
|
|
- summary
|
|
- source_descriptor
|
|
properties:
|
|
id:
|
|
type: integer
|
|
summary:
|
|
type: string
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
StoredReportListPage:
|
|
type: object
|
|
required:
|
|
- items
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/StoredReportListEntry'
|
|
InventoryItemPage:
|
|
type: object
|
|
required:
|
|
- id
|
|
- display_name
|
|
- type_descriptor
|
|
- source_descriptor
|
|
properties:
|
|
id:
|
|
type: integer
|
|
display_name:
|
|
type: string
|
|
type_descriptor:
|
|
$ref: '#/components/schemas/InventoryTypeDescriptor'
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
provider_detail:
|
|
$ref: '#/components/schemas/ArtifactProviderDetail'
|
|
InventoryItemListEntry:
|
|
type: object
|
|
required:
|
|
- id
|
|
- display_name
|
|
- type_descriptor
|
|
- source_descriptor
|
|
properties:
|
|
id:
|
|
type: integer
|
|
display_name:
|
|
type: string
|
|
type_descriptor:
|
|
$ref: '#/components/schemas/InventoryTypeDescriptor'
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
InventoryItemListPage:
|
|
type: object
|
|
required:
|
|
- items
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/InventoryItemListEntry'
|
|
TenantReviewArtifactSection:
|
|
type: object
|
|
required:
|
|
- section_key
|
|
- headline
|
|
- source_descriptor
|
|
properties:
|
|
section_key:
|
|
type: string
|
|
headline:
|
|
type: string
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
provider_detail:
|
|
$ref: '#/components/schemas/ArtifactProviderDetail'
|
|
control_summary:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/CanonicalControlSummary'
|
|
- type: 'null'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
TenantReviewListEntry:
|
|
type: object
|
|
required:
|
|
- id
|
|
- status
|
|
- source_descriptor
|
|
properties:
|
|
id:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
source_descriptor:
|
|
$ref: '#/components/schemas/ArtifactSourceDescriptor'
|
|
freshness:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/FreshnessSummary'
|
|
- type: 'null'
|
|
TenantReviewListPage:
|
|
type: object
|
|
required:
|
|
- items
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TenantReviewListEntry'
|
|
TenantReviewPage:
|
|
type: object
|
|
required:
|
|
- id
|
|
- status
|
|
- sections
|
|
properties:
|
|
id:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
sections:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TenantReviewArtifactSection' |