Security Information and Event Management (SIEM) Connector

Installing the Lookout SIEM Connector in your computing environment enables mobile threat and device events to flow into your SIEM instance. This enables the integration of mobile security threat, audit, and device events into your company’s security incident and event programs, as well as policies for action.

The Lookout SIEM Connector polls the RESTful Mobile Risk API every 30 seconds asking for new threat and device events that have occurred since the last successful poll. The app then writes the events into either the customer-configured syslog or directly to the receiver. You can then configure the various SIEM applications to obtain those events.

The Lookout SIEM Connector is a Docker image, compressed in TAR format, that you install into your environment.

Requirements, SIEM Connector

The Lookout SIEM Connector requires the following.

• 1 VM
• 2 GHz CPU
• 2 GB RAM
• 10 GB disk (~250 MB for the Docker image with JAR file and the remaining space for logging). If you plan to log with DEBUG information included, then you should allocate more disk space.
• Allow port 443

SIEM Application Configuration

The Lookout SIEM Connector supports these SIEM applications: ArcSight, QRadar, Splunk. You can configure ArcSight, QRadar, or Splunk using either a syslog receiver or a socket receiver.

Syslog Receiver

In this configuration, the Lookout SIEM Connector writes to a syslog server and the SIEM application then reads from the syslog.

Socket Receiver

In this configuration, the Lookout SIEM Connector writes to the SIEM application’s receiver directly.

Installation Prerequisites

Before you install the Lookout SIEM Connector, verify that your SIEM application configuration is done properly, for example, syslog/receiver is configured correctly and the ports are open. Take note of the following information about the destination of Lookout SIEM Connector events before you begin.

• Hostname or IP address
• Port
• Protocol
  • If SSL: keystore and trusted storage locations, passwords
  • If proxy: proxy hostname/IP, port, optional username/password

Install Docker

Docker is a free tool for creating, deploying, and running applications using containers. Docker is distributed under the Apache License 2.0. Install Docker for your environment’s operating system. Follow Docker’s installation instructions from https://docs.docker.com/engine/installation/.

NOTE: The Lookout SIEM Connector image is built with Docker version 1.12.2. However, you can install a newer Docker version since the connector is upward compatible.

Install the Lookout SIEM Connector

If you’re using QRadar, see the QRadar Installation Prerequisite section before starting this installation.

1. Download the SIEM connector to the machine where you installed Docker.

2. Load and tag the Docker image:

   1. Load the Docker image:

      $ docker load --input siem-connector-<version>.tar

      For example:

      $ docker load --input siem-connector-1.0.6-17.tar

      7cbcbac42c44: Loading layer 5.05 MB/5.05 MB
      675e192b8244: Loading layer 122.3 MB/122.3 MB
      aba29c42eb15: Loading layer 20.52 MB/20.52 MB
      Loaded image ID: Sha256:35f2d3578...
      

   2. Tag the Docker image as "lookoutsiem":

      $ docker tag <image ID> lookoutsiem

      For example:

      $ docker images

      REPOSITORY	TAG	IMAGE ID	CREATED	SIZE
      <none>	<none>	35f2d3578aa9	12 hours ago	145.2 MB

      $ docker tag 35f2d3578aa9 lookoutsiem

      $ docker images

      REPOSITORY	TAG	IMAGE ID	CREATED	SIZE
      lookoutsiem	latest	35f2d3578aa9	12 hours ago	145.2 MB

3. Create the configuration files.

   1. Create a directory to store the configuration files.

      For example (your directory location may vary, the "opt" syntax below is for Linux):

      $ mkdir -p /opt/lookoutsiem/configs

   2. Create a new application_key file in the /configs directory.

      From the Workspace ONE Mobile Threat Defense console you can obtain a generated application key. See Application Key File for the steps to obtain the application key. Create the application_key file using that generated key.

   3. Create a new app.properties file in the /configs directory.

      See Application Properties File for the fields you’ll need in this file.

