In the NetWitness Core database, the Rules tree holds the main functionality related to managing rules for all Core services that have rules: Concentrators, Decoders, Log Decoders, and Archivers. Although you can manage rules in the NetWitness Platform user interface, advanced users may prefer to manage rules using a command line to add, merge, replace, delete, and validate rules on a service. This section provides a brief overview of the commands and their usage. These are the available commands:

add - Adds a single rule at the specified position.

clear - Deletes all existing rules in the current node on the service. For example, using the command in /decoder/config/rules/application node deletes all existing application rules on the Decoder.

delete - Deletes one or more rules at a specified position and count.

merge - Merges a pushed rule set with an existing rule set. Existing rules that match the incoming rules (by name or rule) are replaced; otherwise, rules are inserted by the position indicated as described in merge Command.

replace - Deletes all existing rules and replaces them with the incoming rule set.

validate - Validates the syntax of a rule, but does not validate the meta keys.

add Command

The add command adds the rule to the existing rule set. Formatting is important because the API uses double quotes in the rule language and also uses double quotes as parameters to all RSA NetWitness® Platform APIs. Therefore, you must escape any double quotes in the rule itself by preceding it with a backslash (\) character. This is the syntax of the command:

Notice how all the double quotes had to be escaped inside the rule parameter. A simple trick to make this more readable is to use single quotes inside the rule. Single and double quotes are interchangeable in the rule and query language, but not in parameters for the API (only double quotes are supported there). Therefore, this is more readable:

merge Command

The merge command is used to merge an incoming list of rules with the existing rules on the service. This is how it works:

It finds existing rules that match via the name OR via a matching rule, updates the existing rule name, and keeps the same position.

It inserts new rules into the rule list based on the NUMBER position. If the number is zero, it goes to the top of the list.

It processes the rules in the order received so if you have two rules numbered zero, the second rule is processed after the first and claims the top spot. All existing rules are pushed down two places. Any numbers higher than existing rule positions are appended after the last existing rule and numbered in sequence.

Any non-numbered rule is appended after the last existing rule and numbered in sequence.

This is the syntax of the merge command:

merge --file-data=<string> --file-format<string>

file-data is the full path and name of the rules file to merge.

file-format is the format of the rules file. Valid values are params-list, string, params, binary, and params-binary.

Methods of Sending a List of Rules to a Service

There are two ways to send a list of rules. You can send them as a .nwr (NetWitness Rule) file or as a numbered set of parameters, each number indicates the position to insert the rule at as well as the encoded rule. If you want to see the current list of rules on a service, you need to run the ls command on the rule category (for instance, application rules on a Decoder are found in /decoder/config/rules/application).

This is an example of commands to list the existing rules using NwConsole:

login <hostname>:50004 <username> <password>

cd /decoder/config/rules/application

ls

This is another example to list existing rules in NwConsole:

send /decoder/config/rules/application ls

This is an example of the command to point to network rules in the RESTful port, which supports a basic admin HTML app.

http[s]://<decoder>:50104/decoder/config/rules/network

Send a NetWitness Rule File

Let's start with an example nwr file, each rule must be on a separate line:

The examples are pushing application rules. To push network rules, send the rules to /decoder/config/rules/network. For correlation rules, send the rules to /decoder/config/rules/correlation.

Send Numbered Parameters

The other way to send a list of rules is to send them as numbered parameters. The difficulty with this method is remembering to escape the quotes within each numbered rule. Though it is only a problem if you are trying to do it by hand. For instance, to send the same rules above as parameters via NwConsole, use the following command:

This command is hard to read because you have to escape the inner quotes with a backslash (\). Otherwise, these two commands accomplish the same thing. Merging or adding three rules in positions 1, 2 and 3. If you think the above was hard to read, this is what the equivalent curl command looks like:

For more details on how to escape double quotes inside parameters, see add Command.

Ordering Rules When Pushing

Pushed rules are ordered in one of two ways. When passing as parameters, the number of each parameter determines the insertion order. If it is not actually a number, merge checks for an order parameter within the rule itself and uses that value if found.

Note: Using order is the only way to set the order with a .nwr file. If neither a number nor an order parameter is found, there are no guarantees of the insertion order.

Example

A Decoder has the following application rules installed; notice the numbering is ALWAYS consecutive and starts at 1:

This rule had a non-number append for order, therefore, it went to the end of the list. You can accomplish the same thing by giving a very large number, like 999999.

4. rule="service=80,443" name=web filter order=3

This rule is last but has order=3, therefore, if it does not match an existing rule by name or the text of the rule itself, it should be placed in position 3. And there it is, the third rule in the list. Any rules that follow were pushed further down.

replace Command

The replace command removes all existing rules and replaces them with the incoming rule list. Refer to merge Command for details on how to format the incoming rule list and how ordering works.

This is an example of the replace command using a Netwitness Rule File :