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

up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-28 20:55:22 +02:00
parent d040c001ac
commit 2548abc56f
231 changed files with 47468 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
docs/schemas/attestation-vuln-scan.schema.json Normal file
View File

@@ -0,0 +1,226 @@
{
"$id": "https://stella.ops/schema/attestation-vuln-scan.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "VulnScanAttestation",
"description": "In-toto style attestation for vulnerability scan results",
"type": "object",
"required": ["_type", "predicateType", "subject", "predicate", "attestationMeta"],
"properties": {
"_type": {
"type": "string",
"const": "https://in-toto.io/Statement/v0.1",
"description": "In-toto statement type URI"
},
"predicateType": {
"type": "string",
"const": "https://stella.ops/predicates/vuln-scan/v1",
"description": "Predicate type URI for Stella Ops vulnerability scans"
},
"subject": {
"type": "array",
"items": {
"$ref": "#/$defs/AttestationSubject"
},
"minItems": 1,
"description": "Artifacts that were scanned"
},
"predicate": {
"$ref": "#/$defs/VulnScanPredicate",
"description": "Vulnerability scan result predicate"
},
"attestationMeta": {
"$ref": "#/$defs/AttestationMeta",
"description": "Attestation metadata including signer info"
}
},
"$defs": {
"AttestationSubject": {
"type": "object",
"required": ["name", "digest"],
"properties": {
"name": {
"type": "string",
"description": "Subject name (e.g. image reference)",
"examples": ["registry.internal/stella/app-service@sha256:7d9c..."]
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Algorithm -> digest map",
"examples": [{"sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"}]
}
}
},
"VulnScanPredicate": {
"type": "object",
"required": ["scanner", "scanStartedAt", "scanCompletedAt", "severityCounts", "findingReport"],
"properties": {
"scanner": {
"$ref": "#/$defs/ScannerInfo",
"description": "Scanner that produced this result"
},
"scannerDb": {
"$ref": "#/$defs/ScannerDbInfo",
"description": "Vulnerability database info"
},
"scanStartedAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when scan started"
},
"scanCompletedAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when scan completed"
},
"severityCounts": {
"type": "object",
"properties": {
"CRITICAL": { "type": "integer", "minimum": 0 },
"HIGH": { "type": "integer", "minimum": 0 },
"MEDIUM": { "type": "integer", "minimum": 0 },
"LOW": { "type": "integer", "minimum": 0 }
},
"description": "Count of findings by severity"
},
"findingReport": {
"$ref": "#/$defs/FindingReport",
"description": "Reference to the full findings report"
}
}
},
"ScannerInfo": {
"type": "object",
"required": ["name", "version"],
"properties": {
"name": {
"type": "string",
"description": "Scanner name",
"examples": ["Trivy", "Snyk", "Grype"]
},
"version": {
"type": "string",
"description": "Scanner version",
"examples": ["0.53.0"]
}
}
},
"ScannerDbInfo": {
"type": "object",
"properties": {
"lastUpdatedAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when vulnerability DB was last updated"
}
}
},
"FindingReport": {
"type": "object",
"required": ["mediaType", "location", "digest"],
"properties": {
"mediaType": {
"type": "string",
"default": "application/json",
"description": "Media type of the report",
"examples": ["application/json", "application/vnd.cyclonedx+json"]
},
"location": {
"type": "string",
"description": "Path or URI to the report file",
"examples": ["reports/trivy/app-service-7d9c-vulns.json"]
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Content digest of the report"
}
}
},
"AttestationMeta": {
"type": "object",
"required": ["statementId", "createdAt", "signer"],
"properties": {
"statementId": {
"type": "string",
"description": "Unique identifier for this attestation statement"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when attestation was created"
},
"signer": {
"$ref": "#/$defs/AttestationSigner",
"description": "Entity that signed this attestation"
}
}
},
"AttestationSigner": {
"type": "object",
"required": ["name", "keyId"],
"properties": {
"name": {
"type": "string",
"description": "Signer name/identity",
"examples": ["ci/trivy-signer"]
},
"keyId": {
"type": "string",
"description": "Key identifier (fingerprint)",
"examples": ["SHA256:ae12c8d1..."]
}
}
}
},
"examples": [
{
"_type": "https://in-toto.io/Statement/v0.1",
"predicateType": "https://stella.ops/predicates/vuln-scan/v1",
"subject": [
{
"name": "registry.internal/stella/app-service@sha256:7d9c...",
"digest": {
"sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"
}
}
],
"predicate": {
"scanner": {
"name": "Trivy",
"version": "0.53.0"
},
"scannerDb": {
"lastUpdatedAt": "2025-11-20T09:32:00Z"
},
"scanStartedAt": "2025-11-21T09:00:00Z",
"scanCompletedAt": "2025-11-21T09:01:05Z",
"severityCounts": {
"CRITICAL": 1,
"HIGH": 7,
"MEDIUM": 13,
"LOW": 4
},
"findingReport": {
"mediaType": "application/json",
"location": "reports/trivy/app-service-7d9c-vulns.json",
"digest": {
"sha256": "db569aa8a1b847a922b7d61d276cc2a0ccf99efad0879500b56854b43265c09a"
}
}
},
"attestationMeta": {
"statementId": "att-vuln-trivy-app-service-7d9c",
"createdAt": "2025-11-21T09:01:05Z",
"signer": {
"name": "ci/trivy-signer",
"keyId": "SHA256:ae12c8d1..."
}
}
}
]
}

