NetBox Drift Reconciliation with GitHub Audit Trail

id: netbox-drift-reconciliation
namespace: company.team
description: |
  Reconcile the live network against NetBox. Scan discovered devices, compare
  them to what NetBox records for a site, register any missing devices, and open
  a GitHub issue summarizing the drift so the team has an audit trail.

inputs:
  - id: site
    type: STRING
    defaults: nyc-dc1
    description: NetBox site slug to reconcile.
  - id: github_repository
    type: STRING
    defaults: my-org/netops
    description: GitHub repository (owner/name) where drift issues are opened.

tasks:
  - id: list_netbox_devices
    type: io.kestra.plugin.ee.netbox.device.List
    description: Fetch the devices NetBox currently records for the site.
    filters:
      site: "{{ inputs.site }}"
    fields:
      - name
    fetchType: FETCH

  - id: scan_and_diff
    type: io.kestra.plugin.scripts.python.Script
    description: Compare a live scan against the NetBox inventory and emit the
      missing devices.
    taskRunner:
      type: io.kestra.plugin.scripts.runner.docker.Docker
    containerImage: python:3.11-slim
    beforeCommands:
      - pip install kestra
    inputFiles:
      netbox_devices.json: "{{ outputs.list_netbox_devices.rows }}"
    script: |
      import json
      from kestra import Kestra

      with open("netbox_devices.json") as f:
          netbox = {d["name"] for d in json.load(f)}

      # Replace this stub with a real discovery source (SNMP sweep, scanner export, etc.).
      discovered = [
          {"name": "sw-new-01", "deviceType": "generic-switch", "deviceRole": "access-switch"},
      ]

      missing = [
          {**d, "site": "{{ inputs.site }}"}
          for d in discovered
          if d["name"] not in netbox
      ]
      Kestra.outputs({"missing": missing, "drift_count": len(missing)})

  - id: register_missing_devices
    type: io.kestra.plugin.core.flow.ForEach
    description: Create a NetBox device record for each discovered device missing
      from NetBox.
    values: "{{ outputs.scan_and_diff.vars.missing }}"
    tasks:
      - id: create_device
        type: io.kestra.plugin.ee.netbox.device.Create
        description: Register one discovered device in NetBox.
        name: "{{ taskrun.value.name }}"
        deviceType: "{{ taskrun.value.deviceType }}"
        deviceRole: "{{ taskrun.value.deviceRole }}"
        site: "{{ taskrun.value.site }}"
        status: active

  - id: open_drift_issue
    type: io.kestra.plugin.github.issues.Create
    description: Open a GitHub issue summarizing the reconciliation result.
    repository: "{{ inputs.github_repository }}"
    title: "NetBox drift detected in {{ inputs.site }}"
    body: |
      Reconciliation for site `{{ inputs.site }}` found {{ outputs.scan_and_diff.vars.drift_count }} device(s)
      present on the network but missing from NetBox. They have been registered automatically.

      NetBox devices before reconciliation: {{ outputs.list_netbox_devices.size }}
    labels:
      - netbox-drift

pluginDefaults:
  - type: io.kestra.plugin.ee.netbox.device.List
    values:
      url: "{{ secret('NETBOX_URL') }}"
      token: "{{ secret('NETBOX_API_TOKEN') }}"
  - type: io.kestra.plugin.ee.netbox.device.Create
    values:
      url: "{{ secret('NETBOX_URL') }}"
      token: "{{ secret('NETBOX_API_TOKEN') }}"
  - type: io.kestra.plugin.github.issues.Create
    values:
      jwtToken: "{{ secret('GITHUB_TOKEN') }}"

triggers:
  - id: daily_reconciliation
    type: io.kestra.plugin.core.trigger.Schedule
    description: Reconcile daily. Adjust or disable as needed.
    cron: "0 5 * * *"
    disabled: true