Amazon SNS Subscription Delivery Failure and DLQ Sentinel

id: aws-sns-dead-letter-topic-failure-sentinel
namespace: company.cloud

description: |
  Audits Amazon SNS subscription delivery status and Dead Letter Queue (DLQ)
  redrive metrics via CloudWatch, detects subscriber notification drops, opens
  an automated GitHub SecOps/Cloud incident issue, and alerts Slack.

inputs:
  - id: aws_region
    type: STRING
    displayName: AWS Region
    defaults: us-east-1

  - id: topic_name
    type: STRING
    displayName: SNS Topic Name
    defaults: production-security-alerts

  - id: target_repository
    type: STRING
    displayName: Infrastructure Issue Tracking Repository
    defaults: my-org/cloud-operations

triggers:
  - id: periodic_sns_dlq_check
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "*/15 * * * *"
    disabled: true

tasks:
  - id: probe_sns_delivery_metrics
    type: io.kestra.plugin.aws.cli.AwsCLI
    description: Interrogates CloudWatch for NumberOfNotificationsFailed metrics on
      target SNS topic
    accessKeyId: "{{ secret('AWS_ACCESS_KEY_ID') }}"
    secretKeyId: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
    region: "{{ inputs.aws_region }}"
    commands:
      - aws cloudwatch get-metric-data --metric-data-queries
        '[{"Id":"m1","MetricStat":{"Metric":{"Namespace":"AWS/SNS","MetricName":"NumberOfNotificationsFailed","Dimensions":[{"Name":"TopicName","Value":"{{
        inputs.topic_name }}"}]},"Period":900,"Stat":"Sum"},"ReturnData":true}]'
        --start-time $(date -u -v-15M +%Y-%m-%dT%H:%M:%SZ) --end-time $(date -u
        +%Y-%m-%dT%H:%M:%SZ) --output json | tr -d '\n' | xargs -0 -I {} echo
        '::{"outputs":{}}::'

  - id: evaluate_failed_notifications
    type: io.kestra.plugin.core.debug.Return
    description: Evaluates whether any delivery failures occurred across SNS subscribers
    format:
      topic: "{{ inputs.topic_name }}"
      failed_count: "{{
        outputs.probe_sns_delivery_metrics.vars.MetricDataResults[0].Values[0]
        ?? 0 }}"
      has_failures: "{{
        (outputs.probe_sns_delivery_metrics.vars.MetricDataResults[0].Values[0]
        ?? 0) > 0 }}"

  - id: branch_on_sns_failures
    type: io.kestra.plugin.core.flow.If
    description: Branches based on whether SNS delivery failures were detected
    condition: "{{ outputs.evaluate_failed_notifications.value.has_failures == true }}"
    then:
      - id: create_sns_incident_issue
        type: io.kestra.plugin.github.issues.Create
        description: Logs a prioritized GitHub issue documenting SNS subscriber delivery
          failures
        oauthToken: "{{ secret('GITHUB_TOKEN') }}"
        repository: "{{ inputs.target_repository }}"
        title: "[SNS Alert] Subscriber Notification Delivery Failures Detected on: {{
          inputs.topic_name }}"
        body: |
          ## 🚨 Amazon SNS Subscriber Delivery Failure Alert

          The cloud notification sentinel detected dropped subscriber messages on Amazon SNS:
          - **Topic Name:** `{{ inputs.topic_name }}`
          - **AWS Region:** `{{ inputs.aws_region }}`
          - **Failed Notifications (Last 15m):** **{{ outputs.evaluate_failed_notifications.value.failed_count }}**

          Please inspect subscription endpoint accessibility, IAM permission policies, and DLQ dead letter queues.
          *Generated automatically by Kestra AWS SNS Sentinel.*

      - id: alert_cloud_slack
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Alerts cloud operations Slack channel with failure count and issue
          hyperlink
        url: "{{ secret('SLACK_WEBHOOK') }}"
        payload: |
          {{ {
            "text": "🚨 *Amazon SNS Delivery Failure Alert*\n*Topic:* `" ~ inputs.topic_name ~ "` (" ~ inputs.aws_region ~ ")\n*Failed Notifications:* *" ~ outputs.evaluate_failed_notifications.value.failed_count ~ "*\n*Incident Ticket:* <" ~ (outputs.create_sns_incident_issue.issueUrl ?? "#") ~ "|View GitHub Issue>"
          } | toJson }}

    else:
      - id: log_sns_healthy
        type: io.kestra.plugin.core.log.Log
        message: "Amazon SNS topic {{ inputs.topic_name }} has zero delivery failures in
          the last 15 minutes."

  - id: log_audit_complete
    type: io.kestra.plugin.core.log.Log
    description: Final audit status log recording SNS delivery health
    message: "SNS delivery audit complete for {{ inputs.topic_name }}. Failed
      notifications: {{ outputs.evaluate_failed_notifications.value.failed_count
      }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alerts Slack when CloudWatch API queries fail
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {{ {
        "text": "⚠️ *Amazon SNS Sentinel Failed* in execution `" ~ execution.id ~ "`. Unable to query CloudWatch metrics for `" ~ inputs.topic_name ~ "`."
      } | toJson }}