312
docs/schemas/audit-bundle-index.schema.json Normal file
View File

@@ -0,0 +1,312 @@
{
"$id": "https://stella.ops/schema/audit-bundle-index.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "AuditBundleIndex",
"description": "Root manifest for an immutable audit bundle containing vulnerability reports, VEX decisions, policy evaluations, and attestations",
"type": "object",
"required": ["apiVersion", "kind", "bundleId", "createdAt", "createdBy", "subject", "artifacts"],
"properties": {
"apiVersion": {
"type": "string",
"const": "stella.ops/v1",
"description": "API version for this bundle format"
},
"kind": {
"type": "string",
"const": "AuditBundleIndex",
"description": "Resource kind identifier"
},
"bundleId": {
"type": "string",
"description": "Unique identifier for this bundle",
"examples": ["bndl-6f6b0c94-9c5b-4bbf-9a77-a5d8a83da4a2"]
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when bundle was created"
},
"createdBy": {
"$ref": "#/$defs/BundleActorRef",
"description": "User who created this bundle"
},
"subject": {
"$ref": "#/$defs/BundleSubjectRef",
"description": "Primary artifact this bundle documents"
},
"timeWindow": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "Start of time window for included artifacts"
},
"to": {
"type": "string",
"format": "date-time",
"description": "End of time window for included artifacts"
}
},
"description": "Optional time window filter for included content"
},
"artifacts": {
"type": "array",
"items": {
"$ref": "#/$defs/BundleArtifact"
},
"description": "List of artifacts included in this bundle"
},
"vexDecisions": {
"type": "array",
"items": {
"$ref": "#/$defs/BundleVexDecisionEntry"
},
"description": "Summary of VEX decisions included in this bundle"
},
"integrity": {
"$ref": "#/$defs/BundleIntegrity",
"description": "Integrity verification data for the entire bundle"
}
},
"$defs": {
"BundleActorRef": {
"type": "object",
"required": ["id", "displayName"],
"properties": {
"id": {
"type": "string",
"description": "User identifier"
},
"displayName": {
"type": "string",
"description": "Human-readable display name"
}
}
},
"BundleSubjectRef": {
"type": "object",
"required": ["type", "name", "digest"],
"properties": {
"type": {
"type": "string",
"enum": ["IMAGE", "REPO", "SBOM", "OTHER"],
"description": "Type of subject artifact"
},
"name": {
"type": "string",
"description": "Human-readable subject name"
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Algorithm -> digest map"
}
}
},
"BundleArtifact": {
"type": "object",
"required": ["id", "type", "source", "path", "mediaType", "digest"],
"properties": {
"id": {
"type": "string",
"description": "Internal identifier for this artifact within the bundle"
},
"type": {
"type": "string",
"enum": ["VULN_REPORT", "SBOM", "VEX", "POLICY_EVAL", "OTHER"],
"description": "Type of artifact"
},
"source": {
"type": "string",
"description": "Tool/service that produced this artifact",
"examples": ["Trivy@0.53.0", "Syft@1.0.0", "StellaOps", "StellaPolicyEngine@2.1.0"]
},
"path": {
"type": "string",
"description": "Relative path within the bundle",
"examples": ["reports/trivy/app-service-7d9c-vulns.json"]
},
"mediaType": {
"type": "string",
"description": "Media type of the artifact",
"examples": ["application/json", "application/vnd.cyclonedx+json"]
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Content digest of the artifact"
},
"attestation": {
"$ref": "#/$defs/BundleArtifactAttestationRef",
"description": "Optional reference to attestation for this artifact"
}
}
},
"BundleArtifactAttestationRef": {
"type": "object",
"required": ["path", "digest"],
"properties": {
"path": {
"type": "string",
"description": "Relative path to attestation within the bundle"
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Content digest of the attestation"
}
}
},
"BundleVexDecisionEntry": {
"type": "object",
"required": ["decisionId", "vulnerabilityId", "status", "path", "digest"],
"properties": {
"decisionId": {
"type": "string",
"format": "uuid",
"description": "VEX decision ID"
},
"vulnerabilityId": {
"type": "string",
"description": "CVE or vulnerability identifier"
},
"status": {
"type": "string",
"enum": ["NOT_AFFECTED", "AFFECTED_MITIGATED", "AFFECTED_UNMITIGATED", "FIXED"],
"description": "VEX status"
},
"path": {
"type": "string",
"description": "Relative path to VEX decision file"
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Content digest of the decision file"
}
}
},
"BundleIntegrity": {
"type": "object",
"required": ["rootHash", "hashAlgorithm"],
"properties": {
"rootHash": {
"type": "string",
"description": "Root hash covering all artifacts in the bundle"
},
"hashAlgorithm": {
"type": "string",
"default": "sha256",
"description": "Hash algorithm used for integrity verification"
}
}
}
},
"examples": [
{
"apiVersion": "stella.ops/v1",
"kind": "AuditBundleIndex",
"bundleId": "bndl-6f6b0c94-9c5b-4bbf-9a77-a5d8a83da4a2",
"createdAt": "2025-11-21T09:05:30Z",
"createdBy": {
"id": "user-123",
"displayName": "Alice Johnson"
},
"subject": {
"type": "IMAGE",
"name": "registry.internal/stella/app-service@sha256:7d9c...",
"digest": {
"sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"
}
},
"timeWindow": {
"from": "2025-11-14T00:00:00Z",
"to": "2025-11-21T09:05:00Z"
},
"artifacts": [
{
"id": "vuln-report-trivy",
"type": "VULN_REPORT",
"source": "Trivy@0.53.0",
"path": "reports/trivy/app-service-7d9c-vulns.json",
"mediaType": "application/json",
"digest": {
"sha256": "db569aa8a1b847a922b7d61d276cc2a0ccf99efad0879500b56854b43265c09a"
},
"attestation": {
"path": "attestations/vuln-scan-trivy.dsse.json",
"digest": {
"sha256": "2e613df97fe2aa9baf7a8dac9cfaa407e60c808a8af8e7d5e50c029f6c51a54b"
}
}
},
{
"id": "sbom-cyclonedx",
"type": "SBOM",
"source": "Syft@1.0.0",
"path": "sbom/app-service-7d9c-cyclonedx.json",
"mediaType": "application/vnd.cyclonedx+json",
"digest": {
"sha256": "9477b3a9410423b37c39076678a936d5854aa2d905e72a2222c153e3e51ab150"
},
"attestation": {
"path": "attestations/sbom-syft.dsse.json",
"digest": {
"sha256": "3ebf5dc03f862b4b2fdef201130f5c6a9bde7cb0bcf4f57e7686adbc83c9c897"
}
}
},
{
"id": "vex-decisions",
"type": "VEX",
"source": "StellaOps",
"path": "vex/app-service-7d9c-vex.json",
"mediaType": "application/json",
"digest": {
"sha256": "b56f0d05af5dc4ba79ccc1d228dba27a0d9607eef17fa7faf569e3020c39da83"
}
},
{
"id": "policy-eval-prod-admission",
"type": "POLICY_EVAL",
"source": "StellaPolicyEngine@2.1.0",
"path": "policy-evals/prod-admission.json",
"mediaType": "application/json",
"digest": {
"sha256": "cf8617dd3a63b953f31501045bb559c7095fa2b6965643b64a4b463756cfa9c3"
},
"attestation": {
"path": "attestations/policy-prod-admission.dsse.json",
"digest": {
"sha256": "a7ea883ffa1100a62f0f89f455b659017864c65a4fad0af0ac3d8b989e1a6ff3"
}
}
}
],
"vexDecisions": [
{
"decisionId": "8a3d0b5a-1e07-4b57-b6a1-1a29ce6c889e",
"vulnerabilityId": "CVE-2023-12345",
"status": "NOT_AFFECTED",
"path": "vex/CVE-2023-12345-app-service.json",
"digest": {
"sha256": "b56f0d05af5dc4ba79ccc1d228dba27a0d9607eef17fa7faf569e3020c39da83"
}
}
],
"integrity": {
"rootHash": "f4ede91c4396f9dfdacaf15fe0293c6349f467701f4ef7af6a2ecd4f5bf42254",
"hashAlgorithm": "sha256"
}
}
]
}

257
docs/schemas/vex-decision.schema.json Normal file
View File

@@ -0,0 +1,257 @@
{
"$id": "https://stella.ops/schema/vex-decision.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "VexDecision",
"description": "VEX-style statement attached to a finding + subject, representing a vulnerability exploitability decision",
"type": "object",
"required": [
"id",
"vulnerabilityId",
"subject",
"status",
"justificationType",
"createdBy",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Internal stable ID for this decision"
},
"vulnerabilityId": {
"type": "string",
"description": "CVE, GHSA, or other vulnerability identifier",
"examples": ["CVE-2023-12345", "GHSA-xxxx-yyyy-zzzz"]
},
"subject": {
"$ref": "#/$defs/SubjectRef",
"description": "The artifact or SBOM component this decision applies to"
},
"status": {
"type": "string",
"enum": [
"NOT_AFFECTED",
"AFFECTED_MITIGATED",
"AFFECTED_UNMITIGATED",
"FIXED"
],
"description": "VEX status following OpenVEX semantics"
},
"justificationType": {
"type": "string",
"enum": [
"CODE_NOT_PRESENT",
"CODE_NOT_REACHABLE",
"VULNERABLE_CODE_NOT_IN_EXECUTE_PATH",
"CONFIGURATION_NOT_AFFECTED",
"OS_NOT_AFFECTED",
"RUNTIME_MITIGATION_PRESENT",
"COMPENSATING_CONTROLS",
"ACCEPTED_BUSINESS_RISK",
"OTHER"
],
"description": "Justification type inspired by CSAF/VEX specifications"
},
"justificationText": {
"type": "string",
"maxLength": 4000,
"description": "Free-form explanation supporting the justification type"
},
"evidenceRefs": {
"type": "array",
"items": {
"$ref": "#/$defs/EvidenceRef"
},
"description": "Links to PRs, commits, tickets, docs supporting this decision"
},
"scope": {
"$ref": "#/$defs/VexScope",
"description": "Environments and projects where this decision applies"
},
"validFor": {
"$ref": "#/$defs/ValidFor",
"description": "Time window during which this decision is valid"
},
"attestationRef": {
"$ref": "#/$defs/AttestationRef",
"description": "Reference to the signed attestation for this decision"
},
"supersedesDecisionId": {
"type": "string",
"format": "uuid",
"description": "ID of a previous decision this one supersedes"
},
"createdBy": {
"$ref": "#/$defs/ActorRef",
"description": "User who created this decision"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when decision was created"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp when decision was last updated"
}
},
"$defs": {
"SubjectRef": {
"type": "object",
"required": ["type", "name", "digest"],
"properties": {
"type": {
"type": "string",
"enum": ["IMAGE", "REPO", "SBOM_COMPONENT", "OTHER"],
"description": "Type of artifact this subject represents"
},
"name": {
"type": "string",
"description": "Human-readable subject name (e.g. image ref, package name)",
"examples": ["registry.internal/stella/app-service@sha256:7d9c..."]
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Algorithm -> digest map (e.g. sha256 -> hex string)",
"examples": [{"sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"}]
},
"sbomNodeId": {
"type": "string",
"description": "Optional SBOM node/bomRef identifier for SBOM_COMPONENT subjects"
}
}
},
"EvidenceRef": {
"type": "object",
"required": ["type", "url"],
"properties": {
"type": {
"type": "string",
"enum": ["PR", "TICKET", "DOC", "COMMIT", "OTHER"],
"description": "Type of evidence link"
},
"title": {
"type": "string",
"description": "Human-readable title for the evidence"
},
"url": {
"type": "string",
"format": "uri",
"description": "URL to the evidence resource"
}
}
},
"VexScope": {
"type": "object",
"properties": {
"environments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Environment names where decision applies (e.g. prod, staging)",
"examples": [["prod", "staging"]]
},
"projects": {
"type": "array",
"items": {
"type": "string"
},
"description": "Project/service names where decision applies"
}
},
"description": "If empty/null, decision applies to all environments and projects"
},
"ValidFor": {
"type": "object",
"properties": {
"notBefore": {
"type": "string",
"format": "date-time",
"description": "Decision is not valid before this timestamp (defaults to creation time)"
},
"notAfter": {
"type": "string",
"format": "date-time",
"description": "Decision expires after this timestamp (recommended to set)"
}
}
},
"AttestationRef": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Internal attestation identifier"
},
"digest": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Content digest of the attestation"
},
"storage": {
"type": "string",
"description": "Storage location (OCI ref, bundle path, or URL)",
"examples": ["oci://registry.internal/stella/attestations@sha256:2e61..."]
}
}
},
"ActorRef": {
"type": "object",
"required": ["id", "displayName"],
"properties": {
"id": {
"type": "string",
"description": "User identifier"
},
"displayName": {
"type": "string",
"description": "Human-readable display name"
}
}
}
},
"examples": [
{
"id": "8a3d0b5a-1e07-4b57-b6a1-1a29ce6c889e",
"vulnerabilityId": "CVE-2023-12345",
"subject": {
"type": "IMAGE",
"name": "registry.internal/stella/app-service@sha256:7d9c...",
"digest": {
"sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"
}
},
"status": "NOT_AFFECTED",
"justificationType": "VULNERABLE_CODE_NOT_IN_EXECUTE_PATH",
"justificationText": "Vulnerable CLI helper is present in the image but never invoked in the running service.",
"evidenceRefs": [
{
"type": "PR",
"title": "Document non-usage of CLI helper",
"url": "https://git.example.com/stella/app-service/merge_requests/42"
}
],
"scope": {
"environments": ["prod", "staging"],
"projects": ["app-service"]
},
"validFor": {
"notBefore": "2025-11-21T10:15:00Z",
"notAfter": "2026-05-21T10:15:00Z"
},
"createdBy": {
"id": "user-123",
"displayName": "Alice Johnson"
},
"createdAt": "2025-11-21T10:15:00Z"
}
]
}