Forcepoint Cloud Security Gateway and Splunk

Table of contents
  1. Forcepoint Cloud Security Gateway and Splunk
  2. Summary
    1. Demo
    2. Source Code
    3. Caveats
    4. Implementation
  3. Register a user in AWS and retrieve credentials
  4. Configure SIEM Integration inside Forcepoint Cloud Security Gateway
    1. Log Export permissions
    2. Switch logs storage to Amazon S3
  5. Setup Forcepoint App inside Splunk
    1. Setup receiving port on the Splunk instance.
    2. Extra steps for distributed Splunk components
  6. Implementation – Docker
    1. Setup Splunk Universal Forwarder for Forcepoint Products
    2. Setup Forcepoint Cloud Security Gateway Log Importer Service
  7. Troubleshooting
    1. Docker Implementation
      1. Validate the prerequisites
      2. Check network connectivity
      3. Check dependencies are installed
      4. Check all components are configured and running properly
License

These contents are licensed under Apache License, Version 2.0. http://www.apache.org/licenses/LICENSE-2.0

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SITE AND ITS CONTENT IS PROVIDED TO YOU ON AN “AS IS,” “AS AVAILABLE” AND “WHERE-IS” BASIS. ALL CONDITIONS, REPRESENTATIONS AND WARRANTIES WITH RESPECT TO THE SITE OR ITS CONTENT, WHETHER EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT OF THIRD PARTY RIGHTS, ARE HEREBY DISCLAIMED

Document Revision
Version Date Author Notes
0.1 14 September 2020 Rabih Abou Fakher First draft
0.2 17 September 2020 Neelima Rai Added Troubleshooting chapter
0.3 18 September 2020 Mattia Maggioli Review
0.4 21 May 2021 Rabih Abou Fakher Update commands and URL’s

Summary

This guide provides step by step instructions to configure an integration between Forcepoint Cloud Security Gateway and Splunk so that insights and data contained into Cloud Security Gateway logs for Web and Email security are automatically exported, indexed and visualized in Splunk.

A description of the workflow between the components involved in this POC is depicted in this diagram:

Demo

Source Code

fp-bd-splunk-app

fp-bd-splunk-universal-forwarder

fp-bd-log-import-service

Caveats

These implementation instructions are tested with the following product versions:

  • Forcepoint Cloud Security Gateway – as of September 2020

  • Splunk Enterprise 8.0.4.1

This integration is developed using the Bring Your Own Storage feature of Forcepoint Cloud Security Gateway. It is therefore assumed that Forcepoint Cloud Security Gateway logs are stored within an Amazon S3 bucket. Instructions are provided in this document to switch from the default log storage (Forcepoint storage) to Amazon S3: the user must configure storage to Amazon S3 in order to avail of this integration.

The following activities are out of the scope of this document and therefore left to the system administrator, as part of ordinary maintenance procedures to be put in place within the existing infrastructure:

  • Monitoring of the scripts, services and applications involved in the solution

Implementation

Two implementation options are provided in this document

  • Docker – leverages a docker image where the integration component is already installed with all necessary dependencies: the user must only edit the configuration files and run the container on an existing docker setup

The docker images have been tested working with the following requirements

  • Docker 19.03.5

  • The docker host machine should meet the minimum hardware requirements of at least 50 GB of free storage, 2 GB of RAM and a 64-bit system

  • User needs sudo permissions in the docker host machine

The files needed to set up the integration are available at the following links:

Register a user in AWS and retrieve credentials

To create a user, set required polices, and retrieve the user’s credentials do the following steps:

  1. Sign into the AWS Management Console and open the Amazon IAM console

  2. Open the Users section and click Add User in the top left

  3. Enter a name for the new user and select Programmatic access in the Access type section

  4. Click on Next: Permissions

  5. Select Attach existing policies directly and search for AmazonS3FullAccess

  6. Select AmazonS3FullAccess and click Next: Tags

  7. Add tags if required by your organization policies (tags are not required by this integration)

  8. Review the details and then click Create user

  9. In the next screen you will be presented with your new user along with your Access key ID and Secret access key: save these or the CSV file in a secure location. This is the only time the Secret access key will be available.

Configure SIEM Integration inside Forcepoint Cloud Security Gateway