4. Run the Docker image in a container and mount the /configs directory you previously created.

   NOTE: Consider adding this to a startup script so that the Docker image always runs at boot time. See the Docker documentation for details on using the --restart always flag when restarting containers.

   $ docker run -d --name <container_name> -v <config_directory>:/conf <image_tag>

   For example, to use the container name lookout, use the config directory /opt/lookoutsiem/configs, and the image tag lookoutsiem that you created in Step 3b:

   $ docker run -d --name lookout -v /opt/lookoutsiem/configs:/conf lookoutsiem

   To see your lookout container running use: $ docker ps -a

   CONTAINER ID	IMAGE	COMMAND	CREATED	STAT	PORTS	NAMES
   1c811c75d2c6	lookoutsiem	...	5 s...	Up 4...		lookout

Update the Lookout SIEM Connector

1. Download the SIEM connector to the machine where you installed Docker.

2. Load and tag the Docker image.

   1. Load the Docker image.

      $ docker load --input siem-connector-<version>.tar

   2. Get the image ID for the new version of the connector (bold in the example below).

      $ docker images

      REPOSITORY	TAG	IMAGE ID
      <host>/lookout/siem-connector	0.2.1-69	39b2d0e4b759

   3. Using the image ID, tag the new image with the lookoutsiem tag.

      $ docker tag 39b2d0e4b759 lookoutsiem

      This removes the tag from the previous version.

   4. Confirm the new image ID has the latest tag applied to the new lookoutsiem image.

      REPOSITORY	TAG	IMAGE ID
      <host>/lookout/siem-connector	0.2.1-69	39b2d0e4b759
      lookoutsiem	latest	39b2d0e4b759
      <host>/lookout/siem-connector	0.1.9-67	1c31132b5b0c

   5. List all running containers.

      $ docker ps -a
      CONTAINER ID IMAGE ... NAMES
      281e5ab1bf9c 1c31132b5b0c ... lookout
      35927f4aae90 32d34d8a93c9 ... lookout-v0.1.9-67
      

   6. Stop the existing lookout container.

      $ docker stop lookout

   7. Rename the existing lookout container with the version it was running.

      $ docker rename lookout lookout-v0.1.9-67

   8. Start a new lookout container running the latest image.

      $ docker run -d --restart always --name lookout -v
      /opt/lookoutsiem/configs:/conf lookoutsiem
      

   9. Confirm that the new image is running and the previous version image is stopped.

      $ docker ps -a

      ...	IMAGE	...	STATUS	NAMES
      ...	lookoutsiem	...	Up 7 seconds	lookout
      ...	1c31132b5b0c	...	Exited (137) 45 seconds ago	lookout-v0.1.9-67

Monitoring and Troubleshooting, SIEM Connector

Locate the Docker logs in their respective container at /logs/LOapp.log. To retrieve the tail of a container’s logs, use...

docker logs --follow <containerID>

or

docker logs --follow <containerNAME>

The most common errors for starting the application are firewall issues or a misconfigured app.properties file. Check to see if the application is running using the docker ps -a command.

Configuration Files, SIEM Connector

Two configuration files, app.properties and application_key, define the Lookout SIEM connector. Any modifications to these files require a restart of your Docker container. The configuration files are mounted to the Docker container in its /conf folder. You can restart your container using...

docker restart <containerNAME>

Application Properties File, SIEM Config

Your app.properties file must contain values for all properties shown as required. Others are optional and you’ll use them based on your deployment configuration and status, for example testing, production, etc.

A basic app.properties file might look like this...

connector.siemApp=splunk
connector.syslog.host=192.168.99.100
connector.syslog.port=2514
connector.syslog.protocol=tcp
connector.ent.name=YourCompanyName

Application Key File, SIEM Config

The Lookout SIEM Connector authenticates with the Lookout Mobile Risk API using OAuth 2.0. You need to have an application key specific to your Lookout tenant to properly configure your SIEM environment.

You store your key value in the Lookout Mobile Risk API application_key file in your Docker container.

To retrieve your application key:

1. Log into the Workspace ONE Mobile Threat Defense console as an administrator.

2. Select System > Application Keys.

   NOTE: If you don’t see the Application Keys tab, contact Omnissa Support to enable this feature for you.

   

3. Select Generate an application key and specify your label name.

4. Copy your generated key by selecting Click to Copy Application Key to Clipboard. This key is unique for the data in your lookout tenant.

   

5. Switch to your Docker container and pull up the application key file.

6. Paste (Ctrl-V) the key from your clipboard into the application_key file on your Docker container.

   IMPORTANT: Ensure that you paste the generated key to the application_key file immediately since you will not be able to see the key again after this procedure.

