git.stella-ops.org/docs/events/scanner.event.scan.completed@1.json

{
  "$id": "https://stella-ops.org/schemas/events/scanner.event.scan.completed@1.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Scanner orchestrator event – scan completed (v1)",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "eventId",
    "kind",
    "version",
    "tenant",
    "occurredAt",
    "source",
    "idempotencyKey",
    "payload"
  ],
  "properties": {
    "eventId": {
      "type": "string",
      "format": "uuid",
      "description": "Globally unique identifier for this occurrence."
    },
    "kind": {
      "const": "scanner.event.scan.completed",
      "description": "Event kind identifier consumed by orchestrator subscribers."
    },
    "version": {
      "const": 1,
      "description": "Schema version for orchestrator envelopes."
    },
    "tenant": {
      "type": "string",
      "description": "Tenant that owns the scan."
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp (UTC) when the scan completed."
    },
    "recordedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp (UTC) when the event was persisted. Optional."
    },
    "source": {
      "type": "string",
      "description": "Producer identifier, e.g. `scanner.webservice`."
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "description": "Deterministic key used to deduplicate events downstream."
    },
    "correlationId": {
      "type": "string",
      "description": "Correlation identifier tying this event to a request or workflow."
    },
    "traceId": {
      "type": "string",
      "description": "W3C trace ID (32 hex chars) for distributed tracing."
    },
    "spanId": {
      "type": "string",
      "description": "Optional span identifier associated with traceId."
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["repo", "digest"],
      "properties": {
        "namespace": {"type": "string"},
        "repo": {"type": "string"},
        "digest": {"type": "string"},
        "component": {"type": "string"},
        "image": {"type": "string"}
      }
    },
    "attributes": {
      "type": "object",
      "description": "String attributes for downstream correlation (policy revision, scan id, etc.).",
      "additionalProperties": {"type": "string"}
    },
    "payload": {
      "type": "object",
      "additionalProperties": true,
      "required": ["reportId", "scanId", "imageDigest", "verdict", "summary", "report"],
      "properties": {
        "reportId": {"type": "string"},
        "scanId": {"type": "string"},
        "imageDigest": {"type": "string"},
        "verdict": {"enum": ["pass", "warn", "fail"]},
        "summary": {
          "type": "object",
          "additionalProperties": false,
          "required": ["total", "blocked", "warned", "ignored", "quieted"],
          "properties": {
            "total": {"type": "integer", "minimum": 0},
            "blocked": {"type": "integer", "minimum": 0},
            "warned": {"type": "integer", "minimum": 0},
            "ignored": {"type": "integer", "minimum": 0},
            "quieted": {"type": "integer", "minimum": 0}
          }
        },
        "delta": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "newCritical": {"type": "integer", "minimum": 0},
            "newHigh": {"type": "integer", "minimum": 0},
            "kev": {
              "type": "array",
              "items": {"type": "string"}
            }
          }
        },
        "policy": {
          "type": "object",
          "description": "Policy revision metadata surfaced alongside the report."
        },
        "findings": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id"],
            "properties": {
              "id": {"type": "string"},
              "severity": {"type": "string"},
              "cve": {"type": "string"},
              "purl": {"type": "string"},
              "reachability": {"type": "string"}
            }
          }
        },
        "links": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "report": {"$ref": "#/definitions/linkTarget"},
            "policy": {"$ref": "#/definitions/linkTarget"},
            "attestation": {"$ref": "#/definitions/linkTarget"}
          }
        },
        "dsse": {
          "type": "object",
          "additionalProperties": false,
          "required": ["payloadType", "payload", "signatures"],
          "properties": {
            "payloadType": {"type": "string"},
            "payload": {"type": "string"},
            "signatures": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["keyId", "algorithm", "signature"],
                "properties": {
                  "keyId": {"type": "string"},
                  "algorithm": {"type": "string"},
                  "signature": {"type": "string"}
                }
              }
            }
          }
        },
        "report": {
          "type": "object",
          "description": "Canonical scanner report document that aligns with the DSSE payload."
        }
      }
    }
  }
  "definitions": {
    "linkTarget": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "ui": {"type": "string", "format": "uri"},
        "api": {"type": "string", "format": "uri"}
      }
    }
  }
}