From 3206fa89006013f255a936683a5f44f9912c165a Mon Sep 17 00:00:00 2001 From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Date: Thu, 26 Jan 2023 13:27:54 -0500 Subject: [PATCH] [8.6] [DOCS] Create open API specification for run connector (#149274) (#149614) # Backport This will backport the following commits from `main` to `8.6`: - [[DOCS] Create open API specification for run connector (#149274)](https://github.com/elastic/kibana/pull/149274) ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) Co-authored-by: Lisa Cawley --- .../connector-apis-passthru.asciidoc | 510 ++++++- .../actions-and-connectors/execute.asciidoc | 14 +- .../plugins/actions/docs/openapi/bundled.json | 1335 +++++++++++++++-- .../plugins/actions/docs/openapi/bundled.yaml | 835 ++++++++++- .../examples/run_index_connector_request.yaml | 7 + .../run_index_connector_response.yaml | 20 + .../examples/run_jira_connector_request.yaml | 4 + .../examples/run_jira_connector_response.yaml | 17 + .../run_server_log_connector_request.yaml | 5 + .../run_server_log_connector_response.yaml | 4 + ...run_servicenow_itom_connector_request.yaml | 8 + ...un_servicenow_itom_connector_response.yaml | 41 + .../run_swimlane_connector_request.yaml | 12 + .../run_swimlane_connector_response.yaml | 12 + .../components/schemas/401_response.yaml | 15 + .../components/schemas/404_response.yaml | 15 + .../run_connector_params_documents.yaml | 13 + .../run_connector_params_level_message.yaml | 20 + .../run_connector_subaction_addevent.yaml | 49 + .../run_connector_subaction_closealert.yaml | 30 + .../run_connector_subaction_createalert.yaml | 112 ++ ...connector_subaction_fieldsbyissuetype.yaml | 22 + .../run_connector_subaction_getchoices.yaml | 23 + .../run_connector_subaction_getfields.yaml | 11 + .../run_connector_subaction_getincident.yaml | 21 + .../run_connector_subaction_issue.yaml | 20 + .../run_connector_subaction_issues.yaml | 20 + .../run_connector_subaction_issuetypes.yaml | 11 + ...run_connector_subaction_pushtoservice.yaml | 133 ++ .../actions/docs/openapi/entrypoint.yaml | 9 +- .../s@{spaceid}@api@actions@connector.yaml | 13 +- ...}@api@actions@connector@{connectorid}.yaml | 49 +- ...ions@connector@{connectorid}@_execute.yaml | 105 ++ ...{spaceid}@api@actions@connector_types.yaml | 11 +- .../s@{spaceid}@api@actions@connectors.yaml | 11 +- 35 files changed, 3226 insertions(+), 311 deletions(-) create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_request.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_request.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_request.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_request.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_request.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/401_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/404_response.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_documents.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_level_message.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_addevent.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_closealert.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_createalert.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_fieldsbyissuetype.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getchoices.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getfields.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getincident.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issue.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issues.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issuetypes.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_pushtoservice.yaml create mode 100644 x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml diff --git a/docs/api-generated/connectors/connector-apis-passthru.asciidoc b/docs/api-generated/connectors/connector-apis-passthru.asciidoc index ac2c18b4f2c295..98ef93db6e820f 100644 --- a/docs/api-generated/connectors/connector-apis-passthru.asciidoc +++ b/docs/api-generated/connectors/connector-apis-passthru.asciidoc @@ -23,6 +23,7 @@ Any modifications made to this file will be overwritten.
  • get /s/{spaceId}/api/actions/connector/{connectorId}
  • get /s/{spaceId}/api/actions/connector_types
  • get /s/{spaceId}/api/actions/connectors
    • +
  • post /s/{spaceId}/api/actions/connector/{connectorId}/_execute
  • put /s/{spaceId}/api/actions/connector/{connectorId}
    • @@ -90,7 +91,7 @@ Any modifications made to this file will be overwritten. connector_response_properties

    401

    Authorization information is missing or invalid. - createConnector_401_response + 401_response
    @@ -138,7 +139,7 @@ Any modifications made to this file will be overwritten.

    401

    Authorization information is missing or invalid. - createConnector_401_response + 401_response

    404

    Object is not found. getConnector_404_response @@ -190,7 +191,7 @@ Any modifications made to this file will be overwritten. connector_response_properties

    401

    Authorization information is missing or invalid. - createConnector_401_response + 401_response

    404

    Object is not found. getConnector_404_response @@ -254,7 +255,7 @@ Any modifications made to this file will be overwritten.

    401

    Authorization information is missing or invalid. - createConnector_401_response + 401_response
    @@ -312,7 +313,78 @@ Any modifications made to this file will be overwritten.

    401

    Authorization information is missing or invalid. -     createConnector_401_response + 401_response +
    +
    +
    +
    + Up + 
    post /s/{spaceId}/api/actions/connector/{connectorId}/_execute
    +
    Runs a connector. (runConnector)
    +
    You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems. You must have read privileges for the Actions and Connectors feature in the Management section of the Kibana feature privileges. If you use an index connector, you must also have all, create, index, or write indices privileges.
    + +

    Path parameters

    +
    +
    connectorId (required)
    + +
    Path Parameter — An identifier for the connector. default: null
    spaceId (required)
    + +
    Path Parameter — An identifier for the space. If /s/ and the identifier are omitted from the path, the default space is used. default: null
    +
    + +

    Consumes

    + This API call consumes the following media types via the Content-Type request header: + + +

    Request body

    +
    +
    Run_connector_request_body_properties Run_connector_request_body_properties (required)
    + +
    Body Parameter —
    + +
    + +

    Request headers

    +
    +
    kbn-xsrf (required)
    + +
    Header Parameter — default: null
    + +
    + + + +

    Return type

    +
    + runConnector_200_response + +
    + + + +

    Example data

    +
    Content-Type: application/json
    + 
    {
+  "connector_id" : "connector_id",
+  "status" : "error"
+}
    + +

    Produces

    + This API call produces the following media types according to the Accept request header; + the media type will be conveyed by the Content-Type response header. + + +

    Responses

    +

    200

    + Indicates a successful call. + runConnector_200_response +

    401

    + Authorization information is missing or invalid. + 401_response
    @@ -383,10 +455,10 @@ Any modifications made to this file will be overwritten. updateConnector_400_response

    401

    Authorization information is missing or invalid. - createConnector_401_response + 401_response

    404

    Object is not found. - getConnector_404_response + 404_response
    @@ -395,6 +467,8 @@ Any modifications made to this file will be overwritten.

    Table of Contents

      +
    1. 401_response - Unsuccessful rule API response
      2. +
    2. 404_response -
    3. Alert_identifier_mapping - Alert identifier mapping
    4. Case_comment_mapping - Case comment mapping
    5. Case_description_mapping - Case description mapping
      6. @@ -405,7 +479,10 @@ Any modifications made to this file will be overwritten.
    6. Get_connector_types_response_body_properties_inner -
    7. Get_connectors_response_body_properties - Get connectors response body properties
    8. Rule_name_mapping - Rule name mapping
      9. +
    9. Run_connector_request_body_properties - Run connector request body properties
      10. +
    10. Run_connector_request_body_properties_params -
    11. Severity_mapping - Severity mapping
      12. +
    12. Subaction_parameters - Subaction parameters
    13. Update_connector_request_body_properties - Update connector request body properties
    14. config_properties_cases_webhook - Connector request properties for Webhook - Case Management connector
    15. config_properties_index - Connector request properties for an index connector
      16. @@ -434,7 +511,6 @@ Any modifications made to this file will be overwritten.
    16. connector_response_properties_webhook - Connector response properties for a Webhook connector
    17. connector_response_properties_xmatters - Connector response properties for an xMatters connector
    18. connector_types - Connector types
      19. -
    19. createConnector_401_response -
    20. create_connector_request_cases_webhook - Create Webhook - Case Managment connector request
    21. create_connector_request_email - Create email connector request
    22. create_connector_request_index - Create index connector request
      23. @@ -454,6 +530,38 @@ Any modifications made to this file will be overwritten.
    23. create_connector_request_xmatters - Create xMatters connector request
    24. features -
    25. getConnector_404_response -
      26. +
    26. runConnector_200_response -
      27. +
    27. runConnector_200_response_data -
      28. +
    28. run_connector_params_documents - Index connector parameters
      29. +
    29. run_connector_params_level_message - Server log connector parameters
      30. +
    30. run_connector_subaction_addevent - The addEvent subaction
      31. +
    31. run_connector_subaction_addevent_subActionParams -
      32. +
    32. run_connector_subaction_closealert - The closeAlert subaction
      33. +
    33. run_connector_subaction_closealert_subActionParams -
      34. +
    34. run_connector_subaction_createalert - The createAlert subaction
      35. +
    35. run_connector_subaction_createalert_subActionParams -
      36. +
    36. run_connector_subaction_createalert_subActionParams_responders_inner -
      37. +
    37. run_connector_subaction_createalert_subActionParams_visibleTo_inner -
      38. +
    38. run_connector_subaction_fieldsbyissuetype - The fieldsByIssueType subaction
      39. +
    39. run_connector_subaction_fieldsbyissuetype_subActionParams -
      40. +
    40. run_connector_subaction_getchoices - The getChoices subaction
      41. +
    41. run_connector_subaction_getchoices_subActionParams -
      42. +
    42. run_connector_subaction_getfields - The getFields subaction
      43. +
    43. run_connector_subaction_getincident - The getIncident subaction
      44. +
    44. run_connector_subaction_getincident_subActionParams -
      45. +
    45. run_connector_subaction_issue - The issue subaction
      46. +
    46. run_connector_subaction_issue_subActionParams -
      47. +
    47. run_connector_subaction_issues - The issues subaction
      48. +
    48. run_connector_subaction_issues_subActionParams -
      49. +
    49. run_connector_subaction_issuetypes - The issueTypes subaction
      50. +
    50. run_connector_subaction_pushtoservice - The pushToService subaction
      51. +
    51. run_connector_subaction_pushtoservice_subActionParams -
      52. +
    52. run_connector_subaction_pushtoservice_subActionParams_comments_inner -
      53. +
    53. run_connector_subaction_pushtoservice_subActionParams_incident -
      54. +
    54. run_connector_subaction_pushtoservice_subActionParams_incident_dest_ip -
      55. +
    55. run_connector_subaction_pushtoservice_subActionParams_incident_malware_hash -
      56. +
    56. run_connector_subaction_pushtoservice_subActionParams_incident_malware_url -
      57. +
    57. run_connector_subaction_pushtoservice_subActionParams_incident_source_ip -
    58. secrets_properties_cases_webhook - Connector secrets properties for Webhook - Case Management connector
    59. secrets_properties_jira - Connector secrets properties for a Jira connector
    60. secrets_properties_opsgenie - Connector secrets properties for an Opsgenie connector
      61. @@ -472,6 +580,32 @@ Any modifications made to this file will be overwritten.
    61. update_connector_request_swimlane - Update Swimlane connector request
    +
    +

    401_response - Unsuccessful rule API response Up

    +
    +
    +
    error (optional)
    String
    +
    Enum:
    +
    Unauthorized
    +
    message (optional)
    String
    +
    statusCode (optional)
    Integer
    +
    Enum:
    +
    401
    +
    +
    +
    +

    404_response - Up

    +
    +
    +
    error (optional)
    String
    +
    Enum:
    +
    Not Found
    +
    message (optional)
    String
    +
    statusCode (optional)
    Integer
    +
    Enum:
    +
    404
    +
    +

    Alert_identifier_mapping - Alert identifier mapping Up

    Mapping for the alert ID.
    @@ -584,6 +718,28 @@ Any modifications made to this file will be overwritten.
    name
    String The name of the field in Swimlane.
    +
    +

    Run_connector_request_body_properties - Run connector request body properties Up

    +
    The properties vary depending on the connector type.
    +
    +
    params
    Run_connector_request_body_properties_params
    +
    +
    +
    +

    Run_connector_request_body_properties_params - Up

    +
    +
    +
    documents
    array[map[String, oas_any_type_not_mapped]] The documents in JSON format for index connectors.
    +
    level (optional)
    String The log level of the message for server log connectors.
    +
    Enum:
    +
    debug
    error
    fatal
    info
    trace
    warn
    +
    message
    String The message for server log connectors.
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    pushToService
    +
    subActionParams
    run_connector_subaction_pushtoservice_subActionParams
    +
    +

    Severity_mapping - Severity mapping Up

    Mapping for the severity.
    @@ -594,6 +750,16 @@ Any modifications made to this file will be overwritten.
    name
    String The name of the field in Swimlane.
    +
    +

    Subaction_parameters - Subaction parameters Up

    +
    Test an action that involves a subaction.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    pushToService
    +
    subActionParams
    run_connector_subaction_pushtoservice_subActionParams
    +
    +

    Update_connector_request_body_properties - Update connector request body properties Up

    The properties vary depending on the connector type.
    @@ -971,15 +1137,6 @@ Any modifications made to this file will be overwritten.
    -
    -

    createConnector_401_response - Up

    -
    -
    -
    error (optional)
    String
    -
    message (optional)
    String
    -
    statusCode (optional)
    Integer
    -
    -

    create_connector_request_cases_webhook - Create Webhook - Case Managment connector request Up

    The Webhook - Case Management connector uses axios to send POST, PUT, and GET requests to a case management RESTful API web service.
    @@ -1194,6 +1351,325 @@ Any modifications made to this file will be overwritten.
    statusCode (optional)
    Integer
    +
    +

    runConnector_200_response - Up

    +
    +
    +
    connector_id
    String The identifier for the connector.
    +
    data (optional)
    runConnector_200_response_data
    +
    status
    String The status of the action.
    +
    Enum:
    +
    error
    ok
    +
    +
    +
    +

    runConnector_200_response_data - Up

    +
    +
    +
    +
    +
    +

    run_connector_params_documents - Index connector parameters Up

    +
    Test an action that indexes a document into Elasticsearch.
    +
    +
    documents
    array[map[String, oas_any_type_not_mapped]] The documents in JSON format for index connectors.
    +
    +
    +
    +

    run_connector_params_level_message - Server log connector parameters Up

    +
    Test an action that writes an entry to the Kibana server log.
    +
    +
    level (optional)
    String The log level of the message for server log connectors.
    +
    Enum:
    +
    debug
    error
    fatal
    info
    trace
    warn
    +
    message
    String The message for server log connectors.
    +
    +
    +
    +

    run_connector_subaction_addevent - The addEvent subaction Up

    +
    The addEvent subaction for ServiceNow ITOM connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    addEvent
    +
    subActionParams (optional)
    run_connector_subaction_addevent_subActionParams
    +
    +
    +
    +

    run_connector_subaction_addevent_subActionParams - Up

    +
    The set of configuration properties for the action.
    +
    +
    additional_info (optional)
    String Additional information about the event.
    +
    description (optional)
    String The details about the event.
    +
    event_class (optional)
    String A specific instance of the source.
    +
    message_key (optional)
    String All actions sharing this key are associated with the same ServiceNow alert. The default value is <rule ID>:<alert instance ID>.
    +
    metric_name (optional)
    String The name of the metric.
    +
    node (optional)
    String The host that the event was triggered for.
    +
    resource (optional)
    String The name of the resource.
    +
    severity (optional)
    String The severity of the event.
    +
    source (optional)
    String The name of the event source type.
    +
    time_of_event (optional)
    String The time of the event.
    +
    type (optional)
    String The type of event.
    +
    +
    +
    +

    run_connector_subaction_closealert - The closeAlert subaction Up

    +
    The closeAlert subaction for Opsgenie connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    closeAlert
    +
    subActionParams
    run_connector_subaction_closealert_subActionParams
    +
    +
    +
    +

    run_connector_subaction_closealert_subActionParams - Up

    +
    +
    +
    alias
    String The unique identifier used for alert deduplication in Opsgenie. The alias must match the value used when creating the alert.
    +
    note (optional)
    String Additional information for the alert.
    +
    source (optional)
    String The display name for the source of the alert.
    +
    user (optional)
    String The display name for the owner.
    +
    +
    +
    +

    run_connector_subaction_createalert - The createAlert subaction Up

    +
    The createAlert subaction for Opsgenie connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    createAlert
    +
    subActionParams
    run_connector_subaction_createalert_subActionParams
    +
    +
    +
    +

    run_connector_subaction_createalert_subActionParams - Up

    +
    +
    +
    actions (optional)
    array[String] The custom actions available to the alert.
    +
    alias (optional)
    String The unique identifier used for alert deduplication in Opsgenie.
    +
    description (optional)
    String A description that provides detailed information about the alert.
    +
    details (optional)
    map[String, oas_any_type_not_mapped] The custom properties of the alert.
    +
    entity (optional)
    String The domain of the alert. For example, the application or server name.
    +
    message
    String The alert message.
    +
    note (optional)
    String Additional information for the alert.
    +
    priority (optional)
    String The priority level for the alert.
    +
    Enum:
    +
    P1
    P2
    P3
    P4
    P5
    +
    responders (optional)
    array[run_connector_subaction_createalert_subActionParams_responders_inner] The entities to receive notifications about the alert. If type is user, either id or username is required. If type is team, either id or name is required.
    +
    source (optional)
    String The display name for the source of the alert.
    +
    tags (optional)
    array[String] The tags for the alert.
    +
    user (optional)
    String The display name for the owner.
    +
    visibleTo (optional)
    array[run_connector_subaction_createalert_subActionParams_visibleTo_inner] The teams and users that the alert will be visible to without sending a notification. Only one of id, name, or username is required.
    +
    +
    +
    +

    run_connector_subaction_createalert_subActionParams_responders_inner - Up

    +
    +
    +
    id (optional)
    String The identifier for the entity.
    +
    name (optional)
    String The name of the entity.
    +
    type (optional)
    String The type of responders, in this case escalation.
    +
    Enum:
    +
    escalation
    schedule
    team
    user
    +
    username (optional)
    String A valid email address for the user.
    +
    +
    +
    +

    run_connector_subaction_createalert_subActionParams_visibleTo_inner - Up

    +
    +
    +
    id (optional)
    String The identifier for the entity.
    +
    name (optional)
    String The name of the entity.
    +
    type
    String Valid values are team and user.
    +
    Enum:
    +
    team
    user
    +
    username (optional)
    String The user name. This property is required only when the type is user.
    +
    +
    +
    +

    run_connector_subaction_fieldsbyissuetype - The fieldsByIssueType subaction Up

    +
    The fieldsByIssueType subaction for Jira connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    fieldsByIssueType
    +
    subActionParams
    run_connector_subaction_fieldsbyissuetype_subActionParams
    +
    +
    +
    +

    run_connector_subaction_fieldsbyissuetype_subActionParams - Up

    +
    +
    +
    id
    String The Jira issue type identifier.
    +
    +
    +
    +

    run_connector_subaction_getchoices - The getChoices subaction Up

    +
    The getChoices subaction for ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    getChoices
    +
    subActionParams
    run_connector_subaction_getchoices_subActionParams
    +
    +
    +
    +

    run_connector_subaction_getchoices_subActionParams - Up

    +
    The set of configuration properties for the action.
    +
    +
    fields
    array[String] An array of fields.
    +
    +
    +
    +

    run_connector_subaction_getfields - The getFields subaction Up

    +
    The getFields subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    getFields
    +
    +
    +
    +

    run_connector_subaction_getincident - The getIncident subaction Up

    +
    The getIncident subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    getIncident
    +
    subActionParams
    run_connector_subaction_getincident_subActionParams
    +
    +
    +
    +

    run_connector_subaction_getincident_subActionParams - Up

    +
    +
    +
    externalId
    String The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier.
    +
    +
    +
    +

    run_connector_subaction_issue - The issue subaction Up

    +
    The issue subaction for Jira connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    issue
    +
    subActionParams (optional)
    run_connector_subaction_issue_subActionParams
    +
    +
    +
    +

    run_connector_subaction_issue_subActionParams - Up

    +
    +
    +
    id
    String The Jira issue identifier.
    +
    +
    +
    +

    run_connector_subaction_issues - The issues subaction Up

    +
    The issues subaction for Jira connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    issues
    +
    subActionParams
    run_connector_subaction_issues_subActionParams
    +
    +
    +
    +

    run_connector_subaction_issues_subActionParams - Up

    +
    +
    +
    title
    String The title of the Jira issue.
    +
    +
    +
    +

    run_connector_subaction_issuetypes - The issueTypes subaction Up

    +
    The issueTypes subaction for Jira connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    issueTypes
    +
    +
    +
    +

    run_connector_subaction_pushtoservice - The pushToService subaction Up

    +
    The pushToService subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, and Swimlane connectors.
    +
    +
    subAction
    String The action to test.
    +
    Enum:
    +
    pushToService
    +
    subActionParams
    run_connector_subaction_pushtoservice_subActionParams
    +
    +
    +
    +

    run_connector_subaction_pushtoservice_subActionParams - Up

    +
    The set of configuration properties for the action.
    +
    +
    comments (optional)
    array[run_connector_subaction_pushtoservice_subActionParams_comments_inner] Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, or Swimlane.
    +
    incident (optional)
    run_connector_subaction_pushtoservice_subActionParams_incident
    +
    +
    +
    +

    run_connector_subaction_pushtoservice_subActionParams_comments_inner - Up

    +
    +
    +
    comment (optional)
    String A comment related to the incident. For example, describe how to troubleshoot the issue.
    +
    commentId (optional)
    Integer A unique identifier for the comment.
    +
    +
    +
    +

    run_connector_subaction_pushtoservice_subActionParams_incident - Up

    +
    Information necessary to create or update a Jira, ServiceNow ITSM, ServiveNow SecOps, or Swimlane incident.
    +
    +
    alertId (optional)
    String The alert identifier for Swimlane connectors.
    +
    caseId (optional)
    String The case identifier for the incident for Swimlane connectors.
    +
    caseName (optional)
    String The case name for the incident for Swimlane connectors.
    +
    category (optional)
    String The category of the incident for ServiceNow ITSM and ServiceNow SecOps connectors.
    +
    correlation_display (optional)
    String A descriptive label of the alert for correlation purposes for ServiceNow ITSM and ServiceNow SecOps connectors.
    +
    correlation_id (optional)
    String The correlation identifier for the security incident for ServiceNow ITSM and ServiveNow SecOps connectors. Connectors using the same correlation ID are associated with the same ServiceNow incident. This value determines whether a new ServiceNow incident is created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as {{ruleID}}:{{alert ID}} to form the correlation ID value in ServiceNow. The maximum character length for this value is 100 characters. 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 (optional)
    String The description of the incident for Jira, ServiceNow ITSM, ServiceNow SecOps, and Swimlane connectors.
    +
    dest_ip (optional)
    run_connector_subaction_pushtoservice_subActionParams_incident_dest_ip
    +
    externalId (optional)
    String The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. If present, the incident is updated. Otherwise, a new incident is created.
    +
    impact (optional)
    String The impact of the incident for ServiceNow ITSM connectors.
    +
    issueType (optional)
    Integer The type of incident for Jira connectors. For example, 10006. To obtain the list of valid values, set subAction to issueTypes.
    +
    labels (optional)
    array[String] The labels for the incident for Jira connectors. NOTE: Labels cannot contain spaces.
    +
    malware_hash (optional)
    run_connector_subaction_pushtoservice_subActionParams_incident_malware_hash
    +
    malware_url (optional)
    run_connector_subaction_pushtoservice_subActionParams_incident_malware_url
    +
    parent (optional)
    String The ID or key of the parent issue for Jira connectors. Applies only to Sub-task types of issues.
    +
    priority (optional)
    String The priority of the incident in Jira and ServiceNow SecOps connectors.
    +
    ruleName (optional)
    String The rule name for Swimlane connectors.
    +
    severity (optional)
    String The severity of the incident for ServiceNow ITSM and Swimlane connectors.
    +
    short_description (optional)
    String A short description of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. It is used for searching the contents of the knowledge base.
    +
    source_ip (optional)
    run_connector_subaction_pushtoservice_subActionParams_incident_source_ip
    +
    subcategory (optional)
    String The subcategory of the incident for ServiceNow ITSM and ServiceNow SecOps connectors.
    +
    summary (optional)
    String A summary of the incident for Jira connectors.
    +
    title (optional)
    String A title for the incident for Jira connectors. It is used for searching the contents of the knowledge base.
    +
    urgency (optional)
    String The urgency of the incident for ServiceNow ITSM connectors.
    +
    +
    +
    +

    run_connector_subaction_pushtoservice_subActionParams_incident_dest_ip - Up

    +
    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.
    +
    +
    +
    +
    +

    run_connector_subaction_pushtoservice_subActionParams_incident_malware_hash - Up

    +
    A list of malware hashes related to the security incident for ServiceNow SecOps connectors. The hashes are added as observables to the security incident.
    +
    +
    +
    +
    +

    run_connector_subaction_pushtoservice_subActionParams_incident_malware_url - Up

    +
    A list of malware URLs related to the security incident for ServiceNow SecOps connectors. The URLs are added as observables to the security incident.
    +
    +
    +
    +
    +

    run_connector_subaction_pushtoservice_subActionParams_incident_source_ip - Up

    +
    A list of source IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident.
    +
    +
    +

    secrets_properties_cases_webhook - Connector secrets properties for Webhook - Case Management connector Up

    diff --git a/docs/api/actions-and-connectors/execute.asciidoc b/docs/api/actions-and-connectors/execute.asciidoc index 7fbaae439094e8..6d94c61f6232bf 100644 --- a/docs/api/actions-and-connectors/execute.asciidoc +++ b/docs/api/actions-and-connectors/execute.asciidoc @@ -6,6 +6,12 @@ Runs a connector by ID. +[NOTE] +==== +For the most up-to-date API details, refer to the +{kib-repo}/tree/{branch}/x-pack/plugins/actions/docs/openapi[open API specification]. For a preview, check out <>. +==== + [[execute-connector-api-request]] === {api-request-title} @@ -362,7 +368,7 @@ on the `subAction` value. This object is not required when `subAction` is [%collapsible%open] ====== `comments`::: -(Optional, array of objects) Additional information that is sent to {sn-sir}. +(Optional, array of objects) Additional information that is sent to {sn-itsm}. + .Properties of `comments` [%collapsible%open] @@ -381,7 +387,7 @@ version:::: ======= `incident`::: -(Required, object) Information necessary to create or update a {sn-sir} incident. +(Required, object) Information necessary to create or update a {sn-itsm} incident. + .Properties of `incident` [%collapsible%open] @@ -520,6 +526,10 @@ to the security incident. The IPs are added as observables to the security incid updated. Otherwise, a new incident is created. `malware_hash`:::: +(Optional, string or array of strings) A list of malware hashes related to the +security incident. The hashes are added as observables to the security incident. + +`malware_url`:::: (Optional, string or array of strings) A list of malware URLs related to the security incident. The URLs are added as observables to the security incident. diff --git a/x-pack/plugins/actions/docs/openapi/bundled.json b/x-pack/plugins/actions/docs/openapi/bundled.json index 0919fea40668ba..d887c6de5a3e43 100644 --- a/x-pack/plugins/actions/docs/openapi/bundled.json +++ b/x-pack/plugins/actions/docs/openapi/bundled.json @@ -134,20 +134,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "example": "Unauthorized" - }, - "message": { - "type": "string" - }, - "statusCode": { - "type": "integer", - "example": 401 - } - } + "$ref": "#/components/schemas/401_response" } } } @@ -202,20 +189,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "example": "Unauthorized" - }, - "message": { - "type": "string" - }, - "statusCode": { - "type": "integer", - "example": 401 - } - } + "$ref": "#/components/schemas/401_response" } } } @@ -278,20 +252,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "example": "Unauthorized" - }, - "message": { - "type": "string" - }, - "statusCode": { - "type": "integer", - "example": 401 - } - } + "$ref": "#/components/schemas/401_response" } } } @@ -430,20 +391,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "example": "Unauthorized" - }, - "message": { - "type": "string" - }, - "statusCode": { - "type": "integer", - "example": 401 - } - } + "$ref": "#/components/schemas/401_response" } } } @@ -453,21 +401,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "example": "Not Found" - }, - "message": { - "type": "string", - "example": "Saved object [action/baf33fc0-920c-11ed-b36a-874bd1548a00] not found" - }, - "statusCode": { - "type": "integer", - "example": 404 - } - } + "$ref": "#/components/schemas/404_response" } } } @@ -568,20 +502,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "example": "Unauthorized" - }, - "message": { - "type": "string" - }, - "statusCode": { - "type": "integer", - "example": 401 - } - } + "$ref": "#/components/schemas/401_response" } } } @@ -685,23 +606,200 @@ }, "401": { "description": "Authorization information is missing or invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/401_response" + } + } + } + } + }, + "servers": [ + { + "url": "https://localhost:5601" + } + ] + }, + "servers": [ + { + "url": "https://localhost:5601" + } + ] + }, + "/s/{spaceId}/api/actions/connector/{connectorId}/_execute": { + "post": { + "summary": "Runs a connector.", + "operationId": "runConnector", + "description": "You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems. You must have `read` privileges for the **Actions and Connectors** feature in the **Management** section of the Kibana feature privileges. If you use an index connector, you must also have `all`, `create`, `index`, or `write` indices privileges.\n", + "tags": [ + "connectors" + ], + "parameters": [ + { + "$ref": "#/components/parameters/kbn_xsrf" + }, + { + "$ref": "#/components/parameters/connector_id" + }, + { + "$ref": "#/components/parameters/space_id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "title": "Run connector request body properties", + "description": "The properties vary depending on the connector type.", + "type": "object", + "required": [ + "params" + ], + "properties": { + "params": { + "oneOf": [ + { + "$ref": "#/components/schemas/run_connector_params_documents" + }, + { + "$ref": "#/components/schemas/run_connector_params_level_message" + }, + { + "title": "Subaction parameters", + "description": "Test an action that involves a subaction.", + "oneOf": [ + { + "$ref": "#/components/schemas/run_connector_subaction_addevent" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_closealert" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_createalert" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_fieldsbyissuetype" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_getchoices" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_getfields" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_getincident" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_issue" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_issues" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_issuetypes" + }, + { + "$ref": "#/components/schemas/run_connector_subaction_pushtoservice" + } + ], + "discriminator": { + "propertyName": "subAction" + } + } + ] + } + } + }, + "examples": { + "runIndexConnectorRequest": { + "$ref": "#/components/examples/run_index_connector_request" + }, + "runJiraConnectorRequest": { + "$ref": "#/components/examples/run_jira_connector_request" + }, + "runServerLogConnectorRequest": { + "$ref": "#/components/examples/run_server_log_connector_request" + }, + "runServiceNowITOMConnectorRequest": { + "$ref": "#/components/examples/run_servicenow_itom_connector_request" + }, + "runSwimlaneConnectorRequest": { + "$ref": "#/components/examples/run_swimlane_connector_request" + } + } + } + } + }, + "responses": { + "200": { + "description": "Indicates a successful call.", "content": { "application/json": { "schema": { "type": "object", + "required": [ + "connector_id", + "status" + ], "properties": { - "error": { + "connector_id": { "type": "string", - "example": "Unauthorized" + "description": "The identifier for the connector." }, - "message": { - "type": "string" + "data": { + "oneOf": [ + { + "type": "object", + "description": "Information returned from the action.", + "additionalProperties": true + }, + { + "type": "array", + "description": "An array of information returned from the action.", + "items": { + "type": "object" + } + } + ] }, - "statusCode": { - "type": "integer", - "example": 401 + "status": { + "type": "string", + "description": "The status of the action.", + "enum": [ + "error", + "ok" + ] } } + }, + "examples": { + "runIndexConnectorResponse": { + "$ref": "#/components/examples/run_index_connector_response" + }, + "runJiraConnectorResponse": { + "$ref": "#/components/examples/run_jira_connector_response" + }, + "runServerLogConnectorResponse": { + "$ref": "#/components/examples/run_server_log_connector_response" + }, + "runServiceNowITOMConnectorResponse": { + "$ref": "#/components/examples/run_servicenow_itom_connector_response" + }, + "runSwimlaneConnectorResponse": { + "$ref": "#/components/examples/run_swimlane_connector_response" + } + } + } + } + }, + "401": { + "description": "Authorization information is missing or invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/401_response" } } } @@ -2741,6 +2839,29 @@ "propertyName": "connector_type_id" } }, + "401_response": { + "type": "object", + "title": "Unsuccessful rule API response", + "properties": { + "error": { + "type": "string", + "example": "Unauthorized", + "enum": [ + "Unauthorized" + ] + }, + "message": { + "type": "string" + }, + "statusCode": { + "type": "integer", + "example": 401, + "enum": [ + 401 + ] + } + } + }, "update_connector_request_cases_webhook": { "title": "Update Webhook - Case Managment connector request", "type": "object", @@ -2919,6 +3040,29 @@ } } }, + "404_response": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "Not Found", + "enum": [ + "Not Found" + ] + }, + "message": { + "type": "string", + "example": "Saved object [action/baf33fc0-920c-11ed-b36a-874bd1548a00] not found" + }, + "statusCode": { + "type": "integer", + "example": 404, + "enum": [ + 404 + ] + } + } + }, "connector_types": { "title": "Connector types", "type": "string", @@ -2953,67 +3097,749 @@ "uptime", "siem" ] - } - }, - "examples": { - "create_index_connector_request": { - "summary": "Create an index connector.", - "value": { - "name": "my-connector", - "connector_type_id": ".index", - "config": { - "index": "test-index" + }, + "run_connector_params_documents": { + "title": "Index connector parameters", + "description": "Test an action that indexes a document into Elasticsearch.", + "type": "object", + "required": [ + "documents" + ], + "properties": { + "documents": { + "type": "array", + "description": "The documents in JSON format for index connectors.", + "items": { + "type": "object", + "additionalProperties": true + } } } }, - "create_index_connector_response": { - "summary": "A new index connector.", - "value": { - "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad", - "connector_type_id": ".index", - "name": "my-connector", - "config": { - "index": "test-index", - "refresh": false, - "executionTimeField": null + "run_connector_params_level_message": { + "title": "Server log connector parameters", + "description": "Test an action that writes an entry to the Kibana server log.", + "type": "object", + "required": [ + "message" + ], + "properties": { + "level": { + "type": "string", + "description": "The log level of the message for server log connectors.", + "enum": [ + "debug", + "error", + "fatal", + "info", + "trace", + "warn" + ], + "default": "info" }, - "is_preconfigured": false, - "is_deprecated": false, - "is_missing_secrets": false - } - }, - "get_connector_response": { - "summary": "A list of connector types", - "value": { - "id": "df770e30-8b8b-11ed-a780-3b746c987a81", - "name": "my_server_log_connector", - "config": {}, - "connector_type_id": ".server-log", - "is_preconfigured": false, - "is_deprecated": false, - "is_missing_secrets": false - } - }, - "update_index_connector_request": { - "summary": "Update an index connector.", - "value": { - "name": "updated-connector", - "config": { - "index": "updated-index" + "message": { + "type": "string", + "description": "The message for server log connectors." } } }, - "get_connectors_response": { - "summary": "A list of connectors", - "value": [ - { - "id": "preconfigured-email-connector", - "name": "my-preconfigured-email-notification", - "connector_type_id": ".email", - "is_preconfigured": true, - "is_deprecated": false, - "referenced_by_count": 0 - }, + "run_connector_subaction_addevent": { + "title": "The addEvent subaction", + "type": "object", + "required": [ + "subAction" + ], + "description": "The `addEvent` subaction for ServiceNow ITOM connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "addEvent" + ] + }, + "subActionParams": { + "type": "object", + "description": "The set of configuration properties for the action.", + "properties": { + "additional_info": { + "type": "string", + "description": "Additional information about the event." + }, + "description": { + "type": "string", + "description": "The details about the event." + }, + "event_class": { + "type": "string", + "description": "A specific instance of the source." + }, + "message_key": { + "type": "string", + "description": "All actions sharing this key are associated with the same ServiceNow alert. The default value is `:`." + }, + "metric_name": { + "type": "string", + "description": "The name of the metric." + }, + "node": { + "type": "string", + "description": "The host that the event was triggered for." + }, + "resource": { + "type": "string", + "description": "The name of the resource." + }, + "severity": { + "type": "string", + "description": "The severity of the event." + }, + "source": { + "type": "string", + "description": "The name of the event source type." + }, + "time_of_event": { + "type": "string", + "description": "The time of the event." + }, + "type": { + "type": "string", + "description": "The type of event." + } + } + } + } + }, + "run_connector_subaction_closealert": { + "title": "The closeAlert subaction", + "type": "object", + "required": [ + "subAction", + "subActionParams" + ], + "description": "The `closeAlert` subaction for Opsgenie connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "closeAlert" + ] + }, + "subActionParams": { + "type": "object", + "required": [ + "alias" + ], + "properties": { + "alias": { + "type": "string", + "description": "The unique identifier used for alert deduplication in Opsgenie. The alias must match the value used when creating the alert." + }, + "note": { + "type": "string", + "description": "Additional information for the alert." + }, + "source": { + "type": "string", + "description": "The display name for the source of the alert." + }, + "user": { + "type": "string", + "description": "The display name for the owner." + } + } + } + } + }, + "run_connector_subaction_createalert": { + "title": "The createAlert subaction", + "type": "object", + "required": [ + "subAction", + "subActionParams" + ], + "description": "The `createAlert` subaction for Opsgenie connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "createAlert" + ] + }, + "subActionParams": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "actions": { + "type": "array", + "description": "The custom actions available to the alert.", + "items": { + "type": "string" + } + }, + "alias": { + "type": "string", + "description": "The unique identifier used for alert deduplication in Opsgenie." + }, + "description": { + "type": "string", + "description": "A description that provides detailed information about the alert." + }, + "details": { + "type": "object", + "description": "The custom properties of the alert.", + "additionalProperties": true, + "example": { + "key1": "value1", + "key2": "value2" + } + }, + "entity": { + "type": "string", + "description": "The domain of the alert. For example, the application or server name." + }, + "message": { + "type": "string", + "description": "The alert message." + }, + "note": { + "type": "string", + "description": "Additional information for the alert." + }, + "priority": { + "type": "string", + "description": "The priority level for the alert.", + "enum": [ + "P1", + "P2", + "P3", + "P4", + "P5" + ] + }, + "responders": { + "type": "array", + "description": "The entities to receive notifications about the alert. If `type` is `user`, either `id` or `username` is required. If `type` is `team`, either `id` or `name` is required.\n", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The identifier for the entity." + }, + "name": { + "type": "string", + "description": "The name of the entity." + }, + "type": { + "type": "string", + "description": "The type of responders, in this case `escalation`.", + "enum": [ + "escalation", + "schedule", + "team", + "user" + ] + }, + "username": { + "type": "string", + "description": "A valid email address for the user." + } + } + } + }, + "source": { + "type": "string", + "description": "The display name for the source of the alert." + }, + "tags": { + "type": "array", + "description": "The tags for the alert.", + "items": { + "type": "string" + } + }, + "user": { + "type": "string", + "description": "The display name for the owner." + }, + "visibleTo": { + "type": "array", + "description": "The teams and users that the alert will be visible to without sending a notification. Only one of `id`, `name`, or `username` is required.", + "items": { + "type": "object", + "required": [ + "type" + ], + "properties": { + "id": { + "type": "string", + "description": "The identifier for the entity." + }, + "name": { + "type": "string", + "description": "The name of the entity." + }, + "type": { + "type": "string", + "description": "Valid values are `team` and `user`.", + "enum": [ + "team", + "user" + ] + }, + "username": { + "type": "string", + "description": "The user name. This property is required only when the `type` is `user`." + } + } + } + } + } + } + } + }, + "run_connector_subaction_fieldsbyissuetype": { + "title": "The fieldsByIssueType subaction", + "type": "object", + "required": [ + "subAction", + "subActionParams" + ], + "description": "The `fieldsByIssueType` subaction for Jira connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "fieldsByIssueType" + ] + }, + "subActionParams": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "The Jira issue type identifier.", + "example": 10024 + } + } + } + } + }, + "run_connector_subaction_getchoices": { + "title": "The getChoices subaction", + "type": "object", + "required": [ + "subAction", + "subActionParams" + ], + "description": "The `getChoices` subaction for ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "getChoices" + ] + }, + "subActionParams": { + "type": "object", + "description": "The set of configuration properties for the action.", + "required": [ + "fields" + ], + "properties": { + "fields": { + "type": "array", + "description": "An array of fields.", + "items": { + "type": "string" + } + } + } + } + } + }, + "run_connector_subaction_getfields": { + "title": "The getFields subaction", + "type": "object", + "required": [ + "subAction" + ], + "description": "The `getFields` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "getFields" + ] + } + } + }, + "run_connector_subaction_getincident": { + "title": "The getIncident subaction", + "type": "object", + "description": "The `getIncident` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors.", + "required": [ + "subAction", + "subActionParams" + ], + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "getIncident" + ] + }, + "subActionParams": { + "type": "object", + "required": [ + "externalId" + ], + "properties": { + "externalId": { + "type": "string", + "description": "The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier.", + "example": 71778 + } + } + } + } + }, + "run_connector_subaction_issue": { + "title": "The issue subaction", + "type": "object", + "required": [ + "subAction" + ], + "description": "The `issue` subaction for Jira connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "issue" + ] + }, + "subActionParams": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "The Jira issue identifier.", + "example": 71778 + } + } + } + } + }, + "run_connector_subaction_issues": { + "title": "The issues subaction", + "type": "object", + "required": [ + "subAction", + "subActionParams" + ], + "description": "The `issues` subaction for Jira connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "issues" + ] + }, + "subActionParams": { + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string", + "description": "The title of the Jira issue." + } + } + } + } + }, + "run_connector_subaction_issuetypes": { + "title": "The issueTypes subaction", + "type": "object", + "required": [ + "subAction" + ], + "description": "The `issueTypes` subaction for Jira connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "issueTypes" + ] + } + } + }, + "run_connector_subaction_pushtoservice": { + "title": "The pushToService subaction", + "type": "object", + "required": [ + "subAction", + "subActionParams" + ], + "description": "The `pushToService` subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, and Swimlane connectors.", + "properties": { + "subAction": { + "type": "string", + "description": "The action to test.", + "enum": [ + "pushToService" + ] + }, + "subActionParams": { + "type": "object", + "description": "The set of configuration properties for the action.", + "properties": { + "comments": { + "type": "array", + "description": "Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, or Swimlane.", + "items": { + "type": "object", + "properties": { + "comment": { + "type": "string", + "description": "A comment related to the incident. For example, describe how to troubleshoot the issue." + }, + "commentId": { + "type": "integer", + "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.", + "properties": { + "alertId": { + "type": "string", + "description": "The alert identifier for Swimlane connectors." + }, + "caseId": { + "type": "string", + "description": "The case identifier for the incident for Swimlane connectors." + }, + "caseName": { + "type": "string", + "description": "The case name for the incident for Swimlane connectors." + }, + "category": { + "type": "string", + "description": "The category of the incident for ServiceNow ITSM and ServiceNow SecOps connectors." + }, + "correlation_display": { + "type": "string", + "description": "A descriptive label of the alert for correlation purposes for ServiceNow ITSM and ServiceNow SecOps connectors." + }, + "correlation_id": { + "type": "string", + "description": "The correlation identifier for the security incident for ServiceNow ITSM and ServiveNow SecOps connectors. Connectors using the same correlation ID are associated with the same ServiceNow incident. This value determines whether a new ServiceNow incident is created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the correlation ID value in ServiceNow. The maximum character length for this value is 100 characters. 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.\n" + }, + "description": { + "type": "string", + "description": "The description of the incident for Jira, ServiceNow ITSM, ServiceNow SecOps, and Swimlane 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.\n", + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "externalId": { + "type": "string", + "description": "The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. If present, the incident is updated. Otherwise, a new incident is created.\n" + }, + "impact": { + "type": "string", + "description": "The impact of the incident for ServiceNow ITSM connectors." + }, + "issueType": { + "type": "integer", + "description": "The type of incident for Jira connectors. For example, 10006. To obtain the list of valid values, set `subAction` to `issueTypes`." + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The labels for the incident for Jira connectors. NOTE: Labels cannot contain spaces.\n" + }, + "malware_hash": { + "description": "A list of malware hashes related to the security incident for ServiceNow SecOps connectors. The hashes are added as observables to the security incident.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "malware_url": { + "type": "string", + "description": "A list of malware URLs related to the security incident for ServiceNow SecOps connectors. The URLs are added as observables to the security incident.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "parent": { + "type": "string", + "description": "The ID or key of the parent issue for Jira connectors. Applies only to `Sub-task` types of issues." + }, + "priority": { + "type": "string", + "description": "The priority of the incident in Jira and ServiceNow SecOps connectors." + }, + "ruleName": { + "type": "string", + "description": "The rule name for Swimlane connectors." + }, + "severity": { + "type": "string", + "description": "The severity of the incident for ServiceNow ITSM and Swimlane connectors." + }, + "short_description": { + "type": "string", + "description": "A short description of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. It is used for searching the contents of the knowledge base.\n" + }, + "source_ip": { + "description": "A list of source IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "subcategory": { + "type": "string", + "description": "The subcategory of the incident for ServiceNow ITSM and ServiceNow SecOps connectors." + }, + "summary": { + "type": "string", + "description": "A summary of the incident for Jira connectors." + }, + "title": { + "type": "string", + "description": "A title for the incident for Jira connectors. It is used for searching the contents of the knowledge base.\n" + }, + "urgency": { + "type": "string", + "description": "The urgency of the incident for ServiceNow ITSM connectors." + } + } + } + } + } + } + } + }, + "examples": { + "create_index_connector_request": { + "summary": "Create an index connector.", + "value": { + "name": "my-connector", + "connector_type_id": ".index", + "config": { + "index": "test-index" + } + } + }, + "create_index_connector_response": { + "summary": "A new index connector.", + "value": { + "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad", + "connector_type_id": ".index", + "name": "my-connector", + "config": { + "index": "test-index", + "refresh": false, + "executionTimeField": null + }, + "is_preconfigured": false, + "is_deprecated": false, + "is_missing_secrets": false + } + }, + "get_connector_response": { + "summary": "A list of connector types", + "value": { + "id": "df770e30-8b8b-11ed-a780-3b746c987a81", + "name": "my_server_log_connector", + "config": {}, + "connector_type_id": ".server-log", + "is_preconfigured": false, + "is_deprecated": false, + "is_missing_secrets": false + } + }, + "update_index_connector_request": { + "summary": "Update an index connector.", + "value": { + "name": "updated-connector", + "config": { + "index": "updated-index" + } + } + }, + "get_connectors_response": { + "summary": "A list of connectors", + "value": [ + { + "id": "preconfigured-email-connector", + "name": "my-preconfigured-email-notification", + "connector_type_id": ".email", + "is_preconfigured": true, + "is_deprecated": false, + "referenced_by_count": 0 + }, { "id": "e07d0c80-8b8b-11ed-a780-3b746c987a81", "name": "my-index-connector", @@ -3072,6 +3898,223 @@ ] } ] + }, + "run_index_connector_request": { + "summary": "Run an index connector.", + "value": { + "params": { + "documents": [ + { + "id": "my_doc_id", + "name": "my_doc_name", + "message": "hello, world" + } + ] + } + } + }, + "run_jira_connector_request": { + "summary": "Run a Jira connector to retrieve the list of issue types.", + "value": { + "params": { + "subAction": "issueTypes" + } + } + }, + "run_server_log_connector_request": { + "summary": "Run a server log connector.", + "value": { + "params": { + "level": "warn", + "message": "Test warning message." + } + } + }, + "run_servicenow_itom_connector_request": { + "summary": "Run a ServiceNow ITOM connector to retrieve the list of choices.", + "value": { + "params": { + "subAction": "getChoices", + "subActionParams": { + "fields": [ + "severity", + "urgency" + ] + } + } + } + }, + "run_swimlane_connector_request": { + "summary": "Run a Swimlane connector to create an incident.", + "value": { + "params": { + "subAction": "pushToService", + "subActionParams": { + "comments": [ + { + "commentId": 1, + "comment": "A comment about the incident." + } + ], + "incident": { + "caseId": "1000", + "caseName": "Case name", + "description": "Description of the incident." + } + } + } + } + }, + "run_index_connector_response": { + "summary": "Response from running an index connector.", + "value": { + "connector_id": "fd38c600-96a5-11ed-bb79-353b74189cba", + "data": { + "errors": false, + "items": [ + { + "create": { + "_id": "4JtvwYUBrcyxt2NnfW3y", + "_index": "my-index", + "_primary_term": 1, + "_seq_no": 0, + "_shards": { + "failed": 0, + "successful": 1, + "total": 2 + }, + "_version": 1, + "result": "created", + "status": 201 + } + } + ], + "took": 135 + }, + "status": "ok" + } + }, + "run_jira_connector_response": { + "summary": "Response from retrieving the list of issue types for a Jira connector.", + "value": { + "connector_id": "b3aad810-edbe-11ec-82d1-11348ecbf4a6", + "data": [ + { + "id": 10024, + "name": "Improvement" + }, + { + "id": 10006, + "name": "Task" + }, + { + "id": 10007, + "name": "Sub-task" + }, + { + "id": 10025, + "name": "New Feature" + }, + { + "id": 10023, + "name": "Bug" + }, + { + "id": 10000, + "name": "Epic" + } + ], + "status": "ok" + } + }, + "run_server_log_connector_response": { + "summary": "Response from running a server log connector.", + "value": { + "connector_id": "7fc7b9a0-ecc9-11ec-8736-e7d63118c907", + "status": "ok" + } + }, + "run_servicenow_itom_connector_response": { + "summary": "Response from retrieving the list of choices for a ServiceNow ITOM connector.", + "value": { + "connector_id": "9d9be270-2fd2-11ed-b0e0-87533c532698", + "data": [ + { + "dependent_value": "", + "element": "severity", + "label": "Critical", + "value": 1 + }, + { + "dependent_value": "", + "element": "severity", + "label": "Major", + "value": 2 + }, + { + "dependent_value": "", + "element": "severity", + "label": "Minor", + "value": 3 + }, + { + "dependent_value": "", + "element": "severity", + "label": "Warning", + "value": 4 + }, + { + "dependent_value": "", + "element": "severity", + "label": "OK", + "value": 5 + }, + { + "dependent_value": "", + "element": "severity", + "label": "Clear", + "value": 0 + }, + { + "dependent_value": "", + "element": "urgency", + "label": "1 - High", + "value": 1 + }, + { + "dependent_value": "", + "element": "urgency", + "label": "2 - Medium", + "value": 2 + }, + { + "dependent_value": "", + "element": "urgency", + "label": "3 - Low", + "value": 3 + } + ], + "status": "ok" + } + }, + "run_swimlane_connector_response": { + "summary": "Response from creating a Swimlane incident.", + "value": { + "connector_id": "a4746470-2f94-11ed-b0e0-87533c532698", + "data": { + "id": "aKPmBHWzmdRQtx6Mx", + "title": "TEST-457", + "url": "https://elastic.swimlane.url.us/record/aNcL2xniGHGpa2AHb/aKPmBHWzmdRQtx6Mx", + "pushedDate": "2022-09-08T16:52:27.866Z", + "comments": [ + { + "commentId": 1, + "pushedDate": "2022-09-08T16:52:27.865Z" + } + ] + }, + "status": "ok" + } } } }, diff --git a/x-pack/plugins/actions/docs/openapi/bundled.yaml b/x-pack/plugins/actions/docs/openapi/bundled.yaml index 1ffc0dc5da1eba..1652412e027e45 100644 --- a/x-pack/plugins/actions/docs/openapi/bundled.yaml +++ b/x-pack/plugins/actions/docs/openapi/bundled.yaml @@ -71,16 +71,7 @@ paths: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '#/components/schemas/401_response' servers: - url: https://localhost:5601 servers: @@ -111,16 +102,7 @@ paths: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '#/components/schemas/401_response' '404': description: Object is not found. content: @@ -158,16 +140,7 @@ paths: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '#/components/schemas/401_response' '404': description: Object is not found. content: @@ -245,32 +218,13 @@ paths: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '#/components/schemas/401_response' '404': description: Object is not found. content: application/json: schema: - type: object - properties: - error: - type: string - example: Not Found - message: - type: string - example: Saved object [action/baf33fc0-920c-11ed-b36a-874bd1548a00] not found - statusCode: - type: integer - example: 404 + $ref: '#/components/schemas/404_response' servers: - url: https://localhost:5601 servers: @@ -338,16 +292,7 @@ paths: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '#/components/schemas/401_response' servers: - url: https://localhost:5601 servers: @@ -415,19 +360,114 @@ paths: $ref: '#/components/examples/get_connector_types_response' '401': description: Authorization information is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/401_response' + servers: + - url: https://localhost:5601 + servers: + - url: https://localhost:5601 + /s/{spaceId}/api/actions/connector/{connectorId}/_execute: + post: + summary: Runs a connector. + operationId: runConnector + description: | + You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems. You must have `read` privileges for the **Actions and Connectors** feature in the **Management** section of the Kibana feature privileges. If you use an index connector, you must also have `all`, `create`, `index`, or `write` indices privileges. + tags: + - connectors + parameters: + - $ref: '#/components/parameters/kbn_xsrf' + - $ref: '#/components/parameters/connector_id' + - $ref: '#/components/parameters/space_id' + requestBody: + required: true + content: + application/json: + schema: + title: Run connector request body properties + description: The properties vary depending on the connector type. + type: object + required: + - params + properties: + params: + oneOf: + - $ref: '#/components/schemas/run_connector_params_documents' + - $ref: '#/components/schemas/run_connector_params_level_message' + - title: Subaction parameters + description: Test an action that involves a subaction. + oneOf: + - $ref: '#/components/schemas/run_connector_subaction_addevent' + - $ref: '#/components/schemas/run_connector_subaction_closealert' + - $ref: '#/components/schemas/run_connector_subaction_createalert' + - $ref: '#/components/schemas/run_connector_subaction_fieldsbyissuetype' + - $ref: '#/components/schemas/run_connector_subaction_getchoices' + - $ref: '#/components/schemas/run_connector_subaction_getfields' + - $ref: '#/components/schemas/run_connector_subaction_getincident' + - $ref: '#/components/schemas/run_connector_subaction_issue' + - $ref: '#/components/schemas/run_connector_subaction_issues' + - $ref: '#/components/schemas/run_connector_subaction_issuetypes' + - $ref: '#/components/schemas/run_connector_subaction_pushtoservice' + discriminator: + propertyName: subAction + examples: + runIndexConnectorRequest: + $ref: '#/components/examples/run_index_connector_request' + runJiraConnectorRequest: + $ref: '#/components/examples/run_jira_connector_request' + runServerLogConnectorRequest: + $ref: '#/components/examples/run_server_log_connector_request' + runServiceNowITOMConnectorRequest: + $ref: '#/components/examples/run_servicenow_itom_connector_request' + runSwimlaneConnectorRequest: + $ref: '#/components/examples/run_swimlane_connector_request' + responses: + '200': + description: Indicates a successful call. content: application/json: schema: type: object + required: + - connector_id + - status properties: - error: + connector_id: type: string - example: Unauthorized - message: + description: The identifier for the connector. + data: + oneOf: + - type: object + description: Information returned from the action. + additionalProperties: true + - type: array + description: An array of information returned from the action. + items: + type: object + status: type: string - statusCode: - type: integer - example: 401 + description: The status of the action. + enum: + - error + - ok + examples: + runIndexConnectorResponse: + $ref: '#/components/examples/run_index_connector_response' + runJiraConnectorResponse: + $ref: '#/components/examples/run_jira_connector_response' + runServerLogConnectorResponse: + $ref: '#/components/examples/run_server_log_connector_response' + runServiceNowITOMConnectorResponse: + $ref: '#/components/examples/run_servicenow_itom_connector_response' + runSwimlaneConnectorResponse: + $ref: '#/components/examples/run_swimlane_connector_response' + '401': + description: Authorization information is missing or invalid. + content: + application/json: + schema: + $ref: '#/components/schemas/401_response' servers: - url: https://localhost:5601 servers: @@ -1951,6 +1991,22 @@ components: - $ref: '#/components/schemas/connector_response_properties_xmatters' discriminator: propertyName: connector_type_id + 401_response: + type: object + title: Unsuccessful rule API response + properties: + error: + type: string + example: Unauthorized + enum: + - Unauthorized + message: + type: string + statusCode: + type: integer + example: 401 + enum: + - 401 update_connector_request_cases_webhook: title: Update Webhook - Case Managment connector request type: object @@ -2078,6 +2134,22 @@ components: example: my-connector secrets: $ref: '#/components/schemas/secrets_properties_swimlane' + 404_response: + type: object + properties: + error: + type: string + example: Not Found + enum: + - Not Found + message: + type: string + example: Saved object [action/baf33fc0-920c-11ed-b36a-874bd1548a00] not found + statusCode: + type: integer + example: 404 + enum: + - 404 connector_types: title: Connector types type: string @@ -2110,6 +2182,495 @@ components: - cases - uptime - siem + run_connector_params_documents: + title: Index connector parameters + description: Test an action that indexes a document into Elasticsearch. + type: object + required: + - documents + properties: + documents: + type: array + description: The documents in JSON format for index connectors. + items: + type: object + additionalProperties: true + run_connector_params_level_message: + title: Server log connector parameters + description: Test an action that writes an entry to the Kibana server log. + type: object + required: + - message + properties: + level: + type: string + description: The log level of the message for server log connectors. + enum: + - debug + - error + - fatal + - info + - trace + - warn + default: info + message: + type: string + description: The message for server log connectors. + run_connector_subaction_addevent: + title: The addEvent subaction + type: object + required: + - subAction + description: The `addEvent` subaction for ServiceNow ITOM connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - addEvent + subActionParams: + type: object + description: The set of configuration properties for the action. + properties: + additional_info: + type: string + description: Additional information about the event. + description: + type: string + description: The details about the event. + event_class: + type: string + description: A specific instance of the source. + message_key: + type: string + description: All actions sharing this key are associated with the same ServiceNow alert. The default value is `:`. + metric_name: + type: string + description: The name of the metric. + node: + type: string + description: The host that the event was triggered for. + resource: + type: string + description: The name of the resource. + severity: + type: string + description: The severity of the event. + source: + type: string + description: The name of the event source type. + time_of_event: + type: string + description: The time of the event. + type: + type: string + description: The type of event. + run_connector_subaction_closealert: + title: The closeAlert subaction + type: object + required: + - subAction + - subActionParams + description: The `closeAlert` subaction for Opsgenie connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - closeAlert + subActionParams: + type: object + required: + - alias + properties: + alias: + type: string + description: The unique identifier used for alert deduplication in Opsgenie. The alias must match the value used when creating the alert. + note: + type: string + description: Additional information for the alert. + source: + type: string + description: The display name for the source of the alert. + user: + type: string + description: The display name for the owner. + run_connector_subaction_createalert: + title: The createAlert subaction + type: object + required: + - subAction + - subActionParams + description: The `createAlert` subaction for Opsgenie connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - createAlert + subActionParams: + type: object + required: + - message + properties: + actions: + type: array + description: The custom actions available to the alert. + items: + type: string + alias: + type: string + description: The unique identifier used for alert deduplication in Opsgenie. + description: + type: string + description: A description that provides detailed information about the alert. + details: + type: object + description: The custom properties of the alert. + additionalProperties: true + example: + key1: value1 + key2: value2 + entity: + type: string + description: The domain of the alert. For example, the application or server name. + message: + type: string + description: The alert message. + note: + type: string + description: Additional information for the alert. + priority: + type: string + description: The priority level for the alert. + enum: + - P1 + - P2 + - P3 + - P4 + - P5 + responders: + type: array + description: | + The entities to receive notifications about the alert. If `type` is `user`, either `id` or `username` is required. If `type` is `team`, either `id` or `name` is required. + items: + type: object + properties: + id: + type: string + description: The identifier for the entity. + name: + type: string + description: The name of the entity. + type: + type: string + description: The type of responders, in this case `escalation`. + enum: + - escalation + - schedule + - team + - user + username: + type: string + description: A valid email address for the user. + source: + type: string + description: The display name for the source of the alert. + tags: + type: array + description: The tags for the alert. + items: + type: string + user: + type: string + description: The display name for the owner. + visibleTo: + type: array + description: The teams and users that the alert will be visible to without sending a notification. Only one of `id`, `name`, or `username` is required. + items: + type: object + required: + - type + properties: + id: + type: string + description: The identifier for the entity. + name: + type: string + description: The name of the entity. + type: + type: string + description: Valid values are `team` and `user`. + enum: + - team + - user + username: + type: string + description: The user name. This property is required only when the `type` is `user`. + run_connector_subaction_fieldsbyissuetype: + title: The fieldsByIssueType subaction + type: object + required: + - subAction + - subActionParams + description: The `fieldsByIssueType` subaction for Jira connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - fieldsByIssueType + subActionParams: + type: object + required: + - id + properties: + id: + type: string + description: The Jira issue type identifier. + example: 10024 + run_connector_subaction_getchoices: + title: The getChoices subaction + type: object + required: + - subAction + - subActionParams + description: The `getChoices` subaction for ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - getChoices + subActionParams: + type: object + description: The set of configuration properties for the action. + required: + - fields + properties: + fields: + type: array + description: An array of fields. + items: + type: string + run_connector_subaction_getfields: + title: The getFields subaction + type: object + required: + - subAction + description: The `getFields` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - getFields + run_connector_subaction_getincident: + title: The getIncident subaction + type: object + description: The `getIncident` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors. + required: + - subAction + - subActionParams + properties: + subAction: + type: string + description: The action to test. + enum: + - getIncident + subActionParams: + type: object + required: + - externalId + properties: + externalId: + type: string + description: The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. + example: 71778 + run_connector_subaction_issue: + title: The issue subaction + type: object + required: + - subAction + description: The `issue` subaction for Jira connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - issue + subActionParams: + type: object + required: + - id + properties: + id: + type: string + description: The Jira issue identifier. + example: 71778 + run_connector_subaction_issues: + title: The issues subaction + type: object + required: + - subAction + - subActionParams + description: The `issues` subaction for Jira connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - issues + subActionParams: + type: object + required: + - title + properties: + title: + type: string + description: The title of the Jira issue. + run_connector_subaction_issuetypes: + title: The issueTypes subaction + type: object + required: + - subAction + description: The `issueTypes` subaction for Jira connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - issueTypes + run_connector_subaction_pushtoservice: + title: The pushToService subaction + type: object + required: + - subAction + - subActionParams + description: The `pushToService` subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, and Swimlane connectors. + properties: + subAction: + type: string + description: The action to test. + enum: + - pushToService + subActionParams: + type: object + description: The set of configuration properties for the action. + properties: + comments: + type: array + description: Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, or Swimlane. + items: + type: object + properties: + comment: + type: string + description: A comment related to the incident. For example, describe how to troubleshoot the issue. + commentId: + type: integer + 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. + properties: + alertId: + type: string + description: The alert identifier for Swimlane connectors. + caseId: + type: string + description: The case identifier for the incident for Swimlane connectors. + caseName: + type: string + description: The case name for the incident for Swimlane connectors. + category: + type: string + description: The category of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. + correlation_display: + type: string + description: A descriptive label of the alert for correlation purposes for ServiceNow ITSM and ServiceNow SecOps connectors. + correlation_id: + type: string + description: | + The correlation identifier for the security incident for ServiceNow ITSM and ServiveNow SecOps connectors. Connectors using the same correlation ID are associated with the same ServiceNow incident. This value determines whether a new ServiceNow incident is created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the correlation ID value in ServiceNow. The maximum character length for this value is 100 characters. 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, and Swimlane 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. + oneOf: + - type: string + - type: array + items: + type: string + externalId: + type: string + description: | + The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. If present, the incident is updated. Otherwise, a new incident is created. + impact: + type: string + description: The impact of the incident for ServiceNow ITSM connectors. + issueType: + type: integer + description: The type of incident for Jira connectors. For example, 10006. To obtain the list of valid values, set `subAction` to `issueTypes`. + labels: + type: array + items: + type: string + description: | + The labels for the incident for Jira connectors. NOTE: Labels cannot contain spaces. + malware_hash: + description: A list of malware hashes related to the security incident for ServiceNow SecOps connectors. The hashes are added as observables to the security incident. + oneOf: + - type: string + - type: array + items: + type: string + malware_url: + type: string + description: A list of malware URLs related to the security incident for ServiceNow SecOps connectors. The URLs are added as observables to the security incident. + oneOf: + - type: string + - type: array + items: + type: string + parent: + type: string + description: The ID or key of the parent issue for Jira connectors. Applies only to `Sub-task` types of issues. + priority: + type: string + description: The priority of the incident in Jira and ServiceNow SecOps connectors. + ruleName: + type: string + description: The rule name for Swimlane connectors. + severity: + type: string + description: The severity of the incident for ServiceNow ITSM and Swimlane connectors. + short_description: + type: string + description: | + A short description of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. It is used for searching the contents of the knowledge base. + source_ip: + description: A list of source IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident. + oneOf: + - type: string + - type: array + items: + type: string + subcategory: + type: string + description: The subcategory of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. + summary: + type: string + description: A summary of the incident for Jira connectors. + title: + type: string + description: | + A title for the incident for Jira connectors. It is used for searching the contents of the knowledge base. + urgency: + type: string + description: The urgency of the incident for ServiceNow ITSM connectors. examples: create_index_connector_request: summary: Create an index connector. @@ -2199,6 +2760,146 @@ components: supported_feature_ids: - alerting - uptime + run_index_connector_request: + summary: Run an index connector. + value: + params: + documents: + - id: my_doc_id + name: my_doc_name + message: hello, world + run_jira_connector_request: + summary: Run a Jira connector to retrieve the list of issue types. + value: + params: + subAction: issueTypes + run_server_log_connector_request: + summary: Run a server log connector. + value: + params: + level: warn + message: Test warning message. + run_servicenow_itom_connector_request: + summary: Run a ServiceNow ITOM connector to retrieve the list of choices. + value: + params: + subAction: getChoices + subActionParams: + fields: + - severity + - urgency + run_swimlane_connector_request: + summary: Run a Swimlane connector to create an incident. + value: + params: + subAction: pushToService + subActionParams: + comments: + - commentId: 1 + comment: A comment about the incident. + incident: + caseId: '1000' + caseName: Case name + description: Description of the incident. + run_index_connector_response: + summary: Response from running an index connector. + value: + connector_id: fd38c600-96a5-11ed-bb79-353b74189cba + data: + errors: false + items: + - create: + _id: 4JtvwYUBrcyxt2NnfW3y + _index: my-index + _primary_term: 1 + _seq_no: 0 + _shards: + failed: 0 + successful: 1 + total: 2 + _version: 1 + result: created + status: 201 + took: 135 + status: ok + run_jira_connector_response: + summary: Response from retrieving the list of issue types for a Jira connector. + value: + connector_id: b3aad810-edbe-11ec-82d1-11348ecbf4a6 + data: + - id: 10024 + name: Improvement + - id: 10006 + name: Task + - id: 10007 + name: Sub-task + - id: 10025 + name: New Feature + - id: 10023 + name: Bug + - id: 10000 + name: Epic + status: ok + run_server_log_connector_response: + summary: Response from running a server log connector. + value: + connector_id: 7fc7b9a0-ecc9-11ec-8736-e7d63118c907 + status: ok + run_servicenow_itom_connector_response: + summary: Response from retrieving the list of choices for a ServiceNow ITOM connector. + value: + connector_id: 9d9be270-2fd2-11ed-b0e0-87533c532698 + data: + - dependent_value: '' + element: severity + label: Critical + value: 1 + - dependent_value: '' + element: severity + label: Major + value: 2 + - dependent_value: '' + element: severity + label: Minor + value: 3 + - dependent_value: '' + element: severity + label: Warning + value: 4 + - dependent_value: '' + element: severity + label: OK + value: 5 + - dependent_value: '' + element: severity + label: Clear + value: 0 + - dependent_value: '' + element: urgency + label: 1 - High + value: 1 + - dependent_value: '' + element: urgency + label: 2 - Medium + value: 2 + - dependent_value: '' + element: urgency + label: 3 - Low + value: 3 + status: ok + run_swimlane_connector_response: + summary: Response from creating a Swimlane incident. + value: + connector_id: a4746470-2f94-11ed-b0e0-87533c532698 + data: + id: aKPmBHWzmdRQtx6Mx + title: TEST-457 + url: https://elastic.swimlane.url.us/record/aNcL2xniGHGpa2AHb/aKPmBHWzmdRQtx6Mx + pushedDate: '2022-09-08T16:52:27.866Z' + comments: + - commentId: 1 + pushedDate: '2022-09-08T16:52:27.865Z' + status: ok security: - basicAuth: [] - apiKeyAuth: [] diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_request.yaml new file mode 100644 index 00000000000000..21bb1c9c3f618a --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_request.yaml @@ -0,0 +1,7 @@ +summary: Run an index connector. +value: + params: + documents: + - id: my_doc_id + name: my_doc_name + message: hello, world \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_response.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_response.yaml new file mode 100644 index 00000000000000..0da76e1e1d1b47 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_index_connector_response.yaml @@ -0,0 +1,20 @@ +summary: Response from running an index connector. +value: + connector_id: fd38c600-96a5-11ed-bb79-353b74189cba + data: + errors: false + items: + - create: + _id: 4JtvwYUBrcyxt2NnfW3y + _index: my-index + _primary_term: 1 + _seq_no: 0 + _shards: + failed: 0 + successful: 1 + total: 2 + _version: 1 + result: created + status: 201 + took: 135 + status: ok \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_request.yaml new file mode 100644 index 00000000000000..6dce9b9bbc153f --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_request.yaml @@ -0,0 +1,4 @@ +summary: Run a Jira connector to retrieve the list of issue types. +value: + params: + subAction: issueTypes \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_response.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_response.yaml new file mode 100644 index 00000000000000..ef3b1be138c63d --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_jira_connector_response.yaml @@ -0,0 +1,17 @@ +summary: Response from retrieving the list of issue types for a Jira connector. +value: + connector_id: b3aad810-edbe-11ec-82d1-11348ecbf4a6 + data: + - id: 10024 + name: Improvement + - id: 10006 + name: Task + - id: 10007 + name: Sub-task + - id: 10025 + name: New Feature + - id: 10023 + name: Bug + - id: 10000 + name: Epic + status: ok \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_request.yaml new file mode 100644 index 00000000000000..0a5bf4568dba05 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_request.yaml @@ -0,0 +1,5 @@ +summary: Run a server log connector. +value: + params: + level: warn + message: Test warning message. \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_response.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_response.yaml new file mode 100644 index 00000000000000..604a32b1abd2db --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_server_log_connector_response.yaml @@ -0,0 +1,4 @@ +summary: Response from running a server log connector. +value: + connector_id: 7fc7b9a0-ecc9-11ec-8736-e7d63118c907 + status: ok diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_request.yaml new file mode 100644 index 00000000000000..fb811c96fa1019 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_request.yaml @@ -0,0 +1,8 @@ +summary: Run a ServiceNow ITOM connector to retrieve the list of choices. +value: + params: + subAction: getChoices + subActionParams: + fields: + - severity + - urgency diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_response.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_response.yaml new file mode 100644 index 00000000000000..5bec5b810c90d0 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_servicenow_itom_connector_response.yaml @@ -0,0 +1,41 @@ +summary: Response from retrieving the list of choices for a ServiceNow ITOM connector. +value: + connector_id: 9d9be270-2fd2-11ed-b0e0-87533c532698 + data: + - dependent_value: "" + element: severity + label: Critical + value: 1 + - dependent_value: "" + element: severity + label: Major + value: 2 + - dependent_value: "" + element: severity + label: Minor + value: 3 + - dependent_value: "" + element: severity + label: Warning + value: 4 + - dependent_value: "" + element: severity + label: OK + value: 5 + - dependent_value: "" + element: severity + label: Clear + value: 0 + - dependent_value: "" + element: urgency + label: 1 - High + value: 1 + - dependent_value: "" + element: urgency + label: 2 - Medium + value: 2 + - dependent_value: "" + element: urgency + label: 3 - Low + value: 3 + status: ok diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_request.yaml new file mode 100644 index 00000000000000..7fc1dd27b21313 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_request.yaml @@ -0,0 +1,12 @@ +summary: Run a Swimlane connector to create an incident. +value: + params: + subAction: pushToService + subActionParams: + comments: + - commentId: 1 + comment: A comment about the incident. + incident: + caseId: "1000" + caseName: Case name + description: Description of the incident. \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_response.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_response.yaml new file mode 100644 index 00000000000000..8ab131212020da --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/examples/run_swimlane_connector_response.yaml @@ -0,0 +1,12 @@ +summary: Response from creating a Swimlane incident. +value: + connector_id: a4746470-2f94-11ed-b0e0-87533c532698 + data: + id: aKPmBHWzmdRQtx6Mx + title: TEST-457 + url: https://elastic.swimlane.url.us/record/aNcL2xniGHGpa2AHb/aKPmBHWzmdRQtx6Mx + pushedDate: 2022-09-08T16:52:27.866Z + comments: + - commentId: 1 + pushedDate: 2022-09-08T16:52:27.865Z + status: ok diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/401_response.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/401_response.yaml new file mode 100644 index 00000000000000..c6044998f86499 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/401_response.yaml @@ -0,0 +1,15 @@ +type: object +title: Unsuccessful rule API response +properties: + error: + type: string + example: Unauthorized + enum: + - Unauthorized + message: + type: string + statusCode: + type: integer + example: 401 + enum: + - 401 \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/404_response.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/404_response.yaml new file mode 100644 index 00000000000000..298c50f418a677 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/404_response.yaml @@ -0,0 +1,15 @@ +type: object +properties: + error: + type: string + example: Not Found + enum: + - Not Found + message: + type: string + example: "Saved object [action/baf33fc0-920c-11ed-b36a-874bd1548a00] not found" + statusCode: + type: integer + example: 404 + enum: + - 404 \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_documents.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_documents.yaml new file mode 100644 index 00000000000000..1874c19d17cc63 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_documents.yaml @@ -0,0 +1,13 @@ +title: Index connector parameters +description: Test an action that indexes a document into Elasticsearch. +type: object +required: + - documents +properties: + documents: + type: array + description: The documents in JSON format for index connectors. + items: + type: object + additionalProperties: true + diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_level_message.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_level_message.yaml new file mode 100644 index 00000000000000..cd8db87b0df824 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_params_level_message.yaml @@ -0,0 +1,20 @@ +title: Server log connector parameters +description: Test an action that writes an entry to the Kibana server log. +type: object +required: + - message +properties: + level: + type: string + description: The log level of the message for server log connectors. + enum: + - debug + - error + - fatal + - info + - trace + - warn + default: info + message: + type: string + description: The message for server log connectors. diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_addevent.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_addevent.yaml new file mode 100644 index 00000000000000..c0ae0d4c424f3d --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_addevent.yaml @@ -0,0 +1,49 @@ +title: The addEvent subaction +type: object +required: + - subAction +description: The `addEvent` subaction for ServiceNow ITOM connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - addEvent + subActionParams: + type: object + description: The set of configuration properties for the action. + properties: + additional_info: + type: string + description: Additional information about the event. + description: + type: string + description: The details about the event. + event_class: + type: string + description: A specific instance of the source. + message_key: + type: string + description: All actions sharing this key are associated with the same ServiceNow alert. The default value is `:`. + metric_name: + type: string + description: The name of the metric. + node: + type: string + description: The host that the event was triggered for. + resource: + type: string + description: The name of the resource. + severity: + type: string + description: The severity of the event. + source: + type: string + description: The name of the event source type. + time_of_event: + type: string + description: The time of the event. + type: + type: string + description: The type of event. + \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_closealert.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_closealert.yaml new file mode 100644 index 00000000000000..43436c1564eb18 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_closealert.yaml @@ -0,0 +1,30 @@ +title: The closeAlert subaction +type: object +required: + - subAction + - subActionParams +description: The `closeAlert` subaction for Opsgenie connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - closeAlert + subActionParams: + type: object + required: + - alias + properties: + alias: + type: string + description: The unique identifier used for alert deduplication in Opsgenie. The alias must match the value used when creating the alert. + note: + type: string + description: Additional information for the alert. + source: + type: string + description: The display name for the source of the alert. + user: + type: string + description: The display name for the owner. + \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_createalert.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_createalert.yaml new file mode 100644 index 00000000000000..e739a9ed6c91d6 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_createalert.yaml @@ -0,0 +1,112 @@ +title: The createAlert subaction +type: object +required: + - subAction + - subActionParams +description: The `createAlert` subaction for Opsgenie connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - createAlert + subActionParams: + type: object + required: + - message + properties: + actions: + type: array + description: The custom actions available to the alert. + items: + type: string + alias: + type: string + description: The unique identifier used for alert deduplication in Opsgenie. + description: + type: string + description: A description that provides detailed information about the alert. + details: + type: object + description: The custom properties of the alert. + additionalProperties: true + example: {"key1":"value1","key2":"value2"} + entity: + type: string + description: The domain of the alert. For example, the application or server name. + message: + type: string + description: The alert message. + note: + type: string + description: Additional information for the alert. + priority: + type: string + description: The priority level for the alert. + enum: + - P1 + - P2 + - P3 + - P4 + - P5 + responders: + type: array + description: > + The entities to receive notifications about the alert. + If `type` is `user`, either `id` or `username` is required. + If `type` is `team`, either `id` or `name` is required. + items: + type: object + properties: + id: + type: string + description: The identifier for the entity. + name: + type: string + description: The name of the entity. + type: + type: string + description: The type of responders, in this case `escalation`. + enum: + - escalation + - schedule + - team + - user + username: + type: string + description: A valid email address for the user. + source: + type: string + description: The display name for the source of the alert. + tags: + type: array + description: The tags for the alert. + items: + type: string + user: + type: string + description: The display name for the owner. + visibleTo: + type: array + description: The teams and users that the alert will be visible to without sending a notification. Only one of `id`, `name`, or `username` is required. + items: + type: object + required: + - type + properties: + id: + type: string + description: The identifier for the entity. + name: + type: string + description: The name of the entity. + type: + type: string + description: Valid values are `team` and `user`. + enum: + - team + - user + username: + type: string + description: The user name. This property is required only when the `type` is `user`. + \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_fieldsbyissuetype.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_fieldsbyissuetype.yaml new file mode 100644 index 00000000000000..e8c8869e7d68b0 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_fieldsbyissuetype.yaml @@ -0,0 +1,22 @@ +title: The fieldsByIssueType subaction +type: object +required: + - subAction + - subActionParams +description: The `fieldsByIssueType` subaction for Jira connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - fieldsByIssueType + subActionParams: + type: object + required: + - id + properties: + id: + type: string + description: The Jira issue type identifier. + example: 10024 + \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getchoices.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getchoices.yaml new file mode 100644 index 00000000000000..7bcf2aca3fc712 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getchoices.yaml @@ -0,0 +1,23 @@ +title: The getChoices subaction +type: object +required: + - subAction + - subActionParams +description: The `getChoices` subaction for ServiceNow ITOM, ServiceNow ITSM, and ServiceNow SecOps connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - getChoices + subActionParams: + type: object + description: The set of configuration properties for the action. + required: + - fields + properties: + fields: + type: array + description: An array of fields. + items: + type: string diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getfields.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getfields.yaml new file mode 100644 index 00000000000000..62e80dc53805cf --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getfields.yaml @@ -0,0 +1,11 @@ +title: The getFields subaction +type: object +required: + - subAction +description: The `getFields` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - getFields diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getincident.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getincident.yaml new file mode 100644 index 00000000000000..666c0257f68b86 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_getincident.yaml @@ -0,0 +1,21 @@ +title: The getIncident subaction +type: object +description: The `getIncident` subaction for Jira, ServiceNow ITSM, and ServiceNow SecOps connectors. +required: + - subAction + - subActionParams +properties: + subAction: + type: string + description: The action to test. + enum: + - getIncident + subActionParams: + type: object + required: + - externalId + properties: + externalId: + type: string + description: The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. + example: 71778 diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issue.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issue.yaml new file mode 100644 index 00000000000000..56ee923b40063f --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issue.yaml @@ -0,0 +1,20 @@ +title: The issue subaction +type: object +required: + - subAction +description: The `issue` subaction for Jira connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - issue + subActionParams: + type: object + required: + - id + properties: + id: + type: string + description: The Jira issue identifier. + example: 71778 \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issues.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issues.yaml new file mode 100644 index 00000000000000..bfd5abc388a24e --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issues.yaml @@ -0,0 +1,20 @@ +title: The issues subaction +type: object +required: + - subAction + - subActionParams +description: The `issues` subaction for Jira connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - issues + subActionParams: + type: object + required: + - title + properties: + title: + type: string + description: The title of the Jira issue. \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issuetypes.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issuetypes.yaml new file mode 100644 index 00000000000000..0ea5104ae1890d --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_issuetypes.yaml @@ -0,0 +1,11 @@ +title: The issueTypes subaction +type: object +required: + - subAction +description: The `issueTypes` subaction for Jira connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - issueTypes diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_pushtoservice.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_pushtoservice.yaml new file mode 100644 index 00000000000000..7692a35b2f05fe --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/components/schemas/run_connector_subaction_pushtoservice.yaml @@ -0,0 +1,133 @@ +title: The pushToService subaction +type: object +required: + - subAction + - subActionParams +description: The `pushToService` subaction for Jira, ServiceNow ITSM, ServiceNow SecOps, and Swimlane connectors. +properties: + subAction: + type: string + description: The action to test. + enum: + - pushToService + subActionParams: + type: object + description: The set of configuration properties for the action. + properties: + comments: + type: array + description: Additional information that is sent to Jira, ServiceNow ITSM, ServiceNow SecOps, or Swimlane. + items: + type: object + properties: + comment: + type: string + description: A comment related to the incident. For example, describe how to troubleshoot the issue. + commentId: + type: integer + 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. + properties: + alertId: + type: string + description: The alert identifier for Swimlane connectors. + caseId: + type: string + description: The case identifier for the incident for Swimlane connectors. + caseName: + type: string + description: The case name for the incident for Swimlane connectors. + category: + type: string + description: The category of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. + correlation_display: + type: string + description: A descriptive label of the alert for correlation purposes for ServiceNow ITSM and ServiceNow SecOps connectors. + correlation_id: + type: string + description: > + The correlation identifier for the security incident for ServiceNow ITSM and ServiveNow SecOps connectors. Connectors using the same correlation ID are associated with the same ServiceNow incident. This value determines whether a new ServiceNow incident is created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the correlation ID value in ServiceNow. The maximum character length for this value is 100 characters. + 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, and Swimlane 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. + oneOf: + - type: string + - type: array + items: + type: string + externalId: + type: string + description: > + The Jira, ServiceNow ITSM, or ServiceNow SecOps issue identifier. + If present, the incident is updated. Otherwise, a new incident is created. + impact: + type: string + description: The impact of the incident for ServiceNow ITSM connectors. + issueType: + type: integer + description: The type of incident for Jira connectors. For example, 10006. To obtain the list of valid values, set `subAction` to `issueTypes`. + labels: + type: array + items: + type: string + description: > + The labels for the incident for Jira connectors. + NOTE: Labels cannot contain spaces. + malware_hash: + description: A list of malware hashes related to the security incident for ServiceNow SecOps connectors. The hashes are added as observables to the security incident. + oneOf: + - type: string + - type: array + items: + type: string + malware_url: + type: string + description: A list of malware URLs related to the security incident for ServiceNow SecOps connectors. The URLs are added as observables to the security incident. + oneOf: + - type: string + - type: array + items: + type: string + parent: + type: string + description: The ID or key of the parent issue for Jira connectors. Applies only to `Sub-task` types of issues. + priority: + type: string + description: The priority of the incident in Jira and ServiceNow SecOps connectors. + ruleName: + type: string + description: The rule name for Swimlane connectors. + severity: + type: string + description: The severity of the incident for ServiceNow ITSM and Swimlane connectors. + short_description: + type: string + description: > + A short description of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. It is used for searching the contents of the knowledge base. + source_ip: + description: A list of source IP addresses related to the security incident for ServiceNow SecOps connectors. The IPs are added as observables to the security incident. + oneOf: + - type: string + - type: array + items: + type: string + subcategory: + type: string + description: The subcategory of the incident for ServiceNow ITSM and ServiceNow SecOps connectors. + summary: + type: string + description: A summary of the incident for Jira connectors. + title: + type: string + description: > + A title for the incident for Jira connectors. + It is used for searching the contents of the knowledge base. + urgency: + type: string + description: The urgency of the incident for ServiceNow ITSM connectors. diff --git a/x-pack/plugins/actions/docs/openapi/entrypoint.yaml b/x-pack/plugins/actions/docs/openapi/entrypoint.yaml index 98a50c7304d587..579845aa9f6d81 100644 --- a/x-pack/plugins/actions/docs/openapi/entrypoint.yaml +++ b/x-pack/plugins/actions/docs/openapi/entrypoint.yaml @@ -23,18 +23,17 @@ paths: $ref: paths/s@{spaceid}@api@actions@connectors.yaml '/s/{spaceId}/api/actions/connector_types': $ref: paths/s@{spaceid}@api@actions@connector_types.yaml -# '/s/{spaceId}/api/actions/connector/{connectorId}/_execute': -# $ref: paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml + '/s/{spaceId}/api/actions/connector/{connectorId}/_execute': + $ref: paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml +# Deprecated endpoints: # '/s/{spaceId}/api/actions/action/{actionId}': # $ref: 'paths/s@{spaceid}@api@actions@action@{actionid}.yaml' # '/s/{spaceId}/api/actions': # $ref: 'paths/s@{spaceid}@api@actions.yaml' -# '/s/{spaceId}/api/actions/list_action_types': +# '/s/{spaceId}/api/actions/list_action_types': # $ref: 'paths/s@{spaceid}@api@actions@list_action_types.yaml' # '/s/{spaceId}/api/actions/action': # $ref: 'paths/s@{spaceid}@api@actions@action.yaml' -# '/s/{spaceId}/api/actions/action/{actionId}': -# $ref: 'paths/s@{spaceid}@api@actions@action@{actionid}.yaml' # '/s/{spaceId}/api/actions/action/{actionId}/_execute': # $ref: 'paths/s@{spaceid}@api@actions@action@{actionid}@_execute.yaml' components: diff --git a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector.yaml b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector.yaml index 110f35c650e91f..fafabb5ce30659 100644 --- a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector.yaml +++ b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector.yaml @@ -6,7 +6,7 @@ post: tags: - connectors parameters: - - $ref: ../components/headers/kbn_xsrf.yaml + - $ref: '../components/headers/kbn_xsrf.yaml' - $ref: '../components/parameters/space_id.yaml' requestBody: required: true @@ -53,16 +53,7 @@ post: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '../components/schemas/401_response.yaml' servers: - url: https://localhost:5601 servers: diff --git a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}.yaml b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}.yaml index c1cb7df5aa0f1b..5633dd7b9dcb6f 100644 --- a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}.yaml +++ b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}.yaml @@ -23,16 +23,7 @@ get: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '../components/schemas/401_response.yaml' '404': description: Object is not found. content: @@ -61,7 +52,7 @@ delete: tags: - connectors parameters: - - $ref: ../components/headers/kbn_xsrf.yaml + - $ref: '../components/headers/kbn_xsrf.yaml' - $ref: '../components/parameters/connector_id.yaml' - $ref: '../components/parameters/space_id.yaml' responses: @@ -72,16 +63,7 @@ delete: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '../components/schemas/401_response.yaml' '404': description: Object is not found. content: @@ -109,7 +91,7 @@ put: tags: - connectors parameters: - - $ref: ../components/headers/kbn_xsrf.yaml + - $ref: '../components/headers/kbn_xsrf.yaml' - $ref: '../components/parameters/connector_id.yaml' - $ref: '../components/parameters/space_id.yaml' requestBody: @@ -167,32 +149,13 @@ put: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '../components/schemas/401_response.yaml' '404': description: Object is not found. content: application/json: schema: - type: object - properties: - error: - type: string - example: Not Found - message: - type: string - example: "Saved object [action/baf33fc0-920c-11ed-b36a-874bd1548a00] not found" - statusCode: - type: integer - example: 404 + $ref: '../components/schemas/404_response.yaml' servers: - url: https://localhost:5601 servers: diff --git a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml new file mode 100644 index 00000000000000..713583759a0173 --- /dev/null +++ b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector@{connectorid}@_execute.yaml @@ -0,0 +1,105 @@ +post: + summary: Runs a connector. + operationId: runConnector + description: > + You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems. + You must have `read` privileges for the **Actions and Connectors** feature in the **Management** section of the Kibana feature privileges. + If you use an index connector, you must also have `all`, `create`, `index`, or `write` indices privileges. + tags: + - connectors + parameters: + - $ref: '../components/headers/kbn_xsrf.yaml' + - $ref: '../components/parameters/connector_id.yaml' + - $ref: '../components/parameters/space_id.yaml' + requestBody: + required: true + content: + application/json: + schema: + title: Run connector request body properties + description: The properties vary depending on the connector type. + type: object + required: + - params + properties: + params: + oneOf: + - $ref: '../components/schemas/run_connector_params_documents.yaml' + - $ref: '../components/schemas/run_connector_params_level_message.yaml' + - title: Subaction parameters + description: Test an action that involves a subaction. + oneOf: + - $ref: '../components/schemas/run_connector_subaction_addevent.yaml' + - $ref: '../components/schemas/run_connector_subaction_closealert.yaml' + - $ref: '../components/schemas/run_connector_subaction_createalert.yaml' + - $ref: '../components/schemas/run_connector_subaction_fieldsbyissuetype.yaml' + - $ref: '../components/schemas/run_connector_subaction_getchoices.yaml' + - $ref: '../components/schemas/run_connector_subaction_getfields.yaml' + - $ref: '../components/schemas/run_connector_subaction_getincident.yaml' + - $ref: '../components/schemas/run_connector_subaction_issue.yaml' + - $ref: '../components/schemas/run_connector_subaction_issues.yaml' + - $ref: '../components/schemas/run_connector_subaction_issuetypes.yaml' + - $ref: '../components/schemas/run_connector_subaction_pushtoservice.yaml' + discriminator: + propertyName: subAction + examples: + runIndexConnectorRequest: + $ref: '../components/examples/run_index_connector_request.yaml' + runJiraConnectorRequest: + $ref: '../components/examples/run_jira_connector_request.yaml' + runServerLogConnectorRequest: + $ref: '../components/examples/run_server_log_connector_request.yaml' + runServiceNowITOMConnectorRequest: + $ref: '../components/examples/run_servicenow_itom_connector_request.yaml' + runSwimlaneConnectorRequest: + $ref: '../components/examples/run_swimlane_connector_request.yaml' + responses: + '200': + description: Indicates a successful call. + content: + application/json: + schema: + type: object + required: + - connector_id + - status + properties: + connector_id: + type: string + description: The identifier for the connector. + data: + oneOf: + - type: object + description: Information returned from the action. + additionalProperties: true + - type: array + description: An array of information returned from the action. + items: + type: object + status: + type: string + description: The status of the action. + enum: + - error + - ok + examples: + runIndexConnectorResponse: + $ref: '../components/examples/run_index_connector_response.yaml' + runJiraConnectorResponse: + $ref: '../components/examples/run_jira_connector_response.yaml' + runServerLogConnectorResponse: + $ref: '../components/examples/run_server_log_connector_response.yaml' + runServiceNowITOMConnectorResponse: + $ref: '../components/examples/run_servicenow_itom_connector_response.yaml' + runSwimlaneConnectorResponse: + $ref: '../components/examples/run_swimlane_connector_response.yaml' + '401': + description: Authorization information is missing or invalid. + content: + application/json: + schema: + $ref: '../components/schemas/401_response.yaml' + servers: + - url: https://localhost:5601 +servers: + - url: https://localhost:5601 diff --git a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector_types.yaml b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector_types.yaml index 001da54c13c14a..72dcd256605330 100644 --- a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector_types.yaml +++ b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connector_types.yaml @@ -63,16 +63,7 @@ get: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '../components/schemas/401_response.yaml' servers: - url: https://localhost:5601 servers: diff --git a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connectors.yaml b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connectors.yaml index 2a0a075703f8a8..afa2c05abdb621 100644 --- a/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connectors.yaml +++ b/x-pack/plugins/actions/docs/openapi/paths/s@{spaceid}@api@actions@connectors.yaml @@ -60,16 +60,7 @@ get: content: application/json: schema: - type: object - properties: - error: - type: string - example: Unauthorized - message: - type: string - statusCode: - type: integer - example: 401 + $ref: '../components/schemas/401_response.yaml' servers: - url: https://localhost:5601 servers: