Allowed Items CSV File Reference

You can use comma-separated value (CSV) files with Tripwire State Analyzer in a few ways:

When migrating from a Whitelist Profiler installation, you can import your WLP CSV files into TSA to create an initial set of Allowed Items.
You can manually create a list of approved configurations in a CSV file, then import that file to quickly add new Allowed Items.
To bulk edit Allowed Items, you can export them to CSV, manually edit the desired values, then import the file back into TSA.

Note:	Each Allowed Item in TSA must be unique. Specifically, when importing Allowed Items from a CSV file, each Item in the file must have at least one system-defined attribute value or scope that is different from an existing Allowed Item in TSA. User-Defined Attributes are not considered when comparing Allowed Items in CSV files to existing Allowed Items.

Allowlist CSV File Formatting

Each Allowlist CSV file created by TSA consists of a list of records. The first line in each file is the header record, and each of the remaining lines is called an allowlist record.

The header record specifies the field names for each record in the file. These fields may be required or optional, and may include User-Defined Attributes. In each header record, the required fields are listed before any optional fields, and each allowlist record must contain values for all required fields.
Each allowlist record defines an Allowed Item for a specific host or group of hosts. The first, required field for each allowlist record is an ItemID, which is a unique identifier for that record.

When importing a CSV file into TSA, if a record has an ItemID, TSA will update the corresponding Allowed Item. If the record does not have an ItemID, TSA will create a new Allowed Item with the values in that record.

Notes:	CSV files generated by Whitelist Profiler don't have an ItemID field, but an ItemID value is added to each record when the files are imported into TSA. If an allowlist record with the same ItemID appears more than once in a CSV file, TSA will only process the last instance of the record.

Notes:

CSV files generated by Whitelist Profiler don't have an ItemID field, but an ItemID value is added to each record when the files are imported into TSA.

If an allowlist record with the same ItemID appears more than once in a CSV file, TSA will only process the last instance of the record.

Some other things to know about editing Allowed Items CSV files:

These files support a number of special characters that control how they are interpreted.
When editing these files, you must use a text editor that supports UTF-8 character encoding. Otherwise, TSA cannot process the file.
Some required fields support Java regular expressions. For syntax conventions, see:
https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html#sum

Table 6. Special characters for Allowlist records
Character	Description
#	To direct TSA to ignore an allowlist record during processing, or to insert a comment, insert a pound sign (#) at the start of the line or in the Allowed Hosts field. Example: #This is a comment
,	To enter multiple fields, insert a comma (,) after each field. Example: Field A, Field B, Field C
;	To enter multiple values for a required field that supports multiple values, insert a semicolon (;) after each value. Example: Value A; Value B; Value C
"	Use double-quotation marks ("") to enclose literal values containing a comma, double-quotation mark, or a backslash. You also need to escape the character with a backslash (\) as described below. Example: To direct TSA to interpret the backslash in \Everyone as a literal value, rather than a special character, enter the following: "\\Everyone"
\	To escape a comma, double-quotation mark, or a backslash in a field value, insert a backslash (\) immediately before the character. You must also double-quote the value ("") as described above. Example 1: To escape the comma in Tripwire, Inc., enter: "Tripwire\, Inc." Example 2: To escape the double-quotation marks in Jonathan "John" Doe, enter: "Jonathan \"John\" Doe" Example 3: To escape the backslash in DOMAIN\User, enter: "DOMAIN\\User"
-	To exclude the following fields from report output, insert a minus sign (-) immediately before one of the following fields: Any field in a header record The ItemID or AllowedHosts fields for any allowlist record A name or regular expression in the Allowed Group Name(s) field for a Group Memberships record A name or regular expression in the Allowed Software Name(s) field for a Software record Example 1: To omit a group membership named Group A, enter: -Group A Example 2: To omit a software item named SoftwarePatch, enter: -SoftwarePatch
!	When entering a regular expression for a field that supports regular expressions, insert an exclamation mark (!) immediately before the field. Example: !.+(Svc\|Service)_.+

Required Fields for Allowlist CSV Files

About the Allowed Host(s) Field

