000031300 - How to monitor if a meta index key is full in the RSA NetWitness Platform

Document created by RSA Customer Support Employee on Jun 14, 2016Last modified by RSA Customer Support on Oct 31, 2018
Version 8Show Document
  • View in full screen mode

Article Content

Article Number000031300
Applies ToRSA Product Set: Security Analytics, NetWitness Logs & Network
RSA Product/Service Type: Concentrator, Log Decoder
Platform: CentOS 6, CentOS 7
IssueEach meta key that is indexed in the RSA NetWitness Platform has a valueMax value associated with it. This is the maximum number of unique values that can be stored in the index for this meta key.

This is defined in the index-concentrator.xml and index-concentrator-custom.xml values on a Security Analytics concentrator.

For example:

<key description="Hostname Aliases" level="IndexValues" name="alias.host" format="Text" valueMax="2500000" />

This shows that the alias.host meta key can contain up to 2500000 unique values in an index slice.

If this value is exceeded, then the additional unique values will not be able to be seen when investigating, although it will still be recorded in the session information.

It is therefore important to be alerted if the index for the meta key is full.

In some cases, the number of unique values for a key may exceed any setting of ValueMax that is used. For example, if you were to index URLs seen by the system then the index for this meta key would become quickly full due to the large number of unique possible values. For source ports and destination ports for a TCP session then there is a maximum of 65536 possible values so the valueMax is set to this value.

When a meta key is full the following will be seen in /var/log/messages on the concentrator:

Sep 18 16:40:20 logconc nw[11922]: [Index] [warning] Index key alias.host has reached max capacity of 2500000 values and will ignore new values for this slice.
TasksWe wish to be alerted if a metakey becomes full so that we can plan accordingly. To do this

1. Install the RSA Security Analytics Parsers from RSA Link here:  https://community.rsa.com/docs/DOC-28866
2. Add the following message to the RSA Security Analytics parser above the </DEVICEMESSAGES> tag.

content="&lt;@event_description:Index Key Full&gt;[warning] Index key &lt;metakey&gt; has reached max capacity of &lt;fld2&gt; values and will ignore new values for this slice."/>

3. Add the following meta key to your concentrators in the  /etc/netwitness/ng/index-concentrator-custom.xml

<key description="Meta Keys" level="IndexValues" name="metakey" format="Text" valueMax="1000" />

4. Add the following to your Log Decoder at /etc/netwitness/ng/envision/etc/table-map-custom.xml

<mapping envisionName="metakey" nwName="metakey" flags="None" format="Text"/>

5. When the Index Key becomes full the event description "Index Key Full" will become populated.
User-added image
ResolutionIf an index key does become full then there are several options. 
  • Create more index slices
  • Increase the valueMax value for the IndexKey
  • Switch off indexing for the key
  • Do nothing - it may not be practical to capture all unique values for the key or it may be that all possible unique values have been captured.
The best option will depend on your environment and what you wish to achieve, so please contact RSA Customer Support if further advice is required.

Attached to this article is a pair of scripts to help report on your current index slices. Please note the index-profile.pl script is meant for 10.X releases while the index-profile.py is meant for 11.X releases. Please download and follow the instructions of the one that best fits your environment.

For Customers using version 10.X:
Please use the index-profile-10.X.zip file. This contains a perl script.
Usage: ./index-profile.pl concentrator_ip [out_file_name]
For example, to take an index profile snapshot every 30 min create a cron job for every concentrator as follows:

# Concentrators 1
0,30 * * * * /root/index-profile-1.2.pl <Concentrator1_IP> index-snap-1.csv >> index-snap-1.csv
# Concentrator 2
0,30 * * * * /root/index-profile-1.2.pl <Concentrator2_IP> index-snap-2.csv >> index-snap-2.csv

 This will generate a CSV file which then can be easily analyzed, so the optimal values of ValueMax, save.session.count or the index save scheduler can be worked out.   

The sample output:

For Customers using the 11.X release:
Please use the index-profile-11.X.zip file. This contains a python script.
The python version of this script is meant for 11.X and has all the same functionality as the first script as well as a couple more options. This script requires Python 2.7.14 and can work either on either the Concentrator device itself or on a Windows or Mac workstation with Python 2.7 installed. All of the options can be found by running the command with the "-h" option. Here is a sample output of what that would look like:

[root@localhost] ➤ ./index-profile.py -h
usage: index-profile.py [-h] [-f OUTPUTFILE] [--host HOST] [--port PORT] [-S]
                        [-u USERNAME] [-p PASSWORD] [--horizontal]
                        [--addHeaders] [-d]

Evaluate the status of the current index slices on the designated device. This
script returns a csv output/file that contains a listing on keys with their
undying usage of the most recent index slice they exist in. Note that if a key
is seldomly used, this may not be from the current slice. This value is
displayed as a percentage by default. The first number is the number of
sessions currently in this index slice. Think of this as the bookmark for our

optional arguments:
  -h, --help            show this help message and exit
                        Designate an output filename that will be a CSV.
                        (indexstatus.csv by default)
  --host HOST           Define the host that we will check the index on.
                        (localhost by default)
  --port PORT           Define the port that we will attempt to connect on the
                        host. (50105 by default)
  -S, -s, --SSL         Enable this if the REST Port is using SSL. (False by
  -u USERNAME, --username USERNAME
                        Define the user that will connect on the Service API
                        (admin by default)
  -p PASSWORD, --password PASSWORD
                        Define the password the user will use to connect to
                        the Service API (netwitness by default)
  --horizontal          Horizontal Output with raw values. Vertical/Default
                        output only puts percentages.
  --addHeaders          When appending an existing file, add the headers
                        before printing the next set of results again. This is
                        not necessary if the file is brand new
  -d, -D                Debug Mode: This really just helps out with what was collected when parsed from API.

While running on the concentrator itself, you may not need to pass any options at all if you are running a standard configuration. 
A couple things to note about this script:
  • The output is similar to the one you see from the 10.X Perl script.
  • A file is generated by default as well as standard output being generated. By default, this file is called "indexstatus.csv" and is written to the same directory the script is being executed from. The -f option can specify where this file is generated.
  • Please note that if your REST interface is using HTTPS, you must pass the -S option into the script. You can navigate to http://concentrator_ip:50105 or https://concentrator_ip:50105 respectively if you'd like to know which one you are currently using.
  • The password you use to login to admin in the UI may not be the same as the local service user account. Typically, this is admin/netwitness.
  • By default, if the file exists, the header information will not be appended a second time unless specified by the --addHeaders parameter.
  • There is a horizontal output option which will print output for each key in the following order if you want to see raw numbers: keyname,number of values occupying the last index file, valuemax, percentage used. Note: Horizontal is not compatible with appendHeaders.

You can do a similar thing with a cron job as in 10.X but like so:

# Concentrators 1 which has a non standard service username and password
0,30 * * * * /root/index-profile.py --host -u admin -p NETWITNESS11 -f /root/index-status-1.csv > /dev/null 2>&1
# Concentrator 2 which has an SSL REST API enabled
0,30 * * * * /root/index-profile.py --host  -S -f /root/index-status-2.csv > /dev/null 2>&1

NotesAll screenshots and hostnames are from an internal lab system.