Create a custom detection

Triggers generate custom detections by calling the commitDetection function in the trigger script.

1. Click the System Settings icon and then click Triggers.
2. Click Create.
3. Specify the following trigger configuration settings:

   Name

   Type a name for your trigger. This name identifies your trigger, not the detection.

   In our example, we will enter the name: Custom Detection: PowerShell Connection to Suspicious Site.

   Description

   (Optional) Type the trigger description. This description is for the trigger, not the detection.

   In our example, we will enter the description: Creates a detection every time a PowerShell client connects to pastebin, raw.githubusercontent.com, or githack. PowerShell clients are identified by JA3 hashes.

   Events

   Select the event on which the trigger runs.

   In our example, we will select the SSL_OPEN event. This event occurs when an TLS connection is first established.

   Assignments

   Select the device or device group that you want to monitor. Initially, assign your trigger to a single device for testing. After you have confirmed that the custom detection works properly, assign the trigger to a device group that contains all of the devices you want to monitor.

   Because PowerShell is a Windows command-line tool, select a Microsoft server to test the trigger. After you confirm that the custom detection is working correctly, change the assignment to a device group that contains all your critical Microsoft servers. For more information about creating device groups, see Create a device group.

4. In the right pane, type the code that determines when your custom detection is generated.
   In our example, the following trigger code identifies when a client initiates connection to pastebin, githubusercontent, or githack:

   if(SSL.host.match(/pastebin/i) || SSL.host.match(/raw.githubusercontent.com/i) || SSL.host.match(/githack/i)) {
   
   }
   

   Copy
5. Next, type the code that commits your custom detection. The commitDetection function must be written in the following format:

    commitDetection('<detection type ID>', {
           title: '<title>',
           description: '<detection description>',
           categories: ['<category>'],
           riskScore: <risk score>,
           participants: [{
               object:<offender participant>,
               role: 'offender'
               }, {
               object: <victim participant>,
               role: 'victim'
               }],
           identityKey: '<identity key>',
           identityTtl: '<time period>',    
           });
   

   Copy

   Enter values for each of the following parameters in your script.

   Value	Description
   detection type ID	A unique string that identifies your custom detection. This string can only contain letters, numbers, and underscores.
   title	Text that appears at the top of the detection card. Type a descriptive title that is easy to scan. This title appears in the Detection Catalog as the display name for your detection type, preceded by [custom].
   detection description	Text that appears below the title and category on a detection card. Type information about the event that generates the detection. This field supports markdown. We recommend that you include interpolation variables to display specific information about your detection. For example, the variables $(Flow.client.ipaddr) and $(Flow.server.ipaddr) display the IP address of the client and server device in the flow and $(Flow.l7proto) displays the L7 protocol. Include \n at the end of each line of text to make sure the description displays correctly.
   risk score	A number that measures the likelihood, complexity, and business impact of a security detection. The risk score icon appears at the top of the detection card and is color coded by severity as red (80-99), orange (31-79), or yellow (1-30). You can sort detections by risk.
   offender participant victim participant	An array of objects that identifies the participants in the detection. Define the role of the participant as either 'offender' or 'victim' and provide a reference to a device, IP address, or application object for that role. For example, the following array identifies the server as the offender and the client as the victim in a flow: participants: [ { role: 'offender', object: Flow.server.device}, { role: 'victim', object: Flow.client.device } ] Copy For more information about device, IP address, and application objects, see the Trigger API Reference.
   identity key	A string that enables the identification of ongoing detections. If multiple detections with the same identity key and detection type are generated within the time period specified by the identityTtl parameter, the detections are consolidated into a single ongoing detection. Create a unique identity key string by combining characteristics of the detection. For example, the following identity key is created by combining the server IP address and the client IP address: identityKey: [Flow.server.ipaddr, Flow.client.ipaddr].join('!!') Copy
   time period	The amount of time after a detection is generated that duplicate detections are consolidated into an ongoing detection. The time period is reset, and the detection does not end until the time period expires. The following time periods are valid: hour day week The default time period is hour.

   The following example shows the completed script section.

   commitDetection('powershell_ja3', {
           title: 
   'PowerShell / BitsAdmin Suspicious Connection',
           description: 
   "This TLS client matched a variant of PowerShell." + "\n"+
   "Investigate other client behaviors on the victim host." + "\n"+
   "- ** PowerShell/BitsAdmin JA3 client match**" + "\n"+
   "- **Client IP:** " + Flow.client.ipaddr + "\n"+
   "- **JA3 Client Value:** " + ja3 + "\n"+
   "- **JA3 Client Match:** " + suspect_ja3_hashes[ja3],        
           riskScore: 60,
           participants: [{
               object:Flow.client.device,
               role: 'offender'
               }],
           identityKey: [
               Flow.server.ipaddr,
               Flow.client.ipaddr,
               hash
           ].join('!!'),
           identityTtl: 'hour',    
   });
   

   Copy

   These values appear in the detection card similar to the following figure:
   

   

   
   

6. Click Save and then click Done.
   See Example Custom Detection Trigger for a complete annotated script.

After you create a trigger to generate your custom detection, you can create a custom detection type in the Detection Catalog to add more information to your detection.

1. Log in to the ExtraHop system through https://<extrahop-hostname-or-IP-address>.
2. Click the System Settings icon and then click Detection Catalog.
3. On the Detection Catalog page, complete one of the following steps:
   • If your trigger has already run, the system automatically adds your custom detection to the catalog with the display name specified in the trigger preceded by [custom]. Click the detection type to edit.
   • If your detection type has not been created, click Create.
4. Complete the following fields:

   Display Name

   Type a unique name for the title of the detection.

   Detection Type ID

   Type the value that you entered for the detection type ID in the trigger. For example, if you typed: commitDetection('network_segmentation_breach'), the detection type ID is "network_segmentation_breach". You can not edit the detection type ID after the detection type is saved.

   Author

   Type the author of the custom detection.

   MITRE Technique

   From the drop-down list, select one or more MITRE techniques that you want to link to the detection.

5. Click Save.