Skip to content

talder/xyOps-Netbox-IPAM

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE.md
LICENSE.md
 
 
README.md
README.md
 
 
ipam.ps1
ipam.ps1
 
 
logo.png
logo.png
 
 
logo.svg
logo.svg
 
 
xyops.json
xyops.json
 
 

Repository files navigation

Logo

xyOps NetBox IPAM

xyOps NetBox IPAM Plugin

Version License: MIT PowerShell NetBox Platform

A comprehensive xyOps Event Plugin for NetBox 4.5 IPAM (IP Address Management) containing 28 tools for managing Prefixes, IP Addresses, VLANs, and VRFs using the PowerNetbox module.

Disclaimer

USE AT YOUR OWN RISK. This software is provided "as is", without warranty of any kind, express or implied. The author and contributors are not responsible for any damages, data loss, or other issues that may arise from the use of this software. Always test in non-production environments first.

Table of Contents

Quick Start

  1. Install the plugin in xyOps (copy to plugins directory or install from Marketplace)
  2. Configure secrets NETBOX_URL and NETBOX_API_TOKEN in the Secret Vault
  3. Add the IPAM event to any job
  4. Select a tool from the dropdown menu
  5. Run the job

Installation

From xyOps Marketplace

  1. Navigate to xyOps Marketplace
  2. Search for "NetBox IPAM"
  3. Click Install

Manual Installation

cd /opt/xyops/plugins
git clone https://github.com/talder/xyOps-Netbox-IPAM.git

PowerNetbox Module

The plugin will automatically install the PowerNetbox module on first run.

If auto-installation fails, install it manually:

Install-Module -Name PowerNetbox -Scope CurrentUser

Secrets Configuration

Configure the following secrets in the xyOps Secret Vault:

Secret Name Description
NETBOX_URL Base URL of your NetBox instance (e.g., https://netbox.example.com)
NETBOX_API_TOKEN Your NetBox API authentication token

Obtaining a NetBox API Token:

  1. Log in to your NetBox instance
  2. Navigate to your user profile (top right menu)
  3. Click on "API Tokens"
  4. Click "Add a token"
  5. Set appropriate permissions (IPAM read/write)
  6. Copy the generated token to the xyOps Secret Vault

Tools Overview

Category Tool Description
Prefixes List List all prefixes with optional filters
Get by NetBox ID Look up a prefix by its NetBox ID
Get by CIDR Find a prefix by CIDR notation
Get by Description Search prefixes by partial description match
Create Create a new prefix with VLAN, site, and VRF
Delete Delete a prefix by NetBox ID
Available IPs List available IPs in a prefix
IP Addresses List List all IP addresses with optional filters
Get by NetBox ID Look up an IP by its NetBox ID
Get by Address Find an IP by its address value
Get by DNS Name Search by partial DNS name match
Get by Description Search by partial description match
Create Create a new IP address
Delete Delete an IP address by NetBox ID
VLANs List List all VLANs with optional filters
Get by NetBox ID Look up a VLAN by its NetBox ID
Get by Name Find by name (case-insensitive, partial match)
Get by VLAN ID Find by VLAN ID (1-4094)
Get by Description Search by partial description match
Create Create a new VLAN with optional site
Delete Delete a VLAN by NetBox ID
VRFs List List all VRFs with optional filters
Get by NetBox ID Look up a VRF by its NetBox ID
Get by Name Find a VRF by its name
Get by Description Search by partial description match
Create Create a new VRF with route distinguisher
Delete Delete a VRF by NetBox ID

Prefix Tools

List Prefixes

List all prefixes with optional filters.

Parameters:

Parameter Type Default Description
Prefix (CIDR) Text - Filter by prefix (e.g., 10.0.0.0/24)
Status Select All Active, Reserved, Deprecated, Container
Site Text - Filter by site slug

Get Prefix by NetBox ID

Parameter Type Default Description
NetBox ID Number - The NetBox ID of the prefix

Get Prefix by CIDR

Parameter Type Default Description
Prefix (CIDR) Text - CIDR notation (e.g., 10.0.0.0/24)

Get Prefix by Description

Parameter Type Default Description
Description Text - Partial description text to search

Create Prefix

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to value in previous job data
Prefix (CIDR) Text - Prefix in CIDR notation
Status Select Active Active, Reserved, Deprecated, Container
Description Text - Description for the prefix
VLAN (Name or NetBox ID) Text - VLAN name or NetBox ID to assign
VLAN ID (1-4094) Number - VLAN ID to find or create
Create VLAN if not exists Checkbox No Auto-create VLAN if not found
Site Text - Site name, slug, or NetBox ID
VRF Text - VRF name or NetBox ID

Delete Prefix

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to ID in previous job data
NetBox ID Number - The NetBox ID of the prefix to delete

Available IPs

Parameter Type Default Description
Prefix (CIDR) Text - CIDR notation (takes priority over NetBox ID)
Prefix NetBox ID Number - NetBox ID of the prefix
Count Number 10 Number of available IPs to show

IP Address Tools

List IP Addresses

Parameter Type Default Description
IP Address Text - Filter by IP address
Parent Prefix Text - Filter by parent prefix (e.g., 10.0.0.0/24)

Get IP Address by NetBox ID

Parameter Type Default Description
NetBox ID Number - The NetBox ID of the IP address

Get IP Address by Address

Parameter Type Default Description
IP Address Text - IP address to search for

Get IP Address by DNS Name

Parameter Type Default Description
DNS Name Text - Partial DNS name to search

Get IP Address by Description

Parameter Type Default Description
Description Text - Partial description text to search

Create IP Address

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to value in previous job data
IP Address Text - IP address with prefix length (e.g., 10.0.0.1/24)
Status Select Active Active, Reserved, Deprecated, DHCP, SLAAC
DNS Name Text - DNS name for the IP address
Description Text - Description for the IP address

Delete IP Address

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to ID in previous job data
NetBox ID Number - The NetBox ID of the IP address to delete

VLAN Tools

List VLANs

Parameter Type Default Description
VLAN ID Text - Filter by VLAN ID
Site Text - Filter by site slug

Get VLAN by NetBox ID

Parameter Type Default Description
NetBox ID Number - The NetBox ID of the VLAN

Get VLAN by Name

Case-insensitive partial match search.

Parameter Type Default Description
VLAN Name Text - Name of the VLAN to find

Get VLAN by VLAN ID

Parameter Type Default Description
VLAN ID Number - VLAN ID (1-4094) to search for

Get VLAN by Description

Parameter Type Default Description
Description Text - Partial description text to search

Create VLAN

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to value in previous job data
VLAN ID Number - VLAN ID (1-4094)
Name Text - Name for the new VLAN
Status Select Active Active, Reserved, Deprecated
Site Text - Site name, slug, or NetBox ID
Description Text - Description for the VLAN

Delete VLAN

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to ID in previous job data
NetBox ID Number - The NetBox ID of the VLAN to delete

VRF Tools

List VRFs

Parameter Type Default Description
Name Text - Filter by VRF name

Get VRF by NetBox ID

Parameter Type Default Description
NetBox ID Number - The NetBox ID of the VRF

Get VRF by Name

Parameter Type Default Description
VRF Name Text - Name of the VRF to find

Get VRF by Description

Parameter Type Default Description
Description Text - Partial description text to search

Create VRF

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to value in previous job data
Name Text - Name for the new VRF
Route Distinguisher Text - Route distinguisher (e.g., 65000:1)
Description Text - Description for the VRF
Enforce Unique Checkbox Yes Enforce unique IP addressing within this VRF

Delete VRF

Parameter Type Default Description
Input Source Select Manual Input Manual Input or From Previous Job
Data Path Text - Dot-path to ID in previous job data
NetBox ID Number - The NetBox ID of the VRF to delete

Smart Object Resolution

When creating prefixes, you can reference related objects by name or NetBox ID. The plugin automatically resolves names to IDs.

Object Accepted Values Examples
Site Name, Slug, or ID Amsterdam DC, amsterdam-dc, 42
VLAN Name or ID Management VLAN, 15
VRF Name or ID Customer-A, 8

Resolution Logic:

  1. Pure numbers (e.g., 42) are treated as NetBox IDs
  2. Text values trigger a search by name or slug
  3. Single match → resolved automatically
  4. No matches → error with helpful message
  5. Multiple matches → error listing all matches

Input from Previous Job

All create and delete tools support receiving data from a linked previous job:

  1. Set Input Source to "From Previous Job"
  2. Specify a Data Path (dot-separated) to navigate the previous job's output (e.g., result.id, result.prefix)

This allows chaining multiple xyOps plugins together in automated workflows.

Example: Manual Input (Default)

When Input Source is set to "Manual Input", simply fill in the fields directly:

Tool:          Prefixes - Create
Input Source:  Manual Input [field]
Prefix (CIDR): 10.0.100.0/24
Status:        Active
Description:   Office network
VLAN ID:       100
Create VLAN:   ☑
Site:          Amsterdam DC

The plugin creates the prefix, resolves "Amsterdam DC" to its NetBox ID, and auto-creates VLAN 100 if it doesn't exist.

Example: Input from Previous Job (Chaining)

When a previous job outputs data, you can reference any field by its dot-path.

Step 1 — Previous job (e.g., Create Prefix) outputs:

{
  "tool": "createPrefix",
  "data": {
    "id": 42,
    "prefix": "10.0.100.0/24",
    "status": { "label": "Active" },
    "site": { "id": 5, "name": "Amsterdam DC" },
    "description": "Office network"
  }
}

Step 2 — Delete Prefix reads the ID from that output:

Tool:          Prefixes - Delete
Input Source:  From Previous Job [input]
Data Path:     data.id
NetBox ID:     (ignored when source is 'input')

The plugin navigates data.id → 42 and deletes that prefix.

Example: Chaining Create IP Address from Another Plugin

A previous job (e.g., a network scanner plugin) outputs:

{
  "data": {
    "discovered": {
      "ip": "10.0.100.50/24",
      "hostname": "srv-web-01.example.com"
    }
  }
}

The IPAM Create IP Address tool can consume this:

Tool:          IP Addresses - Create
Input Source:  From Previous Job [input]
Data Path:     data.discovered.ip
DNS Name:      srv-web-01.example.com
Status:        Active

The plugin navigates data.discovered.ip → 10.0.100.50/24 and creates the IP address.

Data Path Reference

Previous Job Output Data Path Resolved Value
{ "data": { "id": 42 } } data.id 42
{ "data": { "prefix": "10.0.0.0/24" } } data.prefix 10.0.0.0/24
{ "data": { "site": { "name": "DC1" } } } data.site.name DC1
{ "result": { "items": { "ip": "10.0.0.1" } } } result.items.ip 10.0.0.1

Data Export

All list operations automatically generate downloadable files:

  • CSV — comma-separated values with headers
  • Markdown — formatted table with timestamp

Output Data Reference

All tools output structured data accessible to downstream workflow events via data.* paths.

Tool Key Output Fields
List Prefixes data.count, data.data
Get Prefix data.data (prefix object)
Create Prefix data.data (created prefix)
Delete Prefix data.deleted, data.data (deleted prefix)
List IP Addresses data.count, data.data
Get IP Address data.data (address object)
Create IP Address data.data (created address)
Delete IP Address data.deleted, data.data (deleted address)
Available IPs data.prefix, data.count, data.data
List VLANs data.count, data.data
Get VLAN data.data (VLAN object)
Create VLAN data.data (created VLAN)
Delete VLAN data.deleted, data.data (deleted VLAN)
List VRFs data.count, data.data
Get VRF data.data (VRF object)
Create VRF data.data (created VRF)
Delete VRF data.deleted, data.data (deleted VRF)

All tools include data.tool containing the tool identifier.

Dependencies

  • PowerNetbox — auto-installed on first run
  • PowerShell 7.0+
  • NetBox 4.5 instance with API access

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Author

Tim Alderweireldt

  • Plugin: xyOps NetBox IPAM
  • Year: 2026

Version History

v1.3.0 (2026-02-20)

  • Input from Previous Job support for all delete tools (Prefix, Address, VLAN, VRF)

v1.2.0 (2026-02-20)

  • Get by Description tools for IP Addresses, VLANs, and VRFs
  • Get by DNS Name tool for IP Addresses
  • Delete tools for Prefixes, IP Addresses, VLANs, and VRFs
  • Site field on VLAN Create tool

v1.1.0 (2026-02-20)

  • Input from Previous Job support for all create tools
  • All numeric ID fields now use number variant for proper UI input

v1.0.0 (2026-02-20)

  • Initial release — extracted IPAM module from xyOps-Netbox into standalone plugin
  • 20 granular tools with operation-specific fields
  • Smart object resolution for Create Prefix
  • Auto-create VLAN option when creating prefixes
  • CSV and Markdown export for all list operations
  • Automatic PowerNetbox module installation on first run

Need help? Open an issue on GitHub or contact the author.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.3.0 Latest
Feb 20, 2026

Packages

 
 
 

Contributors

Languages