Prove Your Domain's Email Authentication Is Actually Enforced

id: spf-dkim-dmarc-audit
namespace: company.team
description: |
  Audit a domain's SPF, DKIM, and DMARC records straight from live DNS,
  report missing or weak email-auth configuration, and alert Slack until
  every check passes — with an optional strict DMARC mode.

triggers:
  - id: monthly_audit
    type: io.kestra.plugin.core.trigger.Schedule
    description: Audit email authentication once a month. Shipped disabled; enable
      it after your first successful manual run.
    cron: "0 5 1 * *"
    disabled: true
  - id: audit_webhook
    type: io.kestra.plugin.core.trigger.Webhook
    description: Call this after changing email-auth DNS records to confirm they
      landed correctly everywhere.
    key: email-auth-audit

inputs:
  - id: domain
    type: STRING
    defaults: example.com
    description: The domain whose email-auth records are audited (the organizational
      domain your mail is sent from).
  - id: dkim_selectors
    type: STRING
    defaults: google,selector1,default
    description: Comma-separated DKIM selectors to probe as
      <selector>._domainkey.<domain>. List the selectors your mail senders
      actually use.
  - id: require_strict_dmarc
    type: BOOLEAN
    defaults: false
    description: When true, a DMARC policy of p=none counts as a failure — use it
      once you have moved past monitoring-only.

tasks:
  - id: audit_records
    type: io.kestra.plugin.scripts.shell.Commands
    description: Install dig in a throwaway Alpine container, then read SPF on the
      apex, DMARC at _dmarc, and a TXT record for every listed DKIM selector.
      Quoted and chunked TXT records are concatenated before matching, policies
      are extracted from the DMARC record, and the verdict — spf_found,
      dmarc_found, dmarc_policy, dkim_found/checked, overall_ok — is published
      through Kestra's stdout outputs protocol. Missing records are findings
      with exit 0, not crashes — an unaudited domain and a broken check are
      different problems.
    containerImage: alpine:3.20
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    commands:
      - |
        set -eu
        apk add --no-cache bind-tools >/dev/null 2>&1
        DOMAIN="{{ inputs.domain }}"
        SELECTORS="{{ inputs.dkim_selectors }}"
        STRICT={{ inputs.require_strict_dmarc }}

        txt_records() {
          dig +short +time=3 +tries=3 TXT "$1" 2>/dev/null | sed 's/" "//g' | tr -d '"'
        }

        SPF_RAW=$(txt_records "$DOMAIN" | grep -m1 'v=spf1' || true)
        SPF_FOUND=false
        if [ -n "$SPF_RAW" ]; then
          SPF_FOUND=true
        fi
        echo "SPF on $DOMAIN: ${SPF_RAW:-MISSING}"

        DMARC_RAW=$(txt_records "_dmarc.$DOMAIN" | grep -m1 'v=DMARC1' || true)
        DMARC_FOUND=false
        DMARC_POLICY="missing"
        if [ -n "$DMARC_RAW" ]; then
          DMARC_FOUND=true
          P=$(printf '%s' "$DMARC_RAW" | grep -o 'p=[a-z]*' | head -n 1 | cut -d= -f 2 || true)
          DMARC_POLICY=${P:-unspecified}
        fi
        echo "DMARC on $DOMAIN: ${DMARC_RAW:-MISSING} (policy: $DMARC_POLICY)"

        DKIM_FOUND=0
        DKIM_CHECKED=0
        OLDIFS=$IFS
        IFS=','
        for s in $SELECTORS; do
          s=$(printf '%s' "$s" | tr -d ' ')
          if [ -z "$s" ]; then
            continue
          fi
          DKIM_CHECKED=$(( DKIM_CHECKED + 1 ))
          REC=$(txt_records "${s}._domainkey.$DOMAIN" | grep -m1 -e 'v=DKIM1' -e 'p=' || true)
          if [ -n "$REC" ]; then
            DKIM_FOUND=$(( DKIM_FOUND + 1 ))
            echo "DKIM selector '$s': present"
          else
            echo "DKIM selector '$s': MISSING"
          fi
        done
        IFS=$OLDIFS

        STRICT_OK=true
        if [ "$STRICT" = "true" ]; then
          case "$DMARC_POLICY" in
            reject|quarantine) STRICT_OK=true ;;
            *) STRICT_OK=false ;;
          esac
        fi

        OVERALL=false
        if [ "$SPF_FOUND" = "true" ] && [ "$DMARC_FOUND" = "true" ] && [ "$DKIM_FOUND" -gt 0 ] && [ "$STRICT_OK" = "true" ]; then
          OVERALL=true
        fi

        echo "verdict: overall_ok=$OVERALL (strict=$STRICT)"
        printf '::{"outputs":{"spf_found":%s,"dmarc_found":%s,"dmarc_policy":"%s","dkim_found":%d,"dkim_checked":%d,"overall_ok":%s}}::\n' \
          "$SPF_FOUND" "$DMARC_FOUND" "$DMARC_POLICY" "$DKIM_FOUND" "$DKIM_CHECKED" "$OVERALL"

  - id: check_verdict
    type: io.kestra.plugin.core.flow.If
    description: Branch on the verdict — a fully passing domain gets a quiet logged
      record, anything missing or weak gets an alert that names each individual
      gap.
    condition: "{{ outputs.audit_records.vars.overall_ok == false }}"
    then:
      - id: alert_auth_gaps
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: List which of SPF, DMARC, and DKIM is missing, the DMARC policy in
          force, and how many selectors answered, so the DNS owner can fix the
          exact record instead of reading a generic warning.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "text": "Email auth audit: {{ inputs.domain }} — SPF {{ outputs.audit_records.vars.spf_found }}, DMARC {{ outputs.audit_records.vars.dmarc_found }} (policy: {{ outputs.audit_records.vars.dmarc_policy }}), DKIM {{ outputs.audit_records.vars.dkim_found }}/{{ outputs.audit_records.vars.dkim_checked }} selectors found. Strict mode: {{ inputs.require_strict_dmarc }}. Fix the missing records so spoofed mail cannot pass as yours. Execution {{ execution.id }}."
          }
    else:
      - id: log_pass
        type: io.kestra.plugin.core.log.Log
        description: Record the passing configuration — policy and selector counts — so
          future runs can show exactly when something changed.
        message: "Email auth audit passed for {{ inputs.domain }}: SPF present, DMARC
          policy {{ outputs.audit_records.vars.dmarc_policy }}, {{
          outputs.audit_records.vars.dkim_found }}/{{
          outputs.audit_records.vars.dkim_checked }} DKIM selector(s) found
          (strict={{ inputs.require_strict_dmarc }})."

errors:
  - id: alert_audit_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert when the audit itself could not run — resolver blocked, no
      dig, container pull failure — because a crashed audit must never be read
      as a passing domain.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "Email auth audit FAILED in flow {{ flow.id }} (execution {{ execution.id }}) for {{ inputs.domain }}. No verdict was produced — verify the Worker can reach DNS on UDP/53 and that the alpine image is pullable."
      }

outputs:
  - id: auth_summary
    type: JSON
    description: 'The verdict — e.g. {"spf_found": true, "dmarc_found": true,
      "dmarc_policy": "reject", "dkim_found": 2, "dkim_checked": 3,
      "overall_ok": true} — ready for dashboards or a compliance gate.'
    value: "{{ outputs.audit_records.vars | toJson }}"