2e89a92d92
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Introduced a new OpenAPI YAML file for the StellaOps Concelier service. - Defined endpoints for listing linksets, retrieving linksets by advisory ID, and searching linksets. - Included detailed parameter specifications and response schemas for each endpoint. - Established components for reusable parameters and schemas, enhancing API documentation clarity.
277 lines
8.2 KiB
YAML
277 lines
8.2 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: StellaOps Concelier – Link-Not-Merge Policy APIs
|
||
version: "0.1.0"
|
||
description: Fact-only advisory/linkset retrieval for Policy Engine consumers.
|
||
servers:
|
||
- url: /
|
||
description: Relative base path (API Gateway rewrites in production).
|
||
tags:
|
||
- name: Linksets
|
||
description: Link-Not-Merge linkset retrieval
|
||
paths:
|
||
/v1/lnm/linksets:
|
||
get:
|
||
summary: List linksets
|
||
tags: [Linksets]
|
||
parameters:
|
||
- $ref: '#/components/parameters/Tenant'
|
||
- name: includeConflicts
|
||
in: query
|
||
required: false
|
||
schema: { type: boolean, default: true }
|
||
- name: includeObservations
|
||
in: query
|
||
required: false
|
||
schema: { type: boolean, default: false }
|
||
- $ref: '#/components/parameters/purl'
|
||
- $ref: '#/components/parameters/cpe'
|
||
- $ref: '#/components/parameters/ghsa'
|
||
- $ref: '#/components/parameters/cve'
|
||
- $ref: '#/components/parameters/advisoryId'
|
||
- $ref: '#/components/parameters/source'
|
||
- $ref: '#/components/parameters/severityMin'
|
||
- $ref: '#/components/parameters/severityMax'
|
||
- $ref: '#/components/parameters/publishedSince'
|
||
- $ref: '#/components/parameters/modifiedSince'
|
||
- $ref: '#/components/parameters/page'
|
||
- $ref: '#/components/parameters/pageSize'
|
||
- $ref: '#/components/parameters/sort'
|
||
responses:
|
||
"200":
|
||
description: Deterministically ordered list of linksets
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PagedLinksets'
|
||
/v1/lnm/linksets/{advisoryId}:
|
||
get:
|
||
summary: Get linkset by advisory ID
|
||
tags: [Linksets]
|
||
parameters:
|
||
- $ref: '#/components/parameters/Tenant'
|
||
- name: advisoryId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: source
|
||
in: query
|
||
required: false
|
||
schema: { type: string }
|
||
- name: includeConflicts
|
||
in: query
|
||
required: false
|
||
schema: { type: boolean, default: true }
|
||
- name: includeObservations
|
||
in: query
|
||
required: false
|
||
schema: { type: boolean, default: false }
|
||
responses:
|
||
"200":
|
||
description: Linkset with provenance and conflicts
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Linkset'
|
||
"404":
|
||
description: Not found
|
||
/v1/lnm/linksets/search:
|
||
post:
|
||
summary: Search linksets (body filters)
|
||
tags: [Linksets]
|
||
parameters:
|
||
- $ref: '#/components/parameters/Tenant'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/LinksetSearchRequest'
|
||
responses:
|
||
"200":
|
||
description: Deterministically ordered search results
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PagedLinksets'
|
||
components:
|
||
parameters:
|
||
Tenant:
|
||
name: Tenant
|
||
in: header
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: Tenant identifier (required).
|
||
purl:
|
||
name: purl
|
||
in: query
|
||
schema:
|
||
type: array
|
||
items: { type: string }
|
||
style: form
|
||
explode: true
|
||
cpe:
|
||
name: cpe
|
||
in: query
|
||
schema: { type: string }
|
||
ghsa:
|
||
name: ghsa
|
||
in: query
|
||
schema: { type: string }
|
||
cve:
|
||
name: cve
|
||
in: query
|
||
schema: { type: string }
|
||
advisoryId:
|
||
name: advisoryId
|
||
in: query
|
||
schema: { type: string }
|
||
source:
|
||
name: source
|
||
in: query
|
||
schema:
|
||
type: string
|
||
severityMin:
|
||
name: severityMin
|
||
in: query
|
||
schema:
|
||
type: number
|
||
format: float
|
||
severityMax:
|
||
name: severityMax
|
||
in: query
|
||
schema:
|
||
type: number
|
||
format: float
|
||
publishedSince:
|
||
name: publishedSince
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
modifiedSince:
|
||
name: modifiedSince
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
page:
|
||
name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
default: 1
|
||
pageSize:
|
||
name: pageSize
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 200
|
||
default: 50
|
||
sort:
|
||
name: sort
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- modifiedAt desc
|
||
- modifiedAt asc
|
||
- publishedAt desc
|
||
- publishedAt asc
|
||
- severity desc
|
||
- severity asc
|
||
- source
|
||
- advisoryId
|
||
description: Default modifiedAt desc; ties advisoryId asc, source asc.
|
||
schemas:
|
||
LinksetSearchRequest:
|
||
type: object
|
||
properties:
|
||
purl: { type: array, items: { type: string } }
|
||
cpe: { type: array, items: { type: string } }
|
||
ghsa: { type: string }
|
||
cve: { type: string }
|
||
advisoryId: { type: string }
|
||
source: { type: string }
|
||
severityMin: { type: number }
|
||
severityMax: { type: number }
|
||
publishedSince: { type: string, format: date-time }
|
||
modifiedSince: { type: string, format: date-time }
|
||
includeTimeline: { type: boolean, default: false }
|
||
includeObservations: { type: boolean, default: false }
|
||
includeConflicts: { type: boolean, default: true }
|
||
page: { type: integer, minimum: 1, default: 1 }
|
||
pageSize: { type: integer, minimum: 1, maximum: 200, default: 50 }
|
||
sort: { type: string, enum: [modifiedAt desc, modifiedAt asc, publishedAt desc, publishedAt asc, severity desc, severity asc, source, advisoryId] }
|
||
PagedLinksets:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/Linkset' }
|
||
page: { type: integer }
|
||
pageSize: { type: integer }
|
||
total: { type: integer }
|
||
Linkset:
|
||
type: object
|
||
required: [advisoryId, source, purl, cpe, provenance]
|
||
properties:
|
||
advisoryId: { type: string }
|
||
source: { type: string }
|
||
purl: { type: array, items: { type: string } }
|
||
cpe: { type: array, items: { type: string } }
|
||
summary: { type: string }
|
||
publishedAt: { type: string, format: date-time }
|
||
modifiedAt: { type: string, format: date-time }
|
||
severity: { type: string, description: Source-native severity label }
|
||
status: { type: string }
|
||
provenance: { $ref: '#/components/schemas/LinksetProvenance' }
|
||
conflicts:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/LinksetConflict' }
|
||
timeline:
|
||
type: array
|
||
items: { $ref: '#/components/schemas/LinksetTimeline' }
|
||
normalized:
|
||
type: object
|
||
properties:
|
||
aliases: { type: array, items: { type: string } }
|
||
purl: { type: array, items: { type: string } }
|
||
versions: { type: array, items: { type: string } }
|
||
ranges: { type: array, items: { type: object } }
|
||
severities: { type: array, items: { type: object } }
|
||
cached:
|
||
type: boolean
|
||
description: True if served from cache; provenance.evidenceHash present for integrity.
|
||
remarks:
|
||
type: array
|
||
items: { type: string }
|
||
observations:
|
||
type: array
|
||
items: { type: string }
|
||
LinksetProvenance:
|
||
type: object
|
||
properties:
|
||
ingestedAt: { type: string, format: date-time }
|
||
connectorId: { type: string }
|
||
evidenceHash: { type: string }
|
||
dsseEnvelopeHash: { type: string }
|
||
LinksetConflict:
|
||
type: object
|
||
properties:
|
||
field: { type: string }
|
||
reason: { type: string }
|
||
observedValue: { type: string }
|
||
observedAt: { type: string, format: date-time }
|
||
evidenceHash: { type: string }
|
||
LinksetTimeline:
|
||
type: object
|
||
properties:
|
||
event: { type: string }
|
||
at: { type: string, format: date-time }
|
||
evidenceHash: { type: string }
|