Log Export permissions

Ensure your account has Log Export permission.

  1. Login to the Forcepoint Cloud Security Gateway portal

  2. Click ACCOUNT > Contacts

  3. Under the User Name column, find your username and click on it.

  4. In the Account Permissions section, ensure the Log Export box is clicked.

  5. Click Save

Enable SIEM Logging

In your Security Portal, navigate to Reporting > Account Reports > SIEM Integration

To export web/email logs do the following steps:

  1. Select Web Security as a data type:

  1. Enable data export:

  1. From the Attributes section, drag and drop the following attributes into the columns section:

    • Risk Class

    • Action

    • User

    • Policy

    • Category

    • Domain

    • Protocol

    • URL – Full

    • Cloud App

    • Cloud App Category

    • Cloud App Risk Level

    • Connection IP

    • Connection IP City

    • Connection IP Country

    • Connection Name

    • Destination IP

    • Source IP

    • Analytic Name

    • File Sandbox Status

    • Severity

    • Threat Name

    • Threat Type

    • Date & Time

    • File Name

    • File Type

    • Operating System

    • User Agent

    • Authentication Method

    • Classification Type

    • Date Center

    • Filtering Source

    • HTTP Status Code

    • Request Method

    • Bytes Received

    • Bytes Sent

Make sure all the above attributes are selected and DO NOT remove any of these attributes from the columns section: data ingest and visualization will not work as expected if data are missing.

  1. Click Save

  2. Change Data type to Email Security

  3. Enable data export

  4. From the Attributes section, drag and drop the following attributes into the columns section:

    • Direction

    • From: Address

    • Policy

    • Recipient Address

    • Recipient Domain

    • Sender Domain

    • Sender Name

    • Subject

    • Action

    • Black/Whitelisted

    • Blocked Attachment Ext

    • Filtering Reason

    • Sender IP

    • Sender IP Country

    • Attachment File Type

    • Attachment Filename

    • Emb. URL Risk Class

    • Emb. URL Severity

    • Advanced Encryption

    • File Sandbox status

    • Virus Name

    • Date & Time

    • Message Size

    • Spam score

    • Attachment Size

Make sure all the above attributes are selected and DO NOT remove any of these attributes from the columns section: data ingest and visualization will not work as expected if data are missing.

  1. Click Save

Switch logs storage to Amazon S3

As described in the Summary chapter of this document, Forcepoint Cloud Security Gateway web/email logs are expected to be stored within an Amazon S3 bucket using the Bring Your Own Storage feature of Forcepoint Cloud Security Gateway.

To switch logs storage from the default location into Amazon S3 please follow the instructions in the UI of Forcepoint Cloud Security Gateway or in the SIEM Guide at this link https://www.websense.com/content/support/library/web/hosted/siem_guide/cloud_SIEM_Guide.pdf

To create a new Amazon S3 bucket follow these steps:

  1. Sign into the AWS Management Console and open the Amazon S3 console

  2. Choose Create bucket.

  3. In Bucket’s name, enter a DNS-compliant name for your bucket. The bucket name must:

    • Be unique across all of Amazon S3.

    • Be between 3 and 63 characters long

    • Not contain uppercase characters.

    • Start with a lowercase letter or number.

  4. In Region, choose the AWS Region.

  5. Click Create

  6. Modify <CSG-AWS-Account-ID> and place the json content below into the bucket policy. Note the Resource value has to match the bucket name created in the step above e.g. in the example below the bucket name is forcepoint-csg-logs and the prefix is log_files

  {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<CSG-AWS-Account-ID>:root"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::forcepoint-csg-logs/log_files/*"
        }
    ]
  }

Once SIEM Integration is configured with your Amazon S3 bucket, any new web/email log generated by Forcepoint Cloud Security Gateway will be sent to your S3 bucket. Our Log Exporter component will fetch the logs from the S3 bucket.

Setup Forcepoint App inside Splunk

