SNMP Notification Channel Reachability Gate for Kestra

id: snmp-notification-channel-reachability-gate
namespace: company.team
description: |
  Send a synthetic SNMP INFORM heartbeat to a network management system
  (NMS) or trap receiver on a schedule, classify the result as
  CHANNEL_REACHABLE, CHANNEL_UNREACHABLE, or PROBE_FAILED based on whether
  the manager actually acknowledged it, log clean heartbeats, and alert
  Slack the moment the notification channel itself goes dark.

inputs:
  - id: snmp_manager_host
    type: STRING
    defaults: "localhost"
    displayName: "SNMP Manager Host"
    description: "Hostname or IP of the SNMP manager or trap receiver (NMS) to heartbeat."

  - id: snmp_manager_port
    type: INT
    defaults: 162
    displayName: "SNMP Manager Port"
    description: "UDP port the SNMP manager listens for traps and informs on."

  - id: snmp_version
    type: SELECT
    values:
      - "v2c"
      - "v3"
    defaults: "v2c"
    displayName: "SNMP Version"
    description: "plugin-snmp's SendInform task only supports v2c or v3; v1 has no
      INFORM PDU type in the SNMP specification and cannot be used here."

  - id: snmp_community
    type: STRING
    defaults: "public"
    displayName: "Community String (v2c)"
    description: "Plaintext community string used for v2c authentication. Ignored
      when snmp_version is v3."

  - id: heartbeat_trap_oid
    type: STRING
    defaults: "1.3.6.1.4.1.8072.2.3.0.1"
    displayName: "Heartbeat Notification OID"
    description: "OID identifying this synthetic heartbeat notification. The default
      is Net-SNMP's well-known demo notification OID; replace it with an
      enterprise-registered OID for production use."

  - id: inform_timeout_ms
    type: INT
    defaults: 2000
    displayName: "Acknowledgement Timeout (ms)"
    description: "Milliseconds to wait for the manager's INFORM acknowledgement
      before treating the attempt as unanswered."

  - id: inform_retries
    type: INT
    defaults: 1
    displayName: "Retry Attempts"
    description: "Number of resend attempts if no acknowledgement is received,
      before the task reports the INFORM as unacknowledged."

  - id: send_slack_alert
    type: STRING
    defaults: "true"
    displayName: "Send Slack Alert"
    description: "When set to true, dispatch a Slack notification when the channel
      is unreachable; when false, only log the breach."

triggers:
  - id: snmp_channel_heartbeat_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: "Heartbeat the SNMP notification channel every 15 minutes."
    cron: "*/15 * * * *"
    disabled: true
    inputs:
      snmp_manager_host: "localhost"
      snmp_manager_port: 162
      snmp_version: "v2c"
      snmp_community: "public"
      heartbeat_trap_oid: "1.3.6.1.4.1.8072.2.3.0.1"
      inform_timeout_ms: 2000
      inform_retries: 1
      send_slack_alert: "true"

tasks:
  - id: heartbeat_notification_channel
    type: io.kestra.plugin.snmp.SendInform
    description: "Send an SNMP INFORM carrying the current execution ID as a varbind
      and wait for the manager's acknowledgement, unlike a TRAP, an INFORM is
      the only SNMP PDU type that confirms delivery."
    host: "{{ inputs.snmp_manager_host }}"
    port: "{{ inputs.snmp_manager_port }}"
    snmpVersion: "{{ inputs.snmp_version }}"
    community: "{{ inputs.snmp_community }}"
    trapOid: "{{ inputs.heartbeat_trap_oid }}"
    bindings:
      - oid: "1.3.6.1.2.1.1.3.0"
        value: "{{ execution.id }}"
    timeoutMs: "{{ inputs.inform_timeout_ms }}"
    retries: "{{ inputs.inform_retries }}"
    allowFailure: true

  - id: classify_channel_status
    type: io.kestra.plugin.core.debug.Return
    description: "Classify as PROBE_FAILED when the task produced no output at all
      (malformed OID, bad v3 security settings, or transport failure before a
      response was even awaited), CHANNEL_UNREACHABLE when it ran but the
      manager never acknowledged, otherwise CHANNEL_REACHABLE."
    format: "{{ (outputs.heartbeat_notification_channel.acknowledged is not defined)
      ? 'PROBE_FAILED' : (outputs.heartbeat_notification_channel.acknowledged ?
      'CHANNEL_REACHABLE' : 'CHANNEL_UNREACHABLE') }}"

  - id: route_by_channel_status
    type: io.kestra.plugin.core.flow.Switch
    description: "Branch on the classification: page Slack when the channel is
      unreachable or the probe fails, otherwise log a healthy heartbeat line."
    value: "{{ outputs.classify_channel_status.value }}"
    cases:
      "CHANNEL_UNREACHABLE":
        - id: evaluate_alert_toggle
          type: io.kestra.plugin.core.flow.If
          description: "Only call the Slack webhook when send_slack_alert is true;
            otherwise log the breach without paging."
          condition: "{{ inputs.send_slack_alert == 'true' }}"
          then:
            - id: dispatch_channel_down_alert
              type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
              description: "Page the NOC/platform channel that the SNMP notification path is
                not acknowledging heartbeats."
              url: "{{ secret('SLACK_WEBHOOK') }}"
              payload: |
                {
                  "text": "SNMP notification channel unreachable: manager {{ inputs.snmp_manager_host }}:{{ inputs.snmp_manager_port }} did not acknowledge the heartbeat INFORM. Error: {{ outputs.heartbeat_notification_channel.error }}. Any real trap or inform sent to this manager during this window may also go unnoticed. Execution {{ execution.id }}."
                }
          else:
            - id: log_alert_suppressed
              type: io.kestra.plugin.core.log.Log
              description: "Record the breach even when Slack paging is disabled, so the
                execution history still shows it."
              message: "SNMP manager {{ inputs.snmp_manager_host }}:{{
                inputs.snmp_manager_port }} did not acknowledge the heartbeat
                (error: {{ outputs.heartbeat_notification_channel.error }}) but
                Slack alert suppressed by send_slack_alert=false."
      "CHANNEL_REACHABLE":
        - id: log_channel_healthy
          type: io.kestra.plugin.core.log.Log
          description: "Record a healthy heartbeat when the manager acknowledges the
            INFORM."
          message: "SNMP notification channel to {{ inputs.snmp_manager_host }}:{{
            inputs.snmp_manager_port }} is reachable; heartbeat acknowledged."
      "PROBE_FAILED":
        - id: alert_probe_failure
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: "Page the channel when the heartbeat task itself could not run,
            since channel reachability is now unknown."
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "SNMP notification channel sentinel could not run its heartbeat against {{ inputs.snmp_manager_host }}:{{ inputs.snmp_manager_port }}. Check snmp_version, community/v3 security settings, and heartbeat_trap_oid formatting. Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        description: "Fallback branch; reached only if classify_channel_status produces
          a value outside the three known cases."
        message: "SNMP notification channel sentinel produced an unclassified status for
          {{ inputs.snmp_manager_host }}:{{ inputs.snmp_manager_port }}: {{
          outputs.classify_channel_status.value }}."

  - id: log_audit_summary
    type: io.kestra.plugin.core.log.Log
    description: "Final post-heartbeat status line recorded on every run regardless
      of branch."
    message: "SNMP channel heartbeat completed for {{ inputs.snmp_manager_host }}:{{
      inputs.snmp_manager_port }}. Status: {{
      outputs.classify_channel_status.value }}. Execution ID: {{ execution.id
      }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: "Flow-level error handler: page the channel when the sentinel flow
      itself fails outright."
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "CRITICAL: SNMP notification channel reachability gate failed during heartbeat of {{ inputs.snmp_manager_host }}:{{ inputs.snmp_manager_port }}. Execution ID: {{ execution.id }}."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.classify_channel_status.value }}"

An SNMP trap pipeline that silently breaks, a firewall rule change, a community string rotation, a manager restart that drops its listener, looks identical to a quiet network until a real incident needs that channel and nothing arrives. This blueprint uses plugin-snmp's SendInform task as the probe because, unlike a TRAP, an INFORM is the only SNMP PDU type that requires and returns a delivery acknowledgement, so a synthetic heartbeat INFORM gives a direct, verifiable signal that the notification path end to end is actually open.

