This article shows how to leverage the Lumu Defender API and Google Cloud Platform API to mitigate security risks.

Requirements

• Google Cloud Platform
  • You need a Google Cloud admin user to perform the configuration steps required to deploy the integration

• 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 Google Cloud. According to the deployment model you select, you will need a host with:
    • Python 3.10+
      or
    • A Docker-enabled host.
• Script package
  • Contact the Lumu Support Team to request the package we created to deploy the required files.

Contacted hosts

• Google Cloud IPs
• defender.lumu.io

Integration’s overview

The Firewall Policy object supports a maximum of 10,000 IP addresses and 100 FQDN distributed in all the firewall rules.

The Firewall Policy can be associated with a Shared VPC Network. This association must be done in the host project, not with its associated child projects.

Configure Google Cloud Platform

Follow these steps to set up your Google Cloud console for Lumu integration.

Configure the Google Cloud projects

You can integrate more than one Google Cloud Project at a time. Make sure you run these steps for all the projects you want to integrate Lumu with.

• Go to the IAM & Admin > Manage Resources module and identify the project you will integrate.

1. List the available projects by clicking on the project list at the top of the screen, next to the Google Cloud image.

Copy the ID of the projects you want to integrate Lumu with. This information will be asked later to configure the integration

The next steps must be executed for each project you want to integrate to Lumu

Enable the Compute Engine API

Select the Google Cloud project before running these steps

1, Click on the API & Services > Enabled API & Services module in the navigation bar.

2. Look for the Compute Engine API and click on the link.

3. Click on the ENABLE button in the Compute Engine API window.

Create a Custom Integration Role

To maintain the lowest privilege for Lumu integration, you must create a Custom role for each Google Cloud project.

1. Click on the IAM & Admin module > Roles module in the navigation bar.

2. Click on the CREATE ROLE button in the Roles window.

3. Create a new role with the following permissions.

Create a Service Account

You can create a service account at the organization level and assign it access to each project you want to integrate to Lumu. If you choose to create a service account at the project level, you must create a service account per project.

Now, you must create a service account attached to the created role

1. Click on the APIs & Services> Credentials module in the navigation bar

2. Click on the CREATE CREDENTIALS button in the Credentials window. Select Service Account.

3. Fill in the required data:

a. In the Service account details, fill in the Name and Description fields

b. Continue and Grant the Service Account access to project by assigning the role created above. 

4. Save the new service account by clicking on the Done button

Add a key to the Service Account

1. Access to the created service account. Then click on the KEYS tab.

2. Click on the ADD KEY button. Select the Create new key option

3. Select JSON as the Key type. Finally, click on the CREATE button

Save the Service Account Authentication in a safe place. It will be required later to configure the integration.

Identify The Network Firewall Policies

Take note of the policy name. It will required to configure the integration

Collect the required data from Lumu portal

• Lumu Defender API key
• Company UUID

Collect the Lumu Defender API key

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

Collect your Lumu company UUID

Deploy the integration

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

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

Prepare Python on your environment

Set up the configuration files

• companies.yml: this file contains the information collected from the Lumu portal
• integrations.yml: this file contains the information collected from your Google Cloud console.

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
      - Anonymizer
    days: 30 # MIN 1, MAX 30

Within this file, COMPANY_UUID and DEFENDER_API_KEY fields are mandatory. Please use the values captured in the previous steps. The ioc_types values must match with the IOC types required by the integration, in this case, ip and domain.

Complete the integrations file

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

- lumu:
    uuid: "<COMPANY-UUID>"
    adversaryTypes: [ "C2C", "Malware", "Mining", "Spam", "Phishing"] # ["C2C", "Malware", "Mining", "Spam", "Phishing"]
    days: 30 # INTEGER=(get incidents from X days of the ioc manager local db)
  app:
    name: UNIQUE-NAME
    clean: false # true | false
    ProjectId: PROJECT-ID # Project ID
    FirewallPolicy: FW-POLICY-NAME # Global/Region Network Firewall Policy
    region: null # default null (Global), String(Region), Optional field
    ioc: [ ip, domain, ]  # either of them or all ones
    auth_filename: "AUTH-FILE-PATH" # Google Service Account JSON file path

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors. Please refer to the Troubleshooting and known issues section at the end of this article for further reference.

Prepare Python on your environment

If Docker is your chosen deployment method, you may skip this step.

Deploy Integration as script

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

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 Examples

Task: query IOCs related to Lumu incidents with default options

To query all the hashes related to Lumu incidents triggered in the days defined in your configuration files, run the following command.

Task: Clean records

The records not manipulated by the integration will be preserved.

Other tasks

Deploy as a Docker container (Optional)

1. Build the container by running the following command.

docker build \

      --tag img-gcp-response \

      --file DockerfileAllInOne .

Do not forget the dot "."

2. Run the container by using the following command.

docker run -d \

      -v ./integrations.yml:/app/integrations.yml \

      -v ./companies.yml:/app/companies.yml \

      --restart unless-stopped \

      --log-driver json-file \

      --log-opt max-size=30m \

      --log-opt max-file=3 \

      --name lumu-gcp-response \

      img-gcp-response

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

Troubleshooting

If you must reset your credentials frequently, you can run your container by adding the following argument to the docker run create command: 

      -v AUTH-FILE-PATH:/app/AUTH_FILENAME

Where AUTH_FILE_PATH is the full path to Google’s credential file on the Docker device and  AUTH_FILENAME is the value of the parameter auth_filename within the integrations.yml configuration file.

Expected results

After running the integration, you will see new rules in the Network Firewall Policy Rules section, if there was any detection related either IP addresses or Domains.

Troubleshooting and known issues

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.

Further steps

1. Go to VPC Network Security> Firewall in the navigation menu. Click on the Firewall Policies left menu under the Cloud NGFW section

2. Look for the Network firewall policies section and click on the selected Policy Name

3, Click on the ASSOCIATIONS tab in the Firewall Policy configuration.

4. Click on ADD ASSOCIATION.

5. Check the VPC networks to associate this policy and then click on the ASSOCIATE button