Skip to main content

Action EditorAction Editor Documentation

Table of Contents

Create a Custom Action Using Action Editor

After you create a custom service from scratch or clone an out-of-the-box service, create a custom action.

1. Add Basic Information about the Action

Name and describe the action to help you identify it when you configure an action node and manually run an action. The action name also appears in the service settings under service details.

Selecting an action type automatically populates the description and inputs for the service. If you don't find an action type that best describes your custom action, create a new action type.

  1. Select a custom service, then next to Actions, click A grey plus symbol..

  2. Enter basic information about the action:

    • Action name – Enter a name for the action. This appears when you select a service to configure a playbook action node.

      Since the action name is used throughout the action's back end, you must carefully choose the action name and review it before you continue. If you return to this step to rename the action, you lose all your work and must reconfigure the action from scratch.

    • Action type – An action type defines an action's basic metadata, inputs, and outputs. To automatically populate the action's description, inputs, and outputs, select an action type that best describes your action from the list.

      If you don't see an action type that describes your action, create your own action type. In the Select action type field, start typing, then click Add [action type]. If you create your own action type, you must enter a description and define all inputs and outputs.

    • Description – Describe the action, what it does, and what it's used for. This description appears when you manually run an action in the workbench.

  3. Review the action name, then click Next.

2. (Optional) Configure Action Inputs

An input is a parameter passed to the action and used to produce an output. You enter a value for the input when you manually run an action or configure a playbook action node.

You don't have to configure inputs if the action can get the information it needs from within the service host, using the information you provided when you configured the service. For example, the out-of-the-box List Context Tables action doesn't require any inputs because the Advanced Analytics API can retrieve a list of context tables without you providing additional information.

  1. Click + Add an Input.

  2. Fill in information about the input:

    • Name – Enter a name for the input. You refer to this name in Python code you write later.

    • Display name – Enter a name that appears when you configure an Incident Responder playbook action node and select an input.

    • (Optional) Description – Describe the input.

    • Data type – Select the intended data type of the input value: URL, String, Password, Long, Boolean, Large_text, Hash, Picklist, File Artifacts, or File Entity.

  3. If you can enter or select multiple input values, select the ALLOW MULTIPLE checkbox. If you can only enter or select one input value, don't select the checkbox.

  4. If you must configure this input to run the action, select the REQUIRED checkbox. If you don't need to configure this input to run the action, don't select the checkbox.

  5. If you can type in text as an input value, select the ALLOW USER INPUT checkbox. If you can only select a pre-defined input value, don't select the checkbox.

3. Configure Action Outputs

An output is a parameter that the action returns after it processes and uses the input parameter.

In a playbook, the output of an action node is used as an input for the next node. The final output of a playbook, and the output for an action you manually run, appear in an incident's workbench.

  1. Click + Add an Output.

  2. Fill in information about the output:

    • Name – Enter a name for the output. You refer to this name in Python code you write later.

    • Display name – Enter a name that appears when you configure an Incident Responder playbook action node and use the output of the previous node as the input.

    • (Optional) Description – Describe the output.

    • Data type – Select the intended data type of the output value: URL, String, Password, Long, Boolean, Large_text, Hash, Number, or Timestamp.

    • Data path – After you execute the action, the output is stored in a JSON file. Enter the file path for the JSON file. This file path is passed to the next playbook node as an input.

  3. If the action can output a list of multiple values, select the ALLOW MULTIPLE checkbox.

  4. Click Next.

4. Customize the Workbench Output

After you manually run an action or playbook, the outputs appear in an incident's workbench. Configure how the outputs of your custom action appear in the workbench.

Select the Workbench Output Type

Select the type of output that appears in the workbench after you run an action.

  • If you don't want any output to appear in the workbench, select No Card, then click Next.

  • To list action outputs in a table, select Table.

  • To display action outputs on a world map, select Map. For example, the out-of-the-box Geolocate IP action produces a map-type workbench output.

Configure a Table Workbench Output

  1. Under Header Title, enter a title for the output header.

  2. Under Header Color, select a color for the output header. To select from a color picker or enter a RGBA value, click the color swatch. To enter a hex code, start typing after #.

  3. Under Empty Result Message, enter a helpful message that displays in Incident Responder when the action can't get any data.

  4. Configure table columns:

    • Column label – Enter a header name for the column.

    • Data type – Select String. Indicates the expected data type for the values in the column.

    • Column width – In the text field, enter a number in pixels (px) or as a percent (%). From the list, select the corresponding unit. If you create multiple columns, it's easiest to use the same units across all columns. If you enter a number in percent, ensure the numbers across all columns sum to 100 percent.

    To add another column, click + Add a Column.

  5. Click Next.

