[Security Solution] Tines connector (#143505)

## Summary

Issue: #140066
Doc:
https://docs.google.com/document/d/14BY-6CIin1CUH5bwJJgfrGl37hWO-CeNMdl_35agpvk/edit?usp=sharing

Create a new connector type that offers low friction/low effort approach
to augmenting Elastic capabilities with SOAR capabilities of Tines.

## Implementation

Tines connector implements subActionConnector. With 4 subActions
configured:

- **stories**: Retrieves the User available Story objects from Tines, to
render the Story selector options in the params form. It uses the
`email` and `token` authentication headers from the configuration.
It is requested only when the form opens and when the connector instance
changes.

- **webhooks**: Retrieves the Story available Webhooks objects from
Tines, to render the Webhook selector in the params form. It uses the
`email` and `token` authentication headers from the configuration and
the `story_id` parameter.
There is no filter for `type` in the actions (a.k.a. agents) endpoint,
so we have to request all actions and filter them by `type ===
'Agents::WebhookAgent'` on our side.
It is requested every time the selected story changes.

- **run**: The main action execution. It sends the alerts to the Tines
configured webhook, using webhook' `path` and `secret` values. There's
no template to render, the data coming from the execution is just pruned
(the `kibana` entry is removed from all `context.alerts`) and sent
directly using the same format to Tines.

- **test**: The test form execution. It ends up calling **run** but
using a parametrized body.

### Pagination
Both **stories** and **webhooks** subActions need pagination, since
Tines do not expose any search endpoint for them. The current hard limit
is 100 pages. The `paginatedRequest` function in the connector
implementation encapsulates this logic.

## Testing

1- Create a [Tines](https://www.tines.com/) free account.

2- Create a [new
Story](https://www.tines.com/docs/quickstart/simple-story) and attach a
[Webhook
Action](https://www.tines.com/docs/quickstart/creating-an-action) to
start receiving events.

3- Create an [API token](https://www.tines.com/api/authentication)

4- Configure the Tines Connector in Kibana using the Tines tenant URL
that has been generated in the Tines app, the email used to sign in, and
the API token generated.
[docs](https://github.com/semd/kibana/blob/140066_tines_connector/docs/management/connectors/action-types/tines.asciidoc#connector-configuration)

5- Attach the Tines Connector to a Detection Rule, selecting the Story
and Webhooks created.
[docs](https://github.com/semd/kibana/blob/140066_tines_connector/docs/management/connectors/action-types/tines.asciidoc#actions)

6- After each rule execution, events should appear in the Tines webhook
action.

## Screenshots

Configure a Tines connector


![tines_connector_selection](https://user-images.githubusercontent.com/17747913/196389019-820aff49-6ad6-442e-a69f-3c782cbd65e6.png)


![tines_connector_config](https://user-images.githubusercontent.com/17747913/198035138-e7f3bb25-ebd1-4cfd-9cc5-b0bfe434c25c.png)

Use the Tines connector 


![tines_rule_action](https://user-images.githubusercontent.com/17747913/196389010-c87045a4-2b74-4903-9a81-ccbcff09fbf1.png)


![tine_params_form](https://user-images.githubusercontent.com/17747913/198034501-7e9ad912-111e-48b6-8387-fcf6f0663511.png)

Tines events


![tines_events](https://user-images.githubusercontent.com/17747913/196734338-91e1a397-2d03-4ee6-8ad2-16cb39abe9bf.png)

### Checklist

Delete any items that are not applicable to this PR.

- [x] Any text added follows [EUI's writing
guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses
sentence case text and includes [i18n
support](https://github.com/elastic/kibana/blob/main/packages/kbn-i18n/README.md)
- [x]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common
scenarios(https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US))

Co-authored-by: kibanamachine <[email protected]>
Co-authored-by: Jonathan Buttner <[email protected]>

docs/management/action-types.asciidoc

@@ -59,6 +59,10 @@ a| <<swimlane-action-type,{swimlane}>>
 
 | Create an incident in {swimlane}.
 
+a| <<tines-action-type,Tines>>
+
+| Send events to a Tines Story.
+
 a| <<webhook-action-type, {webhook}>>
 
 | Send a request to a web service.

docs/management/connectors/action-types/tines.asciidoc

@@ -0,0 +1,105 @@
+[role="xpack"]
+[[tines-action-type]]
+== Tines connector
+++++
+<titleabbrev>Tines</titleabbrev>
+++++
+
+The Tines connector uses Tines's https://www.tines.com/docs/actions/types/webhook[Webhook actions] to send events via POST request.
+
+[float]
+[[tines-connector-configuration]]
+=== Connector configuration
+
+Tines connectors have the following configuration properties.
+
+URL::        The Tines tenant URL. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
+Email::      The email used to sign in to Tines.
+API Token::  A Tines API token created by the user. https://www.tines.com/api/authentication#generate-api-token[Docs]
+
+[role="screenshot"]
+image::../images/tines-connector.png[Tines connector]
+
+[float]
+[[Preconfigured-tines-configuration]]
+==== Preconfigured connector type
+
+[source,text]
+--
+ my-tines:
+   name: preconfigured-tines-connector-type
+   actionTypeId: .tines
+   config:
+     url: https://some-tenant-2345.tines.com
+   secrets:
+     email: [email protected]
+     token: ausergeneratedapitoken
+--
+
+Config defines information for the connector type.
+
+`url`:: A Tines tenant URL string that corresponds to *URL*.
+
+Secrets defines sensitive information for the connector type.
+
+`email`:: A string that corresponds to *Email*.
+`token`:: A string that corresponds to *API Token*.
+
+[float]
+[[tines-action-parameters]]
+=== Action parameters
+
+Tines action have the following parameters.
+
+Story::   The Story to send the events to.
+Webhook:: The Webhook action from the previous story that will receive the events, it is the data entry point. 
+
+Test Tines action parameters.
+
+[role="screenshot"]
+image::../images/tines-params-test.png[Tines params test]
+
+[float]
+[[tines-action-format]]
+=== Actions
+
+Once the Tines connector has been configured in an Alerting Rule.
+
+[role="screenshot"]
+image::../images/tines-alerting.png[Tines rule alert]
+
+It will send a POST request to the Tines webhook action on every action execution with at least one result.
+
+[float]
+[[webhookUrlFallback-tines-configuration]]
+==== Webhook URL fallback
+
+It is possible for the requests to the Tines API, to get the stories and webhooks for the selectors, to hit the 500 results limit; in this scenario, the webhook URL fallback text field will be displayed.
+Users can still use the selectors if the story or webhook exists in the 500 options loaded. Otherwise, users can paste the webhook URL in the test input field, it can be copied from the Tines webhook configuration. 
+
+When the webhook URL is defined, the connector will use it directly in the execution stage, and the story and webhook selectors will be disabled and ignored. To re-enable the story and webhook selectors, remove the webhook URL value.
+
+[role="screenshot"]
+image::../images/tines-webhook-url-fallback.png[Tines Webhook URL fallback]
+
+[float]
+[[tines-story-library]]
+=== Tines Story Libary
+
+In order to simplify the integration with Elastic, Tines offers a set of pre-defined Elastic stories in the Story library.
+They can be found by searching for "Elastic" in the Tines Story library:
+
+[role="screenshot"]
+image::../images/tines_elastic_stories.png[Tines Elastic stories]
+
+They can be imported directly into your Tines tenant.
+
+=== Format
+
+Tines connector will send the data in JSON format.
+
+The message contains execution specific fields, such as `alertId`, `date`, `_index`, `kibanaBaseUrl`, along with the `rule` and `params` objects. 
+
+The number of alerts (signals) can be found at `state.signals_count`.
+
+The alerts (signals) data is stored in the `context.alerts` array, following the https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html[ECS] format.

docs/management/connectors/index.asciidoc

@@ -14,4 +14,5 @@ include::action-types/webhook.asciidoc[]
 include::action-types/cases-webhook.asciidoc[leveloffset=+1]
 include::action-types/opsgenie.asciidoc[]
 include::action-types/xmatters.asciidoc[]
+include::action-types/tines.asciidoc[]
 include::pre-configured-connectors.asciidoc[]

docs/settings/alert-action-settings.asciidoc

@@ -131,7 +131,7 @@ A list of allowed email domains which can be used with the email connector. When
 WARNING: This feature is available in {kib} 7.17.4 and 8.3.0 onwards but is not supported in {kib} 8.0, 8.1 or 8.2. As such, this setting should be removed before upgrading from 7.17 to 8.0, 8.1 or 8.2. It is possible to configure the settings in 7.17.4 and then upgrade to 8.3.0 directly.
 
 `xpack.actions.enabledActionTypes` {ess-icon}::
-A list of action types that are enabled. It defaults to `[*]`, enabling all types. The names for built-in {kib} action types are prefixed with a `.` and include: `.email`, `.index`, `.jira`, `.opsgenie`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, .`servicenow-itom`, `.servicenow-sir`, `.slack`, `.swimlane`, `.teams`, `.xmatters`, and `.webhook`. An empty list `[]` will disable all action types.
+A list of action types that are enabled. It defaults to `[*]`, enabling all types. The names for built-in {kib} action types are prefixed with a `.` and include: `.email`, `.index`, `.jira`, `.opsgenie`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, .`servicenow-itom`, `.servicenow-sir`, `.slack`, `.swimlane`, `.teams`, `.tines`, `.xmatters`, and `.webhook`. An empty list `[]` will disable all action types.
 +
 Disabled action types will not appear as an option when creating new connectors, but existing connectors and actions of that type will remain in {kib} and will not function.
 

x-pack/plugins/stack_connectors/common/connector_types/security/tines/constants.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+export const TINES_TITLE = 'Tines';
+export const TINES_CONNECTOR_ID = '.tines';
+export const API_MAX_RESULTS = 500;
+export const enum SUB_ACTION {
+  STORIES = 'stories',
+  WEBHOOKS = 'webhooks',
+  RUN = 'run',
+  TEST = 'test',
+}

x-pack/plugins/stack_connectors/common/connector_types/security/tines/schema.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { schema } from '@kbn/config-schema';
+
+// Connector schema
+export const TinesConfigSchema = schema.object({ url: schema.string() });
+export const TinesSecretsSchema = schema.object({ email: schema.string(), token: schema.string() });
+
+// Stories action schema
+export const TinesStoriesActionParamsSchema = null;
+export const TinesStoryObjectSchema = schema.object({
+  id: schema.number(),
+  name: schema.string(),
+  published: schema.boolean(),
+});
+export const TinesStoriesActionResponseSchema = schema.object({
+  stories: schema.arrayOf(TinesStoryObjectSchema),
+  incompleteResponse: schema.boolean(),
+});
+
+// Webhooks action schema
+export const TinesWebhooksActionParamsSchema = schema.object({ storyId: schema.number() });
+export const TinesWebhookObjectSchema = schema.object({
+  id: schema.number(),
+  name: schema.string(),
+  storyId: schema.number(),
+  path: schema.string(),
+  secret: schema.string(),
+});
+export const TinesWebhooksActionResponseSchema = schema.object({
+  webhooks: schema.arrayOf(TinesWebhookObjectSchema),
+  incompleteResponse: schema.boolean(),
+});
+
+// Run action schema
+export const TinesRunActionParamsSchema = schema.object({
+  webhook: schema.maybe(TinesWebhookObjectSchema),
+  webhookUrl: schema.maybe(schema.string()),
+  body: schema.string(),
+});
+export const TinesRunActionResponseSchema = schema.object({}, { unknowns: 'ignore' });

x-pack/plugins/stack_connectors/common/connector_types/security/tines/types.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { TypeOf } from '@kbn/config-schema';
+import {
+  TinesConfigSchema,
+  TinesSecretsSchema,
+  TinesRunActionParamsSchema,
+  TinesRunActionResponseSchema,
+  TinesStoriesActionResponseSchema,
+  TinesWebhooksActionResponseSchema,
+  TinesWebhooksActionParamsSchema,
+  TinesWebhookObjectSchema,
+  TinesStoryObjectSchema,
+} from './schema';
+
+export type TinesConfig = TypeOf<typeof TinesConfigSchema>;
+export type TinesSecrets = TypeOf<typeof TinesSecretsSchema>;
+export type TinesRunActionParams = TypeOf<typeof TinesRunActionParamsSchema>;
+export type TinesRunActionResponse = TypeOf<typeof TinesRunActionResponseSchema>;
+export type TinesStoriesActionParams = void;
+export type TinesStoryObject = TypeOf<typeof TinesStoryObjectSchema>;
+export type TinesStoriesActionResponse = TypeOf<typeof TinesStoriesActionResponseSchema>;
+export type TinesWebhooksActionParams = TypeOf<typeof TinesWebhooksActionParamsSchema>;
+export type TinesWebhooksActionResponse = TypeOf<typeof TinesWebhooksActionResponseSchema>;
+export type TinesWebhookObject = TypeOf<typeof TinesWebhookObjectSchema>;

x-pack/plugins/stack_connectors/public/connector_types/index.ts

@@ -29,6 +29,8 @@ import {
   getSwimlaneConnectorType,
 } from './cases';
 
+import { getTinesConnectorType } from './security';
+
 export interface RegistrationServices {
   validateEmailAddresses: (
     addresses: string[],
@@ -59,4 +61,5 @@ export function registerConnectorTypes({
   connectorTypeRegistry.register(getResilientConnectorType());
   connectorTypeRegistry.register(getOpsgenieConnectorType());
   connectorTypeRegistry.register(getTeamsConnectorType());
+  connectorTypeRegistry.register(getTinesConnectorType());
 }

x-pack/plugins/stack_connectors/public/connector_types/security/index.ts

@@ -4,3 +4,5 @@
  * 2.0; you may not use this file except in compliance with the Elastic License
  * 2.0.
  */
+
+export { getTinesConnectorType } from './tines';

x-pack/plugins/stack_connectors/public/connector_types/security/tines/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+export { getConnectorType as getTinesConnectorType } from './tines';

x-pack/plugins/stack_connectors/public/connector_types/security/tines/logo.tsx

@@ -0,0 +1,40 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import React from 'react';
+import { LogoProps } from '../types';
+
+const Logo = (props: LogoProps) => (
+  <svg
+    version="1.1"
+    id="Layer_1"
+    xmlns="http://www.w3.org/2000/svg"
+    xmlnsXlink="http://www.w3.org/1999/xlink"
+    x="0"
+    y="0"
+    width="32px"
+    height="32px"
+    viewBox="0 0 32 32"
+    enableBackground="new 0 0 32 32"
+    xmlSpace="preserve"
+    {...props}
+  >
+    <g>
+      <rect y="128.4" className="st0" width="25.7" height="46.6" style={{ fill: '#06AC38' }} />
+      <path
+        className="st0"
+        style={{ fill: '#8578E6' }}
+        fillRule="evenodd"
+        clipRule="evenodd"
+        d="M11.8018 0C8.01458 0 4.66599 2.45749 3.53258 6.06868L0.415527 16L3.53258 25.9313C4.66599 29.5425 8.01458 32 11.8018 32H20.1981C23.9853 32 27.3339 29.5425 28.4673 25.9313L31.5844 16L28.4673 6.06868C27.3339 2.45749 23.9853 0 20.1981 0H11.8018ZM20.1982 2.49634C22.8938 2.49634 25.2772 4.24548 26.0839 6.81577L26.8481 9.25062C25.3107 7.98154 23.3639 7.26723 21.3292 7.26707L10.648 7.26679C8.62691 7.26694 6.69264 7.97168 5.16015 9.22481L5.91625 6.81577C6.72297 4.24548 9.10635 2.49634 11.8019 2.49634H20.1982ZM5.73674 12.1986L3.79587 14.7519L28.1811 14.7519L26.2404 12.1989C25.0741 10.6646 23.2571 9.76356 21.329 9.76341H10.5898C8.68349 9.78153 6.89125 10.6798 5.73674 12.1986ZM28.1771 17.2482L26.2403 19.7989C25.0739 21.3349 23.2555 22.237 21.326 22.2368L10.6509 22.2366C8.72137 22.2367 6.90298 21.3346 5.73661 19.7986L3.79996 17.2482L28.1771 17.2482ZM5.9161 25.1842C6.72282 27.7545 9.1062 29.5037 11.8018 29.5037H20.1981C22.8936 29.5037 25.277 27.7545 26.0837 25.1842L26.8485 22.7476C25.3104 24.0182 23.3622 24.7333 21.3258 24.7332L10.651 24.7329C8.6283 24.7331 6.69244 24.0274 5.15921 22.7727L5.9161 25.1842Z"
+      />
+    </g>
+  </svg>
+);
+
+// eslint-disable-next-line import/no-default-export
+export { Logo as default };