Skopeo Container Image Digest Drift and Tag Immutability Sentinel

id: skopeo-container-image-digest-drift-and-tag-immutability-sentinel
namespace: company.platform

inputs:
  - id: image_reference
    type: STRING
    displayName: Container Image Reference
    description: Remote container image reference to audit (e.g.,
      docker.io/library/redis:7.2-alpine or ghcr.io/org/app:v1.2.0).
    defaults: "docker.io/library/redis:7.2-alpine"

  - id: expected_digest
    type: STRING
    displayName: Expected Pinned Digest
    description: The approved immutable SHA256 manifest digest. Set to AUTO_DISCOVER
      to accept the initial remote digest, or specify sha256:... to enforce
      immutability.
    defaults: "AUTO_DISCOVER"

  - id: enforce_immutability
    type: BOOL
    displayName: Enforce Immutability Gate
    description: When true, fails the execution on detected digest drift or
      unreachable registry to block downstream deployment pipelines.
    defaults: true

  - id: auto_alert_on_drift
    type: BOOL
    displayName: Auto Alert on Drift
    description: When true, dispatches high-priority diagnostic payload to Slack
      upon detecting digest drift.
    defaults: true

triggers:
  - id: scheduled_immutability_audit
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 */4 * * *"

tasks:
  - id: inspect_remote_image
    type: io.kestra.plugin.skopeo.cli.SkopeoCLI
    description: Queries the remote container registry via Skopeo inspect without
      pulling image layers, capturing the OCI/Docker manifest digest and
      metadata.
    commands:
      - skopeo inspect docker://{{ inputs.image_reference }} >
        inspect_metadata.json || echo
        '{"error":"INSPECT_FAILED","Digest":"UNKNOWN"}' > inspect_metadata.json
    outputFiles:
      - inspect_metadata.json

  - id: parse_image_digest
    type: io.kestra.plugin.core.output.OutputValues
    description: Extracts the resolved remote digest, architecture, and created
      timestamp using jq from the Skopeo inspection file.
    values:
      remote_digest: "{{
        (read(outputs.inspect_remote_image.outputFiles['inspect_metadata.json'])
        | jq('.Digest') | first) ?? 'UNKNOWN' }}"
      architecture: "{{
        (read(outputs.inspect_remote_image.outputFiles['inspect_metadata.json'])
        | jq('.Architecture') | first) ?? 'UNKNOWN' }}"
      os: "{{ (read(outputs.inspect_remote_image.outputFiles['inspect_metadata.json'])
        | jq('.Os') | first) ?? 'UNKNOWN' }}"
      created_at: "{{
        (read(outputs.inspect_remote_image.outputFiles['inspect_metadata.json'])
        | jq('.Created') | first) ?? 'UNKNOWN' }}"

  - id: evaluate_digest_drift
    type: io.kestra.plugin.core.output.OutputValues
    description: Evaluates whether the remote image tag matches the expected pinned
      digest or has suffered silent overwrite/drift.
    values:
      integrity_status: "{{ outputs.parse_image_digest.values.remote_digest ==
        'UNKNOWN' ? 'UNREACHABLE' : (inputs.expected_digest == 'AUTO_DISCOVER'
        or outputs.parse_image_digest.values.remote_digest ==
        inputs.expected_digest ? 'IMMUTABLE' : 'DIGEST_DRIFT') }}"
      drift_detected: "{{ outputs.parse_image_digest.values.remote_digest != 'UNKNOWN'
        and inputs.expected_digest != 'AUTO_DISCOVER' and
        outputs.parse_image_digest.values.remote_digest !=
        inputs.expected_digest }}"

  - id: route_integrity_findings
    type: io.kestra.plugin.core.flow.If
    description: Branches on integrity status to alert DevSecOps or commit an
      operational audit log.
    condition: "{{ outputs.evaluate_digest_drift.values.integrity_status !=
      'IMMUTABLE' }}"
    then:
      - id: alert_digest_drift
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Alerts platform engineers and DevSecOps when remote container image
          digest drift is detected.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "attachments": [
              {
                "color": "#E53935",
                "title": "[ALERT] Container Image Digest Drift Detected",
                "text": "Remote container image tag has drifted from approved immutable baseline.\n*Image Reference:* `{{ inputs.image_reference }}`\n*Status:* `{{ outputs.evaluate_digest_drift.values.integrity_status }}`\n*Expected Digest:* `{{ inputs.expected_digest }}`\n*Observed Remote Digest:* `{{ outputs.parse_image_digest.values.remote_digest }}`\n*Platform Architecture:* `{{ outputs.parse_image_digest.values.architecture }}/{{ outputs.parse_image_digest.values.os }}`\n*Remote Created At:* `{{ outputs.parse_image_digest.values.created_at }}`\nVerify build provenance and registry push history to prevent untracked binaries in production.",
                "footer": "Kestra Sentinel | Skopeo Immutability Gate"
              }
            ]
          }

      - id: gate_enforcement
        type: io.kestra.plugin.core.flow.If
        description: Enforces pipeline failure when enforce_immutability is enabled.
        condition: "{{ inputs.enforce_immutability }}"
        then:
          - id: fail_on_drift
            type: io.kestra.plugin.core.execution.Fail
            description: Blocks workflow execution to prevent deployment of mutated or
              untracked container images.

    else:
      - id: log_immutability_verified
        type: io.kestra.plugin.core.log.Log
        description: Records audit verification log confirming image tag immutability.
        message: "[OK] Container image immutability verified for '{{
          inputs.image_reference }}'. Digest: {{
          outputs.parse_image_digest.values.remote_digest }}, Arch: {{
          outputs.parse_image_digest.values.architecture }}/{{
          outputs.parse_image_digest.values.os }}."