doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements
This commit is contained in:
master
280
docs/api/gates-api.yaml
Normal file
280
docs/api/gates-api.yaml
Normal file
@@ -0,0 +1,280 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Stella Ops Gates API
|
||||
description: |
|
||||
Gate check API for unknowns queue integration.
|
||||
|
||||
Sprint: SPRINT_20260118_018_Unknowns_queue_enhancement (UQ-006)
|
||||
|
||||
## Overview
|
||||
|
||||
The Gates API provides endpoints to check if a component can pass through
|
||||
the release gate based on its unknowns status. It implements fail-closed
|
||||
semantics by default for HOT unknowns.
|
||||
|
||||
## Gate Decisions
|
||||
|
||||
- **pass**: No blocking unknowns, component may proceed
|
||||
- **warn**: Non-blocking unknowns present, proceed with caution
|
||||
- **block**: HOT unknowns, KEV items, or SLA breaches require resolution
|
||||
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: Stella Ops Team
|
||||
license:
|
||||
name: AGPL-3.0-or-later
|
||||
|
||||
servers:
|
||||
- url: /api/v1
|
||||
description: API v1
|
||||
|
||||
tags:
|
||||
- name: Gates
|
||||
description: Gate check operations for unknowns
|
||||
|
||||
paths:
|
||||
/gates/{bom_ref}:
|
||||
get:
|
||||
operationId: getGateStatus
|
||||
tags: [Gates]
|
||||
summary: Get gate check result for a component
|
||||
description: |
|
||||
Returns the current unknowns state and gate decision for a BOM reference.
|
||||
Results are cached for 30 seconds.
|
||||
parameters:
|
||||
- name: bom_ref
|
||||
in: path
|
||||
required: true
|
||||
description: URL-encoded BOM reference (PURL)
|
||||
schema:
|
||||
type: string
|
||||
example: pkg%3Anpm%2Flodash%404.17.21
|
||||
responses:
|
||||
'200':
|
||||
description: Gate status retrieved successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GateStatusResponse'
|
||||
'500':
|
||||
description: Internal server error
|
||||
|
||||
/gates/{bom_ref}/check:
|
||||
post:
|
||||
operationId: checkGate
|
||||
tags: [Gates]
|
||||
summary: Perform gate check for a component
|
||||
description: |
|
||||
Performs a fresh gate check with optional verdict proposal.
|
||||
Returns 403 if the gate is blocked.
|
||||
parameters:
|
||||
- name: bom_ref
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GateCheckRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Gate passed or warning
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GateCheckResponse'
|
||||
'403':
|
||||
description: Gate blocked
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GateCheckResponse'
|
||||
|
||||
/gates/{bom_ref}/exception:
|
||||
post:
|
||||
operationId: requestGateException
|
||||
tags: [Gates]
|
||||
summary: Request an exception to bypass the gate
|
||||
description: |
|
||||
Requests approval to bypass blocking unknowns.
|
||||
Exceptions are not auto-granted and require manual approval.
|
||||
parameters:
|
||||
- name: bom_ref
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ExceptionRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Exception granted
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ExceptionResponse'
|
||||
'403':
|
||||
description: Exception denied
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ExceptionResponse'
|
||||
|
||||
components:
|
||||
schemas:
|
||||
GateStatusResponse:
|
||||
type: object
|
||||
required:
|
||||
- bom_ref
|
||||
- state
|
||||
- gate_decision
|
||||
- checked_at
|
||||
properties:
|
||||
bom_ref:
|
||||
type: string
|
||||
description: BOM reference (PURL)
|
||||
example: "pkg:npm/lodash@4.17.21"
|
||||
state:
|
||||
type: string
|
||||
enum: [resolved, pending, under_review, escalated, rejected]
|
||||
description: Aggregate state across all unknowns
|
||||
verdict_hash:
|
||||
type: string
|
||||
nullable: true
|
||||
description: SHA-256 hash of verdict if resolved
|
||||
example: "sha256:abc123..."
|
||||
unknowns:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/UnknownDto'
|
||||
gate_decision:
|
||||
type: string
|
||||
enum: [pass, warn, block]
|
||||
description: Gate decision
|
||||
checked_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: When the check was performed
|
||||
|
||||
UnknownDto:
|
||||
type: object
|
||||
required:
|
||||
- unknown_id
|
||||
- band
|
||||
- state
|
||||
properties:
|
||||
unknown_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Unknown entry ID
|
||||
cve_id:
|
||||
type: string
|
||||
nullable: true
|
||||
description: CVE identifier if applicable
|
||||
example: "CVE-2026-1234"
|
||||
band:
|
||||
type: string
|
||||
enum: [hot, warm, cold]
|
||||
description: Priority band based on score
|
||||
sla_remaining_hours:
|
||||
type: number
|
||||
nullable: true
|
||||
description: Hours remaining before SLA breach
|
||||
state:
|
||||
type: string
|
||||
enum: [pending, under_review, escalated, resolved, rejected]
|
||||
description: Current processing state
|
||||
|
||||
GateCheckRequest:
|
||||
type: object
|
||||
properties:
|
||||
proposed_verdict:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Proposed VEX verdict (e.g., "not_affected")
|
||||
example: "not_affected"
|
||||
|
||||
GateCheckResponse:
|
||||
type: object
|
||||
required:
|
||||
- bom_ref
|
||||
- decision
|
||||
- state
|
||||
- checked_at
|
||||
properties:
|
||||
bom_ref:
|
||||
type: string
|
||||
decision:
|
||||
type: string
|
||||
enum: [pass, warn, block]
|
||||
state:
|
||||
type: string
|
||||
blocking_unknown_ids:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
format: uuid
|
||||
reason:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Human-readable reason for decision
|
||||
exception_granted:
|
||||
type: boolean
|
||||
description: Whether an exception was granted
|
||||
exception_ref:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Exception reference if granted
|
||||
checked_at:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
ExceptionRequest:
|
||||
type: object
|
||||
required:
|
||||
- justification
|
||||
properties:
|
||||
unknown_ids:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
format: uuid
|
||||
description: IDs of unknowns to bypass
|
||||
justification:
|
||||
type: string
|
||||
description: Business justification for exception
|
||||
minLength: 10
|
||||
|
||||
ExceptionResponse:
|
||||
type: object
|
||||
required:
|
||||
- granted
|
||||
- requested_at
|
||||
properties:
|
||||
granted:
|
||||
type: boolean
|
||||
description: Whether exception was granted
|
||||
exception_ref:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Exception reference for tracking
|
||||
denial_reason:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Reason if not granted
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: When exception expires
|
||||
requested_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: When request was made
|
||||
Reference in New Issue
Block a user