Manage Passive Sensors via Nidstool

This section describes the nidstool utility for eyeInspect Passive Sensors.

Overview

Nidstool is a management utility for eyeInspect Passive Sensors. It can be used to perform activities such as checking the status of the sensor containers, starting/stopping/restarting them, and so on.

Nidstool is automatically installed alongside passive sensors.

Every sensor has a unique name in nidstool, also referred to as the service name. This name is used to refer to a specific sensor in the nidstool commands, nidstool configuration file and in the eyeInspect Command Center user interface during enrollment.

All sensors have an unique state folder, located by default in /opt/nids-docker/states/<SERVICE_NAME>. The sensor stores in this folder all its configuration, profiles and transient files.

Warning: Do not modify the /opt/nids-docker/states/ folder. The nidstool utility manages the creation and deletion of state folders when a new configuration is applied.

Commands

Nidstool commands are executed from the Linux terminal, from any location on the system. For an overview of the supported commands, run the following command:

sudo nidstool --help

All commands support the --help option. When used, this option prints further details about the specified command:

sudo nidstool <COMMAND> --help

Some commands also accept subcommands. For additional information, use the --help option after the subcommand:

sudo nidstool <COMMAND> <SUBCOMMAND> --help

The following table lists the available nidstool commands.

CommandSyntax and Example CommandsDescription
LS
sudo nidstool ls

Prints the list of known sensors services. Prints the name, the docker container status, interfaces and uptime of each sensor.

UP
sudo nidstool up <SERVICE NAME>

To start a sensor named nids-first, use:

sudo nidstool up nids-first
To start all sensors, use:
sudo nidstool up all

Creates the sensor container (if it does not exist) and starts it. The Passive Sensor runs as a background task.

RUN

sudo nidstool run [--entrypoint=<BIN PATH>] <SERVICE NAME>
[<SENSOR ARGUMENTS>]

  • SERVICE NAME must be the name of an individual sensor service (”all” is not allowed)
  • SENSOR ARGUMENTS are passed to the sensor as startup arguments. They must be separated from the nidstool arguments with a double-dash (--) separator, as shown in the following example:
    sudo nidstool run nids-first -- --no-sniff
  • The --entrypoint option is for overriding the entry point of the container. This allows to run a different binary in the container instead of the sensor. For example, to access the container shell, use:
    sudo nidstool run --entrypoint=/bin/bash nids-first

Note: The run command blocks other nidstool commands from being executed while the sensor is running.

Runs the Passive Sensor container in interactive mode. The STDIN and STDOUT of the sensor are attached to the terminal that executed this command. Can be used to troubleshoot individual sensors.

STOP
sudo nidstool stop <SERVICE NAME>
To stop a sensor named nids-first, use:
sudo nidstool stop nids-first

To stop all sensors, use:

sudo nidstool stop all

Stops the sensor container without removing it.
RESTART
sudo nidstool restart <SERVICE NAME>
To restart a sensor named nids-first, use:
sudo nidstool restart nids-first

To restart all sensors, use:

sudo nidstool restart all

Restarts the sensor container
DOWN
sudo nidstool down <SERVICE NAME>
To remove a sensor named nids-first, use:
sudo nidstool down nids-first

To remove all sensors, use:

sudo nidstool down all

Stops and removes the sensor container
UPDATE Updates specific sensor parameters, provided by the CERTS sub-command.
CERTS (sub-command)
sudo nidstool update certs <CERT_FOLDER_PATH>

Note: This subcommand restarts the sensors after applying the new certificates. This results in a minor downtime while the sensors are restarted.

Replaces, validates, and applies the certificates used by all Passive Sensors.

The following files must be present in the <CERT_FOLDER_PATH> folder:

  • sensor_cert.pem
  • sensor_cc.crt
  • sensor_key.pem
  • dh.pem

Refer to the Custom X.509 certificates in eyeInspect documentation for more information on how to generate these files.

If the private key of the certificate is encrypted, you will be prompted to enter its passphrase. The passphrase will also be updated in the nids.conf files.

CONFIG Applies or exports a sensor configuration file, determined by the provided sub-commands. Go to the Configuration File section to learn more.
EXPORT (sub-command)
sudo nidstool config export <CONFIG PATH>

Exports the current configuration to the nidstool configuration file format. This sub-command generates the configuration based on the contents from the sensor's Docker compose file and the configuration from all sensors (nids.conf and rdkafka.conf). This subcommand generates a new file in the path specified in <CONFIG PATH>.

APPLY (sub-command)

sudo nidstool config apply [--permissive] [--skip-confirmation]
<CONFIG_PATH>

  • CONFIG_PATH must point to a nidstool configuration file.
  • The --permissive option displays a warning instead of an error if the number of threads exceeds the number of CPU cores in the machine.
  • The --skip-confirmation option disables the confirmation prompt when applying the configuration

Applies the configuration from the nidstool configuration file. By default, it verifies that the number of sniffing threads does not exceed the number of CPU cores of the machine and prompts the user before applying the configuration.

When applying a new configuration, nidstool shows the generated sensor configuration files in the terminal before applying.