Configure a Map Workbench Output

  1. (Optional) Under Header Title, enter a title for the output header.

  2. Under Header Color, select the color of the output header. To select from a color picker or enter a RGBA value, click the color swatch. To enter a hex code, start typing after #.

  3. (Optional) Under Empty Result Message, enter a helpful message that displays in Incident Responder when the action can't get any data.

  4. Click Next.

5. Edit the Action Module

Under ACTION RELATED FILES, in the module for the action, build all logic necessary for it to function, including how inputs are computed into outputs, what error messages are shown, and how action outputs are displayed in the workbench.

In any action module, you must:

  • Import the SoarAction parent class:

    from soar.library.common.soar_action import SoarAction

  • Define a class that inherits from the SoarAction parent class, and name it after the action:

    class youraction(SoarAction):

    For example:

    class GetGeolocationIpApi(SoarAction):

    Ensure that you import this action class into __init__.py.

  • Underneath the action class, create a method named action:

    def action(self) -> bool:

Underneath this method, insert all action-related logic. When you run an action in Incident Responder , it starts reading from this point.

To set an action input:

actioninput = self.get_input_value_with_default('actioninput', 'defaultinputvalue
')

If the action can't set the input, it returns the default input value. This parameter is optional.

  • If you don't set a default input value, it returns None. For example:

    ips = self.get_input_value_with_default('ips')

  • If you set a default input value, it returns that value. For example:

    ips = self.get_input_value_with_default('ips','8.8.8.8')

    If the action can't set the input, it returns 8.8.8.8.

To set an action output and save it so it can be passed along and used as inputs in playbook nodes:

self.set_result({'actionoutput':'outputvalue'})

Send Data to a Table Workbench Output

If you previously configured a table workbench output, specify the exact data that appears in the output.

To add a row to the table:

self.builder.add_row(datakey, [columnvalues])

For example:

self.builder.add_row(now, [host, status])

To indicate that there's no more data to add and display the workbench output:

self.add_display(self.builder.build())

Display the Empty Result Message in Incident Responder when the action can't get any data:

self-builder.add_empty_data(now)

If you didn't set an Empty Result Message, the workbench output displays Action ran successfully but returned no results.

Send Data to a Map Workbench Output

If you previously configured a map workbench output, specify the exact data that appears in the workbench output.

To set coordinates for and display an exact point on the map:

.set_coord(youroutputvalue, lat=latitude, lng=longitude, markerContent=youroutputvalue)

markerContent is an optional parameter that uses a marker to identify a location on the map.

To indicate that there's no more data to add and display the workbench output:

self.add_display(self.builder.build())

Display the Empty Result Message in Incident Responder when the action can't get any data:

self.builder.add_empty_data(now)

If you didn't set an Empty Result Message, the workbench output displays Action ran successfully but returned no results.

Create Error Messages and Exceptions

If something goes wrong, it's helpful to provide error messages, exceptions, and other information about what happened so you can identify and debug the problem.

To import an Exabeam exception:

from soar.utility.custom_exceptions import ExabeamConnectorException


When you import the SoarAction class, you also import a logging package. Use it to print error messages or exceptions to a console or write them to a file:

self.logger.logginglevel('yourmessage')

For example:

self.logger.debug("No IP address found in input")

6. Edit the Service Configuration Documents

Under GENERAL FILES, make the necessary changes to connector.py, __init__.py, and requirements.txt. These documents determine how all actions for a service communicate with it and are required for Incident Responder to process and upload the service.

Ensure that you update __init__.py so it imports the action class you created in the action module:

from .modulename import actionclass

For example:

from .get_reputation import GetFileReputation, GetIPReputation, GetURLReputation

You must import all action classes. If you don't import it, you can't use it in Incident Responder .

7. Download and Upload Your Service to Incident Responder

After you create all custom actions and you're ready to use your custom service, download and upload it to Incident Responder .

  1. In your custom service, click the download A grey download symbol. icon. The service downloads as a ZIP file.

  2. In Incident Responder, upload the service. You must have version i53 or later.