Requirements

• A ServiceDesk Plus Standard Edition or above with an administrator user
  
• The user will be used to prepare the ServiceDesk Plus environment for the integration.
  
• Lumu Defender API key
  
• To retrieve an API token, please refer to the Defender API document.
  
• A Docker-enabled host
  
•  This host will be used to deploy the integration component. It must have Internet visibility over the Lumu Defender API endpoints and the ServiceDesk Plus server.
  
• Component and Script package 
  
• Contact the Lumu support team to request for indication or visit the documentation component in our DockerHub site.
  

Contacted Hosts

• ServiceDesk Plus server
• defender.lumu.io
• docker.io

Integration’s overview

The Lumu Custom integration with ServiceDesk Plus On-premise uses the ServiceDesk API to sync Lumu detections as ServiceDesk service requests, allowing security operators to work in Lumu incident detections from the ServiceDesk Plus portal. Operational tasks recorded in the ServiceDesk Plus portal will be automatically reflected in the corresponding incident in the Lumu Portal.

Preliminary Setup - ServiceDesk Plus Server

To set up the integration, you must prepare your ServiceDesk Plus On-premise deployment to communicate with the Lumu integration. To do this, you need to:

• Identify your ServiceDesk Plus host and port.
• Generate an Integration key.
• Collect the Help Desk operational parameters.

The following sections will guide you on how to perform these tasks.

Identify your ServiceDesk Plus host and port

The ServiceDesk Plus host and ports can be extracted from the URL you use to access your ServiceDesk Plus console on a Web browser. Open your preferred Web browser and access your ServiceDesk Plus instance. Extract the URL from the navigation bar.

https://HOSTNAME_OR_IP:PORT/ui/home

If the collected URL doesn’t have a port, you can infer the PORT as follows:

• If the scheme is http, the PORT is  80.
• If the scheme is https, the PORT is 443.

Once you have retrieved the hostname and port, Log in to your ServiceDesk Plus console with an administrator user account before proceeding to the next sections.

An administrator user account is required to perform the operations required to set up the integration.

Generate an Integration key

The integration key will allow the integration to authenticate to your ServiceDesk Plus instance. When logged in to your ServiceDesk Plus instance, click the Gear icon at the right side of your top navigation bar.

Then, follow these steps to create your integration key.

1. Click the Integration Key option under the Developer Space tile.

2. Click New in the Developer Space - Integration key window.

3. Fill in the information as follows:

• Enter a Name for the integration key.
• Set the Roles to SDAdmin.
• Set the expiration date according to your security policy. Ensure you renew the key before its expiration date once the integration has been set up.
  
• When finished, click the Generate button.
  

4. Copy the generated key and save it for later use. You won’t be able to see it again.

Collect the Help Desk operational parameters

You must collect these parameters if you need to use specific operational parameters such as Requester, Assigned Technician, Site, Category, and related. Click the Gear icon in the top right side of the ServiceDesk window.

To collect the required values for the Requester name and Technician, follow these steps from the Admin view:

1. Click the Users option in the Users & Permission tile.

2. Search for the desired user and technician in the Users & Permission - Users window. Ensure you select the appropriate record based on the Type of user. Copy the exact values.

To collect optional values such as Site, Category, Mode, Impact, Urgency, and Priority, click the Gear icon in the top right side of the ServiceDesk Plus console and:

1. Click the Helpdesk option in the Customization tile.

2. Run through each tab in the Customization - Helpdesk window and collect the desired values for these fields:

• Site
• Category
• Mode
• Impact
• Urgency
• Priority

Alternatively, you can open an active request, then edit it, and examine the different fields and their corresponding values.

As the ServiceDesk Plus Administrator, you must ensure that the user designated as a Technician has the necessary associations with the sites where the incidents are expected to be filed. Failure to associate the Technician user with the relevant sites could lead to errors due to insufficient coverage in the integration setup.

Preliminary setup - Lumu portal

You must collect the following information from the Lumu portal:

• Lumu Defender API key.
• 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

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.

#!/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/servicedesk-plus-on-premise-ticketing:latest
INTEGRATION_NAME=lumu-servicedesk-plus-on-premise-ticketing
INTEGRATION_DIR=${HOME}/ServiceDeskOnPremise
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 "  SERVICEDESK PLUS ONPREMISE 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:

• Configure the integration.
• Start the integration.
• Check the status of the integration.
• Check the audit logs of the integration.

You can check these options by running the following command:

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, prompting 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 of the third-party solution. Fix any errors in your inputs if prompted.

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

Run the Integration

Run the integration by running this command.

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

After you have successfully completed the integration, you can run the following command to check its current status.

For additional debugging or information, you can execute the relevant Docker commands detailed in the Troubleshooting section of this document.

Monitor the console output for any unexpected errors. If there are any errors present, fix them and run the command again. Check the Troubleshooting section for further reference.

Review the integration logs

You can use this command to check the integration logs.

Expected results

Upon execution of the script, the updated list of incidents will be visible, mapped as requests in the Request Tab view.

Limited actions, such as changing the status (in progress, on hold, and closed), can be synchronized between the two service consoles.

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-radware-defensepro-response
  

• Starting the integration Run the following command to start the integration.
  
  docker start lumu-radware-defensepro-response

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.

Network Connection Problems

Logs indicating a connection problem will often contain keywords such as timeout or connection error. These terms are suggestive of an underlying network issue, check the network and internet status and try again.