Fw-host-discovery NPM

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!