using logging, improved documentation

README.md

@@ -4,9 +4,16 @@ A scanner util for NetBox, because certain networks can be updated automagically
 ## Installation
 `netbox-scanner` is available as a Python package via PyPi, so you can install it using `pip`:
 
-    pip3 install netbox-scanner
+    $ pip3 install netbox-scanner
 
 Note that `netbox-scanner` will require Nmap and an instance of NetBox ready to use.
 
 ## Usage
 `netbox-scanner` can be used both in your programs or as a script to be used in shell.
+
+To use `netbox-scanner` as a script, edit `netbox-scanner/config.py` with your setup, and run the command below:
+
+    $ netbox-scanner.py
+
+## License
+`netbox-scanner` is licensed under a MIT license --read `LICENSE` file for more information.

netbox-scanner/config.py

@@ -1,5 +1,7 @@
 # netbox-scanner configuration file.
 
+from logging import DEBUG
+
 NETBOX = {
     'ADDRESS': '',
     'TOKEN': '',
@@ -7,7 +9,22 @@ NETBOX = {
     'PORT': 443,
 }
 
-TAGS = ['auto']  # only 1 tag is allowed
+LOGGING_CONFIG = dict(
+    version = 1,
+    formatters = {
+        'f': {'format': '%(asctime)s %(name)-12s %(levelname)-8s %(message)s'}
+    },
+    handlers = {
+        'h': {
+            'class': 'logging.StreamHandler', 
+            'formatter': 'f', 
+            'level': DEBUG
+        }
+    },
+    root = {'handlers': ['h'], 'level': DEBUG},
+)
+
+TAG = 'auto'
 UNKNOWN_HOSTNAME = 'UNKNOWN HOST'
 DISABLE_TLS_WARNINGS = True  # stop displaying TLS/SSL warnings?
 

netbox-scanner/nbscan.py

@@ -7,14 +7,14 @@ from nmap import PortScanner
 from cpe import CPE
 from netbox import NetBox
 
-from config import TAGS, UNKNOWN_HOSTNAME
-
 
 class NetBoxScanner(object):
     
-    def __init__(self, host, tls, token, port, warnings=True):
+    def __init__(self, host, tls, token, port, tag, unknown, warnings=True):
         self.netbox = NetBox(host=host, use_ssl=tls, auth_token=token,
             port=port)
+        self.tag = tag
+        self.unknown = unknown
         if warnings:
             disable_warnings(InsecureRequestWarning)
     
@@ -27,7 +27,12 @@ class NetBoxScanner(object):
                 c.get_product()[0], c.get_version()[0])
             
     def scan(self, network):
-        ''''''
+        '''Scan a network.
+        
+        :param network: a valid network, like 10.0.0.0/8
+        :return: a list with dictionaries of responsive 
+        hosts (addr and description)
+        '''
         hosts = []
         nm = PortScanner()
         nm.scan(network, arguments='-T4 -O -F')
@@ -38,27 +43,32 @@ class NetBoxScanner(object):
                 description = self.get_description(nm[host]['hostnames'][0]['name'], 
                     nm[host]['osmatch'][0]['osclass'][0]['cpe'])
             except (KeyError, AttributeError):
-                description = UNKNOWN_HOSTNAME
+                description = self.unknown
             hosts.append({'address':address,'description':description})
         return hosts
     
     def sync(self, networks):
+        '''Scan some networks and sync them to NetBox.
+
+        :param networks: a list of valid networks, like ['10.0.0.0/8']
+        :return: nothing will be returned
+        '''
         for net in networks:
             hosts = self.scan(net)
             for host in hosts:
                 nbhost = self.netbox.ipam.get_ip_addresses(address=host['address'])
                 if nbhost:
-                    if (TAGS[0] in nbhost[0]['tags']) and (host['description'] != nbhost[0]['description']):
+                    if (self.tag in nbhost[0]['tags']) and (host['description'] != nbhost[0]['description']):
                         self.netbox.ipam.update_ip('{}/32'.format(host['address']), description=host['description'])
                 else:
-                    self.netbox.ipam.create_ip_address('{}/32'.format(host['address']), tags=TAGS, description=host['description'])
+                    self.netbox.ipam.create_ip_address('{}/32'.format(host['address']), tags=[self.tag], description=host['description'])
             
             for ipv4 in IPv4Network(net):
                 address = str(ipv4)
                 if not any(h['address'] == address for h in hosts):
                     nbhost = self.netbox.ipam.get_ip_addresses(address=address)
                     try:
-                        if TAGS[0] in nbhost[0]['tags']:
+                        if self.tag in nbhost[0]['tags']:
                             self.netbox.ipam.delete_ip_address(address)
                     except IndexError:
                         pass

netbox-scanner/netbox-scanner.py

@@ -1,12 +1,21 @@
+#!/usr/bin/env python3
+
+from logging import getLogger
+from logging.config import dictConfig
+
+import config
 from nbscan import NetBoxScanner
-from config import NETBOX, DISABLE_TLS_WARNINGS, TARGETS
 
-from datetime import datetime
+dictConfig(config.LOGGING_CONFIG)
+logger = getLogger('netbox-scanner')
 
-print('starting  - {}'.format(datetime.now()))
-nbs = NetBoxScanner(NETBOX['ADDRESS'], NETBOX['TLS'], 
-    NETBOX['TOKEN'], NETBOX['PORT'], DISABLE_TLS_WARNINGS)
-nbs.sync(TARGETS)
-print('finishing - {}'.format(datetime.now()))
+nbs = NetBoxScanner(config.NETBOX['ADDRESS'], config.NETBOX['TLS'], 
+    config.NETBOX['TOKEN'], config.NETBOX['PORT'], config.TAG, 
+    config.UNKNOWN_HOSTNAME, config.DISABLE_TLS_WARNINGS)
+
+logger.debug('starting')
+nbs.sync(config.TARGETS)
+logger.debug('finished')
 
 exit(0)
+1975107045

setup.py

@@ -7,7 +7,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
     name="netbox-scanner",
-    version="0.0.4",
+    version="0.0.5",
     author='José Lopes de Oliveira Jr.',
     author_email="jlojunior@gmail.com",
     description="A scanner util for NetBox",