Skip to main content
Version: 2.14.1

ManageEngine ServiceDesk Plus Zero Trust Alert to Problem Sync

Free integration setupWe’ll install and validate this for you.
Book a setup call

Support Statement​

DISCLAIMER

This documentation is provided "as is" without support for 3rd party software. The level of support for this integration guide is best effort without any SLA on response time. No 3rd party product support can be provided by Superna directly. 3rd party components require support contracts. See EULA for more details.

Overview​

Customers using ServiceDesk Plus get a comprehensive service management solution integrating ITSM, IT asset management, and a CMDB, alongside enterprise service management tools for departments like HR, facilities, and finance. It can be deployed on-premises or in the cloud.

Solution Overview​

Superna Defender Zero Trust API receives webhook alerts and parses the key data into problems that are sent to ManageEngine ServiceDesk Plus. ManageEngine ServiceDesk Plus is a modular architecture that provides real-time visibility of your IT infrastructure, which you can use for threat detection and prioritization using problems created by this integration.

Advanced Zero Trust Capabilities​

  • Webhook to native syslog alarm integration

What Is ManageEngine ServiceDesk Plus?​

ManageEngine ServiceDesk Plus maps CyberStorage threats to UDM-formatted problems in ServiceDesk Plus, providing real-time visibility of your IT infrastructure for threat detection and prioritization.

Integration Architecture​

ManageEngine ServiceDesk Plus integration architecture

Integration Features​

  • Creates problems from Zero Trust alerts using OAuth authentication
  • Stores access keys in an encrypted file on disk
  • Refreshes access tokens after expiry with rolling limited authentication tokens stored in an encrypted cache
  • Creates notes from Zero Trust events in problem notes and conversations
  • Encodes the event ID into the title with the username listed in the title
  • Updates problem notes on state changes of events in Superna Data Security Edition — closed-state problems are ignored

Solution Configuration in ManageEngine ServiceDesk Plus and Defender Zero Trust​

Prerequisites​

  • Installed Security Edition
  • Eyeglass OS appliance version 15.5 — verify with cat /etc/os-release
  • License key for the Zero Trust API
  • ManageEngine ServiceDesk Plus

Configuration in ManageEngine ServiceDesk Plus​

The steps below create an OAuth configuration to authenticate API calls.

  1. Log in to the developer console for your region. Use the ManageEngine data centers guide to look up your Developer Console URL. For example, the Canada region console is at https://api-console.zohocloud.ca/.

  2. Click Create to create a new self-client OAuth access token.

  3. On the Generate Code tab, configure the following:

    • Scope — paste the following minimal required scopes:

      SDPOnDemand.problems.ALL, SDPOnDemand.setup.ALL

    • Duration — set to 10 minutes

  4. Click Create.

  5. Click Download and save the self_client.json file for use in the steps below.

    note

    The create and download steps must be repeated once the Python code is installed and configured on the Eyeglass VM. The authorization does not return the token after the timer expires — a new JSON file must be generated. Once the token is cached locally, it can be refreshed against the OAuth endpoint as needed by the integration code.

Configuration Steps on Eyeglass Virtual Machine​

High-Level Steps​

  1. Create the Python location to run the application on the Eyeglass VM.
  2. Create the Python main application script.
  3. Create the Linux systemd service and set it to auto-start.
  4. Create the Zero Trust configuration in Defender.
  5. Update the main script to customize it with the ManageEngine ServiceDesk Plus Python code.
  6. Test the script is running as a service.
  7. Create a test event in Defender to validate alerts appear as problems in ManageEngine ServiceDesk Plus.

Configure the Service Start and Python Integration Files​

Log in to the Eyeglass VM via SSH as the admin user:

ssh admin@<your-vm-ip>

Become root:

sudo -s

mkdir -p /opt/superna/cgi-bin

chown -R sca:users /opt/superna/cgi-bin

chmod -R u+rwX,g+rwX /opt/superna/cgi-bin

Switch to the SCA user:

sudo -u sca -s

cd /opt/superna/cgi-bin

Create a Python virtual environment for the integration:

python3 -m venv venv-zt-servicedesk

source venv-zt-servicedesk/bin/activate

Install required Python packages:

pip install flask cryptography requests logging

deactivate

Create integration script files:

touch zt-servicedesk.py

touch zt-servicedesk.sh

chmod +x zt-servicedesk.py

chmod +x zt-servicedesk.sh

Create the zt-servicedesk.sh launch script:

nano /opt/superna/cgi-bin/zt-servicedesk.sh

Paste the following content into the file:

#!/bin/bash

export PATH="/opt/.pyenv/bin:$PATH"

