search

damienstuart / trapex

An SNMP Trap forwarder/relay
MIT License
11 stars 2 forks source link

readme

Trapex - A Program for Filtering, Translating, and Forwarding SNMP Traps

Trapex is an SNMP Trap proxy/forwarder. It can receive, filter, manipulate, log, and forward SNMP traps to zero or mulitple destinations. It can receive and process SNMPv1, SNMPv2c, or SNMPv3 traps.

Presently, v2c and v3 traps are converted to v1 before they are logged and/or forwarded. Support for sending other versions may be added in a future release.

Overview

The trapex program was created as a replacement for the aging eHealth Trap Exploder - which a commercial product, and does not support SNMPv3.

Trapex has the following features:

This initial version's functionality and configuration options are very similar to the current eHealth Trapexploder program, but there are some differences, so be sure to carefully read this documentation if you will be working with this program.

Notes

This implementation uses external GO modules:

Trapex Configuration

Trapex gets its configuration and runtime options from the configuration file. Some options can be overridden by command-line arguments to trapex

Though the out-of-the box configuration file will have resonable defaults and will have a filter directive for logging any traps, you should edit it and set any configuration options as needed, and add/edit any other filter directives.

See the trapex.conf file section below for details on the configuration file and its directives

Running trapex

For a usage message for running trapex, run: ./trapex -h and you will get the following usage message:

Usage: trapex [-h] [-c <config_file>] [-b <bind_ip>] [-p <listen_port>]
              [-d] [-v]
  -h  - Show this help message and exit.
  -c  - Override the location of the trapex configuration file.
  -b  - Override the bind IP address on which to listen for incoming traps.
  -p  - Override the UDP port on which to listen for incoming traps.
  -d  - Enable debug mode (note: produces very verbose runtime output).
  -v  - Print the version of trapex and exit.

trapex will stay in the foreground and print information to STDOUT. On startup, any filter directives that forward a trap will be printed as they are loaded from the configuration file. Here is an example:

Loading configuration for trapex version 0.9.2 from: /opt/trapex/etc/trapex.conf.
 -Added trap destination: 216.203.5.174, port 162
 -Added trap destination: 10.131.125.61, port 162
 -Added trap destination: 10.131.125.62, port 162
 -Added trap destination: 69.164.113.76, port 162
 -Added log destination: /opt/trapex/log/trapex.log

Also, any actions triggered by a signal will cause output to be printed to STDOUT as well.

Signals

Trapex has handlers for the following signals:

  Got SIGUSR1
  Trapex stats as of: Fri, 10 Jul 2020 08:35:30 EDT
   - Uptime..............: 0d-15h-41m-0s
   - Traps Received......: 2744275
   - Traps Processed.....: 2744275
   - Traps Dropped.......: 879493
   - Translated from v2c.: 288232
   - Translated from v3..: 497
   - Trap Rates (based on all traps received):
      - Last Minute......: 48
      - Last 5 Minutes...: 50
      - Last 15 Minutes..: 50
      - Last Hour........: 49
      - Last 4 Hours.....: 49
      - Last 8 Hours.....: 49
      - Last 24 Hours....: 32
      - Since Start......: 49

The trap rates above are calculated based on all incoming traps before any filtering or processing takes place. If the ignoreVersion option was used, there would be a counter for Traps Ignored in the list. Also, if v2c and/or v3 versions are ignored, the Translated from vX line will not be included in the list.

Note that the Traps Dropped counter indicates traps that were matched on a filter that has the break action. Depending on the position of the filter entry it matched, the trap may or may not have been forwarded or logged. This is just an indicator that the trap did not traverse the entire filter list.

The Trapex Configuration File

The trapex configuration file (trapex.conf) is used to set the various runtime options as well as the filtering, forwarding, and logging directives.

Blank lines are allowed, and those that start with # are for comments.

There are two types of directives in the trapex.conf file:

CONFIGURATION DIRECTIVES

General Options:

Log File Handling:

These directive affect only the regular log files. They do not apply to the CSV-based logs.

SNMP v3 Setting:

These are options for receiving SNMP v3 traps. Note that trapex currently only supports the SNMP v3 User-based Security Model (USM).

IP SETS

An IP Set is a named list of IP addresses that can be referenced in the filter entries for the Source IP or Agent IP fields. The format is:

  ipset <ipset_name> {
      10.1.3.4
      10.1.3.5
      100.3.66.4
  }

You can also put multiple (whitespace-separated) IPs on a single line:

  ipset <ipset_name2> {
      10.1.3.4 10.1.3.5 100.3.66.4
      192.168.3.4 192.168.3.5 200.4.99.1 200.4.99.26
      10.222.121.7
  }

In the filter lines, you can then use "'ipset:'" in either or both the 'Source IP' or 'Agent Address' fields.

FILTER DIRECTIVES

The trapex configuration filter directives are used for specifying which traps are processed and what action is taken for traps that match the filter.

Each filter line starts with the word filter followed by the filter expressions, the action for that filter, and for some actions, an option argument for that action.

Filter Expressions:

The filter expression is a space separated set of 6 filter criteria for trap data fields in the following order:

An asterisk (*) can be used as a wildcard to indicate that any value for that field matches. For instance, a filter that would match all traps and forward them to 192.168.1.1 port 162 would look like this:

filter * * * * * * forward 192.168.1.1:162

If multiple fields are set to a non-wildcard value, then all of them have to match (logical AND) in order for the trap to match and trigger the action.

Filter Actions

The actions that are currenly supported by trapex are:

Filter Processing:

The order of the filter directives in the configuration file is important.

The filters are processed in the order they appear in the configuration file. When a trap is received, it is checked against each filter in order. If it matches a filter, the trap data is processed by the action for that filter, and that trap is checked against the next filter, and so on (unless the action is break - where the trap is dropped and ignored from that point on).

Filter Examples

These are sample filter entries for various modes of filtering traps and actions.

A sample IP Set

The IP addresses in this list can be referenced in filter directives below.

ipset test_ipset {
    10.1.3.4 10.1.3.5 100.3.66.4
    192.168.3.4 192.168.3.5 200.4.99.1
    10.222.121.7
}

Forward all traps to another host

filter * * * * * * forward 192.168.7.7:162

Log all traps.

Note that this would be all traps that have made it to this filter line in the configuration file.

filter * * * * * * log /opt/trapex/log/trapex.log

Log all trap data to CSV file.

filter * * * * * * csv /opt/trapex/log/trapex.csv

Log only coldStart traps

This filters on a Generic trap type of 0 and a specific Enterprise OID.

filter * * * 0 * ^1\.3\.6\.1\.6\.3\.1\.1\.5 log /var/log/trapex-cold_start.log

When filtering on Enterprise OID, a regular expression (regex) is used. When using a regex in a filter, you should always put a backslash (\) in front of the dots to escape them. Otherwise you may end up matching values you did not intend to filter.

Filter on Source IP address

This filters a trap based on the SNMP packet source IP address - which may not be the actual IP of the sending host if it is behind a NAT, or is a trap that was forwarded from another system.

Here we send any traps from this source IP to a specific destination, then break to drop it here to stop further processing for this trap.

filter * 10.66.48.1 * * * * forward 192.168.7.12:162
filter * 10.66.48.1 * * * * break

Filter on Source IP subnet

This is similar to the filter above accept that it will match all source IPs in a subnet as specified via CIDR notation. In this case, IPs between 10.66.48.0 and 10.66.48.63

filter * 10.66.48.0/26 * * * * forward 192.168.7.12:162
filter * 10.66.48.0/26 * * * * break

Filter on Agent Address

Force agent_addr 0.0.0.0 to be source IP

Some traps might have 0.0.0.0 as the agent address. This filter forces the agent address to be the same as the trap packet source IP address.

filter * * 0.0.0.0 * * * nat $SRC_IP

Filter on Agent Address

Filtering on Agent Address is just like filtering on the source IP except that is is checking the AgentAddr value in the trap.

filter * * 10.66.48.1 * * * forward 192.168.7.12:162
filter * * 10.66.48.1 * * * break

# Or combine the two lines above into a single filter line by adding "break" using
# the optional second argument:
#
filter * * 10.66.48.1 * * * forward 192.168.7.12:162 break

Filters using an IP SET (defined earlier in the config file)

Here we drop traps for agent_addr IPs that are in the sample ip set: "test_ipset":

filter  * * ipset:test_ipset * * * break

IP filter using a regular expression

*Trapex does support using a regex for IP filters. To do this, the IP address has to start with a forward slash (/) to let the filter processor know it should be treated as a regex.

Here we want to filter on 4 different Agent IP addresses in the same /24 subnet that end with .11, .22, .30, and .76, then forword them to a trap host that is listening on port 1162.

filter * * /^10\.131\.125\.(11|22|30|76)$ * * * forward 10.131.125.200:1162

NAT Actions

There are cases where we may want to set the trap's Agent Address to another value. Common use-cases are changing the agent addr to match an address that was NAT'ed, or where the agent address is invalid (like 0.0.0.0).

Change Agent Addr to another IP based on source IP

Here we want any traps with a packet source IP of 192.168.63.2 to have an agent address of 10.16.20.2.

filter  * 192.168.63.2 * * * * nat 10.16.20.2

Make the Agent Addr match the Source IP

Here we make the Agent Address the same as the packet source IP. We have one entry for a single IP and one for a subnet.

filter * * 10.22.0.98 * * * nat $SRC_IP
filter * * 10.122.0.0/16 * * * nat $SRC_IP

Log Actions

For cases where you would like to log specific traps to a separate log file, the 'log' action is used.

Log incoming v3 traps to a specific log file.

Here we want all incoming SNMPv3 trap to go to a log file called trapex-v3.log.

filter  v3 * * * * * log /opt/trapex/log/trapex-v3.log

Log only cold

Here we want only to log SNMP cold start traps from a agent addresses on a particular subnet, then ignore and drop the trap after that. This can be done in a single filter entry by using a second arg of 'break'.

filter * * 10.22.0.0/16 0 * ^1\.3\.6\.1\.6\.3\.1\.1\.5 log /var/log/trapex-10.22-cold_start.log break

Author

Trapex was writen by Damien Stuart - (dstuart@dstuart.org)