8bbfe4d2d2
- Add RateLimitConfig for configuration management with YAML binding support. - Introduce RateLimitDecision to encapsulate the result of rate limit checks. - Implement RateLimitMetrics for OpenTelemetry metrics tracking. - Create RateLimitMiddleware for enforcing rate limits on incoming requests. - Develop RateLimitService to orchestrate instance and environment rate limit checks. - Add RateLimitServiceCollectionExtensions for dependency injection registration.
623 lines
17 KiB
YAML
623 lines
17 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: StellaOps Proof Chain API
|
|
version: 1.0.0
|
|
description: |
|
|
API for proof chain operations including proof spine creation, verification receipts,
|
|
VEX attestations, and trust anchor management.
|
|
|
|
The proof chain provides cryptographic evidence linking SBOM entries to vulnerability
|
|
assessments through attestable DSSE envelopes.
|
|
|
|
license:
|
|
name: AGPL-3.0-or-later
|
|
url: https://www.gnu.org/licenses/agpl-3.0.html
|
|
|
|
servers:
|
|
- url: https://api.stellaops.dev/v1
|
|
description: Production API
|
|
- url: http://localhost:5000/v1
|
|
description: Local development
|
|
|
|
tags:
|
|
- name: Proofs
|
|
description: Proof spine and receipt operations
|
|
- name: Anchors
|
|
description: Trust anchor management
|
|
- name: Verify
|
|
description: Proof verification endpoints
|
|
|
|
paths:
|
|
/proofs/{entry}/spine:
|
|
post:
|
|
operationId: createProofSpine
|
|
summary: Create proof spine for SBOM entry
|
|
description: |
|
|
Assembles a merkle-rooted proof spine from evidence, reasoning, and VEX verdict
|
|
for an SBOM entry. Returns a content-addressed proof bundle ID.
|
|
tags: [Proofs]
|
|
security:
|
|
- bearerAuth: []
|
|
- mtls: []
|
|
parameters:
|
|
- name: entry
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
|
|
description: SBOMEntryID in format sha256:<hash>:pkg:<purl>
|
|
example: "sha256:abc123...def:pkg:npm/lodash@4.17.21"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateSpineRequest'
|
|
responses:
|
|
'201':
|
|
description: Proof spine created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateSpineResponse'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'422':
|
|
$ref: '#/components/responses/ValidationError'
|
|
|
|
get:
|
|
operationId: getProofSpine
|
|
summary: Get proof spine for SBOM entry
|
|
description: Retrieves the existing proof spine for an SBOM entry.
|
|
tags: [Proofs]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: entry
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
|
|
description: SBOMEntryID
|
|
responses:
|
|
'200':
|
|
description: Proof spine retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProofSpineDto'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/proofs/{entry}/receipt:
|
|
get:
|
|
operationId: getProofReceipt
|
|
summary: Get verification receipt
|
|
description: |
|
|
Retrieves a verification receipt for the SBOM entry's proof spine.
|
|
The receipt includes merkle proof paths and signature verification status.
|
|
tags: [Proofs]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: entry
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
|
|
description: SBOMEntryID
|
|
responses:
|
|
'200':
|
|
description: Verification receipt
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VerificationReceiptDto'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/proofs/{entry}/vex:
|
|
get:
|
|
operationId: getProofVex
|
|
summary: Get VEX attestation for entry
|
|
description: Retrieves the VEX verdict attestation for the SBOM entry.
|
|
tags: [Proofs]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: entry
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}:pkg:.+'
|
|
description: SBOMEntryID
|
|
responses:
|
|
'200':
|
|
description: VEX attestation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VexAttestationDto'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/anchors:
|
|
get:
|
|
operationId: listAnchors
|
|
summary: List trust anchors
|
|
description: Lists all configured trust anchors with their status.
|
|
tags: [Anchors]
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: List of trust anchors
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
anchors:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TrustAnchorDto'
|
|
|
|
post:
|
|
operationId: createAnchor
|
|
summary: Create trust anchor
|
|
description: Creates a new trust anchor with the specified public key.
|
|
tags: [Anchors]
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateAnchorRequest'
|
|
responses:
|
|
'201':
|
|
description: Trust anchor created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TrustAnchorDto'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'409':
|
|
description: Anchor already exists
|
|
|
|
/anchors/{anchorId}:
|
|
get:
|
|
operationId: getAnchor
|
|
summary: Get trust anchor
|
|
description: Retrieves a specific trust anchor by ID.
|
|
tags: [Anchors]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: anchorId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Trust anchor ID
|
|
responses:
|
|
'200':
|
|
description: Trust anchor details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TrustAnchorDto'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
delete:
|
|
operationId: deleteAnchor
|
|
summary: Delete trust anchor
|
|
description: Deletes a trust anchor (soft delete, marks as revoked).
|
|
tags: [Anchors]
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: anchorId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Trust anchor ID
|
|
responses:
|
|
'204':
|
|
description: Anchor deleted
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/verify:
|
|
post:
|
|
operationId: verifyProofBundle
|
|
summary: Verify proof bundle
|
|
description: |
|
|
Performs full verification of a proof bundle including:
|
|
- DSSE signature verification
|
|
- Content-addressed ID recomputation
|
|
- Merkle path verification
|
|
- Optional Rekor inclusion proof verification
|
|
tags: [Verify]
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VerifyRequest'
|
|
responses:
|
|
'200':
|
|
description: Verification result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VerificationResultDto'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
|
|
/verify/batch:
|
|
post:
|
|
operationId: verifyBatch
|
|
summary: Verify multiple proof bundles
|
|
description: Performs batch verification of multiple proof bundles.
|
|
tags: [Verify]
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- bundles
|
|
properties:
|
|
bundles:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/VerifyRequest'
|
|
maxItems: 100
|
|
responses:
|
|
'200':
|
|
description: Batch verification results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
results:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/VerificationResultDto'
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: Authority-issued OpToken
|
|
mtls:
|
|
type: mutualTLS
|
|
description: Mutual TLS with client certificate
|
|
|
|
schemas:
|
|
CreateSpineRequest:
|
|
type: object
|
|
required:
|
|
- evidenceIds
|
|
- reasoningId
|
|
- vexVerdictId
|
|
- policyVersion
|
|
properties:
|
|
evidenceIds:
|
|
type: array
|
|
description: Content-addressed IDs of evidence statements
|
|
items:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}$'
|
|
minItems: 1
|
|
example: ["sha256:e7f8a9b0c1d2..."]
|
|
reasoningId:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}$'
|
|
description: Content-addressed ID of reasoning statement
|
|
example: "sha256:f0e1d2c3b4a5..."
|
|
vexVerdictId:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}$'
|
|
description: Content-addressed ID of VEX verdict statement
|
|
example: "sha256:d4c5b6a7e8f9..."
|
|
policyVersion:
|
|
type: string
|
|
pattern: '^v[0-9]+\.[0-9]+\.[0-9]+$'
|
|
description: Version of the policy used
|
|
example: "v1.2.3"
|
|
|
|
CreateSpineResponse:
|
|
type: object
|
|
required:
|
|
- proofBundleId
|
|
properties:
|
|
proofBundleId:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}$'
|
|
description: Content-addressed ID of the created proof bundle (merkle root)
|
|
example: "sha256:1a2b3c4d5e6f..."
|
|
receiptUrl:
|
|
type: string
|
|
format: uri
|
|
description: URL to retrieve the verification receipt
|
|
example: "/proofs/sha256:abc:pkg:npm/lodash@4.17.21/receipt"
|
|
|
|
ProofSpineDto:
|
|
type: object
|
|
required:
|
|
- sbomEntryId
|
|
- proofBundleId
|
|
- evidenceIds
|
|
- reasoningId
|
|
- vexVerdictId
|
|
- policyVersion
|
|
- createdAt
|
|
properties:
|
|
sbomEntryId:
|
|
type: string
|
|
description: The SBOM entry this spine covers
|
|
proofBundleId:
|
|
type: string
|
|
description: Merkle root hash of the proof bundle
|
|
evidenceIds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Sorted list of evidence IDs
|
|
reasoningId:
|
|
type: string
|
|
description: Reasoning statement ID
|
|
vexVerdictId:
|
|
type: string
|
|
description: VEX verdict statement ID
|
|
policyVersion:
|
|
type: string
|
|
description: Policy version used
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
description: Creation timestamp (UTC ISO-8601)
|
|
|
|
VerificationReceiptDto:
|
|
type: object
|
|
required:
|
|
- graphRevisionId
|
|
- findingKey
|
|
- decision
|
|
- createdAt
|
|
- verified
|
|
properties:
|
|
graphRevisionId:
|
|
type: string
|
|
description: Graph revision ID this receipt was computed from
|
|
findingKey:
|
|
type: object
|
|
properties:
|
|
sbomEntryId:
|
|
type: string
|
|
vulnerabilityId:
|
|
type: string
|
|
rule:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
version:
|
|
type: string
|
|
decision:
|
|
type: object
|
|
properties:
|
|
verdict:
|
|
type: string
|
|
enum: [pass, fail, warn, skip]
|
|
severity:
|
|
type: string
|
|
reasoning:
|
|
type: string
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
verified:
|
|
type: boolean
|
|
description: Whether the receipt signature verified correctly
|
|
|
|
VexAttestationDto:
|
|
type: object
|
|
required:
|
|
- sbomEntryId
|
|
- vulnerabilityId
|
|
- status
|
|
- vexVerdictId
|
|
properties:
|
|
sbomEntryId:
|
|
type: string
|
|
vulnerabilityId:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum: [not_affected, affected, fixed, under_investigation]
|
|
justification:
|
|
type: string
|
|
policyVersion:
|
|
type: string
|
|
reasoningId:
|
|
type: string
|
|
vexVerdictId:
|
|
type: string
|
|
|
|
TrustAnchorDto:
|
|
type: object
|
|
required:
|
|
- id
|
|
- keyId
|
|
- algorithm
|
|
- status
|
|
- createdAt
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique anchor identifier
|
|
keyId:
|
|
type: string
|
|
description: Key identifier (fingerprint)
|
|
algorithm:
|
|
type: string
|
|
enum: [ECDSA-P256, Ed25519, RSA-2048, RSA-4096]
|
|
description: Signing algorithm
|
|
publicKey:
|
|
type: string
|
|
description: PEM-encoded public key
|
|
status:
|
|
type: string
|
|
enum: [active, revoked, expired]
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
revokedAt:
|
|
type: string
|
|
format: date-time
|
|
|
|
CreateAnchorRequest:
|
|
type: object
|
|
required:
|
|
- keyId
|
|
- algorithm
|
|
- publicKey
|
|
properties:
|
|
keyId:
|
|
type: string
|
|
description: Key identifier
|
|
algorithm:
|
|
type: string
|
|
enum: [ECDSA-P256, Ed25519, RSA-2048, RSA-4096]
|
|
publicKey:
|
|
type: string
|
|
description: PEM-encoded public key
|
|
|
|
VerifyRequest:
|
|
type: object
|
|
required:
|
|
- proofBundleId
|
|
properties:
|
|
proofBundleId:
|
|
type: string
|
|
pattern: '^sha256:[a-f0-9]{64}$'
|
|
description: The proof bundle ID to verify
|
|
checkRekor:
|
|
type: boolean
|
|
default: true
|
|
description: Whether to verify Rekor inclusion proofs
|
|
anchorIds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Specific trust anchors to use for verification
|
|
|
|
VerificationResultDto:
|
|
type: object
|
|
required:
|
|
- proofBundleId
|
|
- verified
|
|
- checks
|
|
properties:
|
|
proofBundleId:
|
|
type: string
|
|
verified:
|
|
type: boolean
|
|
description: Overall verification result
|
|
checks:
|
|
type: object
|
|
properties:
|
|
signatureValid:
|
|
type: boolean
|
|
description: DSSE signature verification passed
|
|
idRecomputed:
|
|
type: boolean
|
|
description: Content-addressed IDs recomputed correctly
|
|
merklePathValid:
|
|
type: boolean
|
|
description: Merkle path verification passed
|
|
rekorInclusionValid:
|
|
type: boolean
|
|
description: Rekor inclusion proof verified (if checked)
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Error messages if verification failed
|
|
verifiedAt:
|
|
type: string
|
|
format: date-time
|
|
|
|
responses:
|
|
BadRequest:
|
|
description: Invalid request
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
detail:
|
|
type: string
|
|
status:
|
|
type: integer
|
|
example: 400
|
|
|
|
NotFound:
|
|
description: Resource not found
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
detail:
|
|
type: string
|
|
status:
|
|
type: integer
|
|
example: 404
|
|
|
|
ValidationError:
|
|
description: Validation error
|
|
content:
|
|
application/problem+json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
title:
|
|
type: string
|
|
detail:
|
|
type: string
|
|
status:
|
|
type: integer
|
|
example: 422
|
|
errors:
|
|
type: object
|
|
additionalProperties:
|
|
type: array
|
|
items:
|
|
type: string
|