Response integration between Forcepoint NGFW and Lumu

A typical Forcepoint NGFW deployment relies on a manager, Forcepoint Security Management Center (SMC), and one or multiple Forcepoint NGFW engines. This integration works with the SMC component.

Requirements

• A Forcepoint SMC with administrative access.
• Lumu Defender API key
• To retrieve an API token, please refer to the Defender API document.
• Script host.
• A scripting host is required to deploy the integration. This host must have Internet visibility over Lumu Defender API endpoints and Forcepoint SMC. According to the deployment model you select, you will need a host with:
• Python 3.10+
  

• A Docker-enabled host.
  

Contacted hosts

Allow all the traffic to the following hosts. These are required for the operation of this integration:

• Forcepoint SMC IP address
• defender.lumu.io

Prepare Forcepoint SMC for Lumu integration

Before you deploy and implement the Lumu Integration, you need to prepare your Forcepoint SMC to ensure the integration works as expected.

Enable SMC API

You need to enable SMC API to allow requests from the integration script. Go to your Forcepoint SMC console and follow these steps:

Create a custom administrator role (recommended) 

It’s strongly recommended to create a custom administrator role to be used by the integration to limit the permissions over your Forcepoint deployment to just the required ones. Create a role within your Forcepoint SMC console following these steps:

Your new role must look as follows:

Create an API Account

To create a Forcepoint SMC API account, follow these steps on your Forcepoint SMC console: 

Before clicking on the OK button, make sure to save the Authentication Key from the General tab. If you forget to do this step, you will need to regenerate it by checking the properties and clicking on the Generate Authentication Key button.

If you are managing multiple domains with the same Forcepoint SMC, make sure you assign permissions over all the required domains to the API user.

Pushing changes to your deployment

Collect the required data from Lumu portal

The integration set-up process needs you to collect this information from Lumu portal:

• Lumu Defender API key
• Company UUID

Log in to your Lumu portal and run the following procedures to collect these data.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, refer to the Defender API document.

Collect your Lumu company UUID

To collect your Lumu company UUID, log in to your Lumu portal. Once you are in the main window, copy the string below your company name.

Deploy the integration

There are 2 environment options to deploy the script, select the one that best fits your current infrastructure.

• Run it as a Python script executing the install.sh bash file
• Creates a Python virtual run time and its dependencies for you
• Installs the crontab line in the host
• Run it as a Docker container.

Whichever alternative you select, you need to first unpack the integration package shared by our Support team.

Unpack the deployment package provided by Lumu in your preferred path/folder. Keep in mind this location, as it will be required for further configurations. From now on, we will refer to this folder as <app_lumu_root>.

If you use the install script, use the uninstall.sh bash file to remove the integration from the host

Set up the configuration files

To set up the integration, you need to add and edit two configuration files:

• companies.yml: this file contains the information collected from the Lumu portal
• integrations.yml: this file contains the information collected from your Forcepoint SMC

Inside the integration package, you will find sample files you can use to build your configuration files. These files are companies_template.yml and integration_template.yml.

Complete the companies file

The companies file is in charge of defining how the integration connects to Lumu and extracts the information of the incidents and related indicators of compromise.

-
  lumu:
    uuid: "<COMPANY-UUID>"
    [name: "<COMPANY-NAME>"]
    [contact_name: "<CONTACT_NAME>"]
    [contact_email: "<CONTACT_EMAIL>"]
    defender_key: "<DEFENDER_API_KEY>"
    hash_type: "<HASH_ALG>" # sha256 | sha1 | md5
    ioc_types: # list of ioc types, option one, many or all
      - ip
      - domain
      - url
      - hash
    adversary:  # list of adversary types, option one, many or all
      - C2C
      - Malware
      - Mining
      - Spam
      - Phishing
    days: 30 # MIN 1, MAX 30

Complete the integrations file

The integration file contains the information required for the integration to connect and interact with your Forcepoint FMC deployment:

-
  lumu:
    uuid: "<COMPANY_UUID>"
    days: 10 # INTEGER=(get incidents from X days of the ioc manager local db)
  app:
    name: "<CLIENT-NAME>" # Name of the headquarters, branch, office, client
    clean: false # true # either clean the instance IOC or not
    GlobalList: false # true # either append the instance IOC to global list in the same Management Server or not
    ioc: # ["ip", "domain", "url"] list of one, many or all ioc types
      - ip
      - domain
      - url
  engines: # list of the Engine Names (Case Sensitive) | null (include all Elements related engine)
      - "ENGINE-NAME-1"
      - "ENGINE-NAME-2"
      - "ENGINE-NAME-X"
      - ...
    commit_strategy: integration-only # STRING Options: all | integration-only | null

    api:
      url: "<PROTO://IP_HOSTNAME:PORT>"
      api_key: "<API-KEY>"
      verify_cert: false # true
      version: "<API-VERSION>" # e.g NUMBER=(float, int) 7.2 | null

Deploy Integration as script

To deploy the integration as script, you need to run the install.sh script inside the integration package.

Make sure the install.sh script has the execution permission before running it.

To run the installation script, locate yourself in the app_lumu_root folder, then execute this line through CLI.

The installation script will set up the Python environment and two different cron jobs.

If you want to modify the default running interval set up by the installation script, you can modify the latest crob job entries based on your environment requirements.

if you want to restart or uninstall the integration run the ./restart all and ./uninstall all respectively

Script details

To use the script, you must locate yourself on the path selected for deployment (<app_lumu_root>). Use the following command to show all options available for the package:

Usage:

Usage Examples

Task: query IOC related to Lumu incidents with default options

To query all the IOC related to Lumu incidents triggered in the last 30 days, run the following command.

Task: query IOC related to specific parameters

By default, the integration script will query incidents related to all adversary types. If you need to filter the query to specific adversary types, you can use the --adversary-types flag as follows

Task: Clean records

To clean the existing records in Elastic, just set up the clean flag in the integrations.yml file to true.

Then, run the integration script as follows:

Or you can run the clean command directly to clean all the companies

The records not manipulated by the integration will be preserved

Other tasks

According to your needs, you can combine the examples shown, also, adding the –logging {file, screen} and –verbose argument can be used for better understanding of what can be rolling wrong.

Deploy as a Docker container (Optional)

If you have a Docker environment, you can select this option to run the integration as a Docker process. To deploy and run your integration as a docker container, locate yourself at the <app_lumu_root> folder, and follow these instructions:

With this mode, your integration will run every 30 minutes.

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

To collect integration logs:

Expected results

After running the integration, you will see new objects under the Configuration section in your Forcepoint SMC. You need to reference these in your policies according to your needs.

Remember, you need to set a traffic inspection policy to analyze and act on encrypted traffic.

Make sure you don’t manage directly these elements. Doing so can create issues in how the integration operates.

Category

IP address list

Domain Names

Groups

Company Group

Global Group

URL list

Troubleshooting and known issues

To identify failures in the script execution, use the -v flag. The script execution log will show more detailed information.

The application logs will be redirected to lumu.log file. The file errors.log stores only the errors to make them easier to find and aid the troubleshooting process.

Another instance is running

If you receive the following error.

There could be another instance running. To check this, open the pid.pid file in the integration folder. This file stores the process ID if it’s running.