Summary

Actions can be executed by rules when alerts are triggered. A user, at the creation of a rule, can define which actions will be executed. To define actions, users need to create connectors. Connectors contain information needed by the actions to execute. For example, they can contain credentials, instance URLs, or configuration options. Usually, connectors are used to communicate with external services like PagerDuty or ServiceNow. Automated actions like opening a case or running an OsQuery do not need any configuration. This document explores ways of supporting these kinds of actions in the actions’ framework. From now on they will be referred to as system actions.

High-level solution

A system action is an action that triggers Kibana workflows. For example, creating a case, running an OsQuery, running an ML job, or logging. System actions will be defined by developers with the use of the existing actions’ framework. By using the existing actions framework, system actions will get all features supported by the framework like retries, using the task manager, conditional actions, etc.

Registration

Solutions should be able to register their system action the same way they register action types through the actions registry. The definition of the system action will be almost identical to the actions. The key differences are:

• isSystemAction must be set to true
• The validation of config and secrets should be empty
• requiredPrivileges should be defined if authentication is needed (See RBAC section)

SavedObjects

System actions will not be persisted as a saved object as they do not have any configuration or secrets. As a consequence, all features supported by saved objects will not be available to system actions. For example, exporting/importing a system action will not be supported. A system action will be represented as a JS object by the actions’ framework. The object will have the same attributes as the actions’ saved object. Attributes, like the config and secrets, that are not needed by the system actions will default to empty values. This will simplify the actions’ framework and reduce the development effort.

The JS object will be loaded in memory at Kibana startup and it will live during the lifecycle of Kibana. The ID of a system action will be generated by the framework automatically and deterministically based on the actionTypeId for all Kibana nodes. The ID will never change during the lifecycle of Kibana and it will be the same between Kibana restarts.

APIs

Users will not be able to create, update, delete, and execute a system action through the APIs. The system actions will not be returned from the Get all connectors API, and the Get connector API and the system connector types will not be returned from the List connector types API.

Preconfigured connectors

Users will not be able to define system actions as preconfigured connectors. The action’s framework will throw an error on such an attempt.

Spaces

As with preconfigured connectors, the system actions will be space-agnostic. There is no need to create one connector for each space.

RBAC

It is possible for system actions to use kibana features that need their own authorization. For example, to use the case action the user needs to have “All” access to Cases to be able to create a case automatically. The actions framework will perform all the needed authorization checks on behalf of the system actions. Creators of system action will have to define a list of the Kibana privileges required by the system action with the use of security.authz.actions.*.get(...). For example, for the case action security.auth.actions.cases.get(‘case_owner’, ‘case_operation’) and for access to a specific saved object security.auth.actions.savedObject.get(‘my_so_object’,’my_operation’).

Regarding the UI, a user that does not have access to the feature privilege should not be able to view and select the system action when creating a rule. For example, if a user does not have access to Cases, they should not be able to select the case system action to automatically create cases even if she has permission to create rules.

Alerts

System actions, like the case action, may need information about the alerts generated by the rule. The framework should provide the alert IDs and indices to the system action through the executor function.

Execution

To preserve the stability of the system, users should not be able to configure the system action execution configuration (action parameters) through the Rules APIs, nor should they be able to modify it through UI forms. The alerting framework should dictate how the system actions will be executed. A system action will not have a group, a frequency, or an alertFilter. The only available and required properties will be id and params.

Action parameters

Usually users, with mustache templating through rule forms, pass certain parameters to the actions. System actions require certain data like a summarization of alerts, information about the rule, etc. To avoid setting them behind the scenes in the UI when configuring a rule and being part of rules’ action parameters and to keep the actions framework agnostic of the implementation details of the alerting framework and vice-versa, we will introduce Connector Adapters. With connector adapters action parameters set in the rule and parameters required by the system action can be different. A connector adapter, specified for a specific connector type, can build extra parameters, required by the connector, based on the rule parameters and extra metadata passed to it like the alerts or the rule.

The alerting framework will expose a registry to allow connectors to register their execution configuration.

PoC: #159866

Schema of actions in the rule

In the rules client (domain layer), a new attribute will be introduced called systemActions, which will aid the methods of the client to handle system actions. The scheme of the system action will be:

export interface RuleSystemAction {
  uuid?: string;
  id: string;
  actionTypeId: string;
  params: RuleActionParams;
}

The systemActions attribute will not be persisted to ES. All methods of the rules’ client will merge the default actions with the system actions before saving the rule. Also, they will split up the actions after they get any rule SO.

All rules APIs will not accept the systemActions in their requests. The system will deduct if an action is a system action automatically using the actions’ client. As system actions are not allowed to have a group, the property will be optional (at the moment it is required) in all APIs. The APIs will convert the actions to the schema needed by the rules client. Finally, the APIs will merge the system actions with the default actions before sending the response back to the client.

UI

Connectors
System actions do not require a configuration. For that reason, users will not be able to create or test system connectors from the UI. Also, the system actions will not be shown in the connector’s list on the connector’s page.

Rules
Users will be able to select a system action when creating a rule. The system actions will be shown in the same list as the other action types, and the users will not be able to select a system action twice. As with actions, the system actions will have to provide a React component to allow users to provide parameters for the system action, usually with the use of a form.

Tasks

• Create TS types for System actions ([Actions] Introduce the isSystemAction property to actions #160753)
• Allow registering system actions using the actionTypeRegistry ([Actions] Set system actions on Kibana start #160983)
• Prevent creating/updating/deleting/getting system actions from the APIs ([Actions] Set system actions on Kibana start #160983, [Actions] Do not return system actions from GET APIs #161845)
• Prevent creating system actions from the kibana.yml ([Actions] System actions enhancements #161340)
• Implement Connector Adapters ([Actions] Connector Adapters MVP #166101)
• Support system actions in the Rules APIs:
  • Create ([Alerting] Enable creating system actions through the Create Rule API #167884)
  • Bulk edit ([Alerting] Enable updating system actions through the Bulk Edit Rule API #168226)
  • Bulk disable ([RAM] System action in bulk disable api #170229)
  • Bulk enable ([RAM] System action in bulk enable api #170476)
  • Bulk delete ([RAM] System action in bulk delete #170741)
  • Update ([RAM] System actions update rule api #171099)
  • Legacy APIs ([System Actions] Complete API audit and update APIs to comply with System Actions #172937)
• Support RBAC ([Actions] System actions authorization #161341)
• Adapt UI to handle system connectors

Feature branch: #166267
Related: #155644, #70303, https://github.com/elastic/security-team/issues/6475, https://github.com/elastic/security-team/issues/5849, https://github.com/elastic/security-team/issues/6200, #153837