Technical Tip: Real-time event Notifications using EDR Custom Connector and Action Scripts

[Keith_Gurev]

Description

This article describes about real-time event notifications using EDR Custom Connector and Action Scripts.

Scope

FortiEDR.

Solution

EDR Custom Integration Connector: Security Event Push Notification.

FortiEDR features adding a Custom Connector with actions set by Python scripts. These scrips are called 'Action Scripts' and are ran on customer's Jumpbox.

In this example, event data will be sent to a Discord Webhook and will generate a real-time Event notification sent to the Discord logged in user.

This article shows how to create the Custom Connector and an Action Script using Python's requests library to send out event data as soon as an event comes in.

Third party systems can then take actions using the provided event data.

1) Create a Discord account and create a Webhook for receiving the notifications. Follow the steps on 'Making a Webhook' on https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks

The Webhook link should be similar to this:

https://discord.com/api/webhooks/983192089024167997/2rTPCXdnYlnbeGC1m91HKPZa9SRx-skAzA2akMz1wZv6py2W...

Take note of the number and the unique string.

These will be the Username and Password used in the Custom Connector.

For this Webhook link it is:

Username: 98319xxxxxxxxxx
Password: 2rTPCXdxxxxxxxxx

FortiEDR features adding a Custom Connector with actions set by Python scripts.

These scrips are called 'Action Scripts' and are ran on customer's Jumpbox. 

In this example, event data will be sent to a Discord Webhook and will generate a real-time Event notification sent to the Discord logged in user.

This article shows how to create the Custom Connector and an Action Script using python's requests library to send out event data as soon as an event comes in.

Third party systems can then take actions using the provided event data.

2) Create an Action Script. Open text editor and paste the code below. Save it as discord_custom_script.py

import json
import platform
import requests  # imports requests library used for creating HTTP/S connections
with open('config.json') as json_file:
    conf = json.load(json_file)

PARAMS = conf.get('PARAMS', {})

if __name__ == "__main__":

    # Grabs host, port, username and password from Custom Connector Configuration Screen
    mUrl = 'https://' + PARAMS['ConnectorHost'] + ':' + PARAMS['ConnectorPort'] + '/api/webhooks/' + PARAMS['ConnectorUsername'] + '/' + PARAMS['ConnectorPassword']
    
    # Set headers and prepare eventdata variable.
    headers = {'Content-type': 'application/json'}
    eventdata = ''
    
    
    # entireEvent key only exists for real Events.
    if 'entireEvent' in PARAMS:
        EVENT = json.loads(PARAMS.get('entireEvent', {}))
        
        # AutomationData key content is too long. Summarize it with AutomationData comment only.
        EVENT['AutomationData'] = EVENT['AutomationData']['comment']
        
        # Convert EVENT keys to plain string, truncate values at 90 chars.
        for key, val in EVENT.items():
            eventdata = eventdata + '**' + key + '**: ' + str(val)[:90] + '\n'
            
    # For testing the connector in the Custom Connector configuration screen, use the entie PARAMS contents because entireEvent does not exist (testing does not use a real event).   
    else:
        # Because of testing just convert PARAMS keys to plain string, truncate values at 90 chars.
        for key, val in PARAMS.items():
            eventdata = eventdata + '**' + key + '**: ' + str(val)[:90] + '\n'
            
    
    # Format response content for Discord. Also truncate the message with 2047 characters because thats Discord's limit.
    webhookdata = { "content": None, "embeds": [ { "title": "FortiEDR Notification", "description": eventdata.replace("u'", "'")[:2047], "color": 5814783 } ] }
    
    # Sends webhook with real time notification to Discord.
    response = requests.post(mUrl, headers=headers, json=webhookdata)


    # Prints to stdout success or failure.
    if(response.status_code == 204) :
        print('Successfully sent webhook.')
        exit(0)
    else :
        print('Failed sending webhook.')
        print(response.content)
        exit(1)

3) Add a new Action in the Action Manager and upload the script.

4) Add the Custom Connector and then select on '+ Add Action' to assign the uploaded Action Script to the Custom Connector. 

Fill the host, port like the screenshot below and use the Username and Password noted in the Webhook.

5) Save, test and enable it. If the test succeeds, get the test notification message in Discord.

6) Assign it to a playbook. Note CUSTOM is now available at the bottom of the Playbook.

7) New events will now generate real-time Discord notifications like the below: