Administration Guides

Custom email or Webhook routing by application or alarm subject contents

Home


Overview

This solution guide explains how to configure custom email routing of specific alarms or notifications within Eyeglass.  This is most commonly used for Easy Auditor or Ransomware Defender to route email notifications to a specific email or group distribution email.  This also ensures other system level alarms are not sent to these emails.    The steps below explain how to setup postfix email routing options.  It is also possible to drop emails silently but the alarm is still visible in the GUI Alarms Icon.

Limitations and Unsupported Configurations

  1. When a rule matches your criteria it will exit and no longer match any other rules listed in the configuration files.
  2. Redirection - Multiple emails on a rule or multiple rows with different emails is unsupported. Redirecting emails should always use a group email.
  3. If a configuration is NOT listed below is not supported. 

 Requirements

  1. Opensuse 15.3 OS Latest OS is recommended .

How to switch to Eyeglass mail routing based on postfix OS SMTP Relay

  1. Most Eyeglass deployments use Notification center to enter SMTP details of your mail server. These steps will switch to a local SMTP engine in the operating system.
    1. Requirements:
      1. This example assumes you are using anonymous non authenticated SMTP over port 25.
      2. The advanced section below covers authentication + TLS configuration
    2. Steps
      1. Setup Eyeglass OS SMTP to Send mail to your mail server
        1. ssh to Eyeglass as admin
        2. sudo -s (enter admin password)
        3. Edit the postfix setting: nano /etc/postfix/main.cf
        4. control+w to search for the word relayhost , to locate the correct instance without a comment.  To find the line that is not commented (no # at the front of the line).  You will need to press control+w [enter], repeat this 8 times to find the very last occurrence of relayhost that does not have the # comment in-front of the line.
        5. Edit the relayhost parameter (NOTE: leave the square brackets are required as per example below)
          1. relayhost = [DNS or ip of your SMTP mail server]:25   (leave the square brackets)
        6. To specify the from email address used on ALL outbound emails
          1. nano /etc/postfix/sender_canonical
          2.  On a new line add the source email entered into the Eyeglass GUI notification center from field and desired  outbound FROM email to be used on all emails. In the example below eyeglass@redacted.gz is the email entered into Eyeglass gui.
          3. eyeglass@redacted.gz eyeglass@quazar.redacted
          4. control+x  answer y and enter to save and exit
        7. Open /etc/postfix/master.cf file and add the following services
          1. userFilter unix - n n - 10 pipe flags=Rq user=sca argv=/opt/superna/bin/email_filter.py ${sender} user_1@superna.net,user_2@superna.net
          2. 127.0.0.1:10026 inet n - n - - smtpd -o content_filter= -o receive_override_options=no_unknown_recipient_checks,no_header_body_checks -o smtpd_helo_restrictions= -o smtpd_client_restrictions= -o smtpd_sender_restrictions= -o smtpd_recipient_restrictions=permit_mynetworks,reject -o mynetworks=127.0.0.0/8 -o smtpd_authorized_xforward_hosts=127.0.0.0/8
          The first part it the filter service, userFilter is the service name, it needs to match the name we configure in the body_checks or anywhere it’s used. The user has to be sca otherwise it is going to be a permission issue. The script path is fixed to /opt/superna/bin/email_filter.py . The first argument has to be ${sender} and the second argument is the recipient address that we want to forward to. It can be multiple addresses as long as it is separated by a comma without space. The second part is used to re-inject the email back to postfix smtp pipeline after filtering. It needs to stay exactly the same. 
        8. Restart postfix service
          1. systemctl restart postfix
          2. Checked that postfix service is running: systemctl status postfix

      2. Eyeglass - Switch to use postfix SMTP local OS mail relay service no Authentication

        1. From Eyeglass UI => Notification Center => Configure SMTP => Outgoing Email Server Information
        2. Host Name change to: localhost
        3. Port should stay set to: 25
        4. From  email can stay the same or change: [any e-mail address] e.g. eyeglass@<your domain>
        5. Specify test e-mail recipient and click TEST E-mail Setting. Expect to receive test e-mail successfully.
        6. Do not proceed until this step is successful with a test email being received.
        7. For Advanced email configuration with authentication and TLS cipher control.
        8. Done - No further steps are required unless email redirect rules are needed.

      3. Adding Filtering and Forwarding Rules to Postfix

        1. This requires adding rules for filtering and forwarding emails based on the subject of the alert email or the body.  These are provided as common examples below.
        2. login as admin user over ssh
        3. sudo -s (enter admin password to become root user)
        4. Preparing Configuration files for Content Filtering Rules (Mandatory Step)
          1. Run these commands to enable content filtering on both subject of emails and the body of emails.  
            1. touch /etc/postfix/body_checks  
            2. touch /etc/postfix/header_checks  
            3. postconf -e "body_checks = regexp:/etc/postfix/body_checks"
            4. postconf -e "header_checks = regexp:/etc/postfix/header_checks"
        5. How to Edit the Rules files for email header_checks and for email body_checks
          1. This section explains which files to edit depending on how you want to filter or forward alarm or report emails.   See specific examples in the sections below that you can use for specific scenarios.
          2. Type the command below to edit email subject filter file
            1. nano /etc/postfix/header_checks   (Use this file for email subject line filtering)
            2. nano /etc/postfix/body_checks   (only edit this file if you need email content filtering rules)
            3. To check for specific patterns in the email body, in the body_checks file use a FILTER like in the example below:
            4. /Configuration Replicat/ FILTER userFilter:127.0.0.1:10025 
            5. The userFilter is the service name, it needs to match the name we set in master.cf. After the service name, is the local address 127.0.0.1, it’s fixed. The port number at the end is also necessary. The data will be sent through this port to the userFilter service. It can be any available number.
          3. Requirements for email Filtering Rules
            1. Under line 1 hit enter a few times to make space to add filters.  Note:you can add more than one filter with different emails and conditions
            2. Each rule must be on its own line.
            3. Rules are processed in the order listed in the file and the first match will exit the filtering logic.
            4. The syntax uses regex syntax when creating filters and actions.  A full list is defined here on the postfix man pages. 

      4. Example 1: Send All Ransomware Alarms to a specific email (person or group email) AND Discarding Or Redirecting Security Guard daily Self Test Emails:

        1. The example will send all Ransomware alarms to a specific email regardless of the configured Notification center alarm configuration and allow discarding or redirecting Security Guard test emails.  This example requires body content matching.
          1. Prerequisite:   Switch Eyeglass to use post fix and add your mail server to the relayhost property.  See instructions above.
          2. NOTE: this will match the string in bold and will send to a different email address.
          3. This also means that alarms for this product will not be sent to the Eyeglass administrator.
          4. Security Guard emails will be discarded or forwarded 
          5. Example assumes Security Guard Cluster user name is "igls-sg," change this value depending on the name of the Security Guard user configured in Ransomware Defender.
        2. Discard Security Guard and Forward all other Ransomware Alarms to an specific email
          1. nano /etc/postfix/body_checks    (place each value below on it's own line the order matters to correctly discard first)
            1. /igls-sg/ DISCARD               
            2. /Ransomware Defender/ REDIRECT customer_email@domain.com
        3. OR to Forward Security Guard emails to email A and forward All other Ransomware Alarms to Email B
          1. nano /etc/postfix/body_checks    (place each value below on it's own line)
            1. /igls-sg/ REDIRECT customer_email_A@domain.com               
            2. /Ransomware Defender/ REDIRECT customer_email_B@domain.com
        4. control+x answer y and the enter key to save and exit
        5. Continue to activate step

      5. Example 2: Send Only alarms when a user is locked out by Ransomware Defender to a specific email (person or group email) but will not be sent to the Eyeglass admin defined to receive all alarms

        1. Prerequisite: Switch Eyeglass to use post fix and add your mail server to the relayhost property. See instructions above.
        2. nano /etc/postfix/header_checks (this file for email subject line filtering)
        3. /^Subject: .*Locked/ REDIRECT xxxx@domain.name 
        4. control+x answer y and the enter key to save and exit
        5. Continue to activate step

      6. Example 3: Send Easy Auditor Reports to a specific user or group email , note only this user or group will receive report emails

        1. Prerequisite: Switch Eyeglass to use post fix and add your mail server to the relayhost property. See instructions above.
        2. nano /etc/postfix/header_checks (this file for email subject line filtering)
        3. /^Subject: Easy Auditor Report/ REDIRECT xxxx@domain.name
        4. control+x answer y and the enter key to save and exit

      7. Example 4: Drop all Easy Auditor Report emails

        1. Prerequisite: Switch Eyeglass to use post fix and add your mail server to the relayhost property. See instructions above.
        2. nano /etc/postfix/header_checks (this file for email subject line filtering) 
        3. /^Subject: Easy Auditor Report/ DISCARD
        4. control+x answer y and the enter key to save and exit
        5. Continue to activate step

      8. Example 5: Send Easy Auditor Triggers to a specific email OR send a specific search report to a specific user

        1. Prerequisite: Switch Eyeglass to use post fix and add your mail server to the relayhost property. See instructions above.​
        2. If you want to send a custom trigger or a saved report to a specific user email or group email, you first need the saved report name or the trigger name.
        3. Get trigger names.  We recommend using the word trigger in all triggers and then a name after to make matching alerts easier.  Alerts will include the trigger name in the body of email. 
        4. For a content filter you must add the rule to the body_check file.  See 3 different examples below.
        5. nano /etc/postfix/body_checks (only edit the file if you need content filtering rules, see examples below) 
          1. /trigger/ REDIRECT xxxx@domain.name  (sends all triggers with the name trigger in the name)
          2. /trigger policy 1/ REDIRECT xxxx@domain.name (sends all triggers with a specific name of a trigger in this example the trigger name is "trigger policy 1")
          3. /departmentXReport/ REDIRECT xxxx@domain.name (sends all Easy Auditor report results with a saved report run manually or on a schedule with a name of "departmentXReport")

      9.  Mandatory Step - Activate Filtering Rules for subject or body of email rules 

        1. Reload the rule set to take effect and restart postfix process
          1. postfix reload
          2. systemctl restart postfix
          3. done

How to edit Filter rules

  1. Each time you edit the filter files
    1. nano /etc/postfix/body_checks    (email body rules)
      1. OR
      2. nano /etc/postfix/header_checks (email header rules)
    2.  You must restart postfix before any changes will take effect.
    3. Activate filter rules

How to Test your new filter or forwarding rule

  1. The examples that use Easy Auditor reports or Ransomware Defender can be tested using Security Guard and Robot Audit run now option to trigger a new alarm.
  2. To verify your rule worked you can tail the mail routing log to see the rule rewrite the original email recipient with new email address.
  3. tail -f -n 100 /var/log/mail    (this command will monitor the mail log during the test)
  4. or you can search the log
  5. grep orig_to /var/log/mail*  (this will locate all entries that the redirect rule triggered and shows the original email and new email used)
  6. Example output shows to original email and the new to email as per below.
  7. Done


How to convert previous Opensuse OS postfix main.cf to Opensuse 15.3 or later Postfix format

  1. This procedure is for backup and restore of an appliance running 15.1 or 15.2 to a 15.3 or later OS that had postfix configured.   Release 2.5.8 backup includes the main.cf, body and header check files.  NOTE: You may need to get these file from your old appliance if the old appliance release is < 2.5.8
  2. Login to the new appliance and follow the steps below.
    1. ssh admin
    2. sudo -s
    3. unzip the Eyeglass backup used to restore the new appliance configuration on a Window PC , locate the postfix backup files and open main.cf in notepad and locate the relayhost line that includes your mail server.
    4. Edit the postfix file on the new appliance
      1. nano /etc/postfix/main.cf 
      2. control + w  enter relayhost press enter, you will need to search 8 times to find the the line without # comment
      3. Fix the relayhost field  with the values from the main.cf opened in notepad from the backup file.
        1. Add the value from the backup to the relayhost =   line in the file opened from the ssh session with nano editor  
        2. relayhost = [DNS or ip of your SMTP mail server]:25 (leave the square brackets) 
    5. Re-apply body and header checks prepare new appliance
      1. Open the header_checks and body_checks files from the backup zip file in notepad
      2. From ssh session to new appliance
        1. touch /etc/postfix/body_checks
        2. touch /etc/postfix/header_checks
        3. postconf -e "body_checks = regexp:/etc/postfix/body_checks"
        4. postconf -e "header_checks = regexp:/etc/postfix/header_checks"
    6. Re Apply previous forwarding filtering rules
      1. nano /etc/postfix/body_checks (paste body_checks from notepad to this file)
      2. control + x  answer yes to save and exit
      3. nano /etc/postfix/header_checks  (paste header_checks from notepad to this file)
      4. control + x  answer yes to save and exit 
    7. Activate the configuration
      1. postfix reload
    8. Test email in Eyeglass and test your rules


Advanced Postfix Configuration For SMTP Authentication and TLS Configuration

  1. This section allows configuration of authentication to your mail system and control of TLS options.
  2. NOTE:  Authentication + TLS is the only supported configuration.
  3. NOTE: This assumes you have configured the relay and basic settings in the section above for switching to postfix MTA.
  4. ssh as admin user
  5. switch to root
    1. sudo -s (enter admin password)
  6. Fix the host file to provide a host name for localhost used by postfix mail relay
    1. nano /etc/hosts file, add the Eyeglass hostname fqdn in the localhost section. example:
      127.0.0.1 localhost igls01 igls01.ad1.test
  7. Edit the postfix setting for Authentication.
    1. nano /etc/postfix/main.cf
    2. Verify the relayhost parameter is set already following steps in the basic configuration section above and change the port to use the TLS port.  control-w type relayhost [enter] and repeat 8 times to find the correct entry.
      1. relayhost = [x.x.x.x]:587   (leave the square brackets)
      2. Replace x.x.x.x with your mail relay host IP or FQDN
    3. Configure Authentication
      1. edit the following parameters for TLS
      2. nano /etc/postfix/main.cf   
        1. press control+w  enter sasl [enter] to locate the section for authentication configuration.  Set the settings as per below 
      3. smtp_sasl_auth_enable = yes
      4. smtp_sasl_security_options = noanonymous
      5. smtp_sasl_password_maps = lmdb:/etc/postfix/sasl_passwd
      6. smtpd_sasl_auth_enable = no
      7. Create the password file  /etc/postfix/sasl_passwd  replace the yellow values to match your environment before creating the file.
        1. nano /etc/postfix/sasl_passwd     (enter the line below and change the yellow highlights to match your environment.
        2. [x.x.x.x]:587 user:password
          1. x.x.x.x is replaced with the ip address or host name of your mail relay host
          2. This assumes port 587 is used on your mail relay host which is the default TLS SMTP port. Change the port to match your mail server.
          3. User is the user name for authentication.  Example user@domain.com
          4. Password is the password for this service account user.
        3. Convert /etc/postfix/sasl_passwd into a format that Postfix can read and remove clear text password file:
          1. postmap lmdb:/etc/postfix/sasl_passwd
          2. This creates a file /etc/postfix/sasl_passwd.lmdb 
          3. You can now delete or remove the clear text password in the  /etc/postfix/sasl_passwd
          4. rm /etc/postfix/sasl_passwd  (removes clear text password file, since it is not used by postfix.  The DB file is used to read the user and password. 
        4. Secure the /etc/postfix/sasl_passwd.lmdb file.
          1. The file must be owned by root, and no one else should have read access to that file
            1. chown root:root /etc/postfix/sasl_passwd.lmdb 
            2. chmod 600  /etc/postfix/sasl_passwd.lmdb 
        5. Restart postfix service
          1. systemctl restart postfix 
    4. TLS Configuration for Secure SMTP
      1. nano /etc/postfix/main.cf
      2. Control+w type tls [enter]
      3. Locate these sections and configure them to match
        1. smtp_use_tls = yes
        2. smtp_tls_loglevel = 1
      4. Done
    5. This configures authenticated TLS SMTP relay.  Continue with the steps below to debug and test the mail is correctly forwarding from Eyeglass to your SMTP mail system.

How to Debug Postfix mail relay Issues

  1. Verify the mail is correctly being forwarded with authentication by tailing the mail log.
    1. tail -f /var/log/mail
  2. Open the Notification Center Icon in Eyeglass from the main menu options, and send a test email to verify authentication and TLS connections are successful.
  3. Example of a successful TLS SMTP message relay from Eyeglass to external SMTP host with TLS 1.2 enabled.  the 250 OK code indicates successful delivery.  The SMTP error or TLS errors will be visible in this log for debugging.
  1. Check for any queued mail that failed
    1. sudo mailq
    2. any queued mail that failed will be listed with a reason code
    3. To reattempt delivery of the mail use the command below
    4. sudo postfix flush
  2. To provide support with configuration of your postfix configuration use this command
    1. postconf -n



Ransomware Defender & Easy Auditor Webhooks - Alarm Integration

Overview

This new solution only exists with Ransomware Defender to integrate alerts with real-time webhooks with customization of the webhook data that allows SIEM and service automation to consume this alert data.  Security Operations teams can now get Defender alert data sent to 1 or more webhook endpoints.  

How to Configure Zero Trust Webhook Alarm forwarding

  1. Prerequisites - Eyeglass and Ransomware Defender 2.5.12 or later
  2. Login to Ransomware Defender and open the Zero Trust menu
  3. Click the plus sign to add your first webhook target url.
  4. Definitions:
    1. Name:  Give this endpoint a name example Splunk
    2. URL: This is the endpoint url that will receive post messages, consult with your SIEM or security vendor to get this url (see below public website for testing your webhook setup)
    3. Event Severity Filter: Select one or more severities that you want to be forwarded to the webhook.  Example if you only wanted Critical events then only select Critical.
    4. Lifecycle filter: Each security event has a life cycle stages from the beginning of the event until it is acknowledged and cleared.   Each lifecycle change can trigger a post message to the webhook.  This can useful for downstream applications to trigger different actions depending on the stage the security event is currently displaying in Ransomware Defender.    Select 1 or more lifecycle stages and ensure to select all stages that you want sent to the webhook  
    5. Headers - If your endpoint requires authentication header values or custom headers to be processed successfully you can enter key value pairs to add to the webhook headers in addition to the payload.
  5. Click Save to save the webhook definition.
  6. Test your webhook
    1. Click the test webhooks button to test all listed webhooks.  This will send a post message with a sample payload to validate your endpoint can process the webhook.


How to view the payload of webhooks for integration or automation within your Sec Ops Tools


  1. NOTE: This procedures requires direct Internet access or Proxy access to the webhook.site url over port https 443.
  2. Click this url to go to the test webhook.site webpage https://webhook.site/
  3. Copy to clipboard the url that is displayed
  4. Paste this url into the endpoint of a test webhook in Ransomware Defender.
  5. Click the test webhooks button and verify that POST command is displayed on the URL page of the webhook.site page.
  6. Now that your test webhook is working, run Security guard to see the full payload available in the webhook payload.
  7. See below the payload available that includes the user, snapshots, shares and affected files.


{
"id": "#17:7089",
"severity": "CRITICAL",
"state": "ACCESS_RESTORED",
"files": [
"\\\\onefs93\\System\\ifs\\igls-securityguard\\igls-securityguard-test-file-1682791438528.iglsrswtest",
"\\\\onefs93\\System\\ifs\\igls-securityguard\\igls-securityguard-test-file-1682791439555.iglsrswtest"
],
"rowKeys": [
"1682791438575_5763",
"1682791439631_3755"
],
"nes": [
"onefs93"
],
"user": "S-1-5-21-1373226064-2672571480-941775786-1000",
"userName": "sguser",
"shares": [
{
"name": "igls-securityguard",
"zone": "System",
"initialRunAsRoot": [

],
"initialPermissions": [
{
"permission": "FULL",
"permission_type": "ALLOW",
"trustee": {
"id": "SID:S-1-5-21-1373226064-2672571480-941775786-1000",
"name": "sguser",
"type": "USER"
}
},
{
"permission": "FULL",
"permission_type": "ALLOW",
"trustee": {
"id": "SID:S-1-5-21-201832566-3187353407-2829991710-1835"
}
}
],
"clonedInitialPermissions": [

],
"clonedInitialRunAsRoot": [

],
"runAsRoot": [

],
"permissions": [
{
"permission": "READ",
"permission_type": "DENY",
"trustee": {
"id": "SID:S-1-5-21-1373226064-2672571480-941775786-1000",
"name": "sguser",
"type": "USER"
}
},
{
"permission": "FULL",
"permission_type": "ALLOW",
"trustee": {
"id": "SID:S-1-5-21-201832566-3187353407-2829991710-1835"
}
}
],
"neSyncKey": "onefs93_00505699edf0a9bc7561f61c46856c418a3b",
"neName": "onefs93",
"path": "/ifs/igls-securityguard/",
"clients": [

],
"roClients": [

],
"rwClients": [

],
"rootClients": [

],
"allowVariableExpansion": false
}
],
"detected": "Apr 29, 2023, 2:03:58 PM",
"detectedTime": 1682791438663,
"firstSignalTimeStamp": 1682791438575,
"archivedTime": 0,
"lockedOut": "Apr 29, 2023, 2:04:11 PM",
"lockedOutTime": 1682791451527,
"expiryTime": 0,
"expiry": "n/a",
"actions": [
{
"action": "Comment",
"dateInLong": 1682791438663,
"resultState": "TO_LOCKOUT",
"admin": "",
"comment": "Signal received; New event is raised"
},
{
"action": "Comment",
"dateInLong": 1682791452494,
"resultState": "LOCKED_OUT",
"admin": "",
"comment": "Signal received; Event state going to LOCKED_OUT"
},
{
"action": "Comment",
"dateInLong": 1682791452323,
"resultState": "LOCKED_OUT",
"admin": "",
"comment": "Saved locked out shares"
},
{
"action": "Comment",
"dateInLong": 1682791447871,
"resultState": "TO_LOCKOUT",
"admin": "",
"comment": "Creating Snapshots for User sguser<br>Successfully created snapshot onefs93 - igls-critical-path-ifs-data-demo2-17_7089-1682791438818.<br>Successfully created snapshot onefs93 - igls-sguser-System-igls-securityguard-17_7089-1682791439983."
},
{
"action": "Comment",
"dateInLong": 1682791447956,
"resultState": "TO_LOCKOUT",
"admin": "",
"comment": "Creating Snapshots for User sguser<br>Successfully created snapshot onefs93 - igls-critical-path-ifs-data-demo2-17_7089-1682791438818.<br>Successfully created snapshot onefs93 - igls-sguser-System-igls-securityguard-17_7089-1682791439983."
},
{
"action": "Lockout",
"dateInLong": 1682791451527,
"resultState": "LOCKED_OUT",
"admin": "",
"comment": "Lockout access result:<br>onefs93: successfully locked share System:igls-securityguard for user sguser."
},
{
"action": "Comment",
"dateInLong": 1682791452731,
"resultState": "LOCKED_OUT",
"admin": "security_guard",
"comment": "Security Guard restore user<br><br> Restore job initiated, please wait for restore job to finish <br>"
},
{
"action": "Restore User Access",
"dateInLong": 1682791453990,
"resultState": "ACCESS_RESTORED",
"admin": "Successfully restored: ",
"comment": "Shares restore access result:<br>Successfully restored permissions of share System:igls-securityguard."
}
],
"possibleActions": [
"Archive As Unsolved",
"Lockout",
"Restore User Access",
"Archive as False Positive",
"Comment",
"Archive as Recovered",
"Create Snapshot"
],
"signalStrengths": {
"THREAT_DETECTOR_06": 2
},
"predicted": {
},
"isRoot": false,
"monitorOnly": false,
"peakMonitor": 2,
"peakWarning": 2,
"peakMajor": 2,
"peakCritical": 2,
"clientIPs": [
"172.31.1.102"
],
"numFiles": 2,
"isAudit": false,
"isRSW": true,
"isNFSMonitorMode": false,
"isSMBSnapshotEnabled": true,
"eventSource": "ISILON_CLUSTER",
"displayUserActivity": false,
"protocol": "SMB2",
"snapshots": {
"onefs93": [
{
"pct_reserve": 0.0,
"shadow_bytes": 0,
"name": "igls-critical-path-ifs-data-demo2-17_7089-1682791438818",
"created": 1682791441,
"expires": 1682964238,
"state": "active",
"has_locks": false,
"path": "/ifs/data/demo2",
"pct_filesystem": 4.871556484431494e-06,
"id": 55189,
"size": 4096
},
{
"pct_reserve": 0.0,
"shadow_bytes": 0,
"name": "igls-sguser-System-igls-securityguard-17_7089-1682791439983",
"created": 1682791444,
"expires": 1682964239,
"state": "active",
"has_locks": false,
"path": "/ifs/igls-securityguard",
"pct_filesystem": 3.653667363323621e-06,
"id": 55191,
"size": 3072
}
]
},
"deletedSnapshots": [

],
"nfsProtocols": [
"nfs",
"nfs4"
],
"isAPIEvent": false,
"rswExtensions": [

],
"extraParams": {
}
}


Ransomware Defender & Easy Auditor ServiceNow Webhook alarm to Incident Integration


  1. This integration examples shows how to configure Ransomware Defender Webhook alarms to create an incident in ServiceNow and include the details of the alert in the description.  NOTE This is a basic example only and would need to be customized further to map fields in the webhook payload to specific ServiceNow fields.   
  2. Using this guide (How to Integrate Webhooks Into ServiceNow) create a ServiceNow Scripted Rest Resource Webhook
    1. Example Scripted REST

      2. In the script section


Sample Scripted REST API Webhook

Cope Code below and paste it into the Script editor.

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {

// use payload data from Defender to map the alarm to Servicenow. The payload needs to be json parsed to gain access to the properties
var requestBodystring = request.body.dataString;
var requestBodyjson = JSON.parse(requestBodystring); //used to extract properties
var incident = new GlideRecord('incident');
incident.initialize();
// get fields from the payload to build a good short description summary
var affectedUser = requestBodyjson.userName; // user name affected by the event
var eventState = requestBodyjson.state; //map alert state to state of incident property in Service now

var affectedCluster = requestBodyjson.nes; // list of affected PowerScale Clusters affected
affectedCluster = affectedCluster.join(", "); //create a string of the cluster names
var affectedShares = requestBodyjson.shares; //list of affected clusters
var shareNames = []; //to store smb share names
// loop through the array of smb shares to turn into a text value to add to the Short Description
for (var i = 0; i < affectedShares.length; i++) {
var share = affectedShares[i];
var shareName = share.name;
shareNames.push(shareName);
}
var shareNamesString = shareNames.join(", "); //create a string of the share names
var shortDes = 'Superna Ransomware Defender Alert - Affected User ' + affectedUser + ', Affected PowerScales ' + affectedCluster + ', Affected SMB Shares ' + shareNamesString + ', Event state ' + eventState;
incident.short_description = shortDes; //set the short description to the summary build from the payload above
incident.description = requestBodystring; //This takes the entire payload of the alert from Defender and stores it in the description of the Incident.
incident.caller_id = 'john.doe'; // Sample caller ID or user name
incident.category = 'Software'; // Sample category
incident.subcategory = 'Superna Ransomware Defender'; // Sample subcategory
var severity = requestBodyjson.severity; //extract the severity of the alerts and map to service now
if (severity == "CRITICAL") {
incident.impact = 1; //set impact to High if alarm is critial
incident.urgency = 1; // Sample urgency level (1: High, 2: Medium, 3: Low)
}
if (severity == "MAJOR") {
incident.impact = 2; //set impact to Medium if alarm is Major
incident.urgency = 2; // Sample urgency level (1: High, 2: Medium, 3: Low)

}
if (severity == "MONITOR") {
incident.impact = 2; //set impact to Medium if alarm is MONITOR
incident.urgency = 2; // Sample urgency level (1: High, 2: Medium, 3: Low)
}
if (severity == "WARNING") {
incident.impact = 3; //set impact to High if alarm is Warning
incident.urgency = 3; // Sample urgency level (1: High, 2: Medium, 3: Low)
}
var sysId = incident.insert();

if (sysId) {
gs.info('Incident created successfully. Sys ID: ' + sysId + ', Number: ' + incident.number);
response.setStatus(201);
response.setBody({
'sys_id': sysId,
'number': incident.number
});
} else {
gs.error('Failed to create incident.');
response.setStatus(500);
response.setBody({
'error': 'Failed to create incident.'
});
}

})(request, response);

See example below


Steps to use the endpoint with Defender Webhooks

  1. Save the Resource script after you paste it
  2. Disable Security for testing.
    1.   
  3. Get the endpoint url for the webhook in Defender
    1. The resource would be https://yourInstance.service-now.com/<resource_Path> 
    2. In this example the resource path is displayed in the editor
    3.  
  4. Configure the Webhook in Ransomware Defender Zero Trust UI 
    1. See guide above for more details
    2. See below with head added for Content-Type and value application/json
    3.  
  5. Save and click the test button
  6. If successfully configured you will recieve an Incident number back see below.
  7.  
  8. Done


Production Integration Steps

In this example, the variables are filled with sample values but could be extracted from the Alarm payload sent by Ransomware Defender and mapped to the ServiceNow fields

  1. The code sample above includes logic to extract variables from the payload of the Zero trust Ransomware Defender and maps the Severity fields in the Superna alarm to map to the ServiceNow Impact and Urgency incident fields.   This code can be modified to change the mapping as required.
  2. The short description was used to summarize the key data in Security events.  This can also be customized further.



Example Incident Created with Zero Trust Webhook and ServiceNow Scripted REST API Capability


© Superna Inc