feat(skills): add NetBox skill for network infrastructure management
Adds a new skill for interacting with NetBox REST API: - Search/list IP addresses (by address, DNS name, device) - Search/list devices (by name, site, role, serial) - Search/list prefixes (by network, site, parent) - Get IP availability in prefixes - Reserve/create IP addresses (single or batch) - Update and delete IP addresses - List VLANs, VMs, sites, racks, interfaces - Comprehensive filtering and pagination examples Uses curl + jq for API interactions, no additional dependencies required.
This commit is contained in:
Daan
parent
6af205a13a
commit
0405b8db06
302
skills/netbox/SKILL.md
Normal file
302
skills/netbox/SKILL.md
Normal file
@ -0,0 +1,302 @@
|
||||
---
|
||||
name: netbox
|
||||
description: Query and manage network infrastructure using the NetBox REST API. Search devices, IP addresses, prefixes, and manage IP allocations.
|
||||
homepage: https://docs.netbox.dev/en/stable/
|
||||
metadata: {"openclaw":{"emoji":"🌐","requires":{"bins":["curl","jq"],"env":["NETBOX_URL","NETBOX_TOKEN"]}}}
|
||||
---
|
||||
|
||||
# NetBox Skill
|
||||
|
||||
Query and manage network infrastructure using the NetBox REST API.
|
||||
|
||||
## Setup
|
||||
|
||||
Set environment variables:
|
||||
```bash
|
||||
export NETBOX_URL="http://netbox.example.com:8080"
|
||||
export NETBOX_TOKEN="your-api-token"
|
||||
```
|
||||
|
||||
## Common Variables
|
||||
|
||||
All commands use these headers:
|
||||
```bash
|
||||
AUTH="Authorization: Token $NETBOX_TOKEN"
|
||||
CT="Content-Type: application/json"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## IPAM Operations
|
||||
|
||||
### Search IP Addresses
|
||||
|
||||
Search by address:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?address=10.0.0.1" | jq '.results[] | {id, address, status: .status.value, dns_name, description}'
|
||||
```
|
||||
|
||||
Search by partial address (contains):
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?address__ic=10.0.0" | jq '.results[] | {id, address, status: .status.value}'
|
||||
```
|
||||
|
||||
Search by DNS name:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?dns_name__ic=myserver" | jq '.results[] | {id, address, dns_name}'
|
||||
```
|
||||
|
||||
List IPs assigned to a device:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?device=mydevice" | jq '.results[] | {address, interface: .assigned_object.name}'
|
||||
```
|
||||
|
||||
### Search Prefixes
|
||||
|
||||
List all prefixes:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?limit=50" | jq '.results[] | {id, prefix, status: .status.value, site: .site.name, vlan: .vlan.vid}'
|
||||
```
|
||||
|
||||
Search prefix by network:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq '.results[] | {id, prefix, status: .status.value, description}'
|
||||
```
|
||||
|
||||
Search prefixes containing an IP:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?contains=10.0.0.50" | jq '.results[] | {prefix, site: .site.name}'
|
||||
```
|
||||
|
||||
Search prefixes within a parent:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?within=10.0.0.0/16" | jq '.results[] | {prefix, status: .status.value}'
|
||||
```
|
||||
|
||||
Search by site:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?site=dc1" | jq '.results[] | {prefix, vlan: .vlan.vid, role: .role.name}'
|
||||
```
|
||||
|
||||
### Get IP Availability in a Prefix
|
||||
|
||||
Get available IPs in a prefix (requires prefix ID):
|
||||
```bash
|
||||
# First get the prefix ID
|
||||
PREFIX_ID=$(curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq -r '.results[0].id')
|
||||
|
||||
# Then get available IPs
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/$PREFIX_ID/available-ips/" | jq '.[0:10]'
|
||||
```
|
||||
|
||||
Get prefix utilization:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq '.results[] | {prefix, description, children: .children, utilization: "\(.mark_utilized)%"}'
|
||||
```
|
||||
|
||||
### Create/Reserve IP Address
|
||||
|
||||
Create a new IP address:
|
||||
```bash
|
||||
curl -s -X POST -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/ip-addresses/" \
|
||||
-d '{
|
||||
"address": "10.0.0.100/24",
|
||||
"status": "active",
|
||||
"dns_name": "myserver.example.com",
|
||||
"description": "Web server primary IP"
|
||||
}' | jq '{id, address, status: .status.value}'
|
||||
```
|
||||
|
||||
Reserve next available IP in a prefix:
|
||||
```bash
|
||||
# First get the prefix ID
|
||||
PREFIX_ID=$(curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq -r '.results[0].id')
|
||||
|
||||
# Create next available IP
|
||||
curl -s -X POST -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/prefixes/$PREFIX_ID/available-ips/" \
|
||||
-d '{
|
||||
"description": "Reserved for new server",
|
||||
"status": "reserved"
|
||||
}' | jq '{id, address, status: .status.value}'
|
||||
```
|
||||
|
||||
Reserve multiple IPs at once:
|
||||
```bash
|
||||
curl -s -X POST -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/prefixes/$PREFIX_ID/available-ips/" \
|
||||
-d '[
|
||||
{"description": "Server 1", "status": "reserved"},
|
||||
{"description": "Server 2", "status": "reserved"}
|
||||
]' | jq '.[] | {address, description}'
|
||||
```
|
||||
|
||||
### Update IP Address
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/ip-addresses/{id}/" \
|
||||
-d '{
|
||||
"status": "active",
|
||||
"dns_name": "newname.example.com"
|
||||
}' | jq '{id, address, status: .status.value, dns_name}'
|
||||
```
|
||||
|
||||
### Delete IP Address
|
||||
|
||||
```bash
|
||||
curl -s -X DELETE -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/{id}/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DCIM Operations
|
||||
|
||||
### Search Devices
|
||||
|
||||
List devices:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?limit=50" | jq '.results[] | {id, name, status: .status.value, site: .site.name, role: .role.name}'
|
||||
```
|
||||
|
||||
Search by name:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?name__ic=server" | jq '.results[] | {id, name, status: .status.value, primary_ip: .primary_ip.address}'
|
||||
```
|
||||
|
||||
Search by site:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?site=dc1" | jq '.results[] | {name, rack: .rack.name, position: .position}'
|
||||
```
|
||||
|
||||
Search by role:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?role=server" | jq '.results[] | {name, device_type: .device_type.model}'
|
||||
```
|
||||
|
||||
Search by serial number:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?serial=ABC123" | jq '.results[] | {name, serial, asset_tag}'
|
||||
```
|
||||
|
||||
Get device details:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/{id}/" | jq '{name, status: .status.value, site: .site.name, rack: .rack.name, position, primary_ip4: .primary_ip4.address, primary_ip6: .primary_ip6.address}'
|
||||
```
|
||||
|
||||
### List Device Interfaces
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/interfaces/?device=mydevice" | jq '.results[] | {id, name, type: .type.value, enabled, mac_address}'
|
||||
```
|
||||
|
||||
### Search Sites
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/sites/" | jq '.results[] | {id, name, slug, status: .status.value, region: .region.name}'
|
||||
```
|
||||
|
||||
### Search Racks
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/racks/?site=dc1" | jq '.results[] | {id, name, u_height, status: .status.value}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VLANs
|
||||
|
||||
### List VLANs
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/vlans/" | jq '.results[] | {id, vid, name, status: .status.value, site: .site.name}'
|
||||
```
|
||||
|
||||
### Search VLAN by ID
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/vlans/?vid=100" | jq '.results[] | {vid, name, description}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Virtualization
|
||||
|
||||
### List Virtual Machines
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/virtualization/virtual-machines/" | jq '.results[] | {id, name, status: .status.value, cluster: .cluster.name, vcpus, memory, disk}'
|
||||
```
|
||||
|
||||
### Search VM by name
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/virtualization/virtual-machines/?name__ic=web" | jq '.results[] | {name, primary_ip: .primary_ip.address}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
### Pagination
|
||||
|
||||
NetBox returns paginated results. Use `limit` and `offset`:
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?limit=100&offset=200" | jq '.results'
|
||||
```
|
||||
|
||||
### Filtering
|
||||
|
||||
Common filter suffixes:
|
||||
- `__ic` - case-insensitive contains
|
||||
- `__nic` - case-insensitive not contains
|
||||
- `__ie` - case-insensitive exact
|
||||
- `__isw` - case-insensitive starts with
|
||||
- `__iew` - case-insensitive ends with
|
||||
|
||||
### Status Values
|
||||
|
||||
Common status values:
|
||||
- IP addresses: `active`, `reserved`, `deprecated`, `dhcp`, `slaac`
|
||||
- Devices: `active`, `planned`, `staged`, `failed`, `offline`, `decommissioning`, `inventory`
|
||||
- Prefixes: `active`, `reserved`, `deprecated`, `container`
|
||||
|
||||
### Get All Results (scripting)
|
||||
|
||||
```bash
|
||||
# Loop through paginated results
|
||||
OFFSET=0
|
||||
LIMIT=100
|
||||
while true; do
|
||||
RESULT=$(curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?limit=$LIMIT&offset=$OFFSET")
|
||||
echo "$RESULT" | jq -r '.results[] | .name'
|
||||
NEXT=$(echo "$RESULT" | jq -r '.next')
|
||||
[ "$NEXT" = "null" ] && break
|
||||
OFFSET=$((OFFSET + LIMIT))
|
||||
done
|
||||
```
|
||||
|
||||
### Export to CSV
|
||||
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?limit=1000" | \
|
||||
jq -r '.results[] | [.address, .dns_name, .status.value, .description] | @csv'
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Find which device has a specific IP
|
||||
```bash
|
||||
IP="10.0.0.50"
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?address=$IP" | \
|
||||
jq '.results[] | {address, device: .assigned_object.device.name, interface: .assigned_object.name}'
|
||||
```
|
||||
|
||||
### List all IPs in a subnet with their assignments
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?parent=10.0.0.0/24" | \
|
||||
jq '.results[] | {address, dns_name, device: .assigned_object.device.name // "unassigned"}'
|
||||
```
|
||||
|
||||
### Get rack utilization
|
||||
```bash
|
||||
curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/racks/?site=dc1" | \
|
||||
jq '.results[] | {name, u_height, utilized: "\(.u_utilized // 0)/\(.u_height)"}'
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user