ServiceNow Custom SecOps Integration

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 and web access.
  • An active Defender subscription.
  • Lumu Defender API key
  • A scripting host with python 3.10
  • A scripting host with Docker support (Optional)

Prepare ServiceNow for Lumu integration

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

Enable the OAuth plugin

1. In your ServiceNow Web console, expand the All menu. Using the search bar, search for the System Plugins option.

2. The All Applications window will appear. Click on the Click here link in the notification bar.

3. Search for the OAuth plugin using the System Plugins search bar. Click on the OAuth row and click on the Activate link. Follow the on-screen instructions to activate the module. If it is already activated, leave it as it is.




Create the OAuth registry for Lumu

1. After activating the OAuth plugin, you need to create a new OAuth registry for Lumu. To do so, use the search bar from the All menu. Search for OAuth. Click on the Application Registry option and then, click on the New button.



2. In the OAuth application window, click on the Create an OAuth API endpoint for external clients link. Fill in the required data. Click on the Submit button. Open the recently created registry to copy the Client ID and Client Secret. These will be used later for setting up the integration.



Create a credential entry with the Lumu Defender key

1. Go to the Credentials menu under the Configuration & Credentials section using the search bar. In the Credentials window, click on the New button. Fill in the required information.

It’s essential to name the credentials as lumu_credentials. If you use a different name, the integration will not work.


Create a dedicated integration user (optional)

1. It’s recommended to create a dedicated ServiceNow user to operate with the integration. This user will be used as the Caller  in the created incidents in ServiceNow. Go to Users under the User Administration section using the search bar in the All menu.



2. In the Users window, click on the New button. Fill in the required data. Be sure that the Web service access only check is marked. Click on the Submit button.


3. To set the password for this user, search for it in the Users window. Open the record and click on the Set Password button. Generate and save the password for the user. Keep this information at hand, it will be required for setting the integration.

Add the Lumu category tree in the incident table

1. You need to add a new category tree to work with Lumu integration. To do so, use the search bar to search for the Tables & Columns menu.


2. In the Tables & Columns window, search for the Incidents table, select it and click on the Edit bu tton.


3. Edit the columns Category and Subcategory, adding the items depicted in the following table:

Column

Label

Value

Dependent value

Category

Lumu

lumu

NA

Subcategory

Malware

malware

lumu

Subcategory

DGA

dga

lumu

Subcategory

C&C

c&c

lumu

Subcategory

Mining

mining

lumu

Subcategory

Spam

spam

lumu

Subcategory

Phishing

phishing

lumu

For more details of how to add the category tree for Lumu, refer to Add a category or a subcategory reference.

Add the Lumu Script action in ServiceNow

To maintain incident records synchronized from ServiceNow to Lumu, you need to add a Script Action. This action will trigger after a Lumu incident record is updated. To do so, use the Search bar to search for Script actions. Click on the Script Actions link under the System Policy > Events section.

On the Script Actions window, click on the New button. Fill in the required data according to the following table:

Field

Value

Name

LumuScript

Event Name

incident.updated

Condition script

current.short_description.toLowerCase().includes('lumu') || current.category.toLowerCase() == 'lumu'

Script

Take the content of the file named

ServiceNow side/script.js  in the integration package


Deploy the package

Remember to contact the Lumu support team to acquire the deployment package if you haven’t already done so.

To deploy the integration package, you have two options:

  • Run it as a Python script.
  • Run it as a Docker container.

Select the alternative that best suits your needs.

Run it as a python script

Script 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 this point on, we will refer to this folder as <sn_lumu_root>.

Install requirements

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

  1. [sudo] pip install -r ./requirements.txt
It is recommended to define a Python virtual environment to deploy the script requirements.

Script details

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

python servicenow_lumu.py --help

Usage: servicenow_lumu.py.py [options]

Options

Description


-h, --help


show this help message and exit

--client_id CLIENT_ID
-cid CLIENT_ID

ServiceNow Application registry (CLIENT ID)

--client_secret CLIENT_SECRET
-cs CLIENT_SECRET

