Free IPAM Open Source Netbox IP Scanner

I have been looking recently for a better way to manage my IP Addresses in the home lab. With multiple VLANs and constant churn in the home lab, it becomes difficult to manage IP addresses effectively and keep up with which VMs and other devices are provisioned on which IPs. Additionally, finding IPs that are available for use can be difficult to manage without stepping on IPs that may have already been provisioned and possibly no longer alive. Recently, I covered the Netbox tool which is a great IPAM and “source of truth” tool for your network. While “scanning” networks is a bit out of the original intended purpose of Netbox as described in the previous post, there is a great add-on module for Netbox called Netbox scanner that allows scanning your network subnets with nmap and automatically importing these into Netbox. Let’s take a look at free IPAM open source Netbox IP Scanner and see how this tool works.

Free IPAM Network Scanner with Netbox Open Source Requirements

Check out the previous post on Netbox Network Modeling and Documentation Ubuntu Installation to take a look at how to get Netbox up and running in general. As mentioned though, Netbox does not natively support network scanning out of the box.

This is by design. Why? Netbox’s purpose as expressed by the software developers is to serve as a “source of truth”. With this being said, Netbox is intended to represent the “desired state” of your network and not necessarily the “current state” of the network.

A network scan may defeat this purpose as you are basically overwriting the desired state with the actual state. However, you may be saying to yourself if you are like me that Netbox is such a great tool and would be even more powerful with the ability to automatically discover your IP address assets.

While my requirements are much more related to simply keeping up with IP addresses used in my home lab and having an easy way to see usage, available IP ranges and keep a record of devices that currently exist on the network.

In steps the netbox-scanner Python module that interacts with Netbox. This is a free download found here: https://pypi.org/project/python-netbox/

For my installation, I decided to just install this on my Netbox server itself. However, I did fight with several little issues along the way getting the netbox-scanner.

What are the requirements of netbox-scanner? There are various Python modules that are required for using the netbox-scanner with Netbox. The Python modules documented as required include the following:

asn1crypto==0.24.0
bcrypt==3.1.6
certifi==2019.3.9
cffi==1.12.2
chardet==3.0.4
cpe==1.2.1
cryptography==2.6.1
idna==2.8
paramiko==2.4.2
pyasn1==0.4.5
pycparser==2.19
PyNaCl==1.3.0
pynetbox==4.0.6
python-nmap==0.6.1
requests==2.21.0
six==1.12.0
urllib3==1.24.1

In addition to the requirements above, I did, at least for my Netbox Ubuntu server, find that I had other requirements missing by simply running the nbscanner and noting the modules it was missing.

Finally, a requirement to note, you need to generate an API token in the Netbox interface. This is done under the user profile of the user you are using for accessing the Netbox server from the netbox-scanner module.

Installing Netbox-Scanner Module for Netbox

The process to install netbox-scanner is fairly straightforward as documented. There are a couple of ways to install the module, either automatically with pip or manually by downloading the files, extracting, and confguring.

$ pip3 install netbox-scanner

You can also download from GitHub:

$ wget https://github.com/forkd/netbox-scanner/archive/master.zip
$ unzip netbox-scanner-master.zip -d netbox-scanner
$ cd netbox-scanner
$ pip install -r requirements.txt
$ python netbox-scanner/nbscanner

The Python nmap module is also required for the actual scanning mechanism enacted by the netbox-scanner module.

Issues Encountered During Installation

I did encounter several little issues when trying to get the module to work. However, I do believe most of these are a result of the environment of the Netbox server I was installing on.

I first used the automatic installation using pip. However, had a few errors when trying to run the scanner.

Error encountered with the Python configparser not being installed. Your installation may vary depending on any requirements you may have missing.

Running the Netbox-Scanner

Running the netbox-scanner is simple in that you run the nbscanner script once and it creates a config file called .netbox-scanner.conf. Using this file, you edit for your environment, including your Netbox URL, credentials, API token, and subnets to scan. Below is an example of this file.

[GENERAL]
tag       = cloudscan
unknown   = unknown host
log       = .
nmap_args = -T4 -O -F --host-timeout 5s

[NETBOX]
address = http://10.1.149.54
token = <your API token string>
tls_verify = True

[TACACS]
user     = <your user>
password = <your password>
command  = show run | inc hostname
regex    = hostname ([A-Z|a-z|0-9|-|_]+)
regroup  = 1

[SCAN]
networks = 1.1.1.0/24,2.2.2.0/24

When the netbox-scanner runs it imports the scan results into Netbox. The great thing as you can see below, it displays used IP addresses in the network ranges configured, those that are active, and the number of contiguous IPs between the active IPs found.

Wrapping Up

While Netbox doesn’t natively support IP scanning and automatic importing of hosts into the IPAM solution, with Free IPAM Open Source Netbox IP Scanner provided by the netbox-scanner module, IPs in use can easily be imported into Netbox. It uses nmap to discover the Active hosts and then import these into Netbox. With the other great Netbox features, adding the ability to perform automatic network scans of various subnets can definitely add to the value that Netbox provides.