Detect then correct phpIPAM subnet VLAN plus VRF assignment drift

id: phpipam-vlan-vrf-assignment-drift-guard
namespace: company.team

description: |
  Read every subnet in a phpIPAM section, compare each one's VLAN plus VRF assignment
  against a declared network design supplied as an input, then correct the subnets that
  drifted behind an approval gate. phpIPAM is re-read afterwards, which is the only
  evidence the write landed.

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

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

  - id: app_token
    type: STRING
    displayName: phpIPAM API token
    description: >-
      API token for that application. The default reads the PHPIPAM_APP_TOKEN
      secret. Kestra renders an input default lazily, so a run that passes a
      literal token never touches the secret store.
    defaults: "{{ secret('PHPIPAM_APP_TOKEN') }}"

  - id: section_id
    type: STRING
    displayName: Section ID
    description: Numeric phpIPAM section whose subnets are audited. Maps to the List
      tasks' sectionId field.
    defaults: "1"

  - id: declared_baseline
    type: STRING
    displayName: Declared VLAN plus VRF design
    description: >-
      The network design, as a JSON array of objects carrying subnetId, vlanId,
      vrfId. This is the authority every comparison is made against, so it is
      required rather than inferred from phpIPAM. Use "0" for deliberately
      unassigned. A subnet absent from this list is never evaluated, never
      written. The shipped default is an empty array, which refuses the run on
      purpose: fill it in before enabling the schedule.
    defaults: "[]"

  - id: protected_subnet_ids
    type: STRING
    displayName: Protected subnet IDs
    description: Comma separated phpIPAM subnet IDs that are reported when they
      drift but never written. Use it for regulated or shared segments that only
      a change window may touch.
    defaults: ""

  - id: max_corrections_per_run
    type: INT
    displayName: Per-run correction ceiling
    description: The run refuses when more subnets need correcting than this.
      Wholesale disagreement between the design plus phpIPAM is a design
      problem, so the flow stops rather than rewriting a section.
    defaults: 5

  - id: dry_run
    type: BOOL
    displayName: Report only
    description: True reports the drift without writing anything to phpIPAM.
    defaults: true

  - id: auto_remediate
    type: BOOL
    displayName: Allow corrections
    description: Must be true, with dry_run false, before any phpIPAM write is even
      offered for approval.
    defaults: false

  - 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: parse_baseline
    type: io.kestra.plugin.core.debug.Return
    description: Counts the usable entries in the declared design. A baseline that
      is empty, unparseable or carrying no subnetId fails this task, which is
      what turns an unusable design into a refusal.
    allowFailure: true
    format: >-
      {{ {'b': inputs.declared_baseline} | toJson | jq('(.b | fromjson) | [.[] |
      select(.subnetId != null)] | length') | first }}

  - id: refuse_unusable_baseline
    type: io.kestra.plugin.core.execution.Fail
    description: Stops the run before any phpIPAM call when there is no design to
      compare against. No baseline is not evidence that every subnet is wrong.
    condition: >-
      {{ (outputs.parse_baseline is not defined) or
      ((outputs.parse_baseline.value ?? '0') == '0') }}
    errorMessage: >-
      Refusing to run. inputs.declared_baseline is empty or does not parse as a
      JSON array of objects carrying subnetId. Supply the design explicitly. An
      absent design is not evidence that every subnet is assigned wrongly.

  - id: read_assignments_before
    type: io.kestra.plugin.phpipam.ipam.subnet.List
    description: Reads every subnet in the section with its current vlanId plus
      vrfId. This is the before picture the whole run is judged against.
    baseUrl: "{{ inputs.base_url }}"
    appId: "{{ inputs.app_id }}"
    auth:
      appToken: "{{ inputs.app_token }}"
    insecureTls: "{{ inputs.insecure_tls }}"
    sectionId: "{{ inputs.section_id }}"
    fetchType: FETCH

  - id: detect_drift
    type: io.kestra.plugin.core.debug.Return
    description: Joins the design to what phpIPAM holds. Emits one row per subnet
      whose VLAN or VRF differs, classified WRITABLE, PROTECTED or MISSING, so
      neither a protected segment nor an ID phpIPAM does not have can reach a
      write.
    format: >-
      {{ {'b': inputs.declared_baseline, 's':
      (outputs.read_assignments_before.subnets | toJson), 'p':
      inputs.protected_subnet_ids} | toJson | jq(' def norm: (. // "0") |
      tostring | if . == "" then "0" else . end; ((.s | fromjson) // []) as $cur
      | [ ((.p // "") | split(","))[] | sub("^ +";"") | sub(" +$";"") |
      select(length > 0) ] as $prot | [ (.b | fromjson)[] | (.subnetId |
      tostring) as $sid | (($cur | map(select((.id | tostring) == $sid)) |
      first) // null) as $c | { subnetId: $sid, cidr: (if $c == null then ""
      else (($c.subnet // "") | tostring) + "/" + (($c.mask // "") | tostring)
      end), name: (if $c == null then "" else (($c.description // "") |
      tostring) end), currentVlanId: (if $c == null then "" else ($c.vlanId |
      norm) end), declaredVlanId: (.vlanId | norm), currentVrfId: (if $c == null
      then "" else ($c.vrfId | norm) end), declaredVrfId: (.vrfId | norm),
      status: (if $c == null then "MISSING" elif (($prot | index($sid)) != null)
      then "PROTECTED" else "WRITABLE" end) } | select(.status == "MISSING" or
      .currentVlanId != .declaredVlanId or .currentVrfId != .declaredVrfId) ] ')
      | first | toJson }}

  - id: log_drift_report
    type: io.kestra.plugin.core.log.Log
    description: The report. Task outputs are not in the execution payload, so the
      counts plus every old-to-new value go to the log where an operator can
      read them.
    message: >-
      phpIPAM section {{ inputs.section_id }} VLAN plus VRF drift report.
      declared_entries={{ outputs.parse_baseline.value }} subnets_read={{
      outputs.read_assignments_before.total }} writable_drift={{
      outputs.detect_drift.value | jq('[.[] | select(.status == "WRITABLE")] |
      length') | first }} protected_drift={{ outputs.detect_drift.value |
      jq('[.[] | select(.status == "PROTECTED")] | length') | first }}
      missing_in_phpipam={{ outputs.detect_drift.value | jq('[.[] |
      select(.status == "MISSING")] | length') | first }} protected_skipped={{
      outputs.detect_drift.value | jq('[.[] | select(.status == "PROTECTED") |
      .subnetId] | join(",")') | first }} details={{ outputs.detect_drift.value
      }}

  - id: refuse_over_ceiling
    type: io.kestra.plugin.core.execution.Fail
    description: Refuses once more subnets need correcting than the per-run ceiling
      allows. The report above is already written, so an operator sees what
      tripped it.
    condition: >-
      {{ (outputs.detect_drift.value | jq('[.[] | select(.status == "WRITABLE")]
      | length') | first) > inputs.max_corrections_per_run }}
    errorMessage: >-
      Refusing to correct. The number of drifted subnets is above
      inputs.max_corrections_per_run. Widespread disagreement usually means the
      declared design is stale, not that the network is. Review the report, then
      raise the ceiling deliberately.

  - id: remediation_gate
    type: io.kestra.plugin.core.flow.If
    description: The only path that writes. It needs auto_remediate true, dry_run
      false plus at least one WRITABLE finding, which is why the shipped
      defaults report then stop.
    condition: >-
      {{ inputs.auto_remediate and (inputs.dry_run == false) and
      ((outputs.detect_drift.value | jq('[.[] | select(.status == "WRITABLE")] |
      length') | first) > 0) }}
    then:
      - id: confirm_corrections
        type: io.kestra.plugin.core.flow.Pause
        description: Holds the run until an operator answers. Rewriting an assignment in
          IPAM changes what downstream automation generates next, so a human
          reads the old-to-new list first.
        onResume:
          - id: approved
            type: BOOL
            displayName: Apply these VLAN plus VRF corrections
            description: Set true to write the corrections listed in the report. Resuming
              without setting it leaves phpIPAM untouched.
            defaults: false

      - id: approved_gate
        type: io.kestra.plugin.core.flow.If
        description: A resume that does not answer true leaves phpIPAM alone, so an
          accidental resume cannot approve a write.
        condition: "{{ outputs.confirm_corrections.onResume.approved ?? false }}"
        then:
          - id: remediate_assignments
            type: io.kestra.plugin.core.flow.Loop
            description: One phpIPAM write per drifted subnet, serialised so two corrections
              cannot race on the same section.
            concurrencyLimit: 1
            values: >-
              {{ outputs.detect_drift.value | jq('[.[] | select(.status ==
              "WRITABLE") | {subnetId: .subnetId, vlanId: .declaredVlanId,
              vrfId: .declaredVrfId} | tojson]') | first }}
            tasks:
              - id: correct_assignment
                type: io.kestra.plugin.phpipam.ipam.subnet.Update
                description: Sets vlanId plus vrfId on one subnet to the declared values. The
                  task returns no output of its own, so the second read below is
                  the only evidence it landed.
                baseUrl: "{{ inputs.base_url }}"
                appId: "{{ inputs.app_id }}"
                auth:
                  appToken: "{{ inputs.app_token }}"
                insecureTls: "{{ inputs.insecure_tls }}"
                subnetId: "{{ item.value | jq('.subnetId') | first }}"
                vlanId: "{{ item.value | jq('.vlanId') | first }}"
                vrfId: "{{ item.value | jq('.vrfId') | first }}"

          - id: record_write_attempt
            type: io.kestra.plugin.core.debug.Return
            description: Marks that the approved write path ran. The re-verify below only
              fails the run when this exists, so a dry run is never failed for
              drift it deliberately left alone.
            format: applied

  - id: read_assignments_after
    type: io.kestra.plugin.phpipam.ipam.subnet.List
    description: Reads the section again from phpIPAM. It runs on every path, so a
      report-only run produces a before plus after pair that has to be
      identical.
    baseUrl: "{{ inputs.base_url }}"
    appId: "{{ inputs.app_id }}"
    auth:
      appToken: "{{ inputs.app_token }}"
    insecureTls: "{{ inputs.insecure_tls }}"
    sectionId: "{{ inputs.section_id }}"
    fetchType: FETCH

  - id: reverify_drift
    type: io.kestra.plugin.core.debug.Return
    description: Recomputes drift from the second read against the same design. On
      the approved write path this has to come back with no WRITABLE rows left.
    format: >-
      {{ {'b': inputs.declared_baseline, 's':
      (outputs.read_assignments_after.subnets | toJson), 'p':
      inputs.protected_subnet_ids} | toJson | jq(' def norm: (. // "0") |
      tostring | if . == "" then "0" else . end; ((.s | fromjson) // []) as $cur
      | [ ((.p // "") | split(","))[] | sub("^ +";"") | sub(" +$";"") |
      select(length > 0) ] as $prot | [ (.b | fromjson)[] | (.subnetId |
      tostring) as $sid | (($cur | map(select((.id | tostring) == $sid)) |
      first) // null) as $c | { subnetId: $sid, cidr: (if $c == null then ""
      else (($c.subnet // "") | tostring) + "/" + (($c.mask // "") | tostring)
      end), name: (if $c == null then "" else (($c.description // "") |
      tostring) end), currentVlanId: (if $c == null then "" else ($c.vlanId |
      norm) end), declaredVlanId: (.vlanId | norm), currentVrfId: (if $c == null
      then "" else ($c.vrfId | norm) end), declaredVrfId: (.vrfId | norm),
      status: (if $c == null then "MISSING" elif (($prot | index($sid)) != null)
      then "PROTECTED" else "WRITABLE" end) } | select(.status == "MISSING" or
      .currentVlanId != .declaredVlanId or .currentVrfId != .declaredVrfId) ] ')
      | first | toJson }}

  - id: log_reverify
    type: io.kestra.plugin.core.log.Log
    description: The after picture, read back from phpIPAM rather than assumed from
      the write task going green.
    message: >-
      phpIPAM section {{ inputs.section_id }} re-read. write_attempted={{
      outputs.record_write_attempt is defined ? 'yes' : 'no' }}
      writable_drift_remaining={{ outputs.reverify_drift.value | jq('[.[] |
      select(.status == "WRITABLE")] | length') | first }}
      protected_drift_remaining={{ outputs.reverify_drift.value | jq('[.[] |
      select(.status == "PROTECTED")] | length') | first }} details={{
      outputs.reverify_drift.value }}

  - id: fail_if_still_drifted
    type: io.kestra.plugin.core.execution.Fail
    description: Fails the run when a correction was approved yet a target still
      disagrees with the design. phpIPAM answers 200 to a write it did not
      apply, so this comparison is the only thing that can tell the two apart.
    condition: >-
      {{ (outputs.record_write_attempt is defined) and
      ((outputs.reverify_drift.value | jq('[.[] | select(.status == "WRITABLE")]
      | length') | first) > 0) }}
    errorMessage: >-
      Corrections were approved yet phpIPAM still disagrees with the declared
      design. Read log_reverify for the subnets still wrong, then check the API
      token's write permission before retrying.

errors:
  - id: alert_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: >-
      Posts the failure to Slack. The refusals above arrive here too, because a
      refused run is something an operator has to see.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: >-
      {{ {"text": "phpIPAM VLAN plus VRF drift guard failed on section " ~
      inputs.section_id ~ ". Execution " ~ execution.id ~ ". Read
      log_drift_report plus log_reverify before retrying."} | toJson }}

triggers:
  - id: daily_design_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Disabled on purpose. Fill declared_baseline first, then enable it.
      Its inputs pin the run to report only.
    disabled: true
    cron: "0 7 * * *"
    inputs:
      dry_run: true
      auto_remediate: false

Findings

Two things about this plugin shape the flow, both measured on a real phpIPAM instance.

io.kestra.plugin.phpipam.ipam.subnet.Update carries no output at all. It takes subnetId, vlanId, vrfId plus resourceDescription, returns nothing, so the task going green says only that phpIPAM answered. That is why the flow reads the section a second time with ipam.subnet.List then recomputes the comparison, rather than trusting the write.

ipam.subnet.List returns vlanId plus vrfId as JSON numbers while an unassigned subnet carries 0. The comparison normalises null, empty string plus 0 to one value, so a subnet that is deliberately unassigned does not read as drift.

One failure mode to know about. phpIPAM refuses a vlanId that is not in its VLAN table with HTTP 404 Vlan does not exist, which the plugin reports as Resource not found naming the subnet path. The subnet is fine, the declared VLAN is the thing that does not exist, so check the design against GET /api/{appId}/vlan/ when a correction fails that way. A write the application has no permission for comes back as HTTP 401 instead, which fails the task.

Safety

Rewriting a VLAN or VRF assignment in IPAM moves nothing on the network. It changes what the next firewall rule, routing policy or template generated from IPAM will target. So a wrong baseline propagates a wrong segment with full confidence. The flow is built around that:

the design is a required input, never inferred from what phpIPAM currently holds
an empty or unparseable design refuses the run before any phpIPAM call
a subnet absent from the design is never evaluated, never written
a baseline entry naming a subnet phpIPAM does not have is reported MISSING, never corrected
protected_subnet_ids subnets are reported when they drift, never written
more drift than max_corrections_per_run refuses the whole correction
every write needs auto_remediate true, dry_run false plus a Pause answered true

How it works

parse_baseline counts the usable entries in declared_baseline. An unparseable design fails this task under allowFailure, which is what the refusal reads.
refuse_unusable_baseline stops the run when that count is zero or absent. Nothing has touched phpIPAM yet at this point.
read_assignments_before lists every subnet in the section with its live vlanId plus vrfId.
detect_drift joins the design to that read, one row per disagreeing subnet, each classified WRITABLE, PROTECTED or MISSING with both the old plus the new value.
log_drift_report writes the counts, the protected skips plus the full detail to the log.
refuse_over_ceiling fails when more subnets are WRITABLE than the per-run ceiling allows.
remediation_gate opens only for auto_remediate true with dry_run false. It pauses for approval, then a serialised Loop calls ipam.subnet.Update once per WRITABLE subnet.
read_assignments_after reads the section again, reverify_drift recomputes, then fail_if_still_drifted fails the run if a target is still wrong after an approved write.

What you get

a drift report naming the subnet, its CIDR, its description plus the old-to-new VLAN or VRF
three classes in that report, so a protected segment reads differently from a real target
corrections applied one at a time through the phpIPAM API
a second phpIPAM read that decides whether the run passes
a Slack message on any failure or refusal

Who it's for

Network plus platform engineers who generate firewall rules, routing policy or device templates out of phpIPAM. If a subnet's VLAN or VRF silently differs from the design, every artifact generated from it targets the wrong segment while IPAM reports no error.

Why orchestrate this with Kestra

The detection is a join between a file of record plus a live API, the correction is a write that nobody should make unattended, the proof is a second read. Kestra carries the inputs, the approval, the serialised writes plus the failing re-verify in one versioned flow, with the schedule already written for when the design is trusted enough to run daily.

Tested end to end

Run against a real phpIPAM instance with six subnets in one section: two matching the design as controls, one with a drifted VLAN, one with a drifted VRF, one drifted but protected, one absent from the design. The design also named a subnet phpIPAM does not have. Nine runs, every outcome confirmed by reading phpIPAM's own API plus its database, never the Kestra log alone.

path	result
design matches reality	5 entries, 6 subnets read, 0 findings, nothing written
VLAN plus VRF drifted	2 WRITABLE, 1 PROTECTED, 1 MISSING, every old-to-new value named
`dry_run: true`	reported only, phpIPAM identical before plus after
approved Pause	subnet 13 VLAN 999 to 103, subnet 14 VRF 299 to 202, re-read confirmed 0 left
declined Pause	no write task ran, both targets still drifted, run passed
protected subnet	drifted 888 against 105, reported PROTECTED, left at 888
subnet absent from design	never evaluated, never written
empty design	refused before any phpIPAM call
unparseable design	refused before any phpIPAM call
ceiling exceeded	refused at 2 findings against a ceiling of 1, report still written
write refused by phpIPAM	the API answered 401, the task failed, the run failed
re-verify disagreement	corrections applied, phpIPAM still disagreed, run failed
failure path	the `errors` block posted to Slack on all five failing runs

Controls stayed byte identical through every run: subnet 11 at VLAN 101 VRF 201, subnet 12 at VLAN 102 VRF 201, subnet 16 at VLAN 105 VRF 299. Subnet descriptions survived the corrections, so the write touches the assignment fields only.

Prerequisites

A phpIPAM instance with the API enabled under Administration, API, an application whose permissions allow read plus write, the declared design for the section.

Secrets

PHPIPAM_APP_TOKEN: the API token for that application. It is the default of the app_token input, so Kestra renders it only when the input is left unset.
SLACK_WEBHOOK_URL: incoming webhook for the failure alert.

Inputs

base_url: root URL of the phpIPAM instance.
app_id: the API application identifier.
app_token: API token, defaulting to the secret above.
section_id: the section whose subnets are audited.
declared_baseline: the design, a JSON array of {"subnetId","vlanId","vrfId"}. Required.
protected_subnet_ids: comma separated IDs reported but never written.
max_corrections_per_run: ceiling above which the run refuses. Default 5.
dry_run: report only. Default true.
auto_remediate: allow corrections at all. Default false.
insecure_tls: skip certificate validation. Default false.

Quick start

Add the PHPIPAM_APP_TOKEN plus SLACK_WEBHOOK_URL secrets.
Run it with declared_baseline set to your design for one section, leaving dry_run true. Read log_drift_report.
Fix the design until the only rows left are real drift. Put anything a change window owns into protected_subnet_ids.
Re-run with auto_remediate: true plus dry_run: false, read the pause, answer approved true. log_reverify reports what phpIPAM holds afterwards.
Enable the schedule once the design is trusted. Its inputs keep it report only.

How to extend

Read the design out of Git instead of an input with io.kestra.plugin.git.Clone, so the source of truth is reviewed the way code is.
Swap ipam.subnet.Update for ipam.vlan.Update or ipam.vrf.Update to hold VLAN names or VRF route distinguishers to a design as well.
Add ipam.subnet.List over several sections, then compare each against its own design file.
Post the report to the network team's channel on every run, not only on failure.

Detect then correct phpIPAM subnet VLAN plus VRF assignment drift

Findings

Safety

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Tested end to end

Prerequisites

Secrets

Inputs

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

Detect then correct phpIPAM subnet VLAN plus VRF assignment drift

Findings

Safety

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Tested end to end

Prerequisites

Secrets

Inputs

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

PipAuditWatch - Python dependency CVE watcher

PhpIPAM Unlabeled Address Hygiene Gate

Pinniped Supervisor JWT Authenticator Clock Skew Sentinel

Apache Pinot Real-Time Ingestion Freshness Sentinel

Run synthetic page health checks with headless Playwright and alert on failure

Get Alerted When a Dependency Version You Pin Is Yanked or Deprecated

New to Kestra?