The CSV Lookup Plugin extracts data from a comma-separated values (CSV) file stored on the Enforce Server. The plugin uses data from the CSV file to populate custom attributes for an incident at the time the incident is generated.
The CSV Lookup Plugin receives a group of lookup parameters that contain data about an incident from the Enforce Server. One or more of the lookup parameters in the group is mapped to column heads in a CSV file. For example, the sender-email lookup parameter might be mapped to the Email column in the CSV file. The value in the lookup parameter is used as a key to find a matching value in the corresponding CSV column. When a match is found, the CSV row that contains the matching value provides the data that is returned to the Enforce Server. The Enforce Server uses the data in that row to populate the custom attributes for that incident. For example, if the sender-email lookup parameter contains the value mary.smith@mycompany.com, the plugin searches the Email column for a row that contains mary.smith@mycompany.com. That row is then used to provide the data to populate the custom attributes for the incident.
The CSV Lookup Plugin uses an in-memory database to process large files.
Mapping attributes and parameter keys to CSV fields:
To configure the CSV Lookup Plugin, you enter the execution code in the Attribute Mapping field. This code maps the lookup parameter keys and custom attributes to column headers in the CSV file. One or more attribute=column pairs is used to map the incident attributes to the column heads. The keys property in the attribute map identifies which columns to use for the lookup.
Here is an example CSV file attribute mapping:
attr.Store-ID=store-id
attr.Store\ Address=store_address
attr.incident-id=incident-id-key
attr.sender-email=sender-email-key
keys=sender-email-key:incident-id-keyWith this example in mind, adhere to the following syntactical rules when mapping the attributes to CSV file data.
Example and syntax :
1] attr.Store-ID=store-id
attr.attribute_name=column_head
---> Attributes map to column header names in attribute-column pairs.
Here, Store-ID is a custom attribute and store-id is a column header name in the CSV file.
2] attr.Store\ Address=store_address
attr.attribute\ name=column\ head
--> Spaces are allowed before and after the = sign (except for the LDAP Lookup Plugin).
Blank spaces in attribute and column names must be preceded by a backslash.
Here, the custom attribute is named Store Address.
3] attr.Store-ID=store-id
attr.Store\ Address=store_address
attr.attribute_name=column_head
attr.attribute_name=column_head
--> Each attribute-column pair is entered on a separate line.
4] attr.Store\ Address=STORE_ADDRESS
--> All syntax is case sensitive.
The identifier attr. must be lower case.
Incident attributes must match the system-definition string precisely.
5] attr.incident-id=incident-id-key
attr.sender-email=sender-email-key
attr.attribute_name=column_head
--> System attributes are mapped to column header names. The column name does not have to match the system attribute, nor does it require the word "key".
6] keys=sender-email-key:incident-id-key
keys=<column_name_1st>:column_name_2nd
--> Keys map the column name headers to the incident attribute keys you want to use to look up the attribute values. The keys map to the column header names, not to the incident attribute names. The order of appearance determines priority. Once the first incident is located in the CSV file, the other attributes are populated.
Requirements for creating the CSV file :
The CSV Lookup Plugin requires a CSV file that is stored on the Enforce Server.
When creating a CSV file, keep in mind the following requirements:
i) The first data row of the CSV file must contain column headers.
ii) Column header fields cannot be blank.
iii) Make sure that there are no white spaces at the end of the column header fields.
iv) Make sure that all rows have the same number of columns.
v) Each row of the file must be on a single, non-breaking line.
vi) One or more columns in the file are used as key-fields for data lookups. You specify in the attribute mapping which column heads are to be used as key fields. You also specify the key field search order. Common key fields typically include email address, Domain\UserName (for Endpoint incidents), and user name (for Storage incidents).
vii) The data values in the key field columns must be unique. If multiple columns are used as key fields (for example, EMP_EMAIL and USER_NAME), the combination of values in each row must be unique.
viii) Fields in data rows (other than the column header row) can be empty, but at least one key field in each row should contain data.
ix) The same type of delimiter must be used for all values in the column header and data rows.
x) If the CSV file is read-only, make sure that the CSV file has a new line at the end of the file. The system will attempt to add a new line to the file on execution of the plugin, but if the file is read-only the system cannot do this and the plugin will not load.
xi) For Discover scan incidents, the file-owner lookup parameter does not include a domain. To use file-owner as the key, the CSV file column that corresponds to file-owner should be in the format owner. The format DOMAIN\owner does not result in a successful lookup. This restriction only applies to Discover incidents, other kinds of incidents can include a domain.
For example, the column-header row and a data-row of a pipe-delimited CSV file might look like:
email|first_name|last_name|domain_user_name|user_name|department|manager|manager_emailjsmith@acme.com|John|Smith|CORP\jsmith1
|jsmith1|Accounting|Mei Wong|mwong@acme.com
if more than 10% of the rows in the CSV file violate any of these requirements, the Plugin does not load.
For accuracy in the lookup, the CSV file needs to be kept up to date.
Choosing the CSV file delimiter :
Use the Delimiter property to specify the CSV file delimiter.
The following delimiters are supported:
i) Comma
ii) Pipe
iii) Tab
iv) Semicolon
The recommended practice is to use the pipe character ("|") as the delimiter. Use of the comma delimiter is discouraged because commas are often included in data fields as part of the data. For example, a street address might contain a comma.
Specifying the CSV file path:
To configure the CSV Lookup Plugin you must specify the CSV File Path property for the location of the CSV file. The CSV file must be stored locally on the Enforce Server.
You can enter either an absolute file path or a relative file path. For example:
../../../../vontu_csv_lookup_file/senders2.csv
C:/vontu_csv_lookup_file/senders2.csv
On Windows you can use either forward or backward slashes. For example: C:/Vontu/Protect/plugins/employees.csv or C:\Vontu\Protect\plugins\employees.csv. On Linux you can only use forward slashes.
The system validates the file path when you save the configuration. If the system cannot locate the file it reports and error and does not let you save the configuration. Make sure that the CSV file is not open and is stored locally to the Enforce Server.
Selecting the CSV file character set :
You must specify the character set for the CSV file. The default is UTF-8.
All supported character sets are listed in the drop-down menu.