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

Refactor code structure for improved readability and maintainability
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-06 21:48:12 +02:00
parent f6c22854a4
commit dd0067ea0b
105 changed files with 12662 additions and 427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

664
docs/schemas/evidence-pointer.schema.json Normal file
View File

@@ -0,0 +1,664 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stella-ops.org/schemas/evidence-pointer.schema.json",
"title": "StellaOps Evidence Pointer Schema",
"description": "Schema for evidence pointers used in timeline events, evidence locker snapshots, and DSSE attestations. Unblocks TASKRUN-OBS-52-001, TASKRUN-OBS-53-001, TASKRUN-OBS-54-001, TASKRUN-OBS-55-001.",
"type": "object",
"definitions": {
"EvidencePointer": {
"type": "object",
"description": "Pointer to evidence artifact in the evidence locker",
"required": ["pointer_id", "artifact_type", "digest", "created_at"],
"properties": {
"pointer_id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for this evidence pointer"
},
"artifact_type": {
"$ref": "#/definitions/ArtifactType"
},
"digest": {
"$ref": "#/definitions/Digest"
},
"uri": {
"type": "string",
"format": "uri",
"description": "URI to retrieve the artifact (may be presigned)"
},
"storage_backend": {
"type": "string",
"enum": ["cas", "evidence", "attestation", "local", "s3", "azure-blob", "gcs"],
"description": "Storage backend where artifact resides"
},
"bucket": {
"type": "string",
"description": "Bucket/container name in object storage"
},
"key": {
"type": "string",
"description": "Object key/path within bucket"
},
"size_bytes": {
"type": "integer",
"minimum": 0,
"description": "Size of artifact in bytes"
},
"media_type": {
"type": "string",
"description": "MIME type of the artifact"
},
"compression": {
"type": "string",
"enum": ["none", "gzip", "zstd", "brotli"],
"default": "none"
},
"encryption": {
"$ref": "#/definitions/EncryptionInfo"
},
"chain_position": {
"$ref": "#/definitions/ChainPosition"
},
"provenance": {
"$ref": "#/definitions/EvidenceProvenance"
},
"redaction": {
"$ref": "#/definitions/RedactionInfo"
},
"retention": {
"$ref": "#/definitions/RetentionPolicy"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true
}
}
},
"ArtifactType": {
"type": "string",
"enum": [
"sbom",
"vex",
"attestation",
"signature",
"callgraph",
"scan_result",
"policy_evaluation",
"timeline_transcript",
"evidence_bundle",
"audit_log",
"manifest",
"provenance",
"rekor_receipt",
"runtime_trace",
"coverage_report",
"diff_report"
],
"description": "Type of evidence artifact"
},
"Digest": {
"type": "object",
"description": "Cryptographic digest of artifact content",
"required": ["algorithm", "value"],
"properties": {
"algorithm": {
"type": "string",
"enum": ["sha256", "sha384", "sha512", "sha3-256", "sha3-384", "sha3-512"],
"default": "sha256"
},
"value": {
"type": "string",
"pattern": "^[a-f0-9]+$",
"description": "Hex-encoded digest value"
}
}
},
"EncryptionInfo": {
"type": "object",
"description": "Encryption information for protected artifacts",
"properties": {
"encrypted": {
"type": "boolean",
"default": false
},
"algorithm": {
"type": "string",
"enum": ["AES-256-GCM", "ChaCha20-Poly1305"],
"description": "Encryption algorithm used"
},
"key_id": {
"type": "string",
"description": "Key identifier for decryption"
},
"key_provider": {
"type": "string",
"enum": ["kms", "vault", "local"],
"description": "Key management provider"
}
}
},
"ChainPosition": {
"type": "object",
"description": "Position in evidence hash chain for tamper detection",
"properties": {
"chain_id": {
"type": "string",
"format": "uuid",
"description": "Evidence chain identifier"
},
"sequence": {
"type": "integer",
"minimum": 0,
"description": "Sequence number in chain"
},
"previous_digest": {
"$ref": "#/definitions/Digest"
},
"merkle_root": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Merkle tree root at this position"
},
"merkle_proof": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"description": "Merkle inclusion proof"
},
"anchored_at": {
"type": "string",
"format": "date-time",
"description": "When chain was anchored to transparency log"
},
"anchor_receipt": {
"type": "string",
"description": "Receipt from transparency log (e.g., Rekor)"
}
}
},
"EvidenceProvenance": {
"type": "object",
"description": "Provenance information for evidence artifact",
"properties": {
"producer": {
"type": "string",
"description": "Service/component that produced the evidence"
},
"producer_version": {
"type": "string"
},
"build_id": {
"type": "string",
"description": "CI/CD build identifier"
},
"source_ref": {
"type": "string",
"description": "Source reference (e.g., git commit)"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"correlation_id": {
"type": "string",
"format": "uuid",
"description": "Trace correlation ID"
},
"parent_pointers": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Parent evidence pointers this derives from"
},
"attestation_id": {
"type": "string",
"format": "uuid",
"description": "Associated attestation if signed"
}
}
},
"RedactionInfo": {
"type": "object",
"description": "Redaction policy for evidence artifact",
"properties": {
"redaction_applied": {
"type": "boolean",
"default": false
},
"redaction_policy": {
"type": "string",
"description": "Policy identifier that was applied"
},
"redacted_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "JSON paths of redacted fields"
},
"original_digest": {
"$ref": "#/definitions/Digest"
},
"redaction_timestamp": {
"type": "string",
"format": "date-time"
}
}
},
"RetentionPolicy": {
"type": "object",
"description": "Retention policy for evidence artifact",
"properties": {
"policy_id": {
"type": "string"
},
"retention_days": {
"type": "integer",
"minimum": 1
},
"legal_hold": {
"type": "boolean",
"default": false
},
"deletion_scheduled_at": {
"type": "string",
"format": "date-time"
},
"immutable_until": {
"type": "string",
"format": "date-time",
"description": "Cannot be modified/deleted until this time"
}
}
},
"EvidenceSnapshot": {
"type": "object",
"description": "Point-in-time snapshot of evidence locker state",
"required": ["snapshot_id", "timestamp", "pointers"],
"properties": {
"snapshot_id": {
"type": "string",
"format": "uuid"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"snapshot_type": {
"type": "string",
"enum": ["full", "incremental", "incident"],
"default": "incremental"
},
"pointers": {
"type": "array",
"items": {
"$ref": "#/definitions/EvidencePointer"
}
},
"aggregate_digest": {
"$ref": "#/definitions/Digest"
},
"previous_snapshot_id": {
"type": "string",
"format": "uuid"
},
"statistics": {
"$ref": "#/definitions/SnapshotStatistics"
},
"manifest_uri": {
"type": "string",
"format": "uri"
},
"attestation": {
"$ref": "#/definitions/SnapshotAttestation"
}
}
},
"SnapshotStatistics": {
"type": "object",
"description": "Statistics about evidence snapshot",
"properties": {
"total_artifacts": {
"type": "integer",
"minimum": 0
},
"total_size_bytes": {
"type": "integer",
"minimum": 0
},
"artifacts_by_type": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"new_since_last": {
"type": "integer"
},
"modified_since_last": {
"type": "integer"
},
"deleted_since_last": {
"type": "integer"
}
}
},
"SnapshotAttestation": {
"type": "object",
"description": "DSSE attestation for snapshot integrity",
"properties": {
"attestation_id": {
"type": "string",
"format": "uuid"
},
"predicate_type": {
"type": "string",
"default": "https://stella-ops.org/attestations/evidence-snapshot/v1"
},
"signature": {
"type": "string",
"description": "Base64-encoded signature"
},
"key_id": {
"type": "string"
},
"signed_at": {
"type": "string",
"format": "date-time"
},
"rekor_log_index": {
"type": "integer",
"description": "Rekor transparency log index"
},
"rekor_log_id": {
"type": "string"
}
}
},
"TimelineEvidenceEntry": {
"type": "object",
"description": "Evidence entry in timeline event stream",
"required": ["entry_id", "event_type", "timestamp", "pointer"],
"properties": {
"entry_id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string",
"enum": [
"evidence.created",
"evidence.updated",
"evidence.accessed",
"evidence.deleted",
"evidence.redacted",
"evidence.exported",
"evidence.verified",
"evidence.anchored",
"snapshot.created",
"snapshot.verified",
"incident.started",
"incident.ended"
]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"pointer": {
"$ref": "#/definitions/EvidencePointer"
},
"actor": {
"$ref": "#/definitions/Actor"
},
"context": {
"type": "object",
"properties": {
"pack_run_id": {
"type": "string",
"format": "uuid"
},
"scan_id": {
"type": "string",
"format": "uuid"
},
"job_id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
}
}
},
"previous_entry_id": {
"type": "string",
"format": "uuid"
}
}
},
"Actor": {
"type": "object",
"description": "Actor who performed the action",
"properties": {
"type": {
"type": "string",
"enum": ["user", "service", "system", "automation"]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"tenant_id": {
"type": "string",
"format": "uuid"
}
}
},
"IncidentModeConfig": {
"type": "object",
"description": "Configuration for incident mode evidence capture",
"required": ["incident_id", "started_at"],
"properties": {
"incident_id": {
"type": "string",
"format": "uuid"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"severity": {
"type": "string",
"enum": ["critical", "high", "medium", "low"]
},
"capture_mode": {
"type": "string",
"enum": ["all", "selective", "enhanced"],
"default": "enhanced",
"description": "Level of evidence capture during incident"
},
"enhanced_retention_days": {
"type": "integer",
"minimum": 1,
"default": 365,
"description": "Extended retention for incident evidence"
},
"legal_hold": {
"type": "boolean",
"default": true
},
"snapshot_interval_minutes": {
"type": "integer",
"minimum": 1,
"default": 15,
"description": "How often to take snapshots during incident"
},
"affected_tenants": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"affected_components": {
"type": "array",
"items": {
"type": "string"
}
},
"root_cause_evidence": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Pointer IDs of root cause evidence"
}
}
},
"EvidenceQuery": {
"type": "object",
"description": "Query parameters for evidence retrieval",
"properties": {
"artifact_types": {
"type": "array",
"items": {
"$ref": "#/definitions/ArtifactType"
}
},
"digest": {
"$ref": "#/definitions/Digest"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"time_range": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
}
}
},
"include_redacted": {
"type": "boolean",
"default": false
},
"include_expired": {
"type": "boolean",
"default": false
},
"chain_id": {
"type": "string",
"format": "uuid"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100
},
"cursor": {
"type": "string"
}
}
},
"EvidenceQueryResult": {
"type": "object",
"description": "Result of evidence query",
"required": ["pointers", "total_count"],
"properties": {
"pointers": {
"type": "array",
"items": {
"$ref": "#/definitions/EvidencePointer"
}
},
"total_count": {
"type": "integer"
},
"next_cursor": {
"type": "string"
},
"query_time_ms": {
"type": "integer"
}
}
}
},
"properties": {
"evidence": {
"type": "array",
"items": {
"$ref": "#/definitions/EvidencePointer"
}
}
},
"examples": [
{
"evidence": [
{
"pointer_id": "550e8400-e29b-41d4-a716-446655440001",
"artifact_type": "sbom",
"digest": {
"algorithm": "sha256",
"value": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
},
"uri": "s3://stellaops-evidence/sbom/2025/12/06/sbom-abc123.json",
"storage_backend": "evidence",
"bucket": "stellaops-evidence",
"key": "sbom/2025/12/06/sbom-abc123.json",
"size_bytes": 45678,
"media_type": "application/vnd.cyclonedx+json",
"compression": "gzip",
"chain_position": {
"chain_id": "660e8400-e29b-41d4-a716-446655440002",
"sequence": 42,
"merkle_root": "b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234567a"
},
"provenance": {
"producer": "stellaops-scanner",
"producer_version": "2025.10.0",
"tenant_id": "770e8400-e29b-41d4-a716-446655440003",
"correlation_id": "880e8400-e29b-41d4-a716-446655440004"
},
"retention": {
"retention_days": 365,
"legal_hold": false
},
"created_at": "2025-12-06T10:00:00Z"
}
]
}
]
}