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.

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.

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.

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.

To ensure that actions performed in Lumu are accurately reflected in ServiceNow incidents, it's crucial for the integrated user account to possess both read and edit privileges within the ServiceNow console. It is strictly necessary that the user has the necessary permissions to not only view incidents but also to modify key incident fields such as State and Urgency. Without these elevated editing capabilities, any updates or changes initiated from Lumu will fail to synchronize with the corresponding incidents in ServiceNow, leading to discrepancies and hindering effective incident management.

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, adding the item depicted in the following table:

Column	Label	Value	Dependent value
Category	Lumu	lumu	NA

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_scripts/script.js  in the integration package

Preliminary setup - Lumu portal

You must  collect the following information from the Lumu portal:

1. Lumu Defender API key.
2. Company UUID.
   

Follow the steps in the sections below to collect this.

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

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.

Preliminary Setup - Docker-enabled host

Follow the steps below if your integration host does not have Docker installed. You must follow the Docker installation documentation that corresponds to your OS. Ensure you follow the Post-installation steps for Linux before deploying the integration.

For Windows users, follow the Install Docker Desktop for Windows documentation to install the Docker Engine.

Deploy the integration

Follow the steps of the following section to deploy the integration

Set up the Management Script

Lumu prepared a short snippet that allows you to manage your integration. Create a file named manage.sh in your integration host. Copy and paste the following code.

Code Snippet

#!/usr/bin/env bash

RED='\033[0;31m'
GREEN='\033[0;32m'
CYAN='\033[0;36m'
YELLOW='\033[1;33m'
BOLD='\033[1m'
RESET='\033[0m'

info()    { echo -e "${CYAN}[INFO]${RESET}  $*"; }
success() { echo -e "${GREEN}[OK]${RESET}    $*"; }
warn()    { echo -e "${YELLOW}[WARN]${RESET}  $*"; }
error()   { echo -e "${RED}[ERROR]${RESET} $*" >&2; }
prompt()  { echo -e "${BOLD}${YELLOW}$*${RESET}"; }

IMG=lumutools/servicenow-itsm-ticketing:latest
INTEGRATION_NAME=lumu-servicenow-itsm-ticketing
INTEGRATION_DIR=${HOME}/ServicenowITSM
VOLUME_DATA=${INTEGRATION_DIR}/data:/app/data
VOLUME_CONFIG=${INTEGRATION_DIR}/data/.config.toml:/app/.config.toml:ro

mkdir -p "${INTEGRATION_DIR}/data"
chmod -R o+w "${INTEGRATION_DIR}/data" > /dev/null 2>&1

run_config() {
    info "Running configuration script ..."
    if docker run --rm -it -v "${INTEGRATION_DIR}/data:/app/data" "${IMG}" bash run_config; then
        success "Configuration completed."
    else
        error "Configuration script failed."; return 1
    fi
}

start_integration() {
    if [[ ! -f "${INTEGRATION_DIR}/data/.config.toml" ]]; then
        error "Please configure the integration first."; return 1
    fi

    info "Setting up integration '${INTEGRATION_NAME}' ..."
    if ! docker container inspect "${INTEGRATION_NAME}" &>/dev/null; then
        info "Integration '${INTEGRATION_NAME}' does not exist. Creating ..."
        if ! docker create \
            -v "${VOLUME_DATA}" \
            -v "${VOLUME_CONFIG}" \
            --restart unless-stopped \
            --log-driver json-file \
            --log-opt max-size=30m \
            --log-opt max-file=3 \
            --name "${INTEGRATION_NAME}" \
            "${IMG}" bash run_component; then
            error "Failed to create integration."; return 1
        fi
    else
        warn "Integration '${INTEGRATION_NAME}' already exists. Skipping create."
    fi
    if docker start "${INTEGRATION_NAME}"; then
        success "Integration started."
    else
        error "Failed to start integration."; return 1
    fi
}

