readme improved

This commit is contained in:
José Lopes 2018-10-26 10:32:49 -03:00
parent 518d5b92de
commit 28c79221a4
4 changed files with 21 additions and 11 deletions

View File

@ -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.

View File

@ -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 = '''

View File

@ -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',