feat(rate-limiting): Implement core rate limiting functionality with configuration, decision-making, metrics, middleware, and service registration
- 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.
This commit is contained in:
master
622
docs/api/proofs-openapi.yaml
Normal file
622
docs/api/proofs-openapi.yaml
Normal file
@@ -0,0 +1,622 @@
|
||||
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
|
||||
Reference in New Issue
Block a user