TheHive Case Connector

docs/management/action-types.asciidoc

@@ -80,6 +80,10 @@ a| <<swimlane-action-type,{swimlane}>>
 
 | Create an incident in {swimlane}.
 
+a| <<thehive-action-type,{thehive}>>
+
+| Create cases and alerts in {thehive}.
+
 a| <<tines-action-type,Tines>>
 
 | Send events to a Tines Story.

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

@@ -0,0 +1,79 @@
+[[thehive-action-type]]
+== TheHive connector and action
+++++
+<titleabbrev>TheHive</titleabbrev>
+++++
+:frontmatter-description: Add a connector that can create cases and alerts in TheHive.
+:frontmatter-tags-products: [kibana]
+:frontmatter-tags-content-type: [how-to]
+:frontmatter-tags-user-goals: [configure]
+
+TheHive connector uses the https://docs.strangebee.com/thehive/api-docs/[TheHive (v1) REST API] to create cases and alerts.
+
+[float]
+[[define-thehive-ui]]
+=== Create connectors in {kib}
+
+You can create connectors in *{stack-manage-app} > {connectors-ui}*
+or as needed when you're creating a rule. For example:
+
+[role="screenshot"]
+image::management/connectors/images/thehive-connector.png[TheHive connector]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+[float]
+[[thehive-connector-configuration]]
+==== Connector configuration
+
+TheHive connectors have the following configuration properties:
+
+Name::         The name of the connector.
+Organisation:: Organisation name in which user intends to create cases or alerts.
+URL::          TheHive instance URL.
+API Key::      TheHive API key for authentication.
+
+[float]
+[[TheHive-action-configuration]]
+=== Test connectors
+
+You can test connectors for creating a case or an alert with the <<execute-connector-api,run connector API>> or
+as you're creating or editing the connector in {kib}. For example:
+
+[role="screenshot"]
+image::management/connectors/images/thehive-params-case-test.png[TheHive case params test]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+[role="screenshot"]
+image::management/connectors/images/thehive-params-alert-test.png[TheHive alert params test]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+TheHive actions have the following configuration properties.
+
+Event Action:: Action that will be performed in thehive. Supported actions are Create Case (default) and Create Alert.
+Title:: Title of the incident.
+Description:: The details about the incident.
+Severity:: Severity of the incident. This can be one of `LOW`, `MEDIUM`(default), `HIGH` or `CRITICAL`.
+TLP:: Traffic Light Protocol designation for the incident. This can be one of `CLEAR`, `GREEN`, `AMBER`(default), `AMBER+STRICT` or `RED`.
+Tags:: The keywords or tags about the incident.
+Additional comments:: Additional information about the Case. 
+Type:: Type of the Alert.
+Source:: Source of the Alert.
+Source Reference:: Source reference of the Alert.
+
+[float]
+[[thehive-connector-networking-configuration]]
+=== Connector networking configuration
+
+Use the <<action-settings, Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
+
+[float]
+[[configure-thehive]]
+=== Configure TheHive
+
+To generate an API Key in TheHive:
+
+1. Log in to your TheHive instance.
+2. Open profile tab and select the settings.
+3. Go to *API Key*.
+4. Click *Create* if no API key has been created previously; otherwise, you can view the API key by clicking on *Reveal*.
+5. Copy the *API key* value to configure the connector in {kib}.

docs/management/connectors/index.asciidoc

@@ -16,6 +16,7 @@ include::action-types/servicenow-sir.asciidoc[leveloffset=+1]
 include::action-types/servicenow-itom.asciidoc[leveloffset=+1]
 include::action-types/swimlane.asciidoc[leveloffset=+1]
 include::action-types/slack.asciidoc[leveloffset=+1]
+include::action-types/thehive.asciidoc[leveloffset=+1]
 include::action-types/tines.asciidoc[leveloffset=+1]
 include::action-types/torq.asciidoc[leveloffset=+1]
 include::action-types/webhook.asciidoc[leveloffset=+1]

