Package: netbox-lists
netbox-listsNetBox Lists generates list of IPs and prefixes from NetBox data.
While this can be accomplished using the existing NetBox API, this plugin
saves the user from having to manipulate the data to get just the IPs/prefixes. Lists endpoints (mostly) share the same filters as the builtin NetBox endpoints, making querying easy.Lists are returned as JSON arrays or as plain text. This means that firewalls
can use NetBox as a source for dynamic address lists, such as Palo Alto's External Dynamic Lists, Fortinet's External Block List (Threat Feed) or
pfSesnse/OPNSense's firewall aliases.This plugin also features endpoints for devices/VMs/IP addresses compatible with Prometheus' http_sd.This plugin supports NetBox v3.0, v3.1, v3.2, v3.3, and v3.4.FeaturesSupports NetBox's object permissions.AnsibleandTerraformintegrations.Prometheus http_sd endpoint for devices/vms.API documented using OpenAPI.Supports standard NetBox object filters.Address family specific prefix length filters.JSON and plain text output formats.DocumentationAPI documentation can be found in NetBox's builtin API docs (/api/docs/).The format of the response can be controlled by theAcceptheader (application/jsonortext/plain)
or by the appendingformat=(text|json)to the URL.This plugin uses NetBox's object permissions. Make sure users have the appropriate permissions.Summarization is enabled by default.When summarization is enabled, all IP addresses will be returned in CIDR format regardless of theas_cidrsetting.InstallationAddnetbox-liststolocal_requirements.txt.Enable the plugin inconfiguration.pyPLUGINS=["netbox_lists"]Runupgrade.shPlugin ConfigPLUGINS_CONFIG={"netbox_lists":{# Return IPs as /32 or /128.# Default: True"as_cidr":True,# For services without any explicit IPs configured,# use the primary IPs of the associated device/vm.# Default: True"service_primary_ips":True,# Summarize responses"summarize":True,# A list of attributes for the devices-vms-attrs endpoint## Attributes will be joined with "__" in the returned object.# eg. ("primary_ip", "address") -> primary_ip__address"devices_vms_attrs":[("id",),("name",),# `role` will automatically be converted to `device_role` for devices.# Don't use `device_role`.("role","slug"),("platform","slug"),("primary_ip","address"),("tags",),],# Tuple/list of attributes to use for Prometheus VM SD target. Defaults are shown.## If all attributes return None, the device's name will be used."prometheus_vm_sd_target":(# For a custom field# ("cf", "fqdn"),# If this returns none, try Name.("primary_ip","address","ip"),("name",),# not necessary),# Dictionary of label to VM attribute for Prometheus VM SD. Defaults are shown."prometheus_vm_sd_labels":{"__meta_netbox_id":("id",),"__meta_netbox_name":("name",),"__meta_netbox_status":("status",),"__meta_netbox_cluster_name":("cluster","name"),"__meta_netbox_site_name":("site","name"),"__meta_netbox_role_name":("role","name"),"__meta_netbox_platform_name":("platform","name"),"__meta_netbox_primary_ip":("primary_ip","address","ip"),"__meta_netbox_primary_ip4":("primary_ip4","address","ip"),"__meta_netbox_primary_ip6":("primary_ip6","address","ip"),# A custom field. Will be an empty string if None.# "__meta_netbox_fqdn": ("cf", "fqdn"),},# Tuple/list of attributes to use for Prometheus device SD target. Defaults are shown.## If all attributes return None, the device's name will be used."prometheus_device_sd_target":(# For a custom field# ("cf", "fqdn"),("primary_ip","address","ip"),("name",),# not necessary),# Dictionary of label to device attribute for Prometheus device SD. Defaults are shown."prometheus_device_sd_labels":{"__meta_netbox_id":("id",),"__meta_netbox_name":("name",),"__meta_netbox_status":("status",),"__meta_netbox_site_name":("site","name"),"__meta_netbox_platform_name":("platform","name"),"__meta_netbox_primary_ip":("primary_ip","address","ip"),"__meta_netbox_primary_ip4":("primary_ip4","address","ip"),"__meta_netbox_primary_ip6":("primary_ip6","address","ip"),"__meta_netbox_serial":("serial",),# A custom field. Will be an empty string if None.# "__meta_netbox_fqdn": ("cf", "fqdn"),},# Tuple/list of attributes to use for Prometheus IP address SD target. Defaults are shown.## If all attributes return None, the address in CIDR format will be used."prometheus_ipaddress_sd_target":(("address","ip"),),# Dictionary of label to IP address attribute for Prometheus ip address SD. Defaults are shown."prometheus_ipaddress_sd_labels":{"__meta_netbox_id":("id",),"__meta_netbox_role":("role",),"__meta_netbox_dns_name":("dns_name",),"__meta_netbox_status":("status",),# For addresses assigned to interfaces#"__meta_netbox_device": ("assigned_object", "device", "name"),#"__meta_netbox_interface": ("assigned_object", "name"),},}}ExamplesGet all IP addresses for devices with the tagtest.https://netbox.example.com/api/plugins/lists/devices/?tag=testGet all IP addresses for devices with the tagtestin plain text.https://netbox.example.com/api/plugins/lists/devices/?tag=test&format=textGet all IP addresses assigned to services namedNTP.https://netbox.example.com/api/plugins/lists/services/?name=NTPGet all IP addresses assigned to services namedNTPand use the assigned device's primary IPs when no IPs
are explicitly configured on the service.https://netbox.example.com/api/plugins/lists/services/?name=NTP&primary_ips=trueGet all IPv6 addresses for devices with the tagtestin plain text.https://netbox.example.com/api/plugins/lists/devices/?tag=test&family=6Get all prefixes and IPs with the taginternalhttps://netbox.example.com/api/plugins/lists/tags/internal/?ips&prefixesGet all prefixes and IPs with the taginternalwithout summarizationhttps://netbox.example.com/api/plugins/lists/tags/internal/?ips&prefixes&summarize=falseAnsible Usage ExampleUsing thenblists collection:# Build an ACL using all NetBox prefixes with the role 'data'-name:Build ACL 10ansible.builtin.set_fact:acl_10_aces:"{{acl_10_aces|default([])+ace}}"vars:ace:-grant:permitsource:address:"{{item|ansible.utils.ipaddr('network')}}"wildcard_bits:"{{item|ansible.utils.ipaddr('wildcard')}}"loop:"{{q('devon_mar.nblists.list','prefixes',role='data')}}"-name:Ensure ACLs are configuredcisco.ios.ios_acls:config:-afi:ipv4acls:-name:10aces:"{{acl_10_aces}}"Terraform Usage ExampleUsing thenblists provider:data"nblists_list""special"{endpoint="ip-addresses"filter={tag=["special"]}}Oxidized usagesource:default:httphttp:# Devices/VMs with the "oxidized" tagurl:https://netbox.example.com/api/plugins/lists/devices-vms-attrs/?tag=oxidizedscheme:httpssecure:truemap:name:primary_ip__addressmodel:platform__slugheaders:Authorization:Token <netbox token>Prometheus usagehttp_sd_configs:# VMs with the role slug "linux"-url:https://netbox.example.com/api/plugins/lists/prometheus-vms/?role=linuxrefresh_interval:60sauthorization:type:Tokencredentials:mynetboxtoken