check_status() {
    info "Checking status of integrations ..."
    if [[ ! -f "${INTEGRATION_DIR}/data/.status.ndjson" ]]; then
        error "Status check failed. Verify if your integration has been deployed."; return 1
    fi
    if docker run --rm -it -v "${VOLUME_DATA}":ro "${IMG}" bash run_status; then
        success "Status check completed."
    else
        error "Status check failed."; return 1
    fi
}

show_logs() {
    info "Showing logs for '${INTEGRATION_NAME}' ..."
    docker logs --tail 100 -f "${INTEGRATION_NAME}"
}

usage() {
    echo ""
    prompt "  SERVICENOW INCIDENT INTEGRATION MANAGEMENT"
    echo -e "  ${BOLD}Usage:${RESET} $0 "
    echo ""
    echo -e "  ${CYAN}config${RESET}   Run configuration"
    echo -e "  ${CYAN}start${RESET}    Start integration"
    echo -e "  ${CYAN}status${RESET}   Check integration status"
    echo -e "  ${CYAN}logs${RESET}     Show integration logs"
    echo ""
}

case "${1}" in
    config) run_config ;;
    start)  start_integration ;;
    status) check_status ;;
    logs)   show_logs ;;
    *)      usage
            [[ -n "${1}" ]] && error "Unknown command '${1}'."
            exit 1 ;;
esac

 

Using the Management Script

With the management script, you can:

1. Configure the integration.
2. Start the integration.
3. Check the status of the integration.
4. Check the audit logs of the integration.

You can check these options by running the following command:

bash manage.sh

When running the configuration options, a wizard will guide you through a series of prompts. If the provided credentials are correct, the wizard will confirm this. If the credentials fail, you will receive an error message and have the option to re-enter the credentials or proceed despite the error.

Set up the configuration parameters

Execute the following command and type in all parameters gathered during the Preliminary Setup. Fix any errors in your inputs if prompted. 

bash manage.config

You must fill in the configuration data carefully. If there are any mistakes or missing data, you’ll receive errors during the deployment and runtime of the integration.

We strongly recommend correcting any credential errors before attempting to start the integration using the start command.

Run the Integration

You are ready to run the integration. You can start it by running this command:

bash manage.sh start

If you have run this process before, you may receive warning messages about the existence of components. To ensure you have the latest version of the integration, we recommend removing the existing integration containers before entering the start command.

Check the integration status

You can check the integration status after it has been activated. Run the following command to check its current status.

bash manage.sh status

If the script reports errors during the integration operation, head to the Show logs section to check how to collect additional details.

Show logs

We kindly request you to, when issuing a support case, attach the integration logs collected using the steps described in this section.

bash manage.sh status

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, Unmute, Close and Comment incident from Lumu Portal

When we trigger these actions from the Lumu Portal will see these actions reflected on Servicenow writing a respective note and changing the state of the incident if that is the case.

Status changed from Lumu

Status and notes reflected in Servicenow

On Hold, Inprogress and Close incident from Servicenow

In the same way we trigger status changes from Lumu, you can perform actions in ServiceNow and they will be reflected in the Lumu incident, we can put onHold, In Progress and Close the incident.

Status change from Servicenow

Status reflected in Lumu

Troubleshooting

You can use the management snippet for general troubleshooting. Here, you will find additional commands to run additional diagnostics if they are needed.

• Stopping the integration
  Run the following command if you need to stop the integration.
  docker stop lumu-servicenow-itsm-ticketing

• Starting the integration
  Run the following command to start the integration.
  
  docker start lumu-servicenow-itsm-ticketing

Known issues

In this section, we collect all the potential issues you will find after you run the troubleshooting commands from the above section.

Docker permission execution

If you got some error building the integration related to docker: permission denied while trying to connect to the Docker daemon socket, there is an official documentation post installation to fix this issue, visit the official documentation.