New Passive Sensors use the same certificates as the first sensor in the nidstool configuration file. If the first sensor does not have a custom certificate, the default eyeInspect certificates are used.

When an existing Passive Sensor is removed upon applying a new configuration, nidstool will save a backup of this sensor’s state folder in /opt/nids-docker/backups/states/<DATE HOUR MS>/<SENSOR NAME>.

PCAP files are not backed up to save space. Go to the Restore Sensor State Backup section to learn how to restore this backup. Only the last 5 state folder backups are saved. If the number of backups exceeds this number, nidstool will ask for confirmation to remove the oldest backup folders. Since this is a destructive operation, you need to confirm this operation even if the –skip-confirmation option is used.

Applying a new configuration will remove all existing sensor containers. Sensors which were running before applying the configuration will be restarted, while new sensors must be manually started.

Configuration File

The nidstool app provides the config apply and config export commands to manage the sensor configuration. These commands parse and export configuration files written in the YAML language. For more information about this language, refer to the official YAML documentation.

An overview of the configuration file is given below:

# The 'configuration' section contains parameters that applies to all sensors. This is an optional section.
# If the same parameter is present both in the 'configuration' and in the 'sensors' section, the one from
# 'sensors' has a precedence over the ones specified here.
configuration:
  # Parameters for the nids.conf file
  nids.conf:
    # Note that you assign the value with "KEY: VALUE" instead of "KEY=VALUE" as in the nids.conf   
	interfaces: eth1
	mgmt-address: cc1.ein.englab.forescout.com
    mgmt-secondary-address: cc2.ein.englab.forescout.com   #(needed for HA)
    sniff-threads: 1

  # Parameters for the rdkafka.conf file
  rdkafka.conf:
    batch.num.messages: 100000

# The 'sensors' section contains a list where each element contains the configuration for a single sensor
sensors:
- name: nids-first
  # Parameters for the nids.conf file, specific for this sensor
  nids.conf:
    interfaces: eth1
- name: nids-two
  # Use this option if you want to rename an existing sensor. 'name' contains the old name, 'rename_to' contains the new name
  rename_to: nids-second
  nids.conf:
    interfaces: eth2
    sniff-threads: 2 # Overwrites the value from the 'configuration' section in this sensor
  # Parameters for the rdkakfa.conf file, specific for this sensor
  rdkafka.conf:
    linger.ms: 2000 
- name: nids-third
  nids.conf:
    interfaces: eth3
  # Docker configuration. Support the service configuration options from Docker compose
  # (https://docs.docker.com/compose/compose-file/compose-file-v2/#service-configuration-reference)
  compose:
    dns: # Equivalent to https://docs.docker.com/compose/compose-file/compose-file-v2/#dns
    - 8.8.8.8
    - 9.9.9.9

  • All parameters in nids.kafka and rdkafka.conf are exactly the same ones as in the sensor. They are simply translated into nids.conf and rdkafka.conf files. The nidstool app will not verify the correctness of the parameter or value.

  • The configuration section contains the default parameters for all the sensors. If nids.conf or rdkafka.conf is specified on the sensor level definition, overlapping parameters will get overwritten by sensor level configuration. For example, if the configuration section says 2 sniffing threads but nids.conf on the sensor level says 4 sniffing threads, then 4 sniffing threads would get applied.

  • To rename a sensor while preserving its state, use the name and rename_to options. For example, to rename sensor A to B, configure it as follows: name: A and rename_to: B.

  • The following nids.conf options are auto-generated if not specified by the user:

    • first-core and clusterid: Cannot use the default values when running multiple sensors in the same host. The nidstool app will generate the appropriate values for these options.

    • mgmt-enroll-name: Defaults to the name of the sensor.

Restore Sensor State Backup

To restore a backup created by the config apply command, first apply a new configuration by re-adding the sensor, and then, copy and overwrite all the contents from /opt/nids-docker/backups/states/<DATE_HOUR_MS>/<SENSOR_NAME> to /opt/nids-docker/states/<SENSOR_NAME>.

For example, consider the following scenario: The sensor nids-first currently exists, and the sensor nids-second was previously deleted and you want to re-add it. To do this:

  1. Export the current configuration with nidstool config export <NIDS_CONFIGURATION_FILENAME>. This command will generate a configuration similar to the one shown below:
    configuration:
  nids.conf:
    sniff-threads: 1
    interfaces: replay1
sensors:
- name: nids-first
  2. Add a new sensor named nids-second to the configuration file:
    configuration:
  nids.conf:
    sniff-threads: 1
    interfaces: replay1
sensors:
- name: nids-first
# There is no need to specify the nids.conf and rdkafka.conf configuration since it will be overwritten when copying the folder.
- name: nids-second
  3. Apply the configuration with nidstool config apply <NIDS_CONFIGURATION_FILENAME>.
  4. Copy the state folder contents from /opt/nids-docker/backups/states/<DATE_HOUR_MS>/<SENSOR_NAME> to /opt/nids-docker/states/<SENSOR_NAME>
  5. Start the nids-second sensor.

Logs

Executed nidstool commands are logged in /opt/nidstool/logs/commands.log. This file logs the time, user, location and the executed command.