. Call the
142 | # common function to parse the interface into separate type/id for use in
143 | # subsequent tasks.
144 | interface_type, interface_id = parse_interface_name(interface_data.name)
145 |
146 | # Get the "primary_ip" of the device to configure. This is where RESTCONF
147 | # requests will be send.
148 | mgmt_ip = format(ipaddress.IPv4Interface(interface_data.device.primary_ip).ip)
149 |
150 | # The variable "g" is imported by Flask and represents a global variable which
151 | # is accessible by any during the request. Every function in this module
152 | # will use the same base URL, which includes the interface identifier.
153 | g.baseurl = f"https://{mgmt_ip}/restconf/data/Cisco-IOS-XE-native:native/interface/" \
154 | f"{interface_type}={interface_id}"
155 |
156 | print(f"Configuring interface '{interface_data.name}' on device"
157 | f" '{interface_data.device.name}'...")
158 |
159 | # If this is the management interface, don't change it! Nothing worse than
160 | # killing your session because you moved the management interface in the
161 | # middle of a configuration task :-)
162 | if interface_data.mgmt_only:
163 | print("\tManagement interface, no changes will be performed...")
164 | else:
165 | # Magic happens here - set the status, description, and MTU.
166 | set_interface_status(netbox_interface_object=interface_data)
167 | update_interface_description(netbox_interface_object=interface_data)
168 | update_interface_mtu(netbox_interface_object=interface_data)
169 |
170 | # Return a generic 204 response to the NetBox webhook
171 | return Response(status=204)
172 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # NetBox Webhook Automation
2 |
3 | As demonstrated in an episode of Cisco DevNet Snack Minute on YouTube!
4 |
5 | This is a demonstration of using Python to receive and process webhook data generated by NetBox. Initial use cases:
6 |
7 | - Interfaces:
8 | - Add / change / remove interface description
9 | - Change interface MTU
10 | - Change interface state (shutdown / no shutdown)
11 | - IPAM:
12 | - Add / change / remove IPv4 or IPv6 addresses on interfaces
13 |
14 | ## Requirements:
15 | - Python 3.8 or higher (this code was developed using Python 3.9)
16 | - Physical or virtual Cisco IOS XE device with RESTCONF enabled
17 | - Code tested against a Cisco Catalyst 8000V Edge (virtual) device running IOS XE 17.06.03a
18 | - Running NetBox instance provisioned with an administrative API token
19 |
20 | ## Getting started with this application:
21 |
22 | ### Clone the repository and create a Python virtual environment:
23 |
24 | 1. Use the ```git clone``` command to create a local repository containing the source code:
25 |
26 | $ git clone https://github.com/CiscoLearning/netbox-webhook-automation.git
27 | Cloning into 'netbox-webhook-automation'...
28 |
29 |
30 | 2. Once the repository has been cloned to the local machine, create a new Python virtual environment using the desired Python interpreter. In this example, Python 3.9 will be used:
31 |
32 |
33 | $ python3.9 -m venv venv
34 | $ source venv/bin/activate
35 | (venv) $
36 |
37 |
38 | 3. After the virtual environment has been activated, it's recommended to update the ```pip```, ```setuptools```, and ```wheel``` packages to the latest version. Use the ```pip install --upgrade``` command with the list of packages to upgrade:
39 |
40 |
41 | (venv) $ pip install --upgrade pip setuptools wheel
42 | Requirement already satisfied: pip in ./venv/lib/python3.9/site-packages (21.1.1)
43 | Collecting pip
44 | Using cached pip-22.2.2-py3-none-any.whl (2.0 MB)
45 | Requirement already satisfied: setuptools in ./venv/lib/python3.9/site-packages (56.0.0)
46 | Collecting setuptools
47 | Using cached setuptools-65.3.0-py3-none-any.whl (1.2 MB)
48 | Collecting wheel
49 | Using cached wheel-0.37.1-py2.py3-none-any.whl (35 kB)
50 | Installing collected packages: wheel, setuptools, pip
51 | Attempting uninstall: setuptools
52 | Found existing installation: setuptools 56.0.0
53 | Uninstalling setuptools-56.0.0:
54 | Successfully uninstalled setuptools-56.0.0
55 | Attempting uninstall: pip
56 | Found existing installation: pip 21.1.1
57 | Uninstalling pip-21.1.1:
58 | Successfully uninstalled pip-21.1.1
59 | Successfully installed pip-22.2.2 setuptools-65.3.0 wheel-0.37.1
60 |
61 |
62 | 4. Now install the prerequisite packages for this application using the ```pip install``` command. Add the ```-r``` option to instruct ```pip``` that requirements will be loaded from a file, and supply the path to this application's ```requirements.txt``` file:
63 |
64 |
65 | (venv) $ pip install -r netbox-webhook-automation/requirements.txt
66 | Collecting Flask~=2.2.2
67 | Using cached Flask-2.2.2-py3-none-any.whl (101 kB)
68 | Collecting pynetbox~=6.6.2
69 | Using cached pynetbox-6.6.2-py3-none-any.whl (32 kB)
70 | ... (output truncated) ...
71 | Successfully installed Flask-2.2.2 Jinja2-3.1.2 MarkupSafe-2.1.1 Werkzeug-2.2.2 certifi-2022.9.14
72 | charset-normalizer-2.1.1 click-8.1.3 idna-3.4 importlib-metadata-4.12.0 itsdangerous-2.1.2
73 | pynetbox-6.6.2 requests-2.28.1 requests-toolbelt-0.9.1 six-1.16.0 urllib3-1.26.12 zipp-3.8.1
74 |
75 |
76 | ### Configure the application:
77 |
78 | 1. Change to the ```netbox-webhook-automation/webhook_listener``` directory:
79 |
80 | (venv) $ cd netbox-webhook-automation/webhook_listener
81 |
82 |
83 | 2. Copy the ```credentials.py.dist``` file to ```credentials.py```:
84 |
85 | (venv) $ cp credentials.py.dist credentials.py
86 |
87 |
88 | 3. Use your editor of choice to open the ```credentials.py``` file. Change the NetBox URL and API token to match your environment, and define credentials for the destination virtual device(s). *Note: as this application is for demonstration purposes, only a single credential will be used. The user associated with this credential must have privilege level 15 on the remote device(s).*
89 |
90 | ```python
91 | NETBOX_URL = "https://netbox"
92 | NETBOX_TOKEN = "0123456789abcdef0123456789abcdef01234567"
93 | DEVICE_USERNAME = "developer"
94 | DEVICE_PASSWORD = "1234QWer"
95 | ```
96 |
97 | 4. The default port for the Flask webhook listener is ```19703```. If you wish to change this, open the ```main.py``` file in your editor and modify the ```app.run``` parameters in the main section:
98 |
99 |
100 | if __name__ == "__main__":
101 | app.debug = True
102 | app.run(host="0.0.0.0", port=19703)
103 |
104 |
105 | ### Start the webhook listener!
106 | 1. Launch the ```main.py``` file using ```python```. The flask app will start and some output will be displayed:
107 |
108 | (venv) $ python main.py
109 | * Serving Flask app 'main'
110 | * Debug mode: on
111 | WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
112 | * Running on all addresses (0.0.0.0)
113 | * Running on http://127.0.0.1:19703
114 | * Running on http://192.168.1.2:19703
115 | Press CTRL+C to quit
116 | * Restarting with stat
117 | * Debugger is active!
118 | * Debugger PIN: 123-456-789
119 |
120 |
121 | ## Configure NetBox webhooks
122 | ### Create a webhook for interface updates:
123 | 1. In the NetBox interface left menu bar, click **Other** and then **Webhooks** to enter the webhook configuration context:
124 |
125 | 
126 |
127 | 2. On the Webhooks configuration page, click **+ Add** in the top right corner to create a new webhook.
128 |
129 | 3. Complete the following fields to add a new webhook:
130 | - Name: Provide a useful name such as **interface-webhook**
131 | - Content types: **DCIM > interface**
132 | - Enabled: **checked** to enable the webhook.
133 | - Events: **Creations**, **Updates**, and **Deletions**
134 | - URL: Enter the IP or hostname of the system running the webhook listener, the port, and the default path for the interface listener which is ```/api/update-interface```. An example URL would be **http://192.168.1.2:19703/api/update-interface**
135 | - HTTP method: **POST**
136 | - HTTP content type: **application/json**
137 | - Additional headers: None (leave empty)
138 | - Body template: None (leave empty)
139 | - Secret: None (leave empty)
140 | - Conditions: null (do not change the default)
141 | - SSL verification: irrelevant (the application is not configured to use TLS)
142 | - CA File path: None (leave empty)
143 |
144 | 4. When completed, your configuration should appear similar to the following:
145 | 
146 |
147 | ### Create a webhook for IPAM updates:
148 | 1. Return to the Webhook configuration screen (**Other** -> **Webhooks**)
149 |
150 | 2. Click **+ Add** to create another webhook
151 |
152 | 3. Add a description name and follow the same steps as for the interface webhook, but note the following important differences:
153 | - Content types: **IPAM > IP address**
154 | - URL: IP/Port of the receiver but the path is **/api/update-address**
155 |
156 | 4. When complete, your webhook configuration for the IP address should appear as follows:
157 | 
158 |
159 | ## Test it!
160 | When you create, update, or delete an IP address or an interface in NetBox, a webhook should be created and your Flask application should display some output. It might not do anything at first, which is OK!
161 |
162 | To ensure that something useful happens, verify that you have a device configured in NetBox to represent your virtual / test device and that there is a **Primary IPv4** address associated with the device. Verify that there is at least one interface associated with this device that is **not** marked as "management only."
163 |
164 | If successful, you should see output similar to the following when updating an interface:
165 |
166 | ```text
167 | Configuring interface 'GigabitEthernet3' on device 'access-rtr01'...
168 | Enabling interface.
169 | Target URL: https://198.18.1.157/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=3/shutdown
170 | Interface GigabitEthernet3 is already enabled!
171 | Response: 404 (Not Found)
172 |
173 | Setting interface description to 'Baconrific!!'
174 | URL: https://198.18.1.157/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=3/description
175 | Payload:
176 | {'description': 'Baconrific!!'}
177 | Response: 201 (Created)
178 |
179 | Setting interface MTU to '1500'
180 | URL: https://198.18.1.157/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=3/mtu
181 | Payload:
182 | {'mtu': 1500}
183 | Response: 201 (Created)
184 |
185 | 198.18.1.146 - - [19/Sep/2022 14:42:16] "POST /api/update-interface HTTP/1.1" 204 -
186 | ```
187 |
188 | And output similar to the following when updating an IP address. In this example, an address is being changed from interface GigabitEthernet3 on access-rtr01 to GigabitEthernet3 on access-rtr02:
189 | ```text
190 | Updating IP address...
191 | Removing address 192.168.222.222/24 from interface 'GigabitEthernet3' on device 'access-rtr01'...
192 | Response: 204 (No Content)
193 | Assigning address 192.168.222.222/24 to interface 'GigabitEthernet3' on device 'access-rtr02'...
194 | Sending payload:
195 | {'primary': {'address': '192.168.222.222', 'mask': '255.255.255.0'}}
196 | To URL:
197 | https://198.18.1.158/restconf/data/Cisco-IOS-XE-native:native/interface/GigabitEthernet=3/ip/address/primary
198 | Response: 204 (No Content)
199 | 198.18.1.146 - - [19/Sep/2022 15:05:29] "POST /api/update-address HTTP/1.1" 204 -
200 | ```
201 |
202 | ## Have fun and keep coding!
203 | Now that you've seen how to automate network device configuration with NetBox webhooks, keep learning and experimenting!
204 |
205 | See if you can add more functionality or create your own webhook listeners for other events - perhaps for VRF definitions or subinterfaces. Your imagination is the only limit!
206 |
207 | ### Additional resources:
208 | - [NetBox-Community GitHub repository](https://github.com/netbox-community/netbox) contains the source for NetBox as well as project information
209 | - [NetBox documentation site](https://docs.netbox.dev/en/stable/) contains everything NetBox-related - from downloading to advanced configuration.
210 | - [Python Flask documentation](https://flask.palletsprojects.com/en/2.2.x/) - Flask is used as the API listener in this project. The documentation site includes quickstart guides, reference material, and code examples.
211 | - [pynetbox - Python API client library for NetBox](https://pynetbox.readthedocs.io/en/latest/) has many examples of using pynetbox to interact with NetBox using Python.
212 | - [Cisco YANG Suite](https://developer.cisco.com/yangsuite/) - Browse YANG models interactively! If you're getting started with YANG models, this tool is *very* useful.
213 |
214 | ---
215 | Original development by Palmer Sample, September 2022. Distributed under the MIT license.
216 |
217 | Please send questions, comments, or suggestions to [psample@cisco.com](mailto:psample@cisco.com?subject=[GitHub.com]%20NetBox%20Webhook%20Automation%20Repository%20Inquiry)
--------------------------------------------------------------------------------
/webhook_listener/ipam_api.py:
--------------------------------------------------------------------------------
1 | """
2 | Functions used when a Webhook request is received for Netbox IPAM (IP Address
3 | Management) objects
4 | """
5 | # ipaddress is needed to parse incoming IP data
6 | import ipaddress
7 |
8 | # "g" represents a Flask app global variable which can be used throughout the
9 | # application.
10 | # "request" represents the Flask received data
11 | # "Response" is an object that we can use to return an HTTP status code to the
12 | # NetBox calling webhook.
13 | from flask import g, request, Response
14 |
15 | # Import the configured NetBox API object and the RESTCONF session object from
16 | # config.py
17 | from config import netbox_api, restconf_session
18 |
19 | # ... And, import the function to parse an interface name into a type and ID
20 | from common_functions import parse_interface_name
21 |
22 |
23 | def configure_interface_ipv4_address(ip_address):
24 | """
25 | Configure an interface's primary IPv4 address.
26 |
27 | :param ip_address: IPv4 address in CIDR notation (IP/Prefix)
28 | :return: Flask HTTP/204 Response object
29 | """
30 |
31 | # Convert the CIDR notation into an IPv4Interface object, allowing easy
32 | # parsing of the address components
33 | ip4_address = format(ipaddress.IPv4Interface(ip_address).ip)
34 | ip4_netmask = format(ipaddress.IPv4Interface(ip_address).netmask)
35 |
36 | # Build the target URL from the Flask "g" global variable containing the
37 | # base URL of the device and interface to be modified
38 | url = f"{g.base_url}/ip/address/primary"
39 |
40 | payload = {
41 | "primary": {
42 | "address": ip4_address,
43 | "mask": ip4_netmask
44 | }
45 | }
46 |
47 | print(f"Sending payload:\n\t{payload}\nTo URL:\n\t{url}")
48 | response = restconf_session.patch(url=url, json=payload)
49 | print(f"\tResponse: {response.status_code} ({response.reason})")
50 |
51 |
52 | def configure_interface_ipv6_address(ip_address):
53 | """
54 | Because an interface may have multiple IPv6 addresses assigned, add the
55 | desired IPv6 address to the list of addresses on the target interface.
56 |
57 | :param ip_address: IPv6 address with prefix
58 | :return: Flask HTTP/204 Response object
59 | """
60 | url = f"{g.base_url}/ipv6/address/prefix-list"
61 |
62 | payload = {
63 | "prefix-list": [
64 | {
65 | "prefix": ip_address
66 | }
67 | ]
68 | }
69 | print(f"Sending payload:\n\t{payload}\nTo URL:\n\t{url}")
70 | response = restconf_session.patch(url=url, json=payload)
71 | print(f"\tResponse: {response.status_code} ({response.reason})")
72 |
73 |
74 | def configure_ip_address(netbox_interface_object, ip_address, address_family):
75 | """
76 | Main function to be called if an IP address will be configured on an
77 | interface. The address family (4/6) will be used to determine which
78 | function must be called to perform the actual configuration. Almost
79 | all other relevant details such as the device management IP can be
80 | gleaned from the NetBox interface object reference.
81 |
82 | :param netbox_interface_object: pynetbox interface object reference
83 | :param ip_address: string - IPv4 or IPv6 address
84 | :param address_family: int - 4 or 6 to match the IP family
85 | :return: None
86 | """
87 |
88 | # Parse the interface type and ID for RESTCONF URL generation
89 | interface_type, interface_id = parse_interface_name(netbox_interface_object.name)
90 |
91 | # Grab the management IP from the pynetbox interface object. Note that this
92 | # is targeting the IPv4 primary IP address, so will be wrapped into an
93 | # ipaddress.IPv4Interface object for easy extraction of the address
94 | # component
95 | mgmt_ip = format(ipaddress.IPv4Interface(netbox_interface_object.device.primary_ip).ip)
96 |
97 | # Generate the base URL for RESTCONF requests against the desired interface
98 | # Note that the Flask "g" global variable is used here to store the URL.
99 | g.base_url = f"https://{mgmt_ip}/restconf/data/Cisco-IOS-XE-native:native/interface/" \
100 | f"{interface_type}={interface_id}"
101 |
102 | print(f"Assigning address {ip_address} "
103 | f"to interface '{netbox_interface_object.name}' "
104 | f"on device '{netbox_interface_object.device.name}'...")
105 |
106 | # Configure the address using the matching AF function
107 | if address_family == 6:
108 | configure_interface_ipv6_address(ip_address)
109 | else:
110 | configure_interface_ipv4_address(ip_address)
111 |
112 |
113 | def unconfigure_interface_ipv4_address():
114 | """
115 | Delete the primary IPv4 address from an interface. No parameters are needed
116 | as an HTTP DELETE is performed against the primary address RESTCONF
117 | endpoint for the device interface
118 |
119 | :return: None
120 | """
121 | url = f"{g.base_url}/ip/address/primary"
122 |
123 | response = restconf_session.delete(url=url)
124 | print(f"\tResponse: {response.status_code} ({response.reason})")
125 |
126 |
127 | def unconfigure_interface_ipv6_address(ip_address):
128 | """
129 | Remove the provided IPv6 address from the list of IPv6 prefixes on an
130 | interface.
131 |
132 | :param ip_address: string - IPv6 address to remove from the interface
133 | :return: None
134 | """
135 | # Convert the "/" in the IPv6 address representation to a URL-friendly
136 | # "%2F" to avoid it being interpreted as part of the RESTCONF target
137 | # URL.
138 | formatted_address = format(ip_address).replace("/", "%2F")
139 | url = f"{g.base_url}/ipv6/address/prefix-list={formatted_address}"
140 | response = restconf_session.delete(url=url)
141 |
142 | print(f"\tResponse: {response.status_code} ({response.reason})")
143 |
144 |
145 | def unconfigure_ip_address(netbox_interface_object, ip_address, address_family):
146 | """
147 | Primary function to remove an address from an interface. Depending on the
148 | address family, call the appropriate function to unconfigure the
149 | v4 or v6 address.
150 |
151 | :param netbox_interface_object: pynetbox interface object reference
152 | :param ip_address: string - IP address in CIDR notation
153 | :param address_family: int - IP address family (4|6)
154 | :return: None
155 | """
156 |
157 | interface_type, interface_id = parse_interface_name(netbox_interface_object.name)
158 | mgmt_ip = format(ipaddress.IPv4Interface(netbox_interface_object.device.primary_ip).ip)
159 |
160 | g.base_url = f"https://{mgmt_ip}/restconf/data/Cisco-IOS-XE-native:native/interface/" \
161 | f"{interface_type}={interface_id}"
162 |
163 | print(f"Removing address {ip_address} "
164 | f"from interface '{netbox_interface_object.name}' "
165 | f"on device '{netbox_interface_object.device.name}'...")
166 |
167 | if address_family == 6:
168 | unconfigure_interface_ipv6_address(ip_address)
169 | else:
170 | unconfigure_interface_ipv4_address()
171 |
172 |
173 | def update_ip_address(netbox_interface_object, snapshot_json, ip_address, address_family):
174 | """
175 | If an IPAM webhook is received indicating the address has been updated and
176 | there is a snapshot key in the webhook payload, it's possible that the
177 | address was previously configured on a different interface and/or a
178 | different device.
179 |
180 | Parse the snapshot payload, check if the target interface/device matches
181 | the "prechange" snapshot. If so, only configure the address on the target
182 | interface.
183 |
184 | If the presnapshot data differs from the target interface, unconfigure the
185 | previously-configured interface before configuring the address on the
186 | target.
187 |
188 | :param netbox_interface_object: pynetbox interface object reference
189 | :param snapshot_json: Contents of the webhook "snapshot" payload
190 | :param ip_address: string - IP address in CIDR notation
191 | :param address_family: int - IP address family (4|6)
192 | :return: None
193 | """
194 | print("Updating IP address...")
195 |
196 | # If the snapshot_json is not None, the snapshot must be compared to the
197 | # webhook data contained in the pynetbox interface object reference.
198 | if snapshot_json:
199 | try:
200 | old_interface_id = snapshot_json["prechange"]["assigned_object_id"]
201 |
202 | if old_interface_id != netbox_interface_object.id:
203 | # Old assignment is on a different interface. Unconfigure
204 | # before configuring the new device.
205 | old_interface_data = netbox_api.dcim.interfaces.get(old_interface_id)
206 | if not old_interface_data.mgmt_only:
207 | unconfigure_ip_address(netbox_interface_object=old_interface_data,
208 | ip_address=ip_address,
209 | address_family=address_family)
210 | except AttributeError:
211 | print("Address not previously assigned")
212 | except ValueError:
213 | print("Address not previously assigned")
214 |
215 | # Regardless of the previous address assignment, it is time to configure
216 | # the address on the target interface...
217 | configure_ip_address(netbox_interface_object=netbox_interface_object,
218 | ip_address=ip_address,
219 | address_family=address_family)
220 |
221 |
222 | def manage_interface_ip_address():
223 | """
224 | Function for the Webhook listener at the IPAM configuration path.
225 |
226 | When an IPAM webhook is received, obtain the IP address and address
227 | family from the payload data. If there is an assigned interface for the
228 | IP address, determine if it's a new address, an existing address to be
229 | deleted, or an existing address to be updated and call the appropriate
230 | function to handle the requested task.
231 |
232 | Note: if the address is assigned to the designated device management
233 | interface, no action will be performed.
234 |
235 | :return: A generic HTTP 204 response via Flask Response object
236 | """
237 |
238 | ip_address = request.json["data"]["address"]
239 | address_family = request.json["data"]["family"]["value"]
240 |
241 | if assigned_interface := request.json["data"].get("assigned_object_id"):
242 | # There is an interface assigned to this object. Get the interface details
243 | # and determine what type of request this is (created, updated, deleted)
244 | # to perform the expected action.
245 |
246 | assigned_interface_details = netbox_api.dcim.interfaces.get(assigned_interface)
247 |
248 | if assigned_interface_details.mgmt_only:
249 | print("\tManagement interface, no changes will be performed...")
250 | else:
251 |
252 | if request.json["event"] == "deleted":
253 | # The IP address has been deleted from NetBox. Unconfigure it from the
254 | # currently-assigned interface.
255 |
256 | unconfigure_ip_address(netbox_interface_object=assigned_interface_details,
257 | ip_address=ip_address,
258 | address_family=address_family)
259 |
260 | elif request.json["event"] == "created":
261 | # This is a newly-created IP address. Configure it on the assigned
262 | # interface.
263 | configure_ip_address(netbox_interface_object=assigned_interface_details,
264 | ip_address=ip_address,
265 | address_family=address_family)
266 |
267 | elif request.json["event"] == "updated":
268 | # Details of the IP have changed. Determine if it was previously
269 | # assigned to a different device / interface. If so, unconfigure
270 | # that interface first and configure on the new one.
271 | update_ip_address(netbox_interface_object=assigned_interface_details,
272 | snapshot_json=request.json.get("snapshots"),
273 | ip_address=ip_address,
274 | address_family=address_family)
275 |
276 | return Response(status=204)
277 |
--------------------------------------------------------------------------------