NetBird Mesh Peer Connectivity & Security Sentinel

id: netbird-mesh-peer-connectivity-and-security-sentinel
namespace: company.team

description: |
  Audits NetBird zero-trust WireGuard overlay networks for peer connectivity, monitors session login expirations and pending device approvals, classifies mesh health, and dispatches incident alerts to Slack.

triggers:
  - id: every_4_hours
    type: io.kestra.plugin.core.trigger.Schedule
    description: Executes automated NetBird peer connectivity and security posture
      audits every 4 hours.
    cron: "0 */4 * * *"
    disabled: true
    inputs:
      netbird_host: "netbird-management"
      netbird_port: 80
      max_tolerated_disconnected_peers: 0

inputs:
  - id: netbird_host
    type: STRING
    displayName: NetBird Management Hostname
    description: Hostname or IP address of the NetBird Management server reachable
      by the Kestra worker.
    defaults: "netbird-management"

  - id: netbird_port
    type: INT
    displayName: NetBird Management HTTP Port
    description: HTTP port of the NetBird Management API service (defaults to 80 or 443).
    defaults: 80

  - id: max_tolerated_disconnected_peers
    type: INT
    displayName: Max Tolerated Disconnected Peers
    description: Maximum allowable number of disconnected registered peers before
      raising a WARNING notification.
    defaults: 0

tasks:
  - id: probe_netbird_users
    type: io.kestra.plugin.core.http.Request
    description: Queries the NetBird users API to verify management service
      reachability and API token validity.
    uri: "http://{{ inputs.netbird_host }}:{{ inputs.netbird_port }}/api/users"
    method: GET
    headers:
      Authorization: "Token {{ secret('NETBIRD_API_KEY') }}"
      Accept: "application/json"
    options:
      allowFailed: true
    allowFailure: true

  - id: probe_netbird_peers
    type: io.kestra.plugin.core.http.Request
    description: Retrieves registered overlay network peers to inspect connectivity,
      IP assignments, and login expiration statuses.
    uri: "http://{{ inputs.netbird_host }}:{{ inputs.netbird_port }}/api/peers"
    method: GET
    headers:
      Authorization: "Token {{ secret('NETBIRD_API_KEY') }}"
      Accept: "application/json"
    options:
      allowFailed: true
    allowFailure: true

  - id: probe_netbird_routes
    type: io.kestra.plugin.core.http.Request
    description: Inspects configured network routes and peer routing distribution
      across the zero-trust mesh.
    uri: "http://{{ inputs.netbird_host }}:{{ inputs.netbird_port }}/api/routes"
    method: GET
    headers:
      Authorization: "Token {{ secret('NETBIRD_API_KEY') }}"
      Accept: "application/json"
    options:
      allowFailed: true
    allowFailure: true

  - id: classify_network_status
    type: io.kestra.plugin.core.debug.Return
    description: Evaluates peer connectivity, expired credentials, and approval
      flags to categorize network state into HEALTHY, APPROVAL_PENDING,
      PEERS_DISCONNECTED_WARNING, LOGIN_EXPIRED_CRITICAL, PROBE_FAILED, or
      API_UNREACHABLE.
    format: |
      {{ (outputs.probe_netbird_users.code is not defined or outputs.probe_netbird_users.code != 200) ? 'API_UNREACHABLE' : ( (outputs.probe_netbird_peers.code is not defined or outputs.probe_netbird_peers.code != 200) ? 'PROBE_FAILED' : ( ((outputs.probe_netbird_peers.body | json | jq('[.[] | select(.login_expired == true)] | length') | first) > 0) ? 'LOGIN_EXPIRED_CRITICAL' : ( ((outputs.probe_netbird_peers.body | json | jq('[.[] | select(.approval_required == true)] | length') | first) > 0) ? 'APPROVAL_PENDING' : ( ((outputs.probe_netbird_peers.body | json | jq('[.[] | select(.connected == false)] | length') | first) > inputs.max_tolerated_disconnected_peers) ? 'PEERS_DISCONNECTED_WARNING' : 'HEALTHY' ) ) ) ) }}

  - id: route_by_network_status
    type: io.kestra.plugin.core.flow.Switch
    description: Routes workflow notifications based on the classified NetBird mesh status.
    value: "{{ outputs.classify_network_status.value }}"
    cases:
      "HEALTHY":
        - id: log_healthy_state
          type: io.kestra.plugin.core.log.Log
          message: "NetBird mesh on {{ inputs.netbird_host }}:{{ inputs.netbird_port }} is
            HEALTHY. Total registered peers: {{ outputs.probe_netbird_peers.body
            | json | jq('length') | first }}. Active routes: {{
            outputs.probe_netbird_routes.body | json | jq('length') | first ?? 0
            }}. All peers connected with active login sessions."

      "PEERS_DISCONNECTED_WARNING":
        - id: alert_disconnected_peers_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "NetBird Mesh WARNING on " ~ inputs.netbird_host ~ ":" ~ inputs.netbird_port ~ ". Disconnected peers count (" ~ (outputs.probe_netbird_peers.body | json | jq('[.[] | select(.connected == false)] | length') | first) ~ ") exceeds threshold of " ~ inputs.max_tolerated_disconnected_peers ~ ". Offline peers: " ~ (outputs.probe_netbird_peers.body | json | jq('[.[] | select(.connected == false) | .name + \" (\" + .ip + \")\"] | join(\", \")') | first) ~ ". Execution: " ~ execution.id ~ "."} | toJson }}

        - id: log_disconnected_warning
          type: io.kestra.plugin.core.log.Log
          message: "Disconnected peers detected: {{ outputs.probe_netbird_peers.body |
            json | jq('[.[] | select(.connected == false) | .name] | join(\",
            \")') | first }}."

      "APPROVAL_PENDING":
        - id: alert_approval_pending_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "NetBird Mesh NOTICE on " ~ inputs.netbird_host ~ ":" ~ inputs.netbird_port ~ ". Detected peer(s) pending administrative approval: " ~ (outputs.probe_netbird_peers.body | json | jq('[.[] | select(.approval_required == true) | .name + \" (\" + .ip + \")\"] | join(\", \")') | first) ~ ". Execution: " ~ execution.id ~ "."} | toJson }}

      "LOGIN_EXPIRED_CRITICAL":
        - id: alert_expired_logins_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "NetBird Mesh CRITICAL on " ~ inputs.netbird_host ~ ":" ~ inputs.netbird_port ~ ". Confirmed expired login sessions on peer(s): " ~ (outputs.probe_netbird_peers.body | json | jq('[.[] | select(.login_expired == true) | .name + \" (\" + .ip + \")\"] | join(\", \")') | first) ~ ". Overlay network tunnel severed. Immediate re-authentication required. Execution: " ~ execution.id ~ "."} | toJson }}

      "PROBE_FAILED":
        - id: alert_probe_failed_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "NetBird Sentinel PROBE_FAILED on " ~ inputs.netbird_host ~ ":" ~ inputs.netbird_port ~ ". Users API responded but peers endpoint returned HTTP " ~ outputs.probe_netbird_peers.code ~ ". Check NETBIRD_API_KEY permissions. Execution: " ~ execution.id ~ "."} | toJson }}

      "API_UNREACHABLE":
        - id: alert_unreachable_slack
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "NetBird Sentinel API_UNREACHABLE. Cannot reach management service at http://" ~ inputs.netbird_host ~ ":" ~ inputs.netbird_port ~ "/api/users. Service is offline or network partitioned. Execution: " ~ execution.id ~ "."} | toJson }}

  - id: log_audit_summary
    type: io.kestra.plugin.core.output.OutputValues
    description: Exports structured telemetry attributes and mesh connectivity
      counts for compliance records.
    values:
      network_status: "{{ outputs.classify_network_status.value }}"
      total_peers: "{{ outputs.probe_netbird_peers.body | json | jq('length') | first
        ?? 0 }}"
      connected_peers_count: "{{ outputs.probe_netbird_peers.body | json | jq('[.[] |
        select(.connected == true)] | length') | first ?? 0 }}"
      disconnected_peers_count: "{{ outputs.probe_netbird_peers.body | json | jq('[.[]
        | select(.connected == false)] | length') | first ?? 0 }}"
      expired_logins_count: "{{ outputs.probe_netbird_peers.body | json | jq('[.[] |
        select(.login_expired == true)] | length') | first ?? 0 }}"
      pending_approvals_count: "{{ outputs.probe_netbird_peers.body | json | jq('[.[]
        | select(.approval_required == true)] | length') | first ?? 0 }}"
      total_network_routes: "{{ outputs.probe_netbird_routes.body | json |
        jq('length') | first ?? 0 }}"

errors:
  - id: alert_flow_error
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Dispatches a high-priority Slack notification if an unhandled error
      halts sentinel execution.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {{ {"text": "NetBird Sentinel workflow error during execution " ~ execution.id ~ " in namespace " ~ flow.namespace ~ "."} | toJson }}

Continuously audits NetBird zero-trust WireGuard overlay networks by querying the Management REST API, validating peer connectivity states, identifying expired login sessions or unapproved devices, classifying mesh health, and dispatching incident alerts to Slack.

How it works

probe_netbird_users queries /api/users using an API access token to verify NetBird Management service vitality and credential validity.
probe_netbird_peers retrieves the complete inventory of registered peers across the mesh network, extracting internal IPs, online connection statuses, login expiration flags, and approval requirements.
probe_netbird_routes queries /api/routes to verify defined subnet routers and network routing health.
classify_network_status evaluates peer attributes using a Pebble conditional expression:
- Flags peers whose login sessions have expired (login_expired: true) and categorizes state as LOGIN_EXPIRED_CRITICAL.
- Flags newly enrolled devices waiting for administrator review (approval_required: true) as APPROVAL_PENDING.
- Flags disconnected peers (connected: false) exceeding max_tolerated_disconnected_peers as PEERS_DISCONNECTED_WARNING.
- Confirms all enrolled peers are active and authorized to categorize state as HEALTHY.
- Detects unreachable management endpoints or API errors as API_UNREACHABLE or PROBE_FAILED.
route_by_network_status switches workflow execution based on the classification:
- HEALTHY: Logs total peers, active network routes, and confirmed connectivity.
- LOGIN_EXPIRED_CRITICAL: Dispatches an urgent escalation alert to Slack naming machines with severed WireGuard tunnels due to expired credentials.
- PEERS_DISCONNECTED_WARNING: Posts a warning to Slack naming offline hostnames and assigned internal IPs.
- APPROVAL_PENDING: Alerts administrators that new edge peers require connection authorization.
- API_UNREACHABLE: Alerts on-call operations that the NetBird management control plane is down.
log_audit_summary produces structured outputs recording peer counts, connected/disconnected ratios, and security flags for compliance reporting.
errors catches unexpected task exceptions and posts a diagnostic notice to Slack.

What you get

Automated, continuous surveillance of zero-trust WireGuard network overlays without third-party monitoring agents.
Instant alerting when peer login sessions expire, preventing silent tunnel collapse between backend microservices, database clusters, and remote workers.
Automated detection of unapproved devices attempting to join the private mesh network.
Contextual Slack alerts containing exact machine hostnames, internal NetBird IPs, and diagnostic status.
Centralized audit tracking of network mesh health, device capacity, and route distribution.

Who it's for

Network Engineers and Security Administrators operating NetBird zero-trust overlay networks for internal corporate infrastructure.
Platform and Site Reliability Engineers managing WireGuard connectivity across multi-cloud and edge Kubernetes nodes.
DevSecOps teams enforcing compliance, peer approval gates, and device identity policies.

Why orchestrate this with Kestra

NetBird secures mission-critical interconnectivity between distributed microservices, databases, and remote environments. When a peer's authentication session expires or an edge subnet router goes offline, internal communication fails without traditional network monitoring picking it up immediately. Kestra delivers declarative, auditable orchestration with centralized secret management, robust HTTP probing, dynamic multi-state classification, and rapid multi-channel alerting.

Prerequisites

A running NetBird Management server instance with HTTP access from the Kestra worker.
A NetBird Personal Access Token (PAT) generated under User Profile > Access Tokens.
An incoming Slack webhook URL for alert delivery.

Secrets

NETBIRD_API_KEY: Personal Access Token or Service User token used for Token authentication against /api/ endpoints.
SLACK_WEBHOOK: Incoming Slack webhook URL used by alert_disconnected_peers_slack, alert_expired_logins_slack, alert_approval_pending_slack, alert_probe_failed_slack, alert_unreachable_slack, and the errors handler.

Quick start

Generate an API token in the NetBird web console under User Profile > Access Tokens.
Configure NETBIRD_API_KEY and SLACK_WEBHOOK as secrets within your Kestra namespace.

Start a local NetBird test stack using Docker Compose:

git clone https://github.com/netbirdio/netbird && cd netbird/infrastructure_files
docker compose up -d

Execute this flow manually in Kestra setting netbird_host: "localhost" or "netbird-management".
The workflow inspects registered peers, validates active connections, classifies HEALTHY, and records audit outputs.
Enable the every_4_hours trigger to automate continuous background monitoring.

How to extend

Add an automated remediation branch that calls PUT /api/peers/{id} to automatically approve known staging peers matching an authorized hostname pattern.
Integrate with PagerDuty or Opsgenie for LOGIN_EXPIRED_CRITICAL states affecting production database primary nodes.
Route separate alerts to Slack channels partitioned by peer user IDs or group tags (e.g. prod-servers vs developer-laptops).
Query /api/setup-keys to audit pre-shared key expiration and alert before automated CI enrollment keys expire.

NetBird Mesh Peer Connectivity and Security Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

NetBird Mesh Peer Connectivity and Security Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

Netskope Security Alert Volume Sentinel

Run Ansible Against NetBox Devices by Role and Site

Neon Postgres Compute Scale And Idle Sentinel

NetBox Drift Reconciliation with GitHub Audit Trail

Netlify Deploy Failure Sentinel

Provision a VM and Register It in NetBox

New to Kestra?