phpIPAM Unlabeled Address Hygiene Gate with Kestra

id: phpipam-unlabeled-address-hygiene-gate
namespace: company.team

description: |
  List every address in a phpIPAM subnet, classify it HEALTHY, WARNING, CRITICAL or
  PROBE_FAILED from the real count of addresses marked in-use with no hostname and no
  description, and alert Slack naming the exact IPs responsible, never an invented list.

inputs:
  - id: base_url
    type: STRING
    displayName: phpIPAM base URL
    description: Root URL of the phpIPAM instance. Maps to every task's baseUrl field.
    defaults: "http://localhost"

  - id: app_id
    type: STRING
    displayName: Application ID
    description: The API application identifier configured in phpIPAM under
      Administration, API. Maps to every task's appId field.
    defaults: "myapp"

  - id: subnet_id
    type: STRING
    displayName: Subnet ID
    description: Numeric phpIPAM ID of the subnet to audit. Maps to the List task's
      subnetId field.
    defaults: "1"

  - id: used_tag_id
    type: STRING
    displayName: Used tag ID
    description: The address tag ID that means in-use on this phpIPAM install. 2 is
      the stock default (1 Offline, 2 Used, 3 Reserved, 4 DHCP), but tags are
      configurable per install, verify yours via GET
      /api/{appId}/addresses/tags/ before relying on this default.
    defaults: "2"

  - id: unlabeled_count_warning_threshold
    type: INT
    displayName: Unlabeled address warning threshold
    description: Number of in-use addresses with no hostname and no description at
      or above which the subnet is classified WARNING instead of HEALTHY.
    defaults: 1

  - id: unlabeled_count_critical_threshold
    type: INT
    displayName: Unlabeled address critical threshold
    description: Number of in-use addresses with no hostname and no description at
      or above which the subnet is classified CRITICAL.
    defaults: 10

  - id: insecure_tls
    type: BOOL
    displayName: Disable TLS certificate validation
    description: Set true only for a local or internal instance with a self-signed
      certificate.
    defaults: false

tasks:
  - id: probe_subnet_addresses
    type: io.kestra.plugin.phpipam.ipam.address.List
    description: Reads every address phpIPAM has recorded for this subnet, including
      its tag, hostname, and description.
    allowFailure: true
    baseUrl: "{{ inputs.base_url }}"
    appId: "{{ inputs.app_id }}"
    auth:
      appToken: "{{ secret('PHPIPAM_APP_TOKEN') }}"
    insecureTls: "{{ inputs.insecure_tls }}"
    subnetId: "{{ inputs.subnet_id }}"
    fetchType: FETCH

  - id: classify_address_hygiene_status
    type: io.kestra.plugin.core.debug.Return
    description: PROBE_FAILED when the probe did not return at all, CRITICAL or
      WARNING from the real count of addresses tagged used_tag_id with both
      hostname and description blank, HEALTHY otherwise.
    format: "{{ outputs.probe_subnet_addresses is not defined ? 'PROBE_FAILED' : (
      ((outputs.probe_subnet_addresses.addresses | jq('[.[] | select(.tag == \"'
      ~ inputs.used_tag_id ~ '\" and ((.hostname // \"\") == \"\") and
      ((.description // \"\") == \"\"))] | length') | first) >=
      inputs.unlabeled_count_critical_threshold) ? 'CRITICAL' : (
      ((outputs.probe_subnet_addresses.addresses | jq('[.[] | select(.tag == \"'
      ~ inputs.used_tag_id ~ '\" and ((.hostname // \"\") == \"\") and
      ((.description // \"\") == \"\"))] | length') | first) >=
      inputs.unlabeled_count_warning_threshold) ? 'WARNING' : 'HEALTHY' ) ) }}"

  - id: route_by_address_hygiene_status
    type: io.kestra.plugin.core.flow.Switch
    description: Branch A logs a fully labeled subnet. Branch B alerts Slack naming
      the real unlabeled IPs found, never an invented list.
    value: "{{ outputs.classify_address_hygiene_status.value }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "phpIPAM subnet {{ inputs.subnet_id }} healthy, every in-use address
            has a hostname or description."
      "WARNING":
        - id: alert_warning
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "phpIPAM subnet " ~ inputs.subnet_id ~ " WARNING. Unlabeled in-use addresses: " ~ (outputs.probe_subnet_addresses.addresses | jq("[.[] | select(.tag == \"" ~ inputs.used_tag_id ~ "\" and ((.hostname // \"\") == \"\") and ((.description // \"\") == \"\")) | .ip] | join(\", \")") | first) ~ "."} | toJson }}
      "CRITICAL":
        - id: alert_critical
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "phpIPAM subnet " ~ inputs.subnet_id ~ " CRITICAL. Unlabeled in-use addresses: " ~ (outputs.probe_subnet_addresses.addresses | jq("[.[] | select(.tag == \"" ~ inputs.used_tag_id ~ "\" and ((.hostname // \"\") == \"\") and ((.description // \"\") == \"\")) | .ip] | join(\", \")") | first) ~ ", at or above the " ~ inputs.unlabeled_count_critical_threshold ~ " threshold."} | toJson }}
      "PROBE_FAILED":
        - id: alert_probe_failed
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {{ {"text": "phpIPAM address probe for subnet " ~ inputs.subnet_id ~ " did not return a result. Check base_url, app_id, subnet_id, and the PHPIPAM_APP_TOKEN secret."} | toJson }}
    defaults:
      - id: log_unexpected_status
        type: io.kestra.plugin.core.log.Log
        message: "Unexpected classify_address_hygiene_status value: {{
          outputs.classify_address_hygiene_status.value }}"

  - id: log_audit_summary
    type: io.kestra.plugin.core.log.Log
    description: Final audit log confirming the gate ran, regardless of the branch
      taken above.
    message: "phpIPAM unlabeled address hygiene gate completed. subnet={{
      inputs.subnet_id }} status={{
      outputs.classify_address_hygiene_status.value }}"

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {{ {"text": "phpIPAM unlabeled address hygiene gate flow failed (execution " ~ execution.id ~ "). Check the execution logs."} | toJson }}

