2.2.20 Reputation Preprocessor

Reputation preprocessor provides basic IP blacklist/whitelist capabilities, to block/drop/pass traffic from IP addresses listed. In the past, we use standard Snort rules to implement Reputation-based IP blocking. This preprocessor will address the performance issue and make the IP reputation management easier. This preprocessor runs before other preprocessors.

2.2.20.1 Configuration

The preprocessor configuration name is reputation.

verbatim388#
Option syntax
<#19591#><#19558#><#19558#><#19591#> 
Option Argument Required Default
memcap ;SPMlt;memcap;SPMgt; NO memcap 500
scan_local NONE NO OFF
blacklist ;SPMlt;list file name;SPMgt; NO NONE
whitelist ;SPMlt;list file name;SPMgt; NO NONE
priority [blacklist whitelist] NO priority whitelist
nested_ip [inner outer both] NO nested_ip inner
white [unblack trust] NO white unblack
verbatim389#
Option explanations
<#19637#><#19592#><#19592#><#19637#> memcap
<#19611#><#19610#><#19593#><#19593#><#19610#><#19611#> Maximum total memory supported. It can be set up to 4095 Mbytes.

<#19638#><#19594#><#19594#><#19638#> scan_local
<#19622#><#19612#><#19595#><#19595#><#19612#><#19622#> Enable to inspect local address defined in RFC 1918:
<#19619#><#19616#><#19613#><#19596#><#19596#><#19613#><#19616#><#19619#> 10.0.0.0 - 10.255.255.255 (10/8 prefix)
<#19620#><#19617#><#19614#><#19597#><#19597#><#19614#><#19617#><#19620#> 172.16.0.0 - 172.31.255.255 (172.16/12 prefix)
<#19621#><#19618#><#19615#><#19598#><#19598#><#19615#><#19618#><#19621#> 192.168.0.0 - 192.168.255.255 (192.168/16 prefix)

<#19639#><#19599#><#19599#><#19639#> blacklist/whitelist
<#19625#><#19623#><#19600#><#19600#><#19623#><#19625#> The IP lists are loaded from external files. It supports relative paths for inclusion and $variables for path. Multiple blacklists or whitelists are supported.

<#19626#><#19624#><#19601#><#19601#><#19624#><#19626#> Note: if the same IP is redefined later, it will overwrite the previous one. In other words, IP lists always favors the last file or entry processed.

<#19640#><#19602#><#19602#><#19640#> priority
<#19629#><#19627#><#19603#><#19603#><#19627#><#19629#> Specify either blacklist or whitelist has higher priority when source/destination is on blacklist while destination/source is on whitelist. By default, whitelist has higher priority. In other words, the packet will be passed when either source or destination is whitelisted.

<#19630#><#19628#><#19604#><#19604#><#19628#><#19630#> Note: this only defines priority when there is a decision conflict, during run-time. During initialization time, if the same IP address is defined in whitelist and blacklist, whoever the last one defined will be the final one. Priority does not work on this case.

<#19641#><#19605#><#19605#><#19641#> nested_ip
<#19632#><#19631#><#19606#><#19606#><#19631#><#19632#> Specify which IP address to be used when there is IP encapsulation.

<#19642#><#19607#><#19607#><#19642#> white
<#19635#><#19633#><#19608#><#19608#><#19633#><#19635#> Specify the meaning of whitelist. When white means unblack, it unblacks IPs that are in blacklists; when white means trust, the packet gets bypassed, without further detection by snort. You can only specify either unblack or trust.

<#19636#><#19634#><#19609#><#19609#><#19634#><#19636#> Note: when white means unblack, whitelist always has higher priority than blacklist.

Configuration examples

verbatim390#
IP List File Format
<#19681#><#19643#><#19643#><#19681#> Syntax
<#19655#><#19654#><#19644#><#19644#><#19654#><#19655#> The IP list file has 1 entry per line. The entry can be either IP entry or comment.

<#19677#><#19656#><#19645#><#19645#><#19656#><#19677#> IP Entry
<#19667#><#19663#><#19657#><#19646#><#19646#><#19657#><#19663#><#19667#> CIDR notation #tex2html_wrap_inline6893#comments#tex2html_wrap_inline6895# line break.
<#19668#><#19664#><#19658#><#19647#><#19647#><#19658#><#19664#><#19668#> Example:
verbatim391#

<#19678#><#19659#><#19648#><#19648#><#19659#><#19678#> Comment
<#19674#><#19669#><#19660#><#19649#><#19649#><#19660#><#19669#><#19674#> The comment start with #
<#19675#><#19670#><#19661#><#19650#><#19650#><#19661#><#19670#><#19675#> # #tex2html_wrap_inline6897#comments#tex2html_wrap_inline6899#
<#19676#><#19671#><#19662#><#19651#><#19651#><#19662#><#19671#><#19676#> Example
verbatim392#

<#19682#><#19652#><#19652#><#19682#> IP List File Example
<#19680#><#19679#><#19653#><#19653#><#19679#><#19680#> 
verbatim393#

Use case
<#19685#><#19683#><#19683#><#19685#> A user wants to protect his/her network from unwanted/unknown IPs, only allowing some trusted IPs. Here is the configuration:
<#19686#><#19684#><#19684#><#19686#> 
verbatim394#

2.2.20.2 Events