In order to install the Forcepoint app in Splunk

  1. Login to the machine hosting Splunk Enterprise with a user who has administrative privileges.

  2. Download the fp-splunk-app package and extract its contents into the /opt/ directory by executing the command below

    PUBLIC_REPO_NAME=fp-bd-splunk-app; \
    DEPLOYMENT_NAME=fp-splunk-app-v.*.tar.gz; \
    LATEST_VERSION=$(curl -sL "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/latest" | grep "$DEPLOYMENT_NAME" | head -1 | grep -E -o "/v.{0,5}" | cut -c 3-); \
    CODE_VERSION=$(curl -sL "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/latest" | grep -E -o "$DEPLOYMENT_NAME" | head -1 | rev | cut -c 8- | awk -F\v- '{print $1}'); \
    DEPLOYMENT_NAME_WITH_VERSION=$(echo "${DEPLOYMENT_NAME::-9}$CODE_VERSION.tar.gz"); \
    wget --content-disposition "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/download/v$LATEST_VERSION/$DEPLOYMENT_NAME_WITH_VERSION" && \
    sudo tar -zxvf $DEPLOYMENT_NAME_WITH_VERSION -C /opt/ && rm -f ./$DEPLOYMENT_NAME_WITH_VERSION*
    
  3. Copy forcepoint-solutions directory in the Splunk instance apps directory, then restart Splunk service by executing the command below:

    sudo cp -r /opt/fp-splunk-app/forcepoint-solutions $SPLUNK_HOME/etc/apps/; \
    sudo $SPLUNK_HOME/bin/splunk restart
    

Once Splunk has restarted you’ll be able to see Forcepoint under the Apps tab.

Setup receiving port on the Splunk instance.

Forcepoint logs are ingested into Splunk using a port on the local Splunk machine necessary to receive traffic generated by the Universal Forwarder component. In order to configure the receiving port

  1. Click on Settings > Forwarding and receiving > Configure receiving

  2. Click New Receiving Port > Type the port number (e.g. 9997) > Save

Note: the receiving port must be accessible from the network location of the Universal Forwarder component. Make sure any firewall or network device is configured appropriately to allow the necessary traffic.

Extra steps for distributed Splunk components

If Splunk is deployed in a distributed environment where the search head and the indexer components are deployed in different machines, please follow these additional instructions and repeat the following steps for each indexer machine deployed on the cluster:

  1. If it does not exist already, create the props.conf file in the folder $SPLUNK_HOME/etc/system/local/

  2. Edit props.conf and append the following configurations:

    [cloud-access-security-broker]
    category=Custom
    description=Forcepoint Cloud Access Security Broker Logs
    SHOULD_LINEMERGE=false
    LINE_BREAKER=([\r\n]+)
    NO_BINARY_CHECK=true
    CHARSET=UTF-8
    disabled=false
    KV_MODE = none
    EXTRACT-cef-message = CEF:\d\|(?<vendor>[^\|]+)\|(?<product>[^\|]+)\|(?<version>[^\|]+)\|(?<signature_id>[^\|]+)\|(?<signature>[^\|]+)\|(?<vendor_severity>[^\|]+)\|(?<cef_message>.*)
    REPORT-parse_cef = cef_auto_kv_fp,cef_auto_kv_fp_last
    TIME_FORMAT=%s%3N
    TIME_PREFIX=start\=
    
    [next-generation-firewall]
    SEDCMD-remove = s/(<6>)//g
    NO_BINARY_CHECK = 1
    pulldown_type = 1
    REPORT-xmlkv = xmlkv-alternative
    TIME_PREFIX=<TIMESTAMP>
    category=Custom
    description=Forcepoint Next Generation Firewall Logs
    
    [cloud-security-gateway]
    SHOULD_LINEMERGE=false
    LINE_BREAKER=([\r\n]+)
    NO_BINARY_CHECK=true
    CHARSET=UTF-8
    INDEXED_EXTRACTIONS=CSV
    KV_MODE=none
    category=Custom
    description=Forcepoint Cloud Security Gateway Logs
    disabled=false
    pulldown_type=true
    
    [private-access]
    TRANSFORMS-null=setnull
    LINE_BREAKER=([\r\n]+)
    SHOULD_LINEMERGE=false
    NO_BINARY_CHECK=true
    category=Custom
    description=Forcepoint Private Access Logs
    disabled=false
    pulldown_type=true
    TIME_FORMAT=%Y-%m-%dT%H:%M:%S.%3N%Z
    TIME_PREFIX="timestamp": "
    
  3. If it does not exist already, create the indexes.conf file in the folder $SPLUNK_HOME/etc/system/local/

  4. Edit indexes.conf and append the following configurations:

    [forcepoint]
    coldPath = $SPLUNK_DB/forcepoint/colddb
    enableDataIntegrityControl = 0
    enableTsidxReduction = 0
    homePath = $SPLUNK_DB/forcepoint/db
    maxTotalDataSizeMB = 512000
    thawedPath = $SPLUNK_DB/forcepoint/thaweddb
    
  5. If it does not exist already, create the transforms.conf file in the folder $SPLUNK_HOME/etc/system/local/

  6. Edit transforms.conf and append the following configurations:

    [setnull]
     REGEX = Node-internal
     DEST_KEY = queue
     FORMAT = nullQueue
    
    [xmlkv-alternative]
     REGEX = <([^\s\>]*)[^\>]*\>([^<]*)\<\/\1\>
     FORMAT = $1::$2
    
    [cef_auto_kv_fp]
     SOURCE_KEY = cef_message
     REGEX = (AD.\w+|\w+)=([^=]+)(?=\s+\w+=*)
     FORMAT = $1::$2
    
    [cef_auto_kv_fp_last]
     SOURCE_KEY = cef_message
     REGEX = (AD.\w+|\w+)=([^=]+)$
     FORMAT = $1::$2
    
  7. Log in with the user account running Splunk processes and run the below command:

    $SPLUNK_HOME/bin/splunk restart 