triggers:
  - id: daily
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled.
    cron: "0 7 * * *"
    disabled: true
    inputs:
      base_url: "http://localhost"
      app_id: "myapp"
      subnet_id: "1"
      used_tag_id: "2"
      unlabeled_count_warning_threshold: 1
      unlabeled_count_critical_threshold: 10
      insecure_tls: false

An IP address marked in-use in phpIPAM with no hostname and no description is a ghost allocation, something is consuming that address, the record even says so, but nobody looking at phpIPAM today can tell what it is or who owns it. Subnet capacity dashboards do not catch this, a fully-utilized subnet full of unlabeled addresses looks exactly as healthy as one full of well-documented ones. This blueprint lists a subnet's addresses on a schedule, finds the real ones marked in-use with both fields blank, and alerts Slack naming the exact IPs, never an invented count.

How it works

probe_subnet_addresses (io.kestra.plugin.phpipam.ipam.address.List) reads every address recorded for subnet_id, including its tag, hostname, and description, with allowFailure: true so a bad URL, app ID, or token does not stop the flow before it can be classified as PROBE_FAILED below.
classify_address_hygiene_status (io.kestra.plugin.core.debug.Return) returns PROBE_FAILED when the probe did not return at all, CRITICAL or WARNING from the real count of addresses where tag equals used_tag_id and both hostname and description are blank, against the two thresholds, HEALTHY otherwise.
route_by_address_hygiene_status (io.kestra.plugin.core.flow.Switch) branches on that status: HEALTHY logs it, the other three each alert Slack, the WARNING and CRITICAL alerts name the real unlabeled IPs found, never an invented list. An unexpected value falls through to a defaults branch that logs it rather than being silently dropped.
log_audit_summary always runs last and logs the final classification.
The errors block posts to Slack if the flow itself fails outside the gate logic above.

What you get

A real list of exactly which IPs are consuming address space with zero identifying information, not a guess from overall subnet utilization.
A Slack alert naming the actual offending IPs, never an invented count.
A severity tier you control, separate from phpIPAM's own address status tags.
A fully local test path against the official phpIPAM Docker image, no managed instance needed.

Who it's for

Network and infrastructure teams running phpIPAM who want address-record hygiene enforced on a schedule, not only discovered during an audit.
Teams evaluating the phpIPAM plugin who want a working example of ipam.address.List and the plugin's app-token authentication.

Why orchestrate this with Kestra

phpIPAM records whether an address is in use, it has no built-in alert for an in-use address with no owner or hostname attached. Kestra adds that check as a scheduled, declarative flow: the probe, the classification against your own thresholds, and the Slack alert naming the real IPs are all one auditable execution history.

