stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity

Add signal contracts for reachability, exploitability, trust, and unknown symbols
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Signals DSSE Sign & Evidence Locker / sign-signals-artifacts (push) Has been cancelled
Details
Signals DSSE Sign & Evidence Locker / verify-signatures (push) Has been cancelled
Details

Browse Source 
- Introduced `ReachabilityState`, `RuntimeHit`, `ExploitabilitySignal`, `ReachabilitySignal`, `SignalEnvelope`, `SignalType`, `TrustSignal`, and `UnknownSymbolSignal` records to define various signal types and their properties.
- Implemented JSON serialization attributes for proper data interchange.
- Created project files for the new signal contracts library and corresponding test projects.
- Added deterministic test fixtures for micro-interaction testing.
- Included cryptographic keys for secure operations with cosign.
This commit is contained in:
StellaOps Bot
2025-12-05 00:27:00 +02:00
parent b018949a8d
commit 8768c27f30
192 changed files with 27569 additions and 2552 deletions
Download Patch File Download Diff File Expand all files Collapse all files

628
docs/schemas/api-baseline.schema.json Normal file
View File

@@ -0,0 +1,628 @@
{
"$id": "https://stella.ops/schema/api-baseline.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ApiBaseline",
"description": "APIG0101 API governance baseline contract for OpenAPI spec management, compatibility tracking, and changelog generation",
"type": "object",
"oneOf": [
{ "$ref": "#/$defs/BaselineDocument" },
{ "$ref": "#/$defs/CompatibilityReport" },
{ "$ref": "#/$defs/ChangelogEntry" },
{ "$ref": "#/$defs/DiscoveryManifest" }
],
"$defs": {
"BaselineDocument": {
"type": "object",
"required": ["documentType", "schemaVersion", "generatedAt", "specVersion", "services"],
"properties": {
"documentType": {
"type": "string",
"const": "API_BASELINE"
},
"schemaVersion": {
"type": "integer",
"const": 1,
"description": "Baseline schema version"
},
"generatedAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when baseline was generated"
},
"specVersion": {
"type": "string",
"description": "OpenAPI specification version",
"examples": ["3.1.0", "3.0.3"]
},
"aggregateDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "SHA-256 digest of the composed aggregate spec"
},
"services": {
"type": "array",
"items": {
"$ref": "#/$defs/ServiceSpec"
},
"minItems": 1,
"description": "Per-service OpenAPI specifications"
},
"sharedComponents": {
"$ref": "#/$defs/SharedComponentsRef",
"description": "Reference to shared component library"
},
"governanceProfile": {
"$ref": "#/$defs/GovernanceProfile",
"description": "Governance rules applied to this baseline"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Additional baseline metadata"
}
}
},
"ServiceSpec": {
"type": "object",
"required": ["serviceId", "specPath", "specDigest", "version"],
"properties": {
"serviceId": {
"type": "string",
"description": "Unique service identifier",
"examples": ["authority", "scanner", "excititor", "concelier"]
},
"displayName": {
"type": "string",
"description": "Human-readable service name"
},
"specPath": {
"type": "string",
"description": "Relative path to service OpenAPI spec",
"examples": ["authority/openapi.yaml", "scanner/openapi.yaml"]
},
"specDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "SHA-256 digest of the service spec"
},
"version": {
"type": "string",
"description": "Service API version",
"examples": ["v1", "v2-beta"]
},
"operationCount": {
"type": "integer",
"minimum": 0,
"description": "Number of operations defined"
},
"schemaCount": {
"type": "integer",
"minimum": 0,
"description": "Number of schemas defined"
},
"exampleCoverage": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Percentage of responses with examples"
},
"securitySchemes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Security schemes used by this service",
"examples": [["bearerAuth", "mTLS", "OAuth2"]]
},
"endpoints": {
"type": "array",
"items": {
"$ref": "#/$defs/EndpointSummary"
},
"description": "Summary of endpoints in this service"
}
}
},
"EndpointSummary": {
"type": "object",
"required": ["path", "method", "operationId"],
"properties": {
"path": {
"type": "string",
"description": "API endpoint path"
},
"method": {
"type": "string",
"enum": ["get", "post", "put", "patch", "delete", "head", "options"],
"description": "HTTP method"
},
"operationId": {
"type": "string",
"description": "Unique operation identifier (lowerCamelCase)"
},
"summary": {
"type": "string",
"description": "Short operation summary"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation tags for grouping"
},
"deprecated": {
"type": "boolean",
"default": false,
"description": "Whether this endpoint is deprecated"
},
"hasRequestBody": {
"type": "boolean",
"description": "Whether operation accepts request body"
},
"responseStatuses": {
"type": "array",
"items": {
"type": "integer"
},
"description": "HTTP status codes returned"
}
}
},
"SharedComponentsRef": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Path to shared components directory",
"examples": ["_shared/"]
},
"digest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "Digest of shared components bundle"
},
"schemas": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of shared schema names"
},
"securitySchemes": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of shared security scheme names"
},
"parameters": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of shared parameter names"
},
"responses": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of shared response names"
}
}
},
"GovernanceProfile": {
"type": "object",
"properties": {
"spectralRuleset": {
"type": "string",
"description": "Path to Spectral ruleset file",
"examples": [".spectral.yaml"]
},
"rules": {
"type": "array",
"items": {
"$ref": "#/$defs/GovernanceRule"
},
"description": "Active governance rules"
},
"requiredExampleCoverage": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Minimum required example coverage percentage"
},
"breakingChangePolicy": {
"type": "string",
"enum": ["BLOCK", "WARN", "ALLOW"],
"description": "Policy for breaking changes"
}
}
},
"GovernanceRule": {
"type": "object",
"required": ["ruleId", "severity"],
"properties": {
"ruleId": {
"type": "string",
"description": "Spectral rule identifier",
"examples": ["stella-2xx-response-examples", "stella-pagination-params"]
},
"severity": {
"type": "string",
"enum": ["error", "warn", "info", "hint", "off"],
"description": "Rule severity level"
},
"description": {
"type": "string",
"description": "Rule description"
}
}
},
"CompatibilityReport": {
"type": "object",
"required": ["documentType", "generatedAt", "baselineDigest", "currentDigest", "compatible"],
"properties": {
"documentType": {
"type": "string",
"const": "COMPATIBILITY_REPORT"
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"baselineDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "Digest of baseline spec"
},
"currentDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "Digest of current spec"
},
"compatible": {
"type": "boolean",
"description": "Whether current spec is backward compatible"
},
"breakingChanges": {
"type": "array",
"items": {
"$ref": "#/$defs/BreakingChange"
},
"description": "List of breaking changes detected"
},
"additiveChanges": {
"type": "array",
"items": {
"$ref": "#/$defs/ApiChange"
},
"description": "List of additive (non-breaking) changes"
},
"deprecations": {
"type": "array",
"items": {
"$ref": "#/$defs/Deprecation"
},
"description": "New deprecations introduced"
}
}
},
"BreakingChange": {
"type": "object",
"required": ["changeType", "path", "description"],
"properties": {
"changeType": {
"type": "string",
"enum": [
"ENDPOINT_REMOVED",
"METHOD_REMOVED",
"REQUIRED_PARAM_ADDED",
"PARAM_REMOVED",
"RESPONSE_REMOVED",
"SCHEMA_INCOMPATIBLE",
"TYPE_CHANGED",
"SECURITY_STRENGTHENED"
],
"description": "Type of breaking change"
},
"path": {
"type": "string",
"description": "JSON pointer to changed element"
},
"description": {
"type": "string",
"description": "Human-readable change description"
},
"service": {
"type": "string",
"description": "Affected service"
},
"operationId": {
"type": "string",
"description": "Affected operation"
},
"before": {
"type": "string",
"description": "Previous value (if applicable)"
},
"after": {
"type": "string",
"description": "New value (if applicable)"
}
}
},
"ApiChange": {
"type": "object",
"required": ["changeType", "path"],
"properties": {
"changeType": {
"type": "string",
"enum": [
"ENDPOINT_ADDED",
"METHOD_ADDED",
"OPTIONAL_PARAM_ADDED",
"RESPONSE_ADDED",
"SCHEMA_EXTENDED",
"EXAMPLE_ADDED"
],
"description": "Type of additive change"
},
"path": {
"type": "string",
"description": "JSON pointer to changed element"
},
"description": {
"type": "string",
"description": "Human-readable change description"
},
"service": {
"type": "string",
"description": "Affected service"
}
}
},
"Deprecation": {
"type": "object",
"required": ["path", "deprecatedAt"],
"properties": {
"path": {
"type": "string",
"description": "JSON pointer to deprecated element"
},
"deprecatedAt": {
"type": "string",
"format": "date-time",
"description": "When deprecation was introduced"
},
"removalDate": {
"type": "string",
"format": "date",
"description": "Planned removal date"
},
"replacement": {
"type": "string",
"description": "Replacement endpoint/schema if available"
},
"reason": {
"type": "string",
"description": "Reason for deprecation"
}
}
},
"ChangelogEntry": {
"type": "object",
"required": ["documentType", "version", "releaseDate", "changes"],
"properties": {
"documentType": {
"type": "string",
"const": "CHANGELOG_ENTRY"
},
"version": {
"type": "string",
"description": "API version for this changelog entry"
},
"releaseDate": {
"type": "string",
"format": "date",
"description": "Release date"
},
"specDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "Digest of the spec at this version"
},
"changes": {
"type": "object",
"properties": {
"added": {
"type": "array",
"items": {
"type": "string"
},
"description": "New features/endpoints added"
},
"changed": {
"type": "array",
"items": {
"type": "string"
},
"description": "Changes to existing features"
},
"deprecated": {
"type": "array",
"items": {
"type": "string"
},
"description": "Newly deprecated features"
},
"removed": {
"type": "array",
"items": {
"type": "string"
},
"description": "Removed features"
},
"fixed": {
"type": "array",
"items": {
"type": "string"
},
"description": "Bug fixes"
},
"security": {
"type": "array",
"items": {
"type": "string"
},
"description": "Security-related changes"
}
}
},
"contributors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Contributors to this release"
}
}
},
"DiscoveryManifest": {
"type": "object",
"required": ["documentType", "spec", "version", "generatedAt"],
"description": "OpenAPI discovery endpoint response (/.well-known/openapi)",
"properties": {
"documentType": {
"type": "string",
"const": "DISCOVERY_MANIFEST"
},
"spec": {
"type": "string",
"description": "Path to the aggregate OpenAPI spec",
"examples": ["/stella.yaml"]
},
"version": {
"type": "string",
"description": "API version identifier",
"examples": ["v1", "v2"]
},
"generatedAt": {
"type": "string",
"format": "date-time",
"description": "When the spec was generated"
},
"specDigest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "Digest of the spec file"
},
"extensions": {
"type": "object",
"properties": {
"x-stellaops-profile": {
"type": "string",
"enum": ["aggregate", "per-service", "minimal"],
"description": "Spec profile type"
},
"x-stellaops-schemaVersion": {
"type": "string",
"description": "Schema version for extensions"
},
"x-stellaops-services": {
"type": "array",
"items": {
"type": "string"
},
"description": "Services included in aggregate"
}
}
},
"alternates": {
"type": "array",
"items": {
"$ref": "#/$defs/AlternateSpec"
},
"description": "Alternative spec formats/versions"
}
}
},
"AlternateSpec": {
"type": "object",
"required": ["format", "path"],
"properties": {
"format": {
"type": "string",
"enum": ["yaml", "json", "html"],
"description": "Spec format"
},
"path": {
"type": "string",
"description": "Path to alternate spec"
},
"version": {
"type": "string",
"description": "OpenAPI version if different"
}
}
}
},
"examples": [
{
"documentType": "API_BASELINE",
"schemaVersion": 1,
"generatedAt": "2025-11-21T10:00:00Z",
"specVersion": "3.1.0",
"aggregateDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
"services": [
{
"serviceId": "authority",
"displayName": "Authority Service",
"specPath": "authority/openapi.yaml",
"specDigest": "sha256:8d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aef",
"version": "v1",
"operationCount": 15,
"schemaCount": 25,
"exampleCoverage": 95.5,
"securitySchemes": ["bearerAuth", "OAuth2"]
}
],
"sharedComponents": {
"path": "_shared/",
"schemas": ["ErrorResponse", "PaginatedResponse", "HealthStatus"],
"securitySchemes": ["bearerAuth", "mTLS"]
},
"governanceProfile": {
"spectralRuleset": ".spectral.yaml",
"requiredExampleCoverage": 90,
"breakingChangePolicy": "BLOCK",
"rules": [
{
"ruleId": "stella-2xx-response-examples",
"severity": "error",
"description": "Every 2xx response must include at least one example"
}
]
}
},
{
"documentType": "DISCOVERY_MANIFEST",
"spec": "/stella.yaml",
"version": "v1",
"generatedAt": "2025-11-21T10:00:00Z",
"specDigest": "sha256:7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee",
"extensions": {
"x-stellaops-profile": "aggregate",
"x-stellaops-schemaVersion": "1.0.0",
"x-stellaops-services": ["authority", "scanner", "excititor", "concelier"]
},
"alternates": [
{ "format": "json", "path": "/stella.json" },
{ "format": "html", "path": "/docs/api" }
]
}
]
}