QRadar Installation Prerequisite

QRadar SIEM requires additional configuration prior to the Lookout SIEM Connector installation.

1. Download lookout_qradar_config.xml. This file contains QIDs, DSM IDs, and custom properties that allow QRadar to recognize MTD events correctly.

2. Save this XML file to your QRadar instance and import it using the Content Management script.

   /opt/qradar/bin/contentManagement.pl -a import -f
   <path>/lookout_qradar_config.xml
   

   Verify that the import was successful. You should see a QRadar message similar to:

   [INFO] Initializing Content Management Tool...
   [INFO] (ContentManagementCLI) Start Time: 2018-01-17 14:04:35
   [INFO] Starting import process
   [INFO] Summary of content found in bundle:
   [INFO] 		Content Type - [Number of items]
   [INFO] 		- dsmevent - [7]
   [INFO] 		- ariel_property_expression - [48]
   [INFO] 		- ariel_regex_property - [32]
   [INFO] 		- qidmap - [7]
   [INFO] Summary of import/update operation:
   [INFO] 		Content Type - [Number of items]
   [INFO] 		Imported/Updated Content Summary -
   [INFO] 		- ariel_regex_property - [32]
   [INFO] 		- ariel_property_expression - [48]
   [INFO] 		- qidmap - [1]
   [INFO] 		- dsmevent - [7]
   [INFO] 		Skipped Content Summary -
   [INFO] 		- qidmap - [6]
   [INFO] 		Failed Content Summary -
   [INFO] 		-- No content failed
   [INFO] Reloading sytem components, please wait
   [INFO] Sending component reload notification
   [INFO] SUCCESS: The import completed successfully. Please allow several minutes for components to finish reloading.
   

For more QRadar information refer to the following IBM documentation: https://www.ibm.com/docs/en/qradar-on-cloud?topic=content-methods-importing-exporting.

3. Enter the IP of the Log Source Identifier as the Docker container’s IP. See this IBM documentation to configure it: https://www.ibm.com/support/knowledgecenter/SSCQGF_7.2.0.1/com.ibm.IBMDI.doc_7.2.0.1/rg_conn_qradar_log_source.html.

4. Add an additional property to the Lookout SIEM Connector app.properties file with the IP address from the previous step. See the Application Properties File section for details.

   connector.qradar.logSourceIdentifier=<IP address>

Update QRadar Configuration

Before uploading a new version of the lookout_qradar_config.xml file, you must delete the existing mappings.

1. Delete the existing mappings:

   a. In QRadar, select the Admin tab.

   b. In the sidebar, go to Data Sources > Events and select Custom Event Properties in the Events pane.

   c. In the Search Properties... field, enter lookout

   d. Multiselect all of the resulting fields that begin with “lookout” or “Lookout” and select Delete.

    ![This screenshot shows the Custom Event Properties screen in QRadar](images/MTD_QRadar_Custom_Event_Properties.png)
   

2. Upload the new mapping file as documented in the QRadar Installation Prerequisite topic.

Event Fields

This section describes the contents of mobile threat and device events generated by the Lookout Mobile Risk API. There is a section specific to the field mappings of each supported SIEM: ArcSight (CEF format), QRadar (LEEF format), and Splunk (syslog key-value format).

NOTE: You can enable privacy controls for your Lookout tenant to prevent certain event field data from being mapped into your SIEM. An asterisk (*) denotes fields that you can make private. Contact Omnissa Support to enable privacy for your Lookout tenant.

ArcSight (CEF) Fields

This section shows the mapping of Lookout event fields into ArcSight (CEF) fields. If you are using another SIEM that takes CEF format fields, it must support at least 6 custom Strings and 1 custom integer so that Lookout can populate the entity name, SSID, device protection status, security status, activation status, MDM ID, and VPN status.

Common Fields, ArcSight

These fields are present in all Lookout events.

Threat Event Common Fields, ArcSight

These fields exist in the details of Lookout events where event.type=THREAT.

Network Threat Fields, ArcSight

These fields exist in the details of Lookout threat events where event.details.type=NETWORK.

* Indicates a field that is omitted when you enable privacy controls.

Application and File Threat Fields, ArcSight

These fields exist in the details of Lookout threat events where event.details.type=APPLICATION or =FILE.

Configuration Threat Fields, ArcSight

