Requirements

• An active Chronicle subscription.
• 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 the Lumu Defender API and the Chronicle environment. According to the deployment model you select, you will need a host with:
• Python 3.10+
  

• A Docker-enabled host
  
• Script package.
• Contact the Lumu support team to request the package we created to deploy the required files.

Contacted hosts

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

• me-central2-malachiteingestion-pa.googleapis.com
• europe-malachiteingestion-pa-malachiteingestion-pa.googleapis.com
• europe-west3-malachiteingestion-pa.googleapis.com
• europe-west2-malachiteingestion-pa.googleapis.com
• asia-south1-malachiteingestion-pa.googleapis.com
• asia-southeast1-malachiteingestion-pa-malachiteingestion-pa.googleapis.com
• australia-southeast1-malachiteingestion-pa.googleapis.com
• me-west1-malachiteingestion-pa.googleapis.com
• malachiteingestion-pa.googleapis.com
• europe-west6-malachiteingestion-pa.googleapis.com
• defender.lumu.io

Please, consult the Chronicle SIEM Regional Endpoints documentation for more details about these hosts.

Make sure the device you use for deploying the integration script can connect to WebSockets.

Prepare Chronicle SIEM

Getting API authentication credentials

Please, contact your Chronicle representative to request a Google Developer Service Account credential. You will receive a Service Account file in JSON format. It looks as follows:

{
  "type": "service_account",
  "project_id": "malachite-nfr…",
  "private_key_id": ".....",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "nfr…-...@malachite-nfr….iam.gserviceaccount.com",
  "client_id": ".....",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/nfr…-...%40malachite-nfr….iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

Getting your deployment region

Please, contact your Chronicle administrator or your Chronicle representative to identify the region where your deployment belongs. You can use the information from Chronicle Regional Endpoints as a guide.

Getting your Customer ID

To get your Customer ID, use your Chronicle SIEM console:

Keep this data at hand. You need it to deploy the integration.

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

The integration works with Python 3.10. If your environment has prior versions, we recommend deploying the integration as a Docker Container.

Save the credentials file

Save the credentials file collected from your Chronicle representative in the integration root path <app_lumu_root>.

Set up the configuration file

To set up the integration, you need to add and edit a configuration file. This file contains all the parameters needed to run properly. The configuration file looks as follows:

-
  lumu:
    uuid: "<COMPANY-ID>"
    defender_key: "<DEFENDER-KEY>"
  app:
    customer_id: "<CHRONICLE-CUSTOMER-ID>"
    # Use one of the following region strings: 
    # Dammam, Europe Multi-Region, Frankfurt, London, Mumbai, Singapore, Sydney, Tel Aviv, United States Multi-Region, Zurich
    # Default: United States Multi-Region
    region: "<CHRONICLE-INSTANCE-REGION>"
    api:
      ingest_auth_file_path: "<CHRONICLE-INGEST-API-AUTH-FILE-PATH>" # Credential File
-
  COMPANY 2
-
  COMPANY 3
-
  …

By default, the integration will use the integration.yml file as the configuration file. This could be changed but be careful to set it as a parameter when the integration is deployed.

Inside the integration package, you will find a sample configuration file named integrations_template.yml. Copy it and work on it accordingly.

For MSP deployments, you can add multiple instances of this configuration block in your configuration file.

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 an auxiliary cron job.

It’s not recommended to change the default running interval of the cron job. This helps the integration script to recover from potential failures.

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: chronicle_lumu [-h] [--config CONFIG] [-v] [-l {screen,file}] [--hours HOURS]

Usage Examples

Task: collect Lumu events and push them to Chronicle SIEM

Run the following command to run the integration, collect Lumu events and push them to Chronicle SIEM.

By default, the integration attempts to read the integrations.yml configuration file

Task: run on debug mode and logging into a file

To redirect all the output from the execution process to a file, use the --logging file argument. The integration output will be stored in a file called lumu.log.

It’s recommended to set this flag. The script runs as a daemon process. The information stored in the file lumu.log is useful for tracing progress or troubleshooting.

Further considerations

The script is intended to be used as a daemon process. It is recommended to use it using complementary tools like nohup. Use the following line as an example:

If you are using a Python virtual environment

If you are NOT using a Python virtual environment

Troubleshooting

To identify failures on the script execution, use the -v flag to activate DEBUG logs. 

The application runs one instance at a time. The script will block multiple attempts to run the same integration if one is already running. If this is the case, the following message appears.

If the integration throws errors, these can be found in errors.log file in the app directory.

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 in the <app_lumu_root> folder, and follow these instructions:

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 at least one event was transmitted to a Chronicle instance you can see the record in the UDM Search section on the Chronicle Web Instance.

it might have a delay reflecting the event while Chronicle SIEM ingests and indexes the records, so, in case the records are not reflected right away then wait a little longer.

Further steps

After ingesting Lumu detections and operating events, you can create your own rule to raise Lumu detections within your Chronicle SIEM deployment. You can use the following YARA-L rule to raise detections based on the destination and the incident ID, grouping all events related to new incidents and new contacts into a single detection, and within a timeframe.

rule Lumu_detections {
  // This rule matches Lumu-related events

  meta:
    author = "Lumu Technologies, Inc."
    description = "Rule to detect new contacts based on Lumu ingested events"
    version = "1.0"

  events:
    // Let's select the events based on the Vendor name, and product event type
    // Then, calculate the destination and incidentId fields. These will be used for grouping events into detections
    $e.metadata.vendor_name = "Lumu"
    $e.metadata.product_event_type = /NewIncidentCreated|IncidentUpdated/
    strings.coalesce($e.target.hostname, $e.target.ip) = $destination
    $e.metadata.product_log_id = $incidentId

  match:
    // Group detections based on the destination and incidentId values collected in the previous step
    // Let's group them within a 2 hours timeframe
    $destination, $incidentId over 2h
  
  outcome:
    // Define additional conditions. These will be used for the alerting section
    $risk_score = max(50)

  condition:
    $e
}

After setting up your detection rule, you can see a detection dashboard like this: