Initial

jondkelley · Mar 27, 2018 · 04a0c1c · 04a0c1c
1 parent aab9746
commit 04a0c1c
Show file tree

Hide file tree

Showing 12 changed files with 998 additions and 29 deletions.
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,13 @@
+## The FreeBSD Copyright
+
+### Copyright 2018 Jonathan Kelley. All rights reserved.
+
+* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY JONATHAN KELLEY ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
diff --git a/README.md → README.rst b/README.md → README.rst
@@ -1,53 +1,107 @@
-# carphunter
+carphunter
+==========
 
-Carphunter is a Python-based network management tool that uses Netmiko to search your Cisco® branded routing/switching equipment. This tool is used to quickly examine recent IP, ARP, and VLAN associations across the  network.
+Own a datacenter? Want to allow network-operators to see the ARP and IP
+assignments without logging in?
 
-## Setup
+Carphunter is a Python-based network management tool using netmiko
+libraries to search your Cisco® branded routing/switching equipment.
+This tool is used to quickly examine recent IP, ARP, and VLAN
+associations across the network.
 
-#### 1) Install the software
+Setup
+-----
+
+1) Install the software
+^^^^^^^^^^^^^^^^^^^^^^^
 
 The latest release is in pip:
 
+::
 
      pip install carphunter
 
 You can always run the latest release from this repository by:
 
-     python setup.py install
-
-#### 2) Make scheduled cron
+::
 
-A cron job allows the tool to automatically keep the database up to date based on your own schedule. On most systems you can edit ```/etc/crontab``` and add
+     python setup.py install
 
-    */10 * * * * root /bin/carphunter --poll
+2) Make scheduled cron
+^^^^^^^^^^^^^^^^^^^^^^
 
-This will save the networks arp database to /etc/carphunter.json every 10 minutes.
+A cron job allows the tool to automatically keep the database up to date
+based on your own schedule. On most systems you can edit
+``/etc/crontab`` and add
 
-#### 3) Edit configuration for your network
+::
 
-TODO
+    */10 * * * * root /bin/carphunter --poll
 
-#### 4) Create initial database
+This will save the networks arp database to /etc/carphunter.json every
+10 minutes.
+
+3) Edit configuration for your network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Change ``/etc/carphunter.yml`` to contain a default global
+user/password. Add your routers and switches, supplying an alternate
+password where neccessary for each device. **Change permissions of this
+file to root-only to protect users from attaining network access.
+Additional use of limited jails for for the python interface will hit
+compliance marks, or just use auditing.**
+
+::
+
+    global:
+        user: "default_user"
+        password: "password"
+    devices:
+        routers:
+            10.16.16.2:
+                name: ROUTER-01
+                user: "router_user"
+                password: "router_password"
+            10.16.16.3:
+                name: ROUTER-02
+                user: "router_user"
+                password: "router_password"
+        switches:
+            172.16.16.10:
+                name: TX-DFW-DIST-A
+            172.16.16.20:
+                name: TX-DFW-DIST-B
+            172.16.16.31:
+                name: TX-DFW-DIST-A
+            172.16.16.31:
+                name: TX-DFW-DIST-A
+
+4) Create initial database
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This will test connectivity to your network build an initial database.
 
-    carphunter --poll
-
+::
 
-## How it works
+    carphunter --poll
 
-This tool uses json and Netmiko to poll all of your existing devices and stores a small database of items. This can be searched using the parameters --mac and --ip to display items in this json database.
+Command Examples
+----------------
 
-## Command Examples
+Find all ARP entries for ``001c.c46b.beef``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-### Find all ARP entries for ```001c.c46b.beef```
+This command will check every switch and router for any ARP or MAC table
+related entries containing a MAC address. Partial matches are supported.
 
-This command will check every switch and router for any ARP or MAC table related entries containing a MAC address. Partial matches are supported.
+::
 
     carphunter -m 001c.c46b.beef
 
 Sample output:
 
+::
+
     Checking network for `001c.c46b.beef`...
 
     Routing Device: TX-DFW-6509-01 found match!
@@ -73,15 +127,20 @@ Sample output:
       * Last poller took 0:02:14.006661
       * This lookup took 0:00:00.031692
 
+Find IP for ``10.10.1.100``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-### Find IP for ```10.10.1.100```
+This command will return IP, MAC, VLAN, AGE and ENCAPSULATION PROTOCOL.
+Partial matches are supported.
 
-This command will return IP, MAC, VLAN, AGE and ENCAPSULATION PROTOCOL. Partial matches are supported.
+::
 
     carphunter -i  10.10.1.100
-
- Sample output:
-
+
+Sample output:
+
+::
+
     Checking network for `10.10.1.100` ARPA entry...
 
     Routing Device: TX-GVO-DC-6509-01 found a matching IP!
@@ -91,12 +150,17 @@ This command will return IP, MAC, VLAN, AGE and ENCAPSULATION PROTOCOL. Partial
     |  10.10.1.100  | 001c.c46b.a0fe |  1   |  3  |  ARPA |
     +---------------+----------------+------+-----+-------+
 
-### Find IP using partial match ```10.10.1```
+Find IP using partial match ``10.10.1``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
 
     carphunter -i  10.10.1
-
- Sample output (ambiguous matches):
-
+
+Sample output (ambiguous matches):
+
+::
+
     Checking network for `10.10.1` ARPA entry...
 
     Routing Device: TX-GVO-DC-6509-01 found a matching IP!