These fields exist in the details of Lookout threat events where event.details.type=CONFIGURATION.

OS Threat Fields, ArcSight

These fields exist in the details of Lookout threat events where event.details.type=OS.

Web Content Threat Fields, ArcSight

These fields exist in the details of Lookout threat events where event.details.type=WEB_CONTENT.

Device Event Common Fields, ArcSight

These fields exist in the details of Lookout events where event.type=DEVICE.

Device Target Fields, ArcSight

These fields exist in the target details of individual Lookout device events.

* Indicates a field that is omitted when you enable privacy controls.

QRadar (LEEF) Fields

This section shows the mapping of Lookout event fields into QRadar (LEEF) fields.

Common Fields, QRadar

These fields are present in all Lookout events.

Threat Event Common Fields, QRadar

These fields exist in the details of all Lookout events where event.type=THREAT.

Network Threat Fields, QRadar

These fields exist in the details of Lookout threat events where event.details.type=NETWORK.

* Indicates a field that is omitted when you enable privacy controls.

Application and File Threat Fields, QRadar

These fields exist in the details of Lookout threat events where event.details.type=APPLICATION or =FILE.

Configuration Threat Fields, QRadar

These fields exist in the details of Lookout threat events where event.details.type=CONFIGURATION.

OS Threat Fields, QRadar

These fields exist in the details of Lookout threat events where event.details.type=OS.

Web Content Threat Fields, QRadar

These fields exist in the details of Lookout threat events where event.details.type=WEB_CONTENT.

Device Event Common Fields, QRadar

These fields exist in the details of Lookout device events where event.type=DEVICE.

Device Target Fields, QRadar

These fields exist in the target details of individual Lookout device events.

* Indicates a field that is omitted when you enable privacy controls.

Splunk (syslog) Fields

This section shows the syslog mappings of Lookout event fields into key-value fields.

Common Fields, Splunk

These fields are present in all Lookout events.

Threat Event Common Fields, Splunk

These fields exist in the details of Lookout events where event.type=THREAT.

Network Threat Fields, Splunk

These fields exist in the details of Lookout threat events where event.details.type=NETWORK.

* Indicates a field that is omitted when you enable privacy controls.

Application and File Threat Fields, Splunk

These fields exist in the details of Lookout threat events where event.details.type=APPLICATION or =FILE.

Configuration Threat Fields, Splunk

These fields exist in the details of Lookout threat events where event.details.type=CONFIGURATION.

OS Threat Fields, Splunk

These fields exist in the details of Lookout threat events where event.details.type=OS.

Web Content Threat Fields, Splunk

These fields exist in the details of Lookout threat events where event.details.type=WEB_CONTENT.

Device Event Common Fields, Splunk

These fields exist in the details of Lookout device events where event.type=DEVICE.

Device Target Fields, Splunk

These fields exist in the target details of individual Lookout device events.

* Indicates a field that is omitted when you enable privacy controls.

Errors

The SIEM connector writes internal errors to the log file specified in the app.properties configuration file (see the Configuration files section). Errors are also written to your SIEM instance, unless the error relates to the connector not contacting your SIEM instance.

ArcSight (CEF) Error Mappings

The following is an example of a CEF format error event.

CEF:0|Lookout|SIEM Client|0.1|CLIENT|ERROR|HIGH|
devicePayloadId=437439f8-fb4a-43c0-95c5-4cc2a9688f27
start=2017-07-22T12:45:07 cs1=testEntName msg=Error while polling events
from Lookout Mobile Risk API

QRadar (LEEF) Error Mappings

The following is an example of a LEEF format error event.

LEEF:1.0|Lookout|SIEM Client|0.1|ERROR,CLIENT|lookoutSeverity=HIGH\t
lookoutId=437439f8-fb4a-43c0-95c5-4cc2a9688f27\tcat=CLIENT\t
lookoutEventTime=2017-03-22T12:45:07\tlookoutMsg=Error while polling
events from Lookout Mobile Risk API \tlookoutEntName=testEntName

Splunk (syslog) Error Mappings

The following is an example of a syslog format error event.

type=ERROR, id=437439f8-fb4a-43c0-95c5-4cc2a9688f27,
eventTime=2017-03-22T12:45:07, entName=testEntName, msg=Error while
polling events from Lookout Mobile Risk API