Implementation – Docker

Setup Splunk Universal Forwarder for Forcepoint Products

The Splunk Universal Forwarder is used to forward Forcepoint Products logs to the Splunk indexer.

Note: The Splunk Universal Forwarder for Forcepoint Products must be able to access the receiving host on the port defined in the Setup receiving port on the Splunk instance chapter.

  1. Login into docker repository, you’ll be asked to enter your username and password (provided below):

      docker login docker.frcpnt.com
    
      $ Username: fp-integrations
      $ Password: t1knmAkn19s
    
  2. Run the container with the command below, replacing:

    1. <universal-forwarder-password-of-your-choice> with a password of your choice (minimum of 8 characters)
    2. <splunk-indexer-ip-address> with the Splunk indexer receiving IP address
    3. <splunk-indexer-receiving-port> with the splunk indexer receiving port number
       docker run --detach \
         --env "SPLUNK_START_ARGS=--accept-license" \
         --env "SPLUNK_PASSWORD=<universal-forwarder-password-of-your-choice>" \
         --env "SPLUNK_INDEXER_IP_ADDRESS=<splunk-indexer-ip-address>" \
         --env "SPLUNK_INDEXER_RECEIVING_PORT=<splunk-indexer-receiving-port>" \
         --env "FP_ENABLE_CSG_FORWARD=true" \
         --name fp-csg-splunk-universal-forwarder \
         --restart always \
         --volume FpLogsVolume:/app/forcepoint-logs:ro \
         docker.frcpnt.com/fp-splunk-universal-forwarder
    

Setup Forcepoint Cloud Security Gateway Log Importer Service