docs/settings/alert-action-settings.asciidoc

@@ -138,7 +138,7 @@ WARNING: This feature is available in {kib} 7.17.4 and 8.3.0 onwards but is not
 A boolean value indicating that a footer with a relevant link should be added to emails sent as alerting actions. Default: true.
 
 `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`, `.tines`, `.torq`, `.xmatters`,  `.gen-ai`,  `.bedrock`,  `.d3security`, 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`, `.thehive`, `.tines`, `.torq`, `.xmatters`,  `.gen-ai`,  `.bedrock`,  `.d3security`, 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/alerting/common/disabled_action_groups.ts

@@ -8,7 +8,7 @@
 import { RecoveredActionGroup } from './builtin_action_groups';
 
 const DisabledActionGroupsByActionType: Record<string, string[]> = {
-  [RecoveredActionGroup.id]: ['.jira', '.resilient'],
+  [RecoveredActionGroup.id]: ['.jira', '.resilient', '.thehive'],
 };
 
 export const DisabledActionTypeIdsForActionGroup: Map<string, string[]> = new Map(

x-pack/plugins/stack_connectors/common/thehive/constants.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 { i18n } from '@kbn/i18n';
+
+export const THEHIVE_TITLE = i18n.translate(
+  'xpack.stackConnectors.components.thehive.connectorTypeTitle',
+  {
+    defaultMessage: 'TheHive',
+  }
+);
+export const THEHIVE_CONNECTOR_ID = '.thehive';
+
+export enum SUB_ACTION {
+  PUSH_TO_SERVICE = 'pushToService',
+  CREATE_ALERT = 'createAlert',
+}
+export enum TheHiveSeverity {
+  LOW = 1,
+  MEDIUM = 2,
+  HIGH = 3,
+  CRITICAL = 4,
+}
+export enum TheHiveTLP {
+  CLEAR = 0,
+  GREEN = 1,
+  AMBER = 2,
+  AMBER_STRICT = 3,
+  RED = 4,
+}

x-pack/plugins/stack_connectors/common/thehive/schema.ts

@@ -0,0 +1,186 @@
+/*
+ * 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';
+import { TheHiveSeverity, TheHiveTLP, SUB_ACTION } from './constants';
+
+export const TheHiveConfigSchema = schema.object({
+  url: schema.string(),
+  organisation: schema.nullable(schema.string()),
+});
+
+export const TheHiveSecretsSchema = schema.object({
+  apiKey: schema.string(),
+});
+
+export const ExecutorSubActionPushParamsSchema = schema.object({
+  incident: schema.object({
+    title: schema.string(),
+    description: schema.string(),
+    externalId: schema.nullable(schema.string()),
+    severity: schema.nullable(schema.number({ defaultValue: TheHiveSeverity.MEDIUM })),
+    tlp: schema.nullable(schema.number({ defaultValue: TheHiveTLP.AMBER })),
+    tags: schema.nullable(schema.arrayOf(schema.string())),
+  }),
+  comments: schema.nullable(
+    schema.arrayOf(
+      schema.object({
+        comment: schema.string(),
+        commentId: schema.string(),
+      })
+    )
+  ),
+});
+
+export const PushToServiceIncidentSchema = {
+  title: schema.string(),
+  description: schema.string(),
+  severity: schema.nullable(schema.number()),
+  tlp: schema.nullable(schema.number()),
+  tags: schema.nullable(schema.arrayOf(schema.string())),
+};
+
+export const ExecutorSubActionGetIncidentParamsSchema = schema.object({
+  externalId: schema.string(),
+});
+
+export const ExecutorSubActionCreateAlertParamsSchema = schema.object({
+  title: schema.string(),
+  description: schema.string(),
+  type: schema.string(),
+  source: schema.string(),
+  sourceRef: schema.string(),
+  severity: schema.nullable(schema.number({ defaultValue: TheHiveSeverity.MEDIUM })),
+  tlp: schema.nullable(schema.number({ defaultValue: TheHiveTLP.AMBER })),
+  tags: schema.nullable(schema.arrayOf(schema.string())),
+});
+
+export const ExecutorParamsSchema = schema.oneOf([
+  schema.object({
+    subAction: schema.literal(SUB_ACTION.PUSH_TO_SERVICE),
+    subActionParams: ExecutorSubActionPushParamsSchema,
+  }),
+  schema.object({
+    subAction: schema.literal(SUB_ACTION.CREATE_ALERT),
+    subActionParams: ExecutorSubActionCreateAlertParamsSchema,
+  }),
+]);
+
+export const TheHiveIncidentResponseSchema = schema.object(
+  {
+    _id: schema.string(),
+    _type: schema.string(),
+    _createdBy: schema.string(),
+    _updatedBy: schema.nullable(schema.string()),
+    _createdAt: schema.number(),
+    _updatedAt: schema.nullable(schema.number()),
+    number: schema.number(),
+    title: schema.string(),
+    description: schema.string(),
+    severity: schema.number(),
+    severityLabel: schema.string(),
+    startDate: schema.number(),
+    endDate: schema.nullable(schema.number()),
+    tags: schema.nullable(schema.arrayOf(schema.string())),
+    flag: schema.boolean(),
+    tlp: schema.number(),
+    tlpLabel: schema.string(),
+    pap: schema.number(),
+    papLabel: schema.string(),
+    status: schema.string(),
+    stage: schema.string(),
+    summary: schema.nullable(schema.string()),
+    impactStatus: schema.nullable(schema.string()),
+    assignee: schema.nullable(schema.string()),
+    customFields: schema.nullable(schema.arrayOf(schema.recordOf(schema.string(), schema.any()))),
+    userPermissions: schema.nullable(schema.arrayOf(schema.string())),
+    extraData: schema.object({}, { unknowns: 'allow' }),
+    newDate: schema.number(),
+    inProgressDate: schema.nullable(schema.number()),
+    closedDate: schema.nullable(schema.number()),
+    alertDate: schema.nullable(schema.number()),
+    alertNewDate: schema.nullable(schema.number()),
+    alertInProgressDate: schema.nullable(schema.number()),
+    alertImportedDate: schema.nullable(schema.number()),
+    timeToDetect: schema.number(),
+    timeToTriage: schema.nullable(schema.number()),
+    timeToQualify: schema.nullable(schema.number()),
+    timeToAcknowledge: schema.nullable(schema.number()),
+    timeToResolve: schema.nullable(schema.number()),
+    handlingDuration: schema.nullable(schema.number()),
+  },
+  { unknowns: 'ignore' }
+);
+
+export const TheHiveUpdateIncidentResponseSchema = schema.any();
+
+export const TheHiveAddCommentResponseSchema = schema.object(
+  {
+    _id: schema.string(),
+    _type: schema.string(),
+    createdBy: schema.string(),
+    createdAt: schema.number(),
+    updatedAt: schema.nullable(schema.number()),
+    updatedBy: schema.nullable(schema.string()),
+    message: schema.string(),
+    isEdited: schema.boolean(),
+    extraData: schema.object({}, { unknowns: 'allow' }),
+  },
+  { unknowns: 'ignore' }
+);
+
+export const TheHiveCreateAlertResponseSchema = schema.object(
+  {
+    _id: schema.string(),
+    _type: schema.string(),
+    _createdBy: schema.string(),
+    _updatedBy: schema.nullable(schema.string()),
+    _createdAt: schema.number(),
+    _updatedAt: schema.nullable(schema.number()),
+    type: schema.string(),
+    source: schema.string(),
+    sourceRef: schema.string(),
+    externalLink: schema.nullable(schema.string()),
+    title: schema.string(),
+    description: schema.string(),
+    severity: schema.number(),
+    severityLabel: schema.string(),
+    date: schema.number(),
+    tags: schema.nullable(schema.arrayOf(schema.string())),
+    tlp: schema.number(),
+    tlpLabel: schema.string(),
+    pap: schema.number(),
+    papLabel: schema.string(),
+    follow: schema.nullable(schema.boolean()),
+    customFields: schema.nullable(schema.arrayOf(schema.object({}, { unknowns: 'allow' }))),
+    caseTemplate: schema.nullable(schema.string()),
+    observableCount: schema.number(),
+    caseId: schema.nullable(schema.string()),
+    status: schema.string(),
+    stage: schema.string(),
+    assignee: schema.nullable(schema.string()),
+    summary: schema.nullable(schema.string()),
+    extraData: schema.object({}, { unknowns: 'allow' }),
+    newDate: schema.number(),
+    inProgressDate: schema.nullable(schema.number()),
+    closedDate: schema.nullable(schema.number()),
+    importedDate: schema.nullable(schema.number()),
+    timeToDetect: schema.number(),
+    timeToTriage: schema.nullable(schema.number()),
+    timeToQualify: schema.nullable(schema.number()),
+    timeToAcknowledge: schema.nullable(schema.number()),
+  },
+  { unknowns: 'ignore' }
+);
+
+export const TheHiveFailureResponseSchema = schema.object(
+  {
+    type: schema.number(),
+    message: schema.string(),
+  },
+  { unknowns: 'ignore' }
+);

x-pack/plugins/stack_connectors/common/thehive/types.ts

@@ -0,0 +1,39 @@
+/*
+ * 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 {
+  TheHiveConfigSchema,
+  TheHiveSecretsSchema,
+  ExecutorParamsSchema,
+  ExecutorSubActionPushParamsSchema,
+  ExecutorSubActionCreateAlertParamsSchema,
+  TheHiveFailureResponseSchema,
+  TheHiveIncidentResponseSchema,
+} from './schema';
+
+export type TheHiveConfig = TypeOf<typeof TheHiveConfigSchema>;
+export type TheHiveSecrets = TypeOf<typeof TheHiveSecretsSchema>;
+
+export type ExecutorParams = TypeOf<typeof ExecutorParamsSchema>;
+export type ExecutorSubActionPushParams = TypeOf<typeof ExecutorSubActionPushParamsSchema>;
+export type ExecutorSubActionCreateAlertParams = TypeOf<
+  typeof ExecutorSubActionCreateAlertParamsSchema
+>;
+
+export type TheHiveFailureResponse = TypeOf<typeof TheHiveFailureResponseSchema>;
+
+export interface ExternalServiceIncidentResponse {
+  id: string;
+  title: string;
+  url: string;
+  pushedDate: string;
+}
+
+export type Incident = Omit<ExecutorSubActionPushParams['incident'], 'externalId'>;
+
+export type GetIncidentResponse = TypeOf<typeof TheHiveIncidentResponseSchema>;

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

@@ -31,6 +31,7 @@ import { getXmattersConnectorType } from './xmatters';
 import { getD3SecurityConnectorType } from './d3security';
 import { ExperimentalFeaturesService } from '../common/experimental_features_service';
 import { getSentinelOneConnectorType } from './sentinelone';
+import { getTheHiveConnectorType } from './thehive';
 import { getCrowdStrikeConnectorType } from './crowdstrike';
 
 export interface RegistrationServices {
@@ -69,6 +70,7 @@ export function registerConnectorTypes({
   connectorTypeRegistry.register(getTorqConnectorType());
   connectorTypeRegistry.register(getTinesConnectorType());
   connectorTypeRegistry.register(getD3SecurityConnectorType());
+  connectorTypeRegistry.register(getTheHiveConnectorType());
 
   if (ExperimentalFeaturesService.get().sentinelOneConnectorOn) {
     connectorTypeRegistry.register(getSentinelOneConnectorType());