Kaseya BMS PSA Custom SecOps Integration

Kaseya BMS PSA Custom SecOps Integration

This article shows how to leverage Kaseya BMS API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a BMS deployment as Service Desk -  Tickets, and syncing both systems.


SecOps integration between Kaseya BMS and Lumu

Requirements

  • A Kaseya BMS subscription and Web 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 Kaseya BMS. According to the deployment model you select, you will need a host with:
      • Python 3.10+
OR
      • A Docker-enabled host.

Contacted hosts

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

  • bms.kaseya.com
  • bmsemea.kaseya.com
  • bmsapac.kaseya.com
  • defender.lumu.io

Prepare Kaseya BMS for Lumu integration

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

Create a Custom Issue Type

A Kaseya BMS issue type is required for ease of management. To create a dedicated issue type for Lumu, log in to your Kaseya BMS instance with an administrator user, and follow these steps:

1. Click on the Admin menu.

2. Click on the Issue Types menu under the Service Desk section.

3. Click on the + New button. Fill in the required data and save the custom Issue Type for Lumu.


Keep record of the Issue Type you created. This data will be required to set up the integration configuration.

Create a Custom Security Role with API REST permission

We recommend you use a custom role dedicated to running the Lumu integration. To create it, log in to your Kaseya BMS instance with an administrator user, and follow these steps:

1. Click on the Admin menu.

2. Click on the Roles menu under the Security section.

3. Click on the + New button. Fill in the required information. Make sure you mark the Has API Access option under the Special Features section. Save your new custom role.


Create an API Employee User

We recommend you create a dedicated user of type API Employee to operate the integration. To create it, log in to your Kaseya BMS instance with an administrator user, and follow these steps:

1. Click on the Admin menu.

2. Click on the Employees menu under the HR section.

3. Click on the + New button. Fill in the mandatory fields, and set the User Type field as API Employee. Make sure you use a valid email address to reset the user’s password.





The integration requires this user and its password. Keep them handy.

Add the API Employee to your Custom Security Role

Finally, you need to link the integration user with the security role created in the previous steps. Log in to your Kaseya BMS instance with an administrator user, and follow these steps:

1. Click on the Admin menu.

2. Click on the Roles menu under the Security section.

3. Click on the role created in previous steps.

4. Click on the Role User tab.

5. Click on the Add button.

6. Select the user created for the integration using the checkbox near the user.

7. Click on the OK button

Collect complementary information

The integration requires this complementary information:

  • Account name and location
  • Queue and priority
  • Statuses

To collect the account name and its location, use an administrator user in your Kaseya BMS console, and follow these steps:

1. Click on the Admin menu.

2. Click on the Accounts menu under the CRM section.

3. Click on the desired account. Then, click on the Locations tab.

4. Identify the location you want to associate your Lumu detections with.

For MSP deployments, you can identify multiple accounts. Make sure you collect the names of both the account and its location. The integration requires this information.

Collect the queue and priority

The integration creates a Service Desk Ticket for each detection. You must define the Queue and the priority you want to use for them. Log in to your Kaseya BMS console with an administrator user, and follow these steps:

1. Click on the Admin menu.

2. Click on the Queues menu under the Service Desk section.

3. Identify the queue you want to use for Lumu Service Desk Tickets.

It’s recommended to copy the queue name from the Queues window instead of typing it to avoid typo misconfigurations in the integration.

You can create your queue for managing Lumu Service Desk Tickets. If you do so, take note of its name. The integration setup process requires this information.

Now, let’s collect the Priority to use.

1. Click on the Admin menu.

2. Click on the Priorities menu under the Service Desk section.

3. Identify the queue you want to use for Lumu Service Desk Tickets.

It’s recommended to copy the priority name from the Priorities window instead of typing it to avoid typo misconfigurations in 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

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 UUID>

    defender_key: <DEFENDER API KEY>

  app:

    Priority: <PRIORITY>

    Queue: <QUEUE>

    IssueType: <CUSTOM ISSUE TYPE FOR LUMU>

    AccountName: <TICKET’S CRM ACCOUNT NAME>

    AccountLocation: <TICKET’S CRM ACCOUNT LOCATION>

    TicketType: "Incident"

    TicketSource: "Monitoring System"

    StatusNewTicket: "New"

    StatusEventMap:

      NewIncidentCreated: "New"

      IncidentClosed: "Completed"

      IncidentMuted: "Waiting For Customer"

      IncidentUnmuted: "In Progress"

    StatusActionMap:

      mute: "Waiting For Customer"

      close: "Completed"

      unmute: "In Progress"

    api:

      username: <API USERNAME>

      password: <API USER PASSWORD>

      tenant: <API USER COMPANY| TENANT NAME>
      hostname: <BMS INSTANCE HOSTNAME>  # bms.kaseya.com | bmsemea.kaseya.com | na1bmspreview.kaseya.com | bmsapac.kaseya.com

-

  COMPANY 2

-

  COMPANY 3

-

  …

Replace the values according to your environment based on the collected data from previous steps, using these indications:

  • The values tagged inside angle brackets must be replaced with the values collected in previous steps
  • The values in the StatusEventMap section must be filled out with the status you want to assign to the Kaseya Service Desk Ticket based on your environment configuration.
  • The StatusActionMap maps the Kaseya statuses with Lumu statuses.

Inside the integration package, you will find a sample configuration file named companies_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, go to the app_lumu_root folder, then execute this line through CLI.

./install.sh

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.

Main Script details

To use the script, you must locate yourself on the path selected for deployment (<app_root_path>). Use the following command to show help command line

python kaseya_lumu.py --help

Usage: kaseya_lumu.py [options]

OptionsDescription
-h, --helpshow this help message and exit
--config CONFIGdefault: companies.yml, CONFIG FILE PATH of the companies, follow the nex YML template.
-v, --verbosethe flag means DEBUG mode, by default is INFO mode
-l {screen,file}, --logging {screen,file}logs output on command line or file
--hours HOURSTo keep db log record from [x hours], for auto maintenance purpose

The script will run as a daemon process. To keep this integration working, you need to guarantee the script is running all the time.

The integration will run smoothly if the configuration within the YAML configuration file is correct. If the script gives errors, solve them based on the log output.

Usage examples

Task: basic usage or standard usage

Use the following command to listen to Lumu operational events and manage service tickets in your Kaseya BMS instance:

python kaseya_lumu --config CONFIG -l screen --hours HOURS

The application will run reading the CONFIG file and keep the preceding HOURS tickets/incidents, by default 720 (30 days)

Task: save script log to file

Use the option --logging=file to store a record of all tasks run by the script. Using this, all the script output will be redirected to a file named lumu.log in the folder where you have deployed the script.

python kaseya_lumu --config CONFIG -l file --hours HOURS

Other tasks

The above samples can be combined according to your needs.

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.

python kaseya_lumu.py

Stopping the integration 3084245, it might have another older instance running, check if is feasible or not

older pid: 3078797 - cwd: /home/lumu/Documents/repos/lumu-kaseya-bms - since: 2023-10-30 11:39:24.840000  

cmdline: /home/lumu/Documents/repos/lumu-kaseya-bms/venv310/bin/python /home/lumu/Documents/repos/lumu-kaseya-bms/kaseya_lumu.py

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

Run it as a Docker container

The integration can be deployed in a docker environment. To do so, run the following commands located in the integration folder:

1. Build the Docker image

docker build --build-arg APP_CONFIG=<YAML FILE>  --tag python-lumu-kaseya .

Do not forget the dot "."

2. Create and run the Docker container

docker run --restart unless-stopped -d --name lumu-kaseya python-lumu-kaseya

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

docker exec -it lumu-kaseya bash

To collect integration logs:

docker logs -f lumu-kaseya

Expected results

After running the script, the list of the incidents mapping to tickets are held in the Tickets window in the Service Desk section.


Any updates and status changes will be reflected in the Details and the Comment section of the ticket




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

        • Related Articles

        • HaloPSA Custom SecOps Integration

          This article shows how to leverage HaloPSA API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a HaloPSA deployment as Tickets, and syncing both systems. Requirements A HaloPSA subscription and Web access. Lumu ...

        • Chronicle SIEM Custom SecOps Integration

          The Chronicle SIEM Custom SecOps integration allows you to receive Lumu detections and related operating events. In this article, you will find out how to configure your Chronicle SIEM instance and its Lumu integration to enhance your current ...

        • Jira Service Management Cloud Custom SecOps Integration

          This article shows how to leverage Jira Service Management API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a Jira SM (Service Management) deployment as Service Management Requests, and syncing both systems. ...

        • ServiceNow Custom SecOps Integration

          This article shows how to leverage ServiceNow API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a ServiceNow deployment Incident Tickets, and syncing both systems. Requirements ServiceNow active subscription ...

        • Autotask Custom SecOps Integration

          This article shows how to leverage Autotask API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into an Autotask deployment as Service Tickets, and syncing both systems. Requirements An Autotask active subscription ...