From 85707767f83c821d8816fa3a298ff3d4a1897bf2 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 9 Sep 2024 18:01:01 -0700 Subject: [PATCH 1/6] Add TheHive connector config; remove obsolete bedrock connector files --- .../schemas/bedrock_create_request.yaml | 23 --------- .../components/schemas/bedrock_response.yaml | 31 ------------ .../schemas/bedrock_update_request.yaml | 13 ----- .../components/schemas/run_createalert.yaml | 47 ++++++++++++++----- .../components/schemas/run_pushtoservice.yaml | 25 ++++++---- .../components/schemas/thehive_config.yaml | 16 +++++++ .../components/schemas/thehive_secrets.yaml | 9 ++++ 7 files changed, 77 insertions(+), 87 deletions(-) delete mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_create_request.yaml delete mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_response.yaml delete mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_update_request.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/thehive_secrets.yaml diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_create_request.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_create_request.yaml deleted file mode 100644 index 2acc21bfbfac7..0000000000000 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_create_request.yaml +++ /dev/null @@ -1,23 +0,0 @@ -title: Create Amazon Bedrock connector request -description: The Amazon Bedrock connector uses axios to send a POST request to Amazon Bedrock. -type: object -required: - - config - - connector_type_id - - name - - secrets -properties: - config: - $ref: 'config_properties_bedrock.yaml' - connector_type_id: - type: string - description: The type of connector. - enum: - - .bedrock - example: .bedrock - name: - type: string - description: The display name for the connector. - example: my-connector - secrets: - $ref: 'secrets_properties_bedrock.yaml' diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_response.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_response.yaml deleted file mode 100644 index 0d3f308744aa3..0000000000000 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_response.yaml +++ /dev/null @@ -1,31 +0,0 @@ -title: Connector response properties for an Amazon Bedrock connector -type: object -required: - - config - - connector_type_id - - id - - is_deprecated - - is_preconfigured - - name -properties: - config: - $ref: 'config_properties_bedrock.yaml' - connector_type_id: - type: string - description: The type of connector. - enum: - - .bedrock - id: - type: string - description: The identifier for the connector. - is_deprecated: - $ref: 'is_deprecated.yaml' - is_missing_secrets: - $ref: 'is_missing_secrets.yaml' - is_preconfigured: - $ref: 'is_preconfigured.yaml' - is_system_action: - $ref: 'is_system_action.yaml' - name: - type: string - description: The display name for the connector. diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_update_request.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_update_request.yaml deleted file mode 100644 index dfa479870aab5..0000000000000 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/bedrock_update_request.yaml +++ /dev/null @@ -1,13 +0,0 @@ -title: Update Amazon Bedrock connector request -type: object -required: - - config - - name -properties: - config: - $ref: 'config_properties_bedrock.yaml' - name: - type: string - description: The display name for the connector. - secrets: - $ref: 'secrets_properties_bedrock.yaml' diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_createalert.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_createalert.yaml index e739a9ed6c91d..194d9d979cdd8 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/run_createalert.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_createalert.yaml @@ -3,7 +3,7 @@ type: object required: - subAction - subActionParams -description: The `createAlert` subaction for Opsgenie connectors. +description: The `createAlert` subaction for Opsgenie and TheHive connectors. properties: subAction: type: string @@ -12,12 +12,10 @@ properties: - createAlert subActionParams: type: object - required: - - message properties: actions: type: array - description: The custom actions available to the alert. + description: The custom actions available to the alert in Opsgenie connectors. items: type: string alias: @@ -28,21 +26,21 @@ properties: description: A description that provides detailed information about the alert. details: type: object - description: The custom properties of the alert. + description: The custom properties of the alert in Opsgenie connectors. additionalProperties: true example: {"key1":"value1","key2":"value2"} entity: type: string - description: The domain of the alert. For example, the application or server name. + description: The domain of the alert in Opsgenie connectors. For example, the application or server name. message: type: string - description: The alert message. + description: The alert message in Opsgenie connectors. note: type: string - description: Additional information for the alert. + description: Additional information for the alert in Opsgenie connectors. priority: type: string - description: The priority level for the alert. + description: The priority level for the alert in Opsgenie connectors. enum: - P1 - P2 @@ -52,7 +50,7 @@ properties: responders: type: array description: > - The entities to receive notifications about the alert. + The entities to receive notifications about the alert in Opsgenie connectors. If `type` is `user`, either `id` or `username` is required. If `type` is `team`, either `id` or `name` is required. items: @@ -75,14 +73,39 @@ properties: username: type: string description: A valid email address for the user. + severity: + type: integer + minimum: 1 + maximum: 4 + description: > + The severity of the incident for TheHive connectors. + The value ranges from 1 (low) to 4 (critical) with a default value of 2 (medium). source: type: string - description: The display name for the source of the alert. + description: The display name for the source of the alert in Opsgenie and TheHive connectors. + sourceRef: + type: string + description: A source reference for the alert in TheHive connectors. tags: type: array - description: The tags for the alert. + description: The tags for the alert in Opsgenie and TheHive connectors. items: type: string + title: + type: string + description: > + A title for the incident for TheHive connectors. + It is used for searching the contents of the knowledge base. + tlp: + type: integer + minimum: 0 + maximum: 4 + default: 2 + description: > + The traffic light protocol designation for the incident in TheHive connectors. Valid values include: 0 (clear), 1 (green), 2 (amber), 3 (amber and strict), and 4 (red). + type: + type: string + description: The type of alert in TheHive connectors. user: type: string description: The display name for the owner. diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_pushtoservice.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_pushtoservice.yaml index d81c0e61059be..210bf1dcf8570 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/run_pushtoservice.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_pushtoservice.yaml @@ -3,7 +3,7 @@ type: object required: - subAction - subActionParams -description: The `pushToService` subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, and Webhook - Case Management connectors. +description: The `pushToService` subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, TheHive, and Webhook - Case Management connectors. properties: subAction: type: string @@ -16,7 +16,7 @@ properties: properties: comments: type: array - description: Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, or Swimlane. + description: Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, or TheHive. items: type: object properties: @@ -28,7 +28,7 @@ properties: description: A unique identifier for the comment. incident: type: object - description: Information necessary to create or update a Jira, ServiceNow ITSM, ServiveNow SecOps, or Swimlane incident. + description: Information necessary to create or update a Jira, ServiceNow ITSM, ServiveNow SecOps, Swimlane, or TheHive incident. properties: alertId: type: string @@ -52,7 +52,7 @@ properties: NOTE: Using the default configuration of `{{ruleID}}:{{alert ID}}` ensures that ServiceNow creates a separate incident record for every generated alert that uses a unique alert ID. If the rule generates multiple alerts that use the same alert IDs, ServiceNow creates and continually updates a single incident record for the alert. description: type: string - description: The description of the incident for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, and Webhook - Case Management connectors. + description: The description of the incident for Jira, ServiceNow ITSM, ServiceNow SecOps, Swimlane, TheHive, and Webhook - Case Management connectors. dest_ip: description: > A list of destination IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident. @@ -113,8 +113,10 @@ properties: type: string description: The rule name for Swimlane connectors. severity: - type: string - description: The severity of the incident for ServiceNow ITSM and Swimlane connectors. + type: integer + description: > + The severity of the incident for ServiceNow ITSM, Swimlane, and TheHive connectors. + In TheHive connectors, the severity value ranges from 1 (low) to 4 (critical) with a default value of 2 (medium). short_description: type: string description: > @@ -139,12 +141,19 @@ properties: type: array items: type: string - description: A list of tags for Webhook - Case Management connectors. + description: A list of tags for TheHive and Webhook - Case Management connectors. title: type: string description: > - A title for the incident for Jira and Webhook - Case Management connectors. + A title for the incident for Jira, TheHive, and Webhook - Case Management connectors. It is used for searching the contents of the knowledge base. + tlp: + type: integer + minimum: 0 + maximum: 4 + default: 2 + description: > + The traffic light protocol designation for the incident in TheHive connectors. Valid values include: 0 (clear), 1 (green), 2 (amber), 3 (amber and strict), and 4 (red). urgency: type: string description: The urgency of the incident for ServiceNow ITSM connectors. diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml new file mode 100644 index 0000000000000..1c8fa603ec131 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml @@ -0,0 +1,16 @@ +title: Connector request properties for a TheHive connector +description: Defines configuration properties for connectors when type is `.thehive`. +type: object +required: + - url +properties: + organization: + type: string + description: > + The organisation in TheHive that will contain the alerts or cases. + By default, the connector uses the default organisation for the user account. + url: + type: string + description: > + The instance URL in TheHive. + If you are using the `xpack.actions.allowedHosts` setting, add the hostname to the allowed hosts. \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_secrets.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_secrets.yaml new file mode 100644 index 0000000000000..595af60710b12 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_secrets.yaml @@ -0,0 +1,9 @@ +title: Connector secrets properties for a TheHive connector +description: Defines secrets for connectors when type is `.thehive`. +required: + - apiKey +type: object +properties: + apiKey: + type: string + description: The API key for authentication in TheHive. From 18ae1f359a587fe70500d2d5e001f57bba1c6b88 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 9 Sep 2024 18:14:00 -0700 Subject: [PATCH 2/6] Add TheHive connector details via overlay --- oas_docs/overlays/connectors.overlays.yaml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/oas_docs/overlays/connectors.overlays.yaml b/oas_docs/overlays/connectors.overlays.yaml index 7cb2f79be3a1e..2cc4463dd6b3a 100644 --- a/oas_docs/overlays/connectors.overlays.yaml +++ b/oas_docs/overlays/connectors.overlays.yaml @@ -159,7 +159,7 @@ actions: # Observability AI Assistant (.observability-ai-assistant) TBD # Azure OpenAI (.gen-ai) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/genai_azure_config.yaml' - # OpenAI (.gen-ai) + # OpenAI (.gen-ai) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/genai_openai_config.yaml' # Opsgenie (.opsgenie) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/opsgenie_config.yaml' @@ -177,6 +177,8 @@ actions: - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/slack_api_config.yaml' # Swimlane (.swimlane) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/swimlane_config.yaml' + # TheHive (.thehive) + - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml' # Tines (.tines) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/tines_config.yaml' # Torq (.torq) @@ -224,6 +226,8 @@ actions: - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/slack_api_secrets.yaml' # Swimlane (.swimlane) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/swimlane_secrets.yaml' + # TheHive (.thehive) + - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/thehive_secrets.yaml' # Tines (.tines) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/tines_secrets.yaml' # Torq (.torq) @@ -284,6 +288,8 @@ actions: - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/slack_api_config.yaml' # Swimlane (.swimlane) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/swimlane_config.yaml' + # TheHive (.thehive) + - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml' # Tines (.tines) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/tines_config.yaml' # Torq (.torq) @@ -331,6 +337,8 @@ actions: - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/slack_api_secrets.yaml' # Swimlane (.swimlane) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/swimlane_secrets.yaml' + # TheHive (.thehive) + - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/thehive_secrets.yaml' # Tines (.tines) - $ref: '../../x-pack/plugins/actions/docs/openapi/components/schemas/tines_secrets.yaml' # Torq (.torq) From dc0f02cd5fd6f7519c663112f07c64fb723935af Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 9 Sep 2024 18:14:32 -0700 Subject: [PATCH 3/6] Add reminders to connector template --- docs/action-type-template.asciidoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/action-type-template.asciidoc b/docs/action-type-template.asciidoc index b9d7ca3c6326c..723ad922367f3 100644 --- a/docs/action-type-template.asciidoc +++ b/docs/action-type-template.asciidoc @@ -22,7 +22,9 @@ or as needed when you're creating a rule. connectors have the following configuration properties: //// -List of user-facing connector configurations. This should align with the fields available in the Create connector flyout form for this connector type. +List of user-facing connector configurations. +This should align with the fields available in the Create connector flyout form for this connector type. +To include these configuration details in the API documentation, add apprpriate files in x-pack/plugins/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml //// Property1:: A short description of this property. @@ -41,7 +43,9 @@ You can test connectors as you're creating or editing the connector in {kib}. actions have the following properties. //// -List of user-facing action configurations. This should align with the fields available in the Action section of the Create/Update alert flyout. +List of user-facing action configurations. +This should align with the fields available in the Action section of the Create/Update alert flyout. +To include these configuration details in the API documentation, add apprpriate files in x-pack/plugins/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml //// Property1:: A short description of this property. From 579396f7c34d13bc869781e5530473f5fdc32947 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 9 Sep 2024 18:14:51 -0700 Subject: [PATCH 4/6] Fix spelling of organisation --- .../actions/docs/openapi/components/schemas/thehive_config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml index 1c8fa603ec131..1e1406bf6d90c 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml @@ -4,7 +4,7 @@ type: object required: - url properties: - organization: + organisation: type: string description: > The organisation in TheHive that will contain the alerts or cases. From 48ce983352b9f95474f1657adfd05b1702f9bd6a Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 10 Sep 2024 08:08:39 -0700 Subject: [PATCH 5/6] Edit the organisation description --- .../actions/docs/openapi/components/schemas/thehive_config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml index 1e1406bf6d90c..d317e3af92f2a 100644 --- a/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/thehive_config.yaml @@ -8,7 +8,7 @@ properties: type: string description: > The organisation in TheHive that will contain the alerts or cases. - By default, the connector uses the default organisation for the user account. + By default, the connector uses the default organisation of the user account that created the API key. url: type: string description: > From e49f23741b54533b11048ad5907283e8e78639af Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 11 Sep 2024 14:27:58 -0700 Subject: [PATCH 6/6] Fix typo --- docs/action-type-template.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/action-type-template.asciidoc b/docs/action-type-template.asciidoc index 723ad922367f3..ad59f2a2d9ed6 100644 --- a/docs/action-type-template.asciidoc +++ b/docs/action-type-template.asciidoc @@ -24,7 +24,7 @@ or as needed when you're creating a rule. //// List of user-facing connector configurations. This should align with the fields available in the Create connector flyout form for this connector type. -To include these configuration details in the API documentation, add apprpriate files in x-pack/plugins/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml +To include these configuration details in the API documentation, add appropriate files in x-pack/plugins/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml //// Property1:: A short description of this property. @@ -45,7 +45,7 @@ You can test connectors as you're creating or editing the connector in {kib}. //// List of user-facing action configurations. This should align with the fields available in the Action section of the Create/Update alert flyout. -To include these configuration details in the API documentation, add apprpriate files in x-pack/plugins/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml +To include these configuration details in the API documentation, add appropriate files in x-pack/plugins/actions/docs/openapi/components/schemas/ and reference them from oas_docs/overlays/connectors.overlays.yaml //// Property1:: A short description of this property.