Passive Sensor Startup Options
The eyeInspect Passive Sensor has a number of startup options, which are described below (brackets indicate alternatives for the same property). To use the startup options, edit the contents of /opt/nids-docker/states/nids-main/conf/nids.conf and use the properties with arguments as property=value and properties without arguments simply as property. Start the Passive Sensor after these changes by executing:
sudo nidstool up nids-main
or, if it was already running, restart the Passive Sensor by executing:
sudo nidstool restart nids-main
The table below describes the various passive sensor startup categories and options:
| Option | Default Value | Description |
|---|---|---|
| Command-line only options: | ||
| -h [ --help ] | - | Print help information. |
| -c [ --config ] arg | /opt/nids/state/conf/nids.conf | Custom configuration file to load. |
| Disk usage restrictions: | ||
| --em-transition-fs-limit arg | 10 | The maximum disk space (in GB) that needs to be available to enable encryption at rest. This space is required only during the encryption process. The Passive Sensor will estimate the required disk space and will reject the request in case of insufficient disk space. |
| --max-log arg | 1024 | The maximum size (in MB) per log file. |
| --max-disk-perc arg | 90 | The maximum disk percentage that will be used by NIDS. |
| --min-disk-space arg | 2048 | The minimum disk space (in MB) to keep free when writing files. |
| Dynamic traffic filtering: | ||
| --filter-traffic | false | Enable traffic filtering. |
| --filter-rotate-rules | false | When enabled, the sensor will start to rotate kernel-side rules when the limit is reached. The oldest rule will be canceled and applied to a new stream instead. Rules limit is 64k rules per interface. |
| --filter-interfaces-ignored arg | - | Comma-separated list of interfaces to avoid filtering on. |
| --filter-tcp-ports-ignored arg | - | List of TCP ports that will not be filtered (destination or source). |
| --filter-udp-ports-ignored arg | - | List of UDP ports that will not be filtered (destination or source). |
| --filter-packets-threshold arg | 40 | Amount of packets the sensor needs to see before a stream can be filtered out. |
| --filter-simple-protocols arg | NotAKnownOne, RTP, RTSP | List of protocols that will be filtered after recognition phase is finished and other configurable requirements are met:
|
| --filter-complex-protocols arg | SSL | List of protocols that will be filtered when filtering policy
is set to enFilteringPolicy::CAN_BE_FILTERED
and other configurable requirements are met. The
Connection::set_filtering_policy(enFilteringPolicy)
call in SDScript changes filtering policy. |
| --filter-max-num-userland-rules | 50000 | Maximum number of filtering rules that we can apply to the userland traffic filter. |
| Frequent event aggregation options: | ||
| --fea-info-interval arg | 3600 | Number of seconds between periodic FEAInfo
alerts for alerts that are in aggregation. Value of 0 means no
FEAInfo alerts will be raised. |
| Hosts and links options: | ||
| --hli-disable | - | Disable the Hosts Links Info module. |
| --hli-iec104-role-by-message-type | - | If added and set to true, roles master and slave are determined based on the combination of type ID and cause of transmission of the IEC104 messages observed in the connection, rather than on the direction of the connection. |
| --hli-max-tracked-hosts | 20000 | Maximum number of hosts monitored and updated by the sensor. |
| --hli-max-tracked-links | 100000 | Maximum number of communication links monitored and updated by the sensor. |
| --hli-strict-host-visibility | - | Enables strict rules for host visibility. If added and set to true, hosts are stored and displayed only if they send UDP packets, (non-reset) TCP packets, or Ethernet frames. Hosts only receiving packets will not be stored. Multicast and broadcast hosts remain visible. |
| Industrial threat library options: | ||
| --itl-alert-cooldown-min arg | 1440 | Certain ITL checks trigger on every connection (e.g. Insecure
Protocol Version), but it’s not interesting to repeat the Alert
on every connection. This parameter controls how long these
Alerts are suppressed per EventTypeID and
endpoint (source and destination pair, without protocol or
port). So, by default, an insecure protocol alert is raised once
a day per endpoint. |
| Kafka options: | ||
| --kafka-broker arg | - | Use a custom broker rather than sending the Kafka messages to the broker installed in the Command Center. |
| --kafka-force-no-ssl | - | Force any Kafka connection to be non-SSL. |
Note: Additional configuration parameters
can be found and edited in the
/opt/nids/conf/rdkafka.conf file. The parameters
mentioned below control the compression of Passive Sensor
messages to Kafka to reduce required bandwidth with the
Command Center. The full list of configuration parameters is
available here. Restart the
Passive Sensor to apply the changes. | ||
| Kafka compression parameters: | ||
| batch.num.messages | 100000 | Maximum number of messages batched in one
MessageSet. The total
MessageSet size is also limited by
batch.size and
message.max.bytes. |
| compression.codec | gzip | Compression codec used for compressing messages. Change to
inherit to inherit global
compression.codec configuration. |
| compression.level | 6 | Compression level parameter for the algorithm selected by
compression.codec. Higher values will
result in better compression at the cost of more CPU usage. The
allowed range is algorithm- dependent:
|
| linger.ms | 1000 | Alias for queue.buffering.max.ms. Delay in
milliseconds for messages accumulating in the producer queue
before constructing message batches
(MessageSets) to transmit to Kafka brokers.
A higher value allows larger and more effective (less overhead,
improved compression) batches of messages to accumulate at the
expense of increased message delivery latency. |
| LAN CP automerge behavior: | ||
| --lancp-disable-udp-automerge | disabled | By default, all UDP rules that can be merged, will be merged automatically. This applies to all new and existing rules. However, if the sensor is started with this option enabled, UDP rules will remain unmerged for as long as this startup option is used. |
| Message broker: | ||
| --broker-type arg | kakfa | Select message broker type. Accepted values are kafka, nats or file. |
| --broker-file-path arg | - | Logs all messages to a file in this path named
<topic>.json. |
| --broker-file-append-existing | false | If set, the existing <topic>.json will be
appended to instead of being overwritten. |
| Netflow options: | ||
| --af-netflow-topic arg | netflow | Use a custom message broker topic for
netflow data. |
| Parsing options: | ||
| --iec104-dialect arg | default | Protocol IEC104 dialect configuration. |
| --process-erspan | - | ERSPAN parsing is disabled by default. Providing this startup option enables it. |
| --process-vxlan | - | Pass this flag to enable decapsulation and processing of Ethernet frames encapsulated in VXLAN packets. |
| --pfring-disable-hw-timestamp | false | Disable the PF_RING_HW_TIMESTAMP flag. When
another application interacts with PF_RING and
disagrees on this option, it causes packets to corrupt. |
| Scanner handler heuristics: | ||
| --sch-ignore-events arg | ps_tcp_ack | Comma-separated list of portscan event types that will be ignored as a source of the portscan hint on potential scanner host whereabouts. |
| --sch-inactivity-timeout-sec arg | 300 | How often to check whether the active scanner host is active
on a network, in seconds. This option, with
sch-inactivity-pkts-threshold defines when
to cancel active filtering policy. |
| --sch-inactivity-pkts-threshold arg | 200 | Amount of packets in
sch-inactivity-timeout-sec time window,
before sensor would consider host to be active on network.
|
| --sch-policy arg | strict | Scanner handler policy. Accepted values are strict and disabled. |
| SD script options: | ||
| --script-max-persistent-size-mb arg | 5 | Maximum size, in MB, of a single SD Script’s ’persistent data’. Changing this value is not recommended and may result in unexpected behavior. |
| --script-total-hostdata-limit-mb arg | 2048 | Maximum size, in MB, of all SDScripts' 'host data'. |
| --script-weak-security-constraints | False | This flag allows the use of insecure Lua APIs and shared objects in SDLibrary packages. It doesn't affect already installed SDLibraries. Use this flag with discretion as this might enable RCE scenarios in SDScripts. |
| Sensor management: | ||
| --handle-uuid-collisions | false | Regenerate the sensor UUID instead of exiting immediately if there is another sensor with the same UUID enrolled on the management server. |
| --mgmt-enroll-name arg | - | Sensor name shown in the UI during the enrollment. |
| --no-mgmt | false | Do not attempt to establish a connection to the management server. |
| --mgmt-address arg | 127.0.0.1 | Address of the management server of the sensor. |
| --mgmt-port arg | 29999 | Port to connect to on the management server. |
| --mgmt-secondary-address arg | - | Address of the secondary management server. Will be used if it was not possible to establish a connection to the primary management server. |
| --mgmt-secondary-port arg | 29999 | Port to connect to on the secondary server. |
| --mgmt-connection-timeout-sec arg | 600 | Number of seconds to wait before the management server connection is timed out, allowing a new management server to connect. A value of 0 means that the connection will never time out. |
| --mgmt-ssl-pwd arg | password | Password used to unlock the SSL private key used for communication with the management server. |
| --srv-revreq-timeout-sec arg | 23 | Server reverse request timeout in seconds |
| --diag-healthcheck-threshold-sec | 40 | Number of seconds that thread has to be blocked for before sensor declares health check failure. |
| Sensor operability options: | ||
| --log-output arg | default | Stream destination of the sensor logs. Supported values are
stdout, stderr, filesystem and
default’ The default option writes logs to
both stdout and
filesystem. |
| --certificates arg | /opt/nids/state/cert | Custom certificates folder path to load. |
| --sensor-type arg | normal | The type of the environment where sensor operates. Possible values are counteract and normal. |
| --pcaps-path arg | /opt/nids/state/pcaps | Custom PCAPs folder path to use. |
| --state-path arg | /opt/nids/state/conf/nids.conf | Custom state folder path that contains sensor configuration and persistent data. |
| --log-max-file-size arg | 5242880 | Maximum size for log file in bytes. |
| --log-max-files arg | 3 | Maximum log files for sensor to store and rotate. |
| --log-mgmt-level arg | info | Minimum log level to report to management. Valid levels are trace, debug, info, warn, error and critical. |
| --log-aggregation-flush-period-sec arg | 3600 | Defines the amount of seconds the sensor would aggregate parsing error logs before logging them. |
| --state-backup-periodicity-sec arg | 60 | The frequency at which to create a backup of the sensor state. Higher values reduce storage access but may lead to data loss in case the sensor is stopped abruptly. |
| --breakpad-max-dumps-size arg | 20971520 | Maximum size in bytes for all minidumps generated in
sys/traces folder. |
| --log-debug-categories | "" | Log categories to be set to debug level. |
| --config-preset | Apply a predefined configuration preset with default values for specific deployment types. | |
| Sniffing: | ||
| --alert-no-include-pcap | - | Do NOT include a PCAP when sending alerts to the Command Center. |
| --non-tcp-stream-timeout-sec arg | 300 | Number of seconds non-TCP Stream should be idle before it is closed. |
| --tcp-stream-just-est-timeout-sec arg | 90 | Number of seconds a TCP Stream without data should be idle before it is closed. |
| --process-etherip | Pass this flag to enable decapsulation and processing of
Ethernet frames encapsulated in EtherIP
packets. | |
--sniff-recursive | false | [DEPRECATED; REPLACED WITH --sniff-options] Only affects
--sniff-from parameter and configures the
sensor sniff path recursively. Identical to the sniff
offline --from ... --recursive terminal
command. |
| -f [ --filter ] arg | - | BPF filter to apply to the monitored traffic using the
tcp- dumpformat. Use this option with care
as it can impact performance. |
| -i [ --interfaces ] arg | - | Comma-separated list of network interfaces to monitor from.
Mutually exclusive with |
| --sniff-from | Start sniffing PCAPs from the specified path immediately after
startup. Mutually exclusive with
--interfaces | |
| --no-sniff | - | Do not start sniffing immediately. |
| --sniff-offline | Do not start sniffing immediately. | |
| --sniff-options=[FLAG] | Actions to apply before/during/after the sniffing from PCAPs.
Works only in combination with --sniff-from.
Replace [FLAG] with one or more of the following to achieve
the corresponding behaviour:
All options will persist and be applied to all Note: To use multiple flags at once,
separate them with commas. An example is given
below: nids --sniff-offline --sniff-from ../my.pcap --sniff-options=QUIT,WFM | |
| --quit-after-sniff | [DEPRECATED; REPLACED WITH --sniff-actions=WFM,QUIT] After sniffing, wait for management to fetch alerts and hosts/links and quit the sensor. | |
| --out-of-order-buffer arg | 1500 | Amount of bytes to accumulate in TCP reassembly logic before a gap will be considered as missing data and not out-of-order packet. This option can improve the amount of parsed data in environments with big amount of out-of-order packets. |
| --process-mpls | - | Enables decapsulation and processing of Ethernet frames encapsulated in MPLS packets. |
| --pc-max-collect-size arg | 262144 | Absolute maximum size of the PCAP that is attached to alerts. |
| --pc-sliding-window-size arg | 5120 | Maximum number of bytes that will be in the PCAP before the PDU that triggered an alert. |
| -t [ --sniff-threads ] arg | 1 | Number of threads to use for sniffing. This cannot be greater
than the number of CPU cores. Please note threads are
scheduled backwards, starting from the last core. For
example, cores 24-31 on a 32-core machine with
|
| --tcp-process-bad-checksum | - | Process TCP segments even if the checksum is incorrect. |
| --tcp-stream-timeout-sec arg | 300 | Timeout (in seconds) for idle TCP Streams to be closed. |
| --udp-process-bad-checksum | - | Process UDP datagrams even if the checksum is incorrect. |
| --cluster-type | 5_tuple_ip_inner_flow | Type of the cluster used for the per-flow packet balancing. Expected values are: per_flow, round_robin, 2_tuple, 2_tuple_inner_flow, 4_tuple, 4_tuple_inner_flow, 5_tuple, 5_tuple_tcp, 5_tuple_ip, 5_tuple_ip_inner_flow, 5_tuple_tcp_inner_flow. |
| Startup options for enrolling the Passive Sensor to a Command Center: | ||
| --diag-collection-time-log-threshold-ms | 5000 | If a diagnostic collection execution takes longer than this value, a warning will be logged. |
| --diag-collect-internal-metrics | false | Determines whether the sensor should collect internal metrics that are not used in the health status. |
| --parse-drecorder-buffer | 1048576 (1MB) | The size in bytes of how much data the
DataRecorder will hold per direction. If
exceeded, recognition finishes preliminary. |
| --parse-realigner-buffer | 512000 (512 KB) | The size in bytes of how much data the
Realigner will hold per direction. If
exceeded, we drop the data. |
| --portscan-max-tracked-hosts | 0 | The number of hosts that the portscan engine will track to
detect potential ongoing port scanning. It takes effect only
when it is set. By default, the sensor uses
hli-max-hosts-num parameter. |
| --tcp-buffer-chunk-size | 1024 | The number of bytes allocated for each chunk of the TCP half-stream buffer. Lower values reduce the memory use in scenarios with a high number of TCP streams at the cost of increasing the number of memory allocation calls. |
| --hli-inactivity-timeout-sec | 3600 | |
| --enhanced-it-parsing | True | Enhanced IT traffic parsing and reporting. Used by the sensor in eyeSight deployments to collect additional asset information, which is not used in OT environments. |
| --script-sdlib-permit-shared | False | |
| Visual analytics options: | ||
| --af-data-periodicity-sec arg | 60 | Periodicity with which to send flow information about a Stream. Higher values reduce required bandwidth and strain on Analytics but reduces accuracy of Analytics throughput graphs. Generally safe to use any value up to 60 (granularity of Analytics widgets). |
| --af-max-num-flow-properties arg | 10 | The maximum number of properties that SDScripts can set to a flow. |
| --af-send-idle-log | - | Send the flow idle log. By default, this log is not sent to reduce required bandwidth and strain on Analytics. |
| --af-topic arg | flow-info | Use a custom message broker topic rather than the default flow-info. |
| --af-trim-notaknownone-dst-port | - | Trim the destination port for NotAKnownOne
protocol to reduce the amount of data generated. |
High Throughput Streams Handling Configuration in Passive Sensors
High-throughput streams often correspond to activities such as backups or video transfers, which involve large volumes of data and frequently use encrypted protocols. These streams can consume disproportionate sensor resources, potentially impairing the visibility and analysis of other traffic.
The passive sensor can detect high-throughput streams that may exceed its processing capacity. When such streams are identified, it automatically engages dynamic traffic filtering to preserve resources for analyzing the rest of the traffic. This heuristic ensures the sensor remains resilient to traffic spikes, maintaining consistent visibility into critical network events and preventing high-volume streams from obscuring important detections.
The sensor monitors the average throughput of each stream over a configurable time window (default: 30 seconds). If a stream’s average throughput exceeds a predefined threshold (default: 300 Mbps), the sensor automatically applies a filtering rule to temporarily exclude that stream from further processing.
This feature is enabled by default but can be disabled using the
hts-disable configuration parameter.
When the sensor detects a high-throughput stream, it logs a message similar to the following:
Detected high-throughput stream exceeding the threshold of 300 Mbps in a 30- second time window. Source: 150.203.213.91:2222 → Destination: 150.203.212.28:45598 (NotAKnownOne/TCP) The threshold was exceeded in 14 seconds with an average throughput of 619 Mbps. A filtering rule was added to optimize traffic processing.
To configure the passive sensor to handle high throughput streams, edit the contents of the nids.conf file, present at /opt/nids-docker/states/nids-main/conf/nids.conf and use the configuration parameters described in the below table.
| Parameter | Default Value | Description |
|---|---|---|
| hts-window-sec | 30 | Time window in seconds of the traffic observation. |
| hts-throughput-threshold-mbps | 300 | Average throughput in Mbps in the window before logic is triggered. |
| hts-disable | false | Disables high-throughput stream filter functionality. |
| hts-protocols-blacklist | Comma separated list of protocols to which we want to restrict filtering. By default all protocols can be filtered. | |
| hts-protocols-whitelist | all | Default value ‘all’ means the logic can be applied to all protocols. If user specifies list of protocols here, logic would be restricted to listed protocols only. |
After making the changes, start the Passive Sensor after these changes by executing:
sudo nidstool up nids-main
or, if it was already running, restart the Passive Sensor by executing:
sudo nidstool restart nids-main