Reputation preprocessor uses GID 136 to register events.
SID Description
1 Packet is blacklisted.
2 Packet is whitelisted.
3 Packet is inspected.

2.2.20.3 Shared memory support

<#19759#><#19697#><#19697#><#19759#> In order to minimize memory consumption when multiple Snort instances are running concurrently, we introduce the support of shared memory. After configured, all the snort instances share the same IP tables in shared memory.

<#19760#><#19698#><#19698#><#19760#> System requirement
<#19721#><#19720#><#19699#><#19699#><#19720#><#19721#> This feature is supported only in Linux.

<#19761#><#19700#><#19700#><#19761#> Build configuration

<#19723#><#19722#><#19701#><#19701#><#19722#><#19723#> A new option, --enable-shared-rep is introduced to ./configure command. This option enables the support for shared memory.

<#19762#><#19702#><#19702#><#19762#> Configuration

<#19745#><#19724#><#19703#><#19703#><#19724#><#19745#> shared_mem
<#19735#><#19732#><#19725#><#19704#><#19704#><#19725#><#19732#><#19735#> If the build supports shared memory, this configuration will enable shared memory. If this option isn't set, standard memory is used. This option must specify a path or directory where IP lists will be loaded in shared memory. One snort instance will create and maintain the shared IP lists. We use instance ID 1, specified in the snort -G option to be the master snort. All the other snort instances are clients (readers).

<#19736#><#19733#><#19726#><#19705#><#19705#><#19726#><#19733#><#19736#> Syntax
verbatim395#
<#19737#><#19734#><#19727#><#19706#><#19706#><#19727#><#19734#><#19737#> Examples
verbatim396#
<#19746#><#19728#><#19707#><#19707#><#19728#><#19746#> shared_refresh

<#19742#><#19738#><#19729#><#19708#><#19708#><#19729#><#19738#><#19742#> This option changes the period of checking new shared memory segment, in the unit of second. By default, the refresh rate is #tex2html_wrap_inline6901# seconds.

<#19743#><#19739#><#19730#><#19709#><#19709#><#19730#><#19739#><#19743#> Syntax
verbatim397#
<#19744#><#19740#><#19731#><#19710#><#19710#><#19731#><#19740#><#19744#> Examples
verbatim398#

<#19763#><#19711#><#19711#><#19763#> Steps to configure shared memory

  • When building Snort, add option --enable-shared-rep to ./configure
    For example:
    verbatim399#
  • Put your IP list file into a directory, where snort has full access.
    For example:

    verbatim400#

    In order to separate whitelist with blacklist, you need to specify whitelist with .wlf extension and blacklist with .blf extension.

  • In snort config file, specify shared memory support with the path to IP files.
    For example:

    verbatim401#

    If you want to change the period of checking new IP lists, add refresh period.
    For example:

    verbatim402#

  • Start shared memory master(writer) with -G 0 option. Note: only one master should be enabled.
  • Start shared memory clients (readers) with -G 1 or other IDs. Note: for one ID, only one snort instance should be enabled.
  • You will see the IP lists got loaded and shared across snort instances!

<#19764#><#19712#><#19712#><#19764#> Reload IP lists using control socket
  • Run snort using command line with option --cs-dir ;SPMlt;path;SPMgt; or configure snort with:
    verbatim403#
  • (Optional) you can create a version file named ;SPMldquo;IPRVersion.dat;SPMrdquo; in the IP list directory. This file helps managing reloading IP lists, by specifying a version. When the version isn't changed, IP lists will not be reloaded if they are already in shared memory. The version number should be a 32 bit number.
    For example:
    verbatim404#
  • In the ;SPMlt;snort root;SPMgt;/src/tools/control directory, you will find snort_control command if built with --enable-control-socket option.
  • Type the following command to reload IP lists. Before typing this command, make sure to update version file if you are using version file. The ;SPMlt;path;SPMgt; is the same path in first step.
    verbatim405#
<#19765#><#19713#><#19713#><#19765#> Using manifest file to manage loading (optional)
<#19753#><#19747#><#19714#><#19714#><#19747#><#19753#> Using manifest file, you can control the file loading sequence, action taken, and support zone based detection. You can create a manifest file named ;SPMldquo;zone.info;SPMrdquo; in the IP list directory.

<#19754#><#19748#><#19715#><#19715#><#19748#><#19754#> When Snort is signaled to load new lists, a manifest file is read first to determine which zones the IPs in each list are applicable to and what action to take per list (Block, White, Monitor).

<#19755#><#19749#><#19716#><#19716#><#19749#><#19755#> Files listed in manifest are loaded from top to bottom. You should put files that have higher priority first. In manifest file, you can put up to 255 files. Without manifest file, files will be loaded in alphabet order.

<#19756#><#19750#><#19717#><#19717#><#19750#><#19756#> Here's the format of the manifest file. Each line of the file has the following format:
verbatim406#

<#19757#><#19751#><#19718#><#19718#><#19751#><#19757#> Using manifest file, you can specify a new action called ;SPMldquo;monitor;SPMrdquo;, which indicates a packet needs to be inspected, but does not disable detection. This is different from ;SPMldquo;block;SPMrdquo; action, which disables further detection. This new action helps users evaluate their IP lists before applying it.
<#19758#><#19752#><#19719#><#19719#><#19752#><#19758#> An example manifest file:
verbatim407#