Forcepoint Web Security Cloud Custom Response Integration

Forcepoint Web Security Cloud Custom Response Integration

This article shows how to leverage the Lumu Defender API and Forcepoint Web Security Cloud to mitigate security risks.


Forcepoint Web Security Cloud service doesn't have a REST API, so this script simulates the actions run by an admin user to feed a Custom category with URLs and sites using the Forcepoint portal. If there is any change in the browsing experience, the script could stop working.

Requirements

  • Forcepoint Web Security Cloud subscription
  • Lumu Defender API key
    • For retrieving an API token, please refer to the Defender API document.
  • Script host.
    • Host with Python 3.6+ with network visibility over Lumu Defender endpoints and Forcepoint Web Security console page.
  • Script package.
    • Contact the Lumu support team to request the package we created to deploy the required files.

Set up Forcepoint Web Security service

Create dedicated Forcepoint admin contact for Lumu

To create a dedicated contact in Forcepoint Web Security for Lumu integration, please refer to Forcepoint - Adding a contact .

Deploy the script

First, contact the Lumu support team to request the deployment package.

You must add firewall exceptions to the following domains to ensure the integration's proper functioning:
  1. https://admin.forcepoint.net:443
  2. http://www.websense.com:80
  3. https://www.mailcontrol.com:443
  4. https://admin.forcepoint.net:443
  5. https://defender.lumu.io:443

Scripts location

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 <forcepoint_lumu_root> .

In the package, you will find the script required to run the integration. To use the script, you must locate yourself on the path selected for deployment ( <forcepoint_lumu_root> ). Specific directions are included in the next sections.

Install requirements

The file requirements.txt  contains the list of requirements for this integration. After deploying the package locally, run the following command from the deployment folder:

[sudo] pip install -r ./requirements.txt

Script details

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

python forcepoint_lumu.py --help

Usage: forcepoint_lumu.py [options]

Options

Description

-h, --help

show this help message and exit

--config CONFIG

Load options from config file

--company-key COMPANY_KEY

--company_key COMPANY_KEY

Lumu Company Key (Defender API).

--proxy-host PROXY_HOST

--proxy_host PROXY_HOST

Proxy host (if required)

--proxy-port PROXY_PORT

--proxy_port PROXY_PORT

Proxy port (if required)

--proxy-user PROXY_USER

--proxy_user PROXY_USER

Proxy user (if required)

--proxy-password PROXY_PASSWORD

--proxy_password PROXY_PASSWORD

Proxy password (if required)

--logging {screen,file}

Logging option (default screen).

--verbose, -v

Verbosity level.

--username USERNAME

Forcepoint Web Security Cloud service username.

--password PASSWORD

Forcepoint Web Security Cloud service password.

--category CATEGORY

Forcepoint Custom category name (default Lumu IOCs).

--description DESCRIPTION

Forcepoint Custom Category description (default Lumu IOCs).

--adversary-types {C2C,Malware,DGA,Mining,Spam,Phishing}

--adversary_types {C2C,Malware,DGA,Mining,Spam,Phishing}

Lumu adversary types to be filtered.

--days DAYS

The number of days backward from now to query Lumu incidents.

--clean

Cleans all rules and objects created by the Lumu integration.

--preserve-file

--preserve_file

Don't delete the intermediate CSV file.

Usage Examples

Task: query and add indicators (URLs) related to Lumu open incidents

Use the following command to fetch and push to Forcepoint Web Security URL IOCs related to open incidents found in your organization by Lumu:

python forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key>

The integration creates a new custom category Lumu IOCs  with the URLs. You need to add the custom category to a policy marking it to Block access . For further executions, the integration will update the site list.

Task: query and add indicators (URLs) related to Lumu open incidents to a specific custom category

Use the following command to fetch and push to a specific custom category of Forcepoint Web Security URL IOCs related to open incidents found in your organization by Lumu:

python forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key> --category <forcepoint_category_name> [--description <forcepoint_category_description>]

You need to add the custom category to a policy marking it to Block access . It's recommended to leave a dedicated custom category for Lumu.

Task: query and add indicators (URLs) related to Lumu open incidents with contacts in the last X days

Use the following command to fetch and push to Forcepoint Web Security IOCs related to open incidents found in your organization by Lumu with contacts in the last X days.


python forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key> --days X
All previously pushed IOC to Forcepoint will be replaced, even if they correspond to incidents with contacts before X days.

Task: query and add indicators (URLs) related to Lumu open incidents of specific types

By default, the script queries open incidents of all adversary types (Phishing, Malware, DAG, Spam, others). If you need to collect specific types of incidents, you can use the argument --adversary-types ADVERSARY_TYPE . If you need to get two or more adversary types, you only need to append a new instance of the parameter.

python forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key> --days X --adversary-types Phishing --adversary-types Malware
In this example, the adversary types queried are  Phishing  and  Malware.

Task: clean all changes made by Lumu integration

If you need to delete the Custom category created by this integration, use the --clean flag with the authentication arguments and its name using the --name  CATEGORY argument.

python forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key> --clean [--name <forcepoint_category_name>]
Keep in mind the name of the Custom Category you have created before. If you have run the integration with the default category name, you can omit the --name  parameter.

Task: preserve CSV intermediate file with IOCs

The script creates and deletes the intermediate CSV file site_list_tmp.csv to upload sites to the Custom category. If you want to preserve it, append --preserve-file to the command line.

python forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key> --preserve-file

The file site_list_tmp.csv  will be located in the script root path for further reference. Have in mind this will be overwritten after each iteration of the integration.

Task: save log output to file

By default, you will see the execution log on the screen console. Use the argument --logging file to store a record of all tasks run in the lumu.log file in the script root path.

python forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key> --logging file

This file is useful for scheduled tasks or processes running in the background. When you open this file, you will see the following. The information displayed aids in checking the execution progress.

Other tasks

According to your needs, you can combine the examples shown.

Expected results

You will see a new Custom category (account level) at the Forcepoint Web Security service as follows:

The details of the category will show you the uploaded sites:


Set up Forcepoint Web Security Policy

After the Custom category has been created and maintained by the integration, you need to use it inside a Forcepoint Policy. For doing this, please go to the Web  menu and click on the Policies  link.


Choose the desired policy and click on its name. Look for the Web Categories tab and click on it. Select the Custom category under the Account Custom Categories  branch under the categories tree on the left side of the page. On the right side, the Action form will display. Click the Block access button and select the Access blocked option under the drop-down list. When you finish the configuration, click on the Save  button.


 It’s recommended to enable the SSL decryption feature in the policy to allow Forcepoint to analyze deeper the Web traffic on the endpoints protected by the service.


Further considerations

To run the script on a timely basis, consider implementing a Scheduled task  in Windows or a Cron task  in Unix-based systems. If you are pushing hashes, the integration could take longer to run. We recommend that the scheduled job runs every 30 minutes.

Following, you have an example of how this Cron job  should look using the recommended time.


*/30 * * * * python3 <repo_root>/forcepoint_lumu.py --username <forcepoint_username> --password <forcepoint_password> --company-key <lumu_company_key> --logging file

It’s recommended to add the --logging file  parameter to any scheduled task. It will record all the output in the log file for further reference

If you need to work with another scheduling time, you can use the  crontab guru service.

To avoid race conditions, you can run only one instance. If you have one running, the second one will be canceled immediately.

Troubleshooting and known issues

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

Another instance is running

If you receive the following error.

Error: Another instance is running. Quitting.

There could be another instance running. To check this, open the pid.pid  file in the integration’s folder. This file stores the process id if it’s running. Search for this process in your system. The following pictures show the process in Windows and Linux.



If the previous validation indicates that another instance is running, please, check its progress using the integration’s log lumu.log .



    Still can’t find an answer?
    Send a message to our experts.
    Contact Us

        • Related Articles

        • Forcepoint NGFW Custom Response Integration

          This article shows how to leverage Forcepoint NGFW provided by the SMC (Security Manager Center) API and Lumu Defender API to enhance your Response capabilities. Response integration between Forcepoint NGFW and Lumu A typical Forcepoint NGFW ...

        • Bitdefender Custom Response Integration

          Bitdefender Custom Response Integration This article shows how to leverage the Lumu Defender API and Bitdefender API to mitigate security risks. Requirements GravityZone Business Security Enterprise, cloud version, ...

        • Infoblox Custom Response Integration

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...

        • Trend Micro Web Security Custom Response Integration

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...

        • CylanceENDPOINT Custom Response Integration

          This article shows how to leverage the Lumu Defender API and CylanceENDPOINT API to mitigate security risks. Requirements CylanceENDPOINT subscription A CylanceENDPOINT Standard subscription or above is required (formerly CylancePROTECT) Lumu ...