ServiceNow Application registry (CLIENT SECRET)

--username USERNAME
-u USERNAME

ServiceNow username with privilege to run the PublicAPI

--password PASSWORD
-p PASSWORD

password of ServiceNow username with privilege to run the PublicAPI

--company_key COMPANY_KEY
-key COMPANY_KEY

Lumu Company Key (Defender API).

--sn_hostname SN_HOSTNAME
-sn SN_HOSTNAME

ServiceNow API Hostname, example: "dev134220.service-now.com"

-snuser SN_USER_NAME

--sn_user_name SN_USER_NAME

ServiceNow Integrator user, example: "lumu.integrator"

--logging {screen,file}
-l {screen,file}

Logging option (default screen )

--verbose, -v

Verbosity level

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 argument -snuser  is used by the integration for setting the Caller in the incidents.

Usage examples

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

  1. python servicenow_lumu.py --company_key <Lumu Defender Key>  --client_id <ServiceNow Client ID> --client_secret <ServiceNow Client Secret> --username <ServiceNow user> --password <ServiceNow password> -sn <ServiceNow API Domain Name>

Task: save script log in 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.

  1. python servicenow_lumu.py --company_key <Lumu Defender Key>  --client_id <ServiceNow Client ID> --client_secret <ServiceNow Client Secret> --username <ServiceNow user> --password <ServiceNow password> -sn <ServiceNow API Domain Name> --logging file

Other tasks

The above samples could be combined according to your needs.

Troubleshooting

For identified failures on the script, please use the -v  flag. This will allow you to identify failures in the script execution.

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
  1. docker build --build-arg company_key=<value> --build-arg client_id=<value> --build-arg client_secret=<value> --build-arg username=<value> --build-arg password=<value> --build-arg sn_hostname=<value> --build-arg sn_user_name=<value> --tag python-lumu-servicenow .

The reference of the arguments used in the Docker image are the same used for the script. Please refer to them for filling up this data.

  1. Create and run the Docker container
  1. docker run -d --name lumu-servicenow python-lumu-servicenow

Troubleshooting

In order to check live logs of the container, run the following command:

  1. docker logs -f lumu-servicenow

Expected results

After running the script, it will listen for incident updates on Lumu. After an incident is updated on Lumu, you will see a new incident in the Incidents window in the Service Desk  section.


The following table shows the transition between states among incidents in Lumu and ServiceNow.

ServiceNow state/action

Lumu state/action

Comments

New

Open

Applies for a new incident detected by Lumu

On hold

Muted

In progress

Unmute

If the incident is unmuted, it will be marked as In progress in ServiceNow

Closed

Closed

These transitions are supported in both directions. Each transition made in one of the services will be reflected in the other. Following, you can find some examples of how the operation between both services works.

Activity from Lumu portal

Mute incident

  1. Mute incident, Lumu Portal


  1. Mute incident, Service Now OnHold State

  1. Mute incident, comment from Lumu


Unmute Incident

  1. Unmute incident, Lumu Portal

  1. Unmute incident, Service Now In Progress State

  1. Unmute incident, comment from Lumu

Comment Incident

  1. Comment incident, Lumu Portal

  1. Comment incident, comment from Lumu

Close Incident

  1. Close incident, Lumu Portal

  1. Status incident, ServiceNow comment

  1. Incident Resolution information

Activity from ServiceNow Platform

Hold On Incident

  1. OnHold Incident, ServiceNow Site

  1. OnHold Incident, ServiceNow Log

  1. OnHold Incident, Lumu Result

In progress Incident

  1. In Progress Incident, ServiceNow Site

  1. In Progress Incident, ServiceNow Log

  1. In Progress Incident, Lumu Result


Resolved Incident

  1. Resolved Incident, ServiceNow Site

  1. Resolved Incident, ServiceNow Log

  1. Resolved Incident, Lumu Result

Close Incident

  1. Closed Incident, ServiceNow Site

  1. Closed Incident, ServiceNow Log

  1. Closed Incident, Lumu Result








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

        • Related Articles

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

        • GLPI Custom SecOps Integration

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

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

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

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