Set default Elastic Security UI connector

edit

Set default Elastic Security UI connector

edit

Sets the default connector in the Elastic Security UI.

Console supports only Elasticsearch APIs. Console doesn’t allow interactions with Kibana APIs. You must use curl or another HTTP tool instead. For more information, refer to Run Elasticsearch API requests.

Connectors are used to interface with external systems. You can only call this method after you have created a connector (see Create connector). After a connector has been created and assigned, call Create or update an external incident to send cases to the external system.

You can also set the default connector in the Elastic Security UI for each case individually (see Update case).

Request URL

edit

POST <kibana host>:<port>/api/cases/configure

Request body

edit

A JSON object with these fields:

Name Type Description Required

connector

connector

Object containing the connector’s configuration.

Yes

closure_type

String

Determines whether a case is automatically closed in Elastic Security when it is pushed to external systems. Valid values are:

  • close-by-pushing: Elastic Security cases are automatically closed when they are pushed.
  • close-by-user: Elastic Security cases are not automatically closed.

Yes

connector schema

Name Type Description Required

id

String

The ID of the connector you want to use for sending cases to external systems.

Yes

name

String

The connector name.

Yes

type

String

The type of the connector.

Must be one of these:

  • .servicenow
  • .servicenow-sir
  • .jira
  • .resilient
  • .swimlane
  • .none

Yes

fields

Object

Object containing the connector’s fields.

For Jira connectors:

  • urgency (string | null): The urgency of the incident.
  • severity (string | null): The severity of the incident.
  • impact (string | null): The impact of the incident.
  • category (string | null): The category of the incident.
  • subcategory (string | null): The subcategory of the incident.

For ServiceNow SecOps connectors:

  • destIp (string | null): A comma separated list of destination IPs.
  • malwareHash (string | null): A comma separated list of malware hashes.
  • malwareUrl (string | null): A comma separated list of malware URLs.
  • sourceIp (string | null): A comma separated list of source IPs.
  • priority (string | null): The priority of the incident.
  • category (string | null): The category of the incident.
  • subcategory (string | null): The subcategory of the incident.

For Jira connectors:

  • issueType (string): The issue type of the issue.
  • priority (string | null): The priority of the issue.
  • parent (string | null): The key of the parent issue (Valid when the issue type is Sub-task).

For IBM Resilient connectors:

  • issueTypes (number[]): The issue types of the issue.
  • severityCode (number): The severity code of the issue.

For Swimlane connectors:

  • caseId (string | null): The case ID.

Yes

Call Find connectors to retrieve connector IDs and names.

Fields can be set but are not being used by case configuration. You can set the fields of the connector at Create case.

Example request

edit
POST api/cases/configure
{
  "connector": {
    "id": "131d4448-abe0-4789-939d-8ef60680b498",
    "name": "Jira",
    "type": ".jira",
    "fields": null,
  },
  "closure_type": "close-by-user",
  "owner": "securitySolution",
}

Response code

edit
200
Indicates a successful call.

Example response

edit
{
  "connector": {
    "id": "131d4448-abe0-4789-939d-8ef60680b498",
    "name": "Jira",
    "type": ".jira",
    "fields": null,
  },
  "closure_type": "close-by-user",
  "created_at": "2020-03-30T13:31:38.083Z",
  "created_by": {
    "email": "moneypenny@hms.gov.uk",
    "full_name": "Ms Moneypenny",
    "username": "moneypenny"
  },
  "error": null,
  "id": "7349772f-421a-4de3-b8bb-2d9b22ccee30",
  "mappings":[
    {
      "source":"title", 
      "target":"summary",
      "action_type": "overwrite"
    },
    {
      "source":"description", 
      "target":"description",
      "action_type": "overwrite"
    },
    {
      "source":"comments", 
      "target":"comments",
      "action_type":"append"
    }
  ],
  "owner": "securitySolution",
  "updated_at": null,
  "updated_by": null,
  "version": "WzE3NywxXQ=="
}

Elastic Security case title fields are mapped to Jira summary fields. When a Elastic Security title field is updated and sent to Jira, the Jira summary field is overwritten.

Elastic Security case description fields are mapped to Jira description fields. When a Elastic Security description field is updated and sent to Jira, the Jira description field is overwritten.

Elastic Security case comments fields are mapped to Jira comments fields. When a Elastic Security comments field is updated and sent to Jira, the updated text is appended to the Jira comments field.