Each allowlist record includes the required Allowed Host(s) field (see Required Fields for Allowlist CSV Files). This field indicates the monitored systems to which the corresponding Allowed Item applies.

The following values may be entered in the Allowed Host(s) field:

To apply the Allowed Item to any monitored system, enter ANY.
To apply the Allowed Item to a group of monitored systems, enter a Tag or Tag Set.
To apply the allowlist record to a specific monitored system, enter the system's hostname or IP address.

When importing Allowed Items, TSA applies the value from the Allowed Hosts field in this order:

If the imported value matches an existing asset in TSA, it is saved as the Allowed Item's Asset field.
If the imported value matches an existing Tag Set or Tag in TSA, it is saved as the Allowed Item's Tags field.
If the value doesn't match either of these, it is saved as the Allowed Item's Saved Filters field.

Table 7. Required fields for Allowlists
Allowlist Type	Required Fields
Group Memberships	Allowed Host(s) – See About the Allowed Host(s) Field. Allowed Group Name(s) – The name of the user group containing the member (i.e., a sub-group or a user account). Possible values include: The name of the user group. A regular expression that matches one or more user-group names (e.g. !^Domain Users.+). Allowed Member Name – The name of the member (i.e., a sub-group or a user account).
Open Ports	Allowed Host(s) – See About the Allowed Host(s) Field. Allowed Protocol – The communication protocol (TCP or UDP). Allowed Port(s) – The number of the open port. Possible values include: ANY to match any port number. A single port number (e.g. ‘22’). An inclusive range of ports separated by a hyphen (e.g. ‘1024-1027’). Allowed Process Name(s) – The name of the associated process. Possible values include: The name of the process (e.g. svchost.exe). All associated service names delimited by semicolons (e.g. RpcSS). A regular expression that matches one or more process names (e.g. !^No associated process (PID.+)). A regular expression that matches all service names (e.g. !^(service1\|service2)). Allowed Service Name(s) – The name(s) of the service(s) to allow. Possible values include: The name of a service. A regular expression that matches one or more service names. For example: !.+(Svc\|Service)_.+
Routes	Allowed Host(s) – See About the Allowed Host(s) Field. Allowed Network – The hostname or IP address of the host or network. Allowed Netmask – The netmask (or subnet mask) of the host or network. Allowed Gateway – The IP address of the gateway through which the monitored system accesses the host or network.
Services	Allowed Host(s) – See About the Allowed Host(s) Field. Allowed Service Name(s) – The name(s) of the service(s) to allow. Possible values include: The name of a service. A regular expression that matches one or more service names. For example: !.+(Svc\|Service)_.+
Shares	Allowed Host(s) – See About the Allowed Host(s) Field. Allowed Share Name – The name of the shared directory. Allowed Path – The path to the shared directory. Allowed User – The name of the user account or user group with access to the shared directory. Allowed Permissions – The permissions granted to the user account or user group.
Software	Allowed Host(s) – See About the Allowed Host(s) Field. Allowed Software Name(s) – The name of the software item. Possible values include: The name of the software item (i.e., an operating system, application, patch, or utility). A regular expression that matches the names of one or more software items (e.g. !^Java 8 Update \\d+ \$64-bit\$$). Required Version(s) – The required version of the software item. Possible values include: ANY (to match any version). NO VERSION DISCOVERED (to match an unknown version). The required version. A list of multiple required versions. Notes for the Required Version(s) field: If a single required version is specified, the software item will be authorized by TSA based on the matching strategy of the Required Versions Attribute. By default, this matching strategy is Greater than or Equal To, so the item will be authorized by TSA if its version is greater than or equal to the required version. If the software item's version and/or the required version contain characters other than numbers, the software item will only be authorized by TSA if the versions match exactly. If multiple required versions are specified, the software item will be authorized by TSA if its version exactly matches any of the required versions.
Users	Allowed Host(s) – See About the Allowed Host(s) Field. Allowed Username – The name of the user account. Allowed Password Age – The maximum number of days permitted for the password of the user account. Possible values include: The maximum permitted age of the password (in days). Any non-integer value, which permits the password to be any age (e.g. ‘Exception #123’).