source /opt/superna/cgi-bin/venv-zt-servicedesk/bin/activate

exec python /opt/superna/cgi-bin/zt-servicedesk.py

Make the script executable:

chmod +x /opt/superna/cgi-bin/zt-servicedesk.sh

Exit back to root:

exit

whoami # confirm you are root

Create the systemd service unit file:

nano /etc/systemd/system/zt-servicedesk.service

Paste the following content into the file:

[Unit]
Description=Webhook listener for Zero Trust API translations and integrations
After=network.target

[Service]
Type=simple
User=sca
Group=users
WorkingDirectory=/opt/superna/cgi-bin
ExecStart=/bin/bash /opt/superna/cgi-bin/zt-servicedesk.sh
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Reload systemd to register the new service:

systemctl daemon-reload

Enable the service to start on boot (do not start it yet):

systemctl enable zt-servicedesk

Configure Python Packages and Customize the Integration Code​

  1. Download the Python template code from the link to download (right-click, save as).

  2. Open the Python template file in a text editor. Only replace the placeholder values — do not delete any commas.

  3. Using the ManageEngine data centers guide, locate the Accounts Server URL and API Endpoint for your region. Replace the placeholder values at the top of the Python file:

    TOKEN_URL = "https://accounts.zohocloud.ca/oauth/v2/token"
    API_URL = "https://servicedeskplus.ca/api/v3/problems"

  4. Open the production file on the Eyeglass VM:

    nano /opt/superna/cgi-bin/zt-servicedesk.py

  5. Open the template file locally in Notepad, select all (Ctrl+A), and copy.

  6. Paste the clipboard into the SSH terminal session with the open nano editor.

  7. Save the file:

    • Press Ctrl+X
    • Answer Yes to save and exit

  8. Copy the self_client.json OAuth configuration file to the Eyeglass VM:

    • Open the self_client.json file locally in a text editor and copy all the text.

    • On the Eyeglass VM:

      nano /opt/superna/cgi-bin/self_client.json

    • Paste the clipboard into the nano editor.

    • Press Ctrl+X and answer Yes to save and exit.

  9. Download an access token. This sends the self_client.json file to the account API endpoint and returns an access token with the OAuth scope encoded into the token. The token is encrypted and stored in tokens.enc, and a random decryption key is created called secret.key:

    whoami  # confirm you are root

    cd /opt/superna/cgi-bin

    python3 zt-servicedesk.py --get-token

    Verify no errors occur. Do not proceed past this step unless you see a token returned with success from the command.

Configure Defender Zero Trust Webhooks​

  1. Configure the Zero Trust endpoint in the Ransomware Defender Zero Trust tab.

    Recommended Configuration

    Send only Critical and Major events, and only webhooks that set lockout or delayed lockout. The goal is to send findings rather than a list of alarms that do not pinpoint a security incident. Customers can customize based on specific requirements.

  2. The endpoint URL uses localhost and sends webhooks to the application service listening on port 5000:

    http://localhost:5000/webhook

  3. Add the Content-Type header with value application/json to complete the webhook configuration.

  4. Click Save to commit the configuration.

  5. Click Save on the main Webhook configuration page.

How to Test the Integration with ManageEngine ServiceDesk Plus​

  1. Download the curl command template and open it with a text editor. Locate the IP address of Eyeglass at the very end of the text and replace it with the IP address of your Eyeglass VM.
  2. Copy all the text in the text editor.
  3. SSH to the Eyeglass VM as the admin user.
  4. Paste the entire CLI command to the SSH prompt to send sample data to the running Zero Trust application. This sends test data directly to the application to be processed and sent to ManageEngine ServiceDesk Plus.

A successfully processed webhook test returns the following text in the SSH terminal:

done sending event to zt-servicedesk and check for http 200 and success count in response

To review the process logs from the web application:

sudo -s

journalctl -f -u zt-servicedesk

To log to a file and review with nano, showing only the most recent 250 lines:

journalctl -f -n 250 -u zt-servicedesk > /tmp/zt-servicedesk.log

nano /tmp/zt-servicedesk.log

The response code from the ManageEngine ServiceDesk Plus API call should show HTTP 200 status code to indicate the problem was successfully created.

Log in to ManageEngine ServiceDesk Plus and verify that a new problem was created.

Starting the Integration Code for Production Use​

systemctl start zt-servicedesk

systemctl status -l zt-servicedesk

Verify the service returns "active and running". If the service does not start, do not proceed — double-check the steps above.

ManageEngine ServiceDesk Plus SecOps Administrators Integration Experience​

When problems are created, the root cause and impact fields are updated along with details of the event in the description. The title of the problem includes the username that was affected.