The Forcepoint Cloud Security Gateway log importer service is used to download the Forcepoint Cloud Security Gateway logs from the S3 bucket.

  1. Download setup-aws-credentials script into the /opt/fp-aws-log-import-service directory by executing the command below:

    PUBLIC_REPO_NAME=fp-bd-log-import-service; \
    DEPLOYMENT_NAME=setup-aws-credentials.sh; \
    LATEST_VERSION=$(curl -sL "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/latest" | grep  "$DEPLOYMENT_NAME" | head -1 | grep -E -o "/v.{0,5}" | cut -c 3-); \
    mkdir -p /opt/fp-aws-log-import-service 2> /dev/null; \
    rm -f /opt/fp-aws-log-import-service/$DEPLOYMENT_NAME* 2> /dev/null; \
    wget --content-disposition "https://github.com/Forcepoint/$PUBLIC_REPO_NAME/releases/download/v$LATEST_VERSION/$DEPLOYMENT_NAME" \
    --directory-prefix=/opt/fp-aws-log-import-service/
    
  2. Provide the AWS credentials necessary to access Forcepoint Cloud Security Gateway logs: the script will ask you to enter the AWS Access Key ID and the AWS Secret Key created as instructed in the Register a user in AWS and retrieve credentials chapter, run the command below:

    sudo chmod +x /opt/fp-aws-log-import-service/setup-aws-credentials.sh; \
    /opt/fp-aws-log-import-service/setup-aws-credentials.sh
    
  3. Login into docker repository, you’ll be asked to enter your username and password (provided below):

      docker login docker.frcpnt.com
    
      $ Username: fp-integrations
      $ Password: t1knmAkn19s
    
  4. Run the container with the command below, replacing: <AWS-S3-Bucket-Name> with the S3 bucket name

       docker run --detach \
         --env "CSG_S3_URL=s3://<AWS-S3-Bucket-Name>" \
         --env "FP_ENABLE_CSG_SYNC=true" \
         --name fp-csg-aws-log-import-service \
         --restart always \
         --volume /opt/fp-aws-log-import-service/.aws:/root/.aws \
         --volume FpLogsVolume:/forcepoint-logs \
         --volume FpErrorLogsVolume:/app/fp-aws-log-import-service/logs \
         docker.frcpnt.com/fp-aws-log-import-service
    

Troubleshooting

Follow these steps to identify issues impacting the normal operation of the integration described in this document.

Docker Implementation

Validate the prerequisites

Make sure the prerequisites described in the Summary chapter are all satisfied:

  • Check the version of Splunk in use is listed as compatible

    Splunk Enterprise 8.0.4.1
    
  • The host machine should have Docker 19.03.5 installed

  • The docker host machine should meet the minimum hardware requirements of 2GB RAM, 50GB free storage and the system needs to be 64-bit

  • User needs sudo permissions in the docker host machine

  • Check the user can download the required files with the link below:

      https://github.com/Forcepoint/fp-bd-splunk-app/releases/latest
      https://github.com/Forcepoint/fp-bd-log-import-service/releases/latest
    

Check network connectivity

Make sure firewalls or other security appliances are not impacting the network connectivity necessary for the operation of all components involved in this integration:

  • Check the host machine has connectivity to the internet: execute the following command on the Docker host machine:

    ping -c 2 www.aws.com

Once done check the result is similar to below:

PING www.aws.com (10.10.120.12) 56(84) bytes of data.
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=179 ms
64 bytes from 10.10.120.12 (10.10.120.12): icmp_seq=1 ttl=128 time=181 ms

Check dependencies are installed

Make sure the software dependencies needed by the components involved in this integration are installed:

  • Check the host machine has docker installed: Execute the following command on the host machine:

    docker info

Check the first few lines of the output are similar to below:

Client:
Debug Mode: false

Server:
Containers: 3
Running: 2
Paused: 0
Stopped: 1
Images: 3
 **Server Version: 19.03.5**

Check all components are configured and running properly

Make sure the products and services involved in this integration are configured as expected and they are running:

  • Check the splunk fp-csg-aws-log-import-service is forwarding data with no errors with the following command:
sudo cat /var/lib/docker/volumes/FpCsgErrorLogsVolume/_data/sync-errors.log

Check the output does not contain error messages.

  • Check the splunk fp-csg-splunk-universal-forwarder service is running.

    docker exec -it -u splunk fp-csg-splunk-universal-forwarder /bin/bash -c "/opt/splunkforwarder/bin/splunkstatus"
    

    Check the output is similar to the picture below

  • Check if the connection between the forwarder and the Splunk instance is active: Execute the following command on the host machine:

    docker exec -it fp-csg-splunk-universal-forwarder /bin/bash -c "/opt/splunkforwarder/bin/splunk list forward-server"
    

It might prompt you for username (admin) and password (the one you setup in step 3 of Implementation - Docker). Verify the output is similar to below:

  • Check the splunk fp-csg-splunk-universal-forwarder is forwarding data with no errors.

    docker exec -it fp-csg-splunk-universal-forwarder /bin/bash -c "cat /opt/splunkforwarder/var/log/splunk/health.log"
    
  • Check after 10 minutes after running the integration: user should see data in the Splunk app

    Check the output is similar to the one shown below: