Kibana Security Detections API API

openapi: 3.0.3
info:
  contact:
    name: Kibana Team
  description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.

    The API calls are stateless.

    Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the

    request.

    API requests return JSON output, which is a format that is machine-readable and works well for automation.


    To interact with Kibana APIs, use the following operations:


    - GET: Fetches the information.

    - PATCH: Applies partial modifications to the existing information.

    - POST: Adds new information.

    - PUT: Updates the existing information.

    - DELETE: Removes the information.


    You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.

    For example:


    ```

    GET kbn:/api/data_views

    ```


    For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).


    NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.


    ## Documentation source and versions


    This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.

    It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).


    This documentation contains work-in-progress information for future Elastic Stack releases.

    '
  title: Kibana APIs Actions Security Detections API API
  version: ''
  x-doc-license:
    name: Attribution-NonCommercial-NoDerivatives 4.0 International
    url: https://creativecommons.org/licenses/by-nc-nd/4.0/
  x-feedbackLink:
    label: Feedback
    url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
  variables:
    kibana_url:
      default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- description: 'Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the **Alerts** page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged.


    This API supports both key-based authentication and basic authentication.


    To use key-based authentication, create an API key, then specify the key in the header of your API calls.


    To use basic authentication, provide a username and password; this automatically creates an API key that matches the current user’s privileges.


    In both cases, the API key is subsequently used for authorization when the rule runs.

    > warn

    > If the API key used for authorization has different privileges than the key that created or most recently updated a rule, the rule behavior might change.


    > If the API key that created a rule is deleted, or the user that created the rule becomes inactive, the rule will stop running.


    To create and run rules, the user must meet specific requirements for the Kibana space. Refer to the [Detections requirements](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html) for a complete list of requirements.

    '
  name: Security Detections API
  x-displayName: Security detections
paths:
  /api/detection_engine/index:
    delete:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb delete">delete</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/index</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Permanently deletes the Elastic Security alerts backing index in the current space, including the alerts

        stored in it. Use with caution; prefer lifecycle policies or the UI when available.

        Call `GET /api/detection_engine/index` first to confirm the index that will be removed.

        '
      operationId: DeleteAlertsIndex
      responses:
        '200':
          content:
            application/json:
              examples:
                acknowledged:
                  value:
                    acknowledged: true
              schema:
                type: object
                properties:
                  acknowledged:
                    type: boolean
                required:
                - acknowledged
          description: Successful response
        '401':
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    error: Unauthorized
                    message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
                    statusCode: 401
              schema:
                $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
          description: Unsuccessful authentication response
        '403':
          content:
            application/json:
              examples:
                forbidden:
                  value:
                    message: API [DELETE /api/detection_engine/index] is unauthorized for the current user. The user needs alerts management permissions for the space.
                    status_code: 403
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Not enough permissions response
        '404':
          content:
            application/json:
              examples:
                notFound:
                  value:
                    message: The Elastic Security alerts index to delete was not found.
                    status_code: 404
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Index does not exist response
        '500':
          content:
            application/json:
              examples:
                serverError:
                  value:
                    message: Internal Server Error
                    status_code: 500
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Internal server error response
      summary: Delete an alerts index
      tags:
      - Security Detections API
      x-metaTags:
      - content: Kibana
        name: product_name
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/index</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Returns the backing Elasticsearch index for Elastic Security detection alerts in the current space, and

        whether its mapping is outdated. Use this to verify that an alert index is provisioned before creating

        or running rules that write alerts to it.

        '
      operationId: ReadAlertsIndex
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  value:
                    index_mapping_outdated: false
                    name: .alerts-security.alerts-default
              schema:
                type: object
                properties:
                  index_mapping_outdated:
                    nullable: true
                    type: boolean
                  name:
                    type: string
                required:
                - name
                - index_mapping_outdated
          description: Successful response
        '401':
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    error: Unauthorized
                    message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
                    statusCode: 401
              schema:
                $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
          description: Unsuccessful authentication response
        '403':
          content:
            application/json:
              examples:
                forbidden:
                  value:
                    message: API [GET /api/detection_engine/index] is unauthorized for the current user. Check Security and Kibana feature privileges (detection engine / alerts) for the space.
                    status_code: 403
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Not enough permissions response
        '404':
          content:
            application/json:
              examples:
                notFound:
                  value:
                    message: Elastic Security alert index is not found for the current space.
                    status_code: 404
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Not found
        '500':
          content:
            application/json:
              examples:
                serverError:
                  value:
                    message: Internal Server Error
                    status_code: 500
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Internal server error response
      summary: Reads the alert index name if it exists
      tags:
      - Security Detections API
      x-metaTags:
      - content: Kibana
        name: product_name
    post:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/index</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Creates an index for Elastic Security alerts. Calling this API is not

        required for the detection engine to function properly. You can create

        rules and alerts without calling this API.

        '
      operationId: CreateAlertsIndex
      responses:
        '200':
          content:
            application/json:
              examples:
                acknowledged:
                  value:
                    acknowledged: true
              schema:
                type: object
                properties:
                  acknowledged:
                    type: boolean
                required:
                - acknowledged
          description: Successful response
        '401':
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    error: Unauthorized
                    message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
                    statusCode: 401
              schema:
                $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
          description: Unsuccessful authentication response
        '403':
          content:
            application/json:
              examples:
                forbidden:
                  value:
                    message: API [POST /api/detection_engine/index] is unauthorized for the current user. The user must be able to create indices for the Elastic Security solution.
                    status_code: 403
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Not enough permissions response
        '404':
          content:
            application/json:
              examples:
                notFound:
                  value:
                    message: A prerequisite resource required to create the alerts index was not found.
                    status_code: 404
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Not found
        '500':
          content:
            application/json:
              examples:
                serverError:
                  value:
                    message: Internal Server Error
                    status_code: 500
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Internal server error response
      summary: Create an alerts index
      tags:
      - Security Detections API
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/detection_engine/privileges:
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/privileges</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Retrieves whether or not the user is authenticated, and the user''s Kibana

        space and index privileges, which determine if the user can create an

        index for the Elastic Security alerts generated by

        detection engine rules.

        '
      operationId: ReadPrivileges
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  value:
                    application: {}
                    cluster:
                      all: true
                      manage: true
                      manage_api_key: true
                      manage_index_templates: true
                      manage_ml: true
                      manage_own_api_key: true
                      manage_pipeline: true
                      manage_security: true
                      manage_transform: true
                      monitor: true
                      monitor_ml: true
                      monitor_transform: true
                    has_all_requested: true
                    has_encryption_key: true
                    index:
                      .alerts-security.alerts-default:
                        all: true
                        create: true
                        create_doc: true
                        create_index: true
                        delete: true
                        delete_index: true
                        index: true
                        maintenance: true
                        manage: true
                        monitor: true
                        read: true
                        view_index_metadata: true
                        write: true
                    is_authenticated: true
                    username: elastic
              schema:
                type: object
                properties:
                  has_encryption_key:
                    type: boolean
                  is_authenticated:
                    type: boolean
                required:
                - is_authenticated
                - has_encryption_key
          description: Successful response
        '401':
          content:
            application/json:
              examples:
                unauthorized:
                  value:
                    error: Unauthorized
                    message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]"
                    statusCode: 401
              schema:
                $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
          description: Unsuccessful authentication response
        '500':
          content:
            application/json:
              examples:
                serverError:
                  value:
                    message: Internal Server Error
                    status_code: 500
              schema:
                $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
          description: Internal server error response
      summary: Returns user privileges for the Kibana space
      tags:
      - Security Detections API
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/detection_engine/rules:
    delete:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb delete">delete</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/rules</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Delete a detection rule using the `rule_id` or `id` field.


        The URL query must include one of the following:


        * `id` - `DELETE /api/detection_engine/rules?id=<id>`

        * `rule_id`- `DELETE /api/detection_engine/rules?rule_id=<rule_id>`


        The difference between the `id` and `rule_id` is that the `id` is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas `rule_id` is a stable rule identifier that can be assigned during rule creation.

        '
      operationId: DeleteRule
      parameters:
      - description: The rule's `id` value.
        in: query
        name: id
        required: false
        schema:
          $ref: '#/components/schemas/Security_Detections_API_UUID'
      - description: The rule's `rule_id` value.
        in: query
        name: rule_id
        required: false
        schema:
          $ref: '#/components/schemas/Security_Detections_API_RuleSignatureId'
      responses:
        '200':
          content:
            application/json:
              examples:
                deletedRule:
                  summary: Response shape after a rule is deleted
                  value:
                    actions: []
                    created_at: '2020-02-03T11:19:04.259Z'
                    created_by: elastic
                    description: Process started by MS Office program in user folder
                    enabled: false
                    false_positives: []
                    from: now-4200s
                    id: c41d170b-8ba6-4de6-b8ec-76440a35ace3
                    immutable: false
                    interval: 1h
                    language: kuery
                    max_signals: 100
                    name: MS Office child process
                    query: event.action:Process*
                    references: []
                    risk_score: 50
                    rule_id: process_started_by_ms_office_user_folder
                    severity: low
                    tags:
                    - tag
                    throttle: null
                    to: now
                    type: query
                    updated_at: '2020-02-03T11:19:04.462Z'
                    updated_by: elastic
                    version: 3
              schema:
                $ref: '#/components/schemas/Security_Detections_API_RuleResponse'
          description: Indicates a successful call.
      summary: Delete a detection rule
      tags:
      - Security Detections API
      x-codeSamples:
      - lang: cURL
        source: "curl \\\n  --request DELETE https://localhost:5601/api/detection_engine/rules?rule_id=bfeaf89b-a2a7-48a3-817f-e41829dc61ee \\\n  --header \"Content-Type: application/json; Elastic-Api-Version=2023-10-31\"\n"
      x-metaTags:
      - content: Kibana
        name: product_name
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/rules</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Retrieve a detection rule using the `rule_id` or `id` field.


        The URL query must include one of the following:


        * `id` - `GET /api/detection_engine/rules?id=<id>`

        * `rule_id` - `GET /api/detection_engine/rules?rule_id=<rule_id>`


        The difference between the `id` and `rule_id` is that the `id` is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas `rule_id` is a stable rule identifier that can be assigned during rule creation.

        '
      operationId: ReadRule
      parameters:
      - description: The rule's `id` value.
        in: query
        name: id
        required: false
        schema:
          $ref: '#/components/schemas/Security_Detections_API_UUID'
      - description: The rule's `rule_id` value.
        in: query
        name: rule_id
        required: false
        schema:
          $ref: '#/components/schemas/Security_Detections_API_RuleSignatureId'
      responses:
        '200':
          content:
            application/json:
              examples:
                example1:
                  summary: Example response for a retrieved rule
                  value:
                    created_at: '2020-02-03T11:19:04.259Z'
                    created_by: elastic
                    description: Process started by MS Office program in user folder
                    enabled: false
                    execution_summary:
                      last_execution:
                        date: '2022-03-23T16:06:12.787Z'
                        message: This rule attempted to query data from Elasticsearch indices listed in the "Index pattern" section of the rule definition, but no matching index was found.
                        metrics:
                          execution_gap_duration_s: 0
                          total_indexing_duration_ms: 15
                          total_search_duration_ms: 135
                        status: partial failure
                        status_order: 20
                    false_positives: []
                    filters:
                    - query:
                        match:
                          event.action:
                            query: 'Process Create (rule: ProcessCreate)'
                            type: phrase
                    from: now-4200s
                    id: c41d170b-8ba6-4de6-b8ec-76440a35ace3
                    immutable: false
                    interval: 1h
                    language: kuery
                    max_signals: 100
                    name: MS Office child process
                    query: process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE
                    references: []
                    related_integrations:
                    - package: o365
                      version: ^2.3.2
                    required_fields:
                    - ecs: true
                      name: process.name
                      type: keyword
                    - ecs: true
                      name: process.parent.name
                      type: keyword
                    risk_score: 21
                    rule_id: process_started_by_ms_office_user_folder
                    setup: ''
                    severity: low
                    tags:
                    - child process
                    - ms office
                    threat:
                    - framework: MITRE ATT&CK
                      tactic:
                        id: TA0001
                        name: Initial Access
                        reference: https://attack.mitre.org/tactics/TA0001
                      technique:
                      - id: T1193
                        name: Spearphishing Attachment
                        reference: https://attack.mitre.org/techniques/T1193
                    to: now-300s
                    type: query
                    updated_at: '2020-02-03T11:19:04.462Z'
                    updated_by: elastic
                    version: 1
              schema:
                $ref: '#/components/schemas/Security_Detections_API_RuleResponse'
          description: 'Indicates a successful call.

            > info

            > These fields are under development and their usage or schema may change: execution_summary.

            '
      summary: Retrieve a detection rule
      tags:
      - Security Detections API
      x-codeSamples:
      - lang: cURL
        source: "curl \\\n  --request GET https://localhost:5601/api/detection_engine/rules?rule_id=bfeaf89b-a2a7-48a3-817f-e41829dc61ee \\\n  --header \"Content-Type: application/json; Elastic-Api-Version=2023-10-31\"\n"
      x-metaTags:
      - content: Kibana
        name: product_name
    patch:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb patch">patch</span>&nbsp;<span class="operation-path">/s/{space_id}/api/detection_engine/rules</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Update specific fields of an existing detection rule using the `rule_id` or `id` field.


        The difference between the `id` and `rule_id` is that the `id` is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas `rule_id` is a stable rule identifier that can be assigned during rule creation.

        > warn

        > When used with [API key](https://www.elastic.co/docs/deploy-manage/api-keys) authentication, the user''s key gets assigned to the affected rules. If the user''s key gets deleted or the user becomes inactive, the rules will stop running.


        > If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.

        '
      operationId: PatchRule
      requestBody:
        content:
          application/json:
            examples:
              example1:
                summary: Patch query rule
                value:
                  id: 14b7b513-3d8d-4b22-b7da-a7ae632f7e76
                  name: New name
              example2:
                summary: Patch EQL rule
                value:
                  rule_id: process_started_by_ms_office_program_possible_payload
                  threat:
                  - framework: MITRE ATT&CK
                    tactic:
                      id: TA0001
                      name: Initial Access
                      reference: https://attack.mitre.org/tactics/TA0001
                    technique:
                    - id: T1193
                      name: Spearphishing Attachment
                      reference: https://attack.mitre.org/techniques/T1193
              example3:
                summary: Patch threshold rule
                value:
                  id: 005d2c4f-51ca-493d-a2bd-20ef076339b1
                  query: 'agent.version : * and agent.id : "243d9b4f-ca01-4311-8e5c-9abbee91afd8"'
                  threshold:
                    cardinality: []
                    field: []
                    value: 600
              example4:
                summary: Patch new terms rule
                value:
                  history_window_start: now-3d
                  id: 569aac91-40dc-4807-a8ae-a2c8698089c4
                  new_terms_fields:
                  - Endpoint.policy.applied.artifacts.global.identifiers.name
              example5:
                summary: Patch esql rule
                value:
                  id: 0b15e8a2-49b6-47e0-a8e6-d63a6cc335bd
                  query: "FROM logs-abc*\n| STATS count = COUNT(*), min_timestamp = MIN(@timestamp)\n| EVAL event_rate = count / DATE_DIFF(\"seconds\", min_timestamp, NOW()) \n| KEEP event_rate\n"
              example6:
                summary: Patch indicator match rule
                value:
                  id: 462f1986-10fe-40a3-a22c-2b1c9c4c48fd
                  threat_query: '@timestamp >= "now-30d/d" and event.module:(threatintel or ti_*) and threat.indicator.ip:* and not labels.is_ioc_transform_source:"false"'
              example7:
                summary: Patch machine learning rule
                value:
                  anomaly_threshold: 50
                  id: 60b13926-289b-41b1-a537-197ef1fa5059
                  machine_learning_job_id:
                  - auth_high_count_logon_events_ea
            schema:
              $ref: '#/components/schemas/Security_Detections_API_RulePatchProps'
        description: '> info

          > You cannot modify the `id` or `rule_id` values.

          '
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                example1:
                  summary: Example response for an updated rule
                  value:
                    actions: []
                    created_at: '2020-04-07T14:51:09.755Z'
                    created_by: elastic
                    description: Updated description for the rule.
                    enabled: false
                    false_positives: []
                    filters:
                    - query: null
                    from: now-70m
                    id: 6541b99a-dee9-4f6d-a86d-dbd1869d73b1
                    immutable: false
                    interval: 1h
                    language: kuery
                    max_signals: 100
                    name: Updated Rule Name
                    query: process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE
                    references: []
                    related_integrations:
                    - package: o365
                    required_fields:
                    - name: process.parent.name
                    risk_score: 50
                    rule_id: process_started_by_ms_office_program
                    setup: ''
                    severity: low
                    tags:
                    - child process
                    - ms office
                    threat: []
                    to: now
                    type: query
                    updated_at: '2020-04-07T14:51:09.970Z'
                    updated_by: elastic
                    version: 2
              schema:
                $ref: '#/components/schemas/Security_Detections_API_RuleResponse'
          description: Indicates a successful call.
      summary: Patch a detection rule
      tags:
      - Security Detections API
      x-metaTags:
      - content: Kibana
        name: product_name
    post:
      description: "**Spaces method and path for this operation:**\n\n<div><span class=\"operation-verb post\">post</span>&nbsp;<span class=\"operation-path\">/s/{space_id}/api/detection_engine/rules</span></div>\n\nRefer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.\n\nCreate a new detection rule.\n> warn\n> When used with [API key](https://www.elastic.co/docs/deploy-manage/api-keys) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.\n\n> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.\n\nYou can create the following types of rules:\n\n* **Custom query**: Searches the defined indices and creates an alert when a document matches the rule's KQL query.\n* **Event correlation**: Searches the defined indices and creates an alert when results match an [

# --- truncated at 32 KB (467 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-security-detections-api-api-openapi.yml