Prerequisites

For local testing, the official phpIPAM Docker Compose stack:

services:
  phpipam-web:
    image: phpipam/phpipam-www:latest
    ports:
      - "80:80"
    environment:
      - IPAM_DATABASE_HOST=phpipam-mariadb
      - IPAM_DATABASE_PASS=my_secret_phpipam_pass
      - IPAM_DATABASE_WEBHOST=%
    depends_on:
      - phpipam-mariadb
  phpipam-mariadb:
    image: mariadb:latest
    environment:
      - MYSQL_ROOT_PASSWORD=my_secret_mysql_root_pass
    volumes:
      - phpipam-db-data:/var/lib/mysql
volumes:
  phpipam-db-data:

Open http://localhost, finish the setup wizard, then generate an App token under Administration, API, with an application that has at least read permission.

A subnet with at least one address manually marked Used (tag 2 by default) and left without a hostname or description, to see WARNING/CRITICAL rather than HEALTHY.
A Slack incoming webhook for alerts.

Secrets

PHPIPAM_APP_TOKEN: the static App token generated in phpIPAM's API administration panel.
SLACK_WEBHOOK: Slack incoming webhook URL used by the alert tasks and the errors block.

In Kestra OSS, set these as base64-encoded environment variables, for example SECRET_PHPIPAM_APP_TOKEN, SECRET_SLACK_WEBHOOK.

Inputs

Input	Type	Default	Allowed values
`base_url`	STRING	`http://localhost`	any reachable phpIPAM base URL
`app_id`	STRING	`myapp`	an application ID configured under Administration, API
`subnet_id`	STRING	`1`	any existing subnet's numeric ID
`used_tag_id`	STRING	`2`	any tag ID configured on this install
`unlabeled_count_warning_threshold`	INT	`1`	any non-negative integer
`unlabeled_count_critical_threshold`	INT	`10`	any non-negative integer, greater than the warning threshold
`insecure_tls`	BOOL	`false`	`true`, `false`

Quick start

Start the phpIPAM stack above and generate an App token.
Create a subnet, add an address, mark it Used, and leave its hostname and description blank.
Add the PHPIPAM_APP_TOKEN and SLACK_WEBHOOK secrets.
Run this flow manually with subnet_id set to that subnet, it should report WARNING and name the address you just created.
Enable the daily trigger.

How to extend

Loop this flow with io.kestra.plugin.core.flow.Loop across every subnet ID returned by io.kestra.plugin.phpipam.ipam.subnet.List to audit an entire phpIPAM instance from one flow.
Also flag addresses with a hostname but a blank owner, a different hygiene gap than a fully blank record.
Join the alert against a CMDB or directory lookup by mac to attempt auto-attribution before falling back to a human-reviewed alert.

Pitfalls

used_tag_id defaults to phpIPAM's stock value of 2, but tags are configurable per install. Confirm yours with GET /api/{appId}/addresses/tags/ before trusting the default on an existing, customized instance.
This gate only reads and alerts, it never assigns a hostname or description, deciding what an unlabeled address actually is needs a human who recognizes the device, not an automated guess.
fetchType: FETCH loads every address in the subnet into memory at once, fine for a typical subnet, switch to STORE and process the file instead for a very large one.
A blank description field in phpIPAM's API can come back as an empty string or be entirely absent from the JSON response depending on how the address was created, the // "" fallback in this gate's jq expressions treats both the same way.

phpIPAM Unlabeled Address Hygiene Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Inputs

Quick start

How to extend

Pitfalls

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

phpIPAM Unlabeled Address Hygiene Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Inputs

Quick start

How to extend

Pitfalls

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

Kafka Consumer Lag Sentinel

Kafka Schema Registry Orphaned Subject Cleanup Guard

Kafka Orphaned Topic Reclaim Guard

Kafka DLQ Quarantine, Classification, and Safe Replay Gate

Kafka Schema Registry Compatibility and Mode Drift Guard

Kafka Producer Compression Ratio Sentinel

More Cloud Blueprints

Kafka DLQ Quarantine, Classification, and Safe Replay Gate

Kong Upstream Target Health and Balancer Sentinel

KMS Key Rotation Compliance Gate

Kubecost Namespace Rightsizing with Approval and Chargeback

Kubernetes Orphaned Volume and Cloud Storage FinOps Reclaimer

Kubernetes Ingress TLS Certificate Expiry Guard

New to Kestra?