fw-host-discovery
v1.1.0
Published
Uses nmap to discover host information and write it to a database, based on a series of scanning schedules defined by the end user.
Downloads
35
Readme
FileWave Host Discovery
This is a stand alone program that performs network scans. The scans can be set to run on a repeating schedule, and the intent is that multiple instances of this program are run throughout an organisation - each one scanning a subset of the network and delivering the results back to the database for reporting purposes.
There is no UI that displays the results at this stage.
The project uses nmap to scan a series of hosts to figure out their MAC, IPv4, hostname and vendor details. The scan configuration is defined inside the database, allowing centralised administration of that configuration.
Check out the fw-host-configure project for the Qt/C++ based UI that enables you to modify the configuration.
Installation
NMAP Binary
You must have nmap binaries installed. The fw-host-discovery system will look for nmap in the path, so if you have installed it in a custom location, just modify the PATH environment variable before running the node app.
Installation
To install the program globally, do the following:
$ npm install fw-host-discovery -g
This will install the npm package as well as provide you with a command line tool to run the program called fw-host-discovery.
Configuration
The host discovery configuration, and the results of the scans are all read/written to/from a centralised Postgres database.
Prerequisites
1. You have created a Postgres database instance called 'discovery' and that the user/password you are using
has sufficient rights to create/modify schema within the database.
2. That the database server is directly reachable from the host running the fw-host-discovery program.
3. That the postgres.conf allows the user to connect from the various hosts where the fw-host-discovery
program has been installed.
Parameters
The parameters that can be controlled at runtime via environment variables, and their defaults are as follows.
DB_HOST: The hostname or IP address of the PostgreSQL database. Default: "", this makes the connector use local Unix sockets
DB_PORT: The port number to use when connecting to PostgreSQL. Default: 9432
DB_USER: The username to use when connecting to PostgreSQL Default: "django"
DB_PASSWORD: The password to use when connecting to PostgreSQL Default: "filewave"
FW_EXPLORER_HOST: The hostname or IP address that the API explorer listens on Default: "0.0.0.0"
FW_EXPLORER_PORT: The port number that the API explorer uses Default: 3000
An example of setting the require DB_HOST and DB_PORT might be:
$ DB_HOST='my-postgres-hostname' DB_PORT=37000 node .
Running
Then run the discovery tool to scan the network, configuration for what to scan is provided by modifying nmap-job entries in the database. Please see the fw-host-configuration project for more information.
NMAP Jobs
Every scan that nmap is to make it defined by an nmap_job entry in the database. Each entry contains fields such as timeout, parameters, range of network addresses to scan and so on.
One very critical parameter is the node_tag. The node_tag is nothing more than a string that represents a group of npm scanning jobs. Lets say you have two buildings on different subnets or vlans or whatever - and you are interested in knowing that the computers being scanned 'belong' to a particular building - this is what the node_tag can achieve.
Assuming the buildings are called 'finance' and 'education', you could create nmap_job entries tagged with 'finance' and 'education', then computers being scanned will also be tagged with the same information - allowing you to work out which scanner (or building) they came from.
To run the program, its as easy as this:
$ fw-host-discovery
Two tables store the data:
nmap_job - a list of jobs and their schedules, the contents of this table controls how nmap runs.
nmap_result - the scans from nmap, including the JSON results.
nmap_discovery - the result of parsing the scans.
Have fun!