How it works

heartbeat_notification_channel (io.kestra.plugin.snmp.SendInform) sends an INFORM carrying the current execution ID as a varbind to snmp_manager_host:snmp_manager_port and waits up to inform_timeout_ms, retrying inform_retries times, for the manager's acknowledgement. allowFailure: true lets the flow continue instead of aborting on a malformed configuration or transport error.
classify_channel_status (io.kestra.plugin.core.debug.Return) checks whether outputs.heartbeat_notification_channel.acknowledged is defined at all. If it is missing, the classification is PROBE_FAILED. If it is defined and false, the classification is CHANNEL_UNREACHABLE. If it is true, the classification is CHANNEL_REACHABLE.
route_by_channel_status (io.kestra.plugin.core.flow.Switch) branches on that string. CHANNEL_UNREACHABLE runs evaluate_alert_toggle (io.kestra.plugin.core.flow.If), which pages Slack via dispatch_channel_down_alert only when send_slack_alert is true, logging a suppressed-alert line otherwise. CHANNEL_REACHABLE logs a clean heartbeat line. PROBE_FAILED pages Slack directly since reachability is now unknown. The defaults branch logs a fallback line that is unreachable under normal operation.
log_audit_summary records a status line on every run regardless of branch, so execution history reads as a continuous channel-uptime trend.
The flow-level errors block pages Slack separately if the sentinel flow itself fails outright.
The snmp_channel_heartbeat_schedule trigger polls every 15 minutes with explicit input overrides, shipped disabled: true until pointed at a real SNMP manager.

What you get

A scheduled, acknowledgement-based proof that an SNMP notification path to a given manager is actually open, not just that the network route exists.
A three-way status output (CHANNEL_REACHABLE / CHANNEL_UNREACHABLE / PROBE_FAILED) other flows can gate on before relying on that channel for a real incident.
A Slack page naming the manager, port, and the SNMP error text returned (or the absence of any response) on breach or probe failure.
A separate failure channel for the sentinel flow itself, plus a standing per-run audit log line.

Who it's for

Network operations and infrastructure teams who depend on SNMP trap/inform delivery to an NMS for device and application alerting.
Platform and SRE teams who have been burned by a monitoring channel that looked configured correctly but had stopped delivering silently.
Teams standardizing Day 2 notification-pipeline governance across legacy and modern monitoring stacks inside Kestra.

Why orchestrate this with Kestra

A one-off snmptrap CLI test proves a channel is open for one instant and leaves no record. This flow keeps every heartbeat in Kestra's execution history, turns the result into a typed status output other flows (deployment gates, incident-response flows) can depend on before trusting that channel, and gives you an If/Switch branch to grow into real remediation (paging a secondary channel, opening a ticket) without rewriting the probe itself.

Prerequisites

