665 lines
18 KiB
JSON
665 lines
18 KiB
JSON
{
|
|
"$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"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|