Triggers (Webhooks)

A quick and easy way of integrating with other security suites

Triggers are the main extensibility mechanism for AIR to receive alerts from other security suites such as SIEM/SOAR/EDRs.

A trigger is the combination of a parser, an acquisition profile, and a destination for saving the collected evidence (either local or remote options are available).

Users access Webhooks via the Integrations button in the Main Menu and by selecting Webhooks from the Secondary Menu. To create a new Webhook select +Add New:

Where to create a new webhook or to select an existing one (none currently exist in the example shown)

Before you start

• Triggers are basic REST endpoints that can be called via HTTP GET or POST methods

• Each trigger

  • Starts with the AIR Console address (AIR-ADDRESS)

  • Has a name that makes it easy to remember (TRIGGER-NAME)

  • Has a security token (TRIGGER-TOKEN) attached to it that can be regenerated when needed

  • Optionally an Endpoint Identifier that could either be the hostname or the IP address of the endpoint trigger is being called for

    • GET Triggers expect this information in the URL

    • POST Triggers extracts this information from the Webhook Payload

Parts of a Trigger URL

http://<AIR-ADDRESS>/api/trigger/<TRIGGER-NAME>/{endpoint}?token=<TRIGGER-TOKEN>

Parsers

To make it easier to integrate with any trigger source, AIR provides two alternative methods of receiving endpoint information (name or IP address):

• URL Parser (HTTP GET)

• Webhook Parser (HTTP POST)

1. URL Parser

This method requires the trigger source to provide an endpoint name or IP address directly in the URL.

Below is an example GET request and response for collecting "Browsing History" from an endpoint with the name "JohnPC".

Request: http://192.168.1.100/api/trigger/browsing-trigger/JohnPC?token=...

Response (application/json)
HTTP 200 
{
 "success": true,
 "data": 
 {
   "parser": "URL",
   "acquisitionProfile": "Browsing History",
   "endpoints": ["JohnPC"]
 }
} 

Even without using a SIEM/SOAR, the above URL can be used for starting an acquisition task simply by:

• Visiting it with a web browser,

• Adding it to the click action of an HTML button in your case management alert reports,

• Creating a simple script for making a GET request to this address.

2. Webhook Parser

Webhook parsers require the trigger source to provide the endpoint information inside a JSON payload which is POSTed to the trigger.

Splunk Parser which is provided out-of-box is a very basic example of this. After adding a trigger URL as a POST workflow action, whenever Splunk generates an alert for an endpoint, it posts JSON alert data containing the endpoint information as a nested property which is parsed by the trigger parser. The parser then uses this information for starting an acquisition on the endpoint automatically. You can read Splunk POST Workflow Actions documentation for more information.

You can contact [email protected] for requesting additional trigger parsers for major SIEM/SOAR/EDR products.

Security

Each created trigger contains a dedicated security token that can be revoked at any time.

Once you re-generate a security token, all previous integrations using the old security token will start receiving HTTP 401/Unauthorized.