diff --git a/README.md b/README.md index 19b723c..2c5e628 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # netbox-scanner -A scanner util for [NetBox](https://netbox.readthedocs.io/en/stable/), because certain networks can be updated automagically. ;) +A scanner util for [NetBox](https://netbox.readthedocs.io/en/stable/), because certain networks can be updated automagically. `netbox-scanner` aims to create, update, and delete hosts (`/32`) in NetBox, either discovered after network probes and imported from CSV files. ## Installation @@ -13,26 +13,23 @@ You can also download from GitHub: $ unzip netbox-scanner-master.zip -d netbox-scanner $ cd netbox-scanner $ pip install -r requirements.txt - $ vi netbox-scanner/config.py # edit this file, save and exit $ python netbox-scanner/netbox-scanner.py Note that `netbox-scanner` will require [Nmap](https://nmap.org/) and an instance of NetBox ready to use. -## Usage -`netbox-scanner` can be used both in your Python programs or as a script. To use `netbox-scanner` as a script, simply run `netbox-scanner/netbox-scanner.py` and it'll create its configuration file (`.netbox-scanner.conf`) in your home folder: +## Scanning the Network +To use `netbox-scanner` as a script, simply run `netbox-scanner/netbox-scanner.py` and it'll create its configuration file (`.netbox-scanner.conf`) in your home folder: $ python netbox-scanner.py -After that, you'll just need to edit that file with your environment settings and run the script again. - -`netbox-scanner` will do the following tasks: +After that, you'll just need to edit that file with your environment settings and run the script again, and `netbox-scanner` will do the following tasks: 1. It will scan all networks defined in the configuration file. 2. For each discovered host it will: - 1. If host is in NetBox, description is different, and `tag` is equal to that defined in the configuration file, it's description will be updated in NetBox. + 1. If it is in NetBox, description is different, and `tag` is equal to that defined in the configuration file, description will be updated in NetBox. 2. If host is not in NetBox, it'll be created. -3. It will iterate through each network to find and delete any hosts registered in NetBox that did not respond to scan, and have the tag defined in the configuration file. +3. The script will iterate through each network to find and delete any hosts registered in NetBox that did not respond to scan, and have the `tag` defined in the configuration file. For instance, if some hosts in your monitored networks are eventually down, but you don't want `netbox-scanner` to manage them, just make sure that they **don't** have the tag defined in the configuration file. @@ -43,5 +40,18 @@ Of course, you can use `cron` to automatically run `netbox-scanner`. `netbox-scanner` have a configuration file with all parameters needed to scan networks and synchronize them to NetBox. By default, this file is located at user's home folder and is created when `netbox-scanner.py` is executed for the first time. Before using `netbox-scanner.py` you should edit that file and fill all variables according to your environment. +## Importing from CSV File +`netbox-scanner` can import data from CSV files in the following format: + + IP Address,Description + 10.0.0.1,Gateway + 10.0.0.2,NTP Server + ... + +Note that the first line is header, IP addresses aren't in CIDR notation (a `/32` will be appended to all addresses automatically) and commas aren't accepted in description. You can import this file using the `--csv` parameter, like this: + + $ netbox-scanner.py --csv netbox.csv + + ## License `netbox-scanner` is licensed under a MIT license --read `LICENSE` file for more information. diff --git a/netbox-scanner/nbscan.py b/netbox-scanner/nbscanner.py similarity index 100% rename from netbox-scanner/nbscan.py rename to netbox-scanner/nbscanner.py diff --git a/netbox-scanner/netbox-scanner.py b/netbox-scanner/netbox-scanner.py index 109567d..7ede4af 100644 --- a/netbox-scanner/netbox-scanner.py +++ b/netbox-scanner/netbox-scanner.py @@ -10,7 +10,7 @@ from datetime import datetime from urllib3 import disable_warnings from urllib3.exceptions import InsecureRequestWarning -from nbscan import NetBoxScanner +from nbscanner import NetBoxScanner template = ''' diff --git a/setup.py b/setup.py index a9a5840..0ec919b 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ with open('README.md', 'r') as fh: setuptools.setup( name='netbox-scanner', - version='0.7.0', + version='0.7.1', author='José Lopes de Oliveira Jr.', author_email='jlojunior@gmail.com', description='A scanner util for NetBox',