An SNMP manager or trap receiver reachable from the Kestra Worker over UDP, configured to accept v2c or v3 INFORM PDUs (plugin-snmp's SendInform does not support v1, since v1 has no INFORM PDU type).
The manager's community string (v2c) or SNMPv3 security credentials (v3) if authentication is required.
A Slack incoming webhook for the breach, probe-failure, and flow-failure alerts.

Quick start

Add the SLACK_WEBHOOK secret.
Point snmp_manager_host and snmp_manager_port at a real SNMP manager or trap receiver, and set snmp_community or configure v3 security to match.
Run the flow once and confirm status reads CHANNEL_REACHABLE.
Enable snmp_channel_heartbeat_schedule.

How to extend

Switch snmp_version to v3 and add a v3 connection block (username, authProtocol, authPassword, privProtocol, privPassword) directly on heartbeat_notification_channel for authenticated and encrypted heartbeats; prefer SHA256 or higher and AES128 or higher, since MD5, SHA (SHA-1), and DES are marked deprecated and cryptographically weak in the plugin's own source.
Fan the heartbeat out to every configured NMS endpoint with a Loop task to monitor a whole monitoring fleet from one flow.
Push status into a KV store to alert only on state transitions instead of every run.
Chain io.kestra.plugin.snmp.SendTrap from this flow's errors block to notify the same NMS through a second, independent path when the heartbeat flow itself fails.

Secrets

SLACK_WEBHOOK: Slack incoming webhook used for the breach, probe-failure, and flow-failure alerts.
OSS note: if your Kestra instance reads secrets from environment variables instead of a secrets backend, set SECRET_SLACK_WEBHOOK as base64, for example echo -n "<your-webhook-url>" | base64.

Inputs

snmp_manager_host (STRING, default localhost): SNMP manager or trap receiver hostname/IP.
snmp_manager_port (INT, default 162): manager's UDP listening port.
snmp_version (SELECT, one of v2c, v3, default v2c): INFORM protocol version.
snmp_community (STRING, default public): v2c community string.
heartbeat_trap_oid (STRING, default 1.3.6.1.4.1.8072.2.3.0.1): OID identifying the heartbeat notification.
inform_timeout_ms (INT, default 2000): milliseconds to wait for acknowledgement.
inform_retries (INT, default 1): resend attempts before giving up.
send_slack_alert (STRING, default "true"): when "true", page Slack on breach; when "false", only log it.

Outputs

{{ outputs.heartbeat_notification_channel.acknowledged }}: boolean, true when the manager returned an error-free INFORM response.
{{ outputs.heartbeat_notification_channel.error }}: SNMP error status text when unacknowledged, otherwise null.
{{ outputs.heartbeat_notification_channel.responseText }}: raw response payload from the manager, when available.
{{ outputs.classify_channel_status.value }}: classification string, one of CHANNEL_REACHABLE, CHANNEL_UNREACHABLE, PROBE_FAILED.
{{ outputs.status }}: flow-level alias of the same classification.

Pitfalls

SendInform's own inline example in the plugin's source uses version: as the property key, but the field actually declared on AbstractSnmpTask (and used correctly in SendTrap's own example in the same plugin) is snmpVersion. This blueprint uses snmpVersion, not version.
SNMP v1 has no INFORM PDU type; setting snmp_version to anything other than v2c or v3 makes the underlying task throw before it can even attempt the heartbeat, which this flow reports as PROBE_FAILED.
acknowledged: false and a missing/failed task both indicate the channel cannot be trusted right now, but they are different failures: the former means the manager answered with an error, the latter means the attempt could not even complete. This blueprint deliberately classifies them as CHANNEL_UNREACHABLE and PROBE_FAILED respectively so you do not conflate a configuration bug with a real network outage.
UDP has no inherent delivery guarantee; a short inform_timeout_ms on a congested or high-latency network path can produce false CHANNEL_UNREACHABLE results. Validate the timeout against your real network path before trusting the alert.
v1/v2c community strings are plaintext on the wire; prefer v3 with authentication and privacy for any manager reachable outside a trusted network segment.

Local Container Setup

To start a local open-source SNMP trap/inform receiver for testing, execute:

docker run -d --name kestra-snmp-manager -p 162:162/udp elcolio/net-snmp

This image starts a generic Net-SNMP trap receiver that dumps received notifications to its log; consult the image's own documentation for INFORM-specific acknowledgement behavior before relying on it for production-equivalent testing.

If Kestra is running inside a Docker network, connect the receiver container to Kestra's network:

docker network connect YOUR_KESTRA_NETWORK kestra-snmp-manager

(Run docker network ls to verify your active Kestra network name.)

SNMP Notification Channel Reachability Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Quick start

How to extend

Secrets

Inputs

Outputs

Pitfalls

Local Container Setup

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

SNMP Notification Channel Reachability Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Quick start

How to extend

Secrets

Inputs

Outputs

Pitfalls

Local Container Setup

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

MongoDB Duplicate Document Dedup Guard

MongoDB Read Model vs PostgreSQL Reconcile Guard

MongoDB Document Validation Drift Repair Guard

Back up a MongoDB collection and prove it restores, every night

MongoDB GridFS Orphaned Chunk and Dangling File Reclamation Guard

MongoDB Expired Document Retention Guard

New to Kestra?