Elastic Security APIs OpenAPI Spec

elastic_security_openapi_spec.yaml

openapi: 3.0.0
info:
  title: Elastic Security SIEM Signals API (https://www.elastic.co/guide/en/security/current/security-apis.html)
  version: 1.0.0
servers:
  - url: 'http://{kibana_host}:{port}'
paths:
  /api/detection_engine/index:
    summary: Signal index operations (used to store detection alerts)
    post:
      summary: Create index
      description: Creates a signal index with the naming convention `.siem-signals-<space name>`.
      responses:
        200:
          description: Indicates a successful call.
    get:
      summary: Get index
      description: Gets the signal index name if it exists.
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
        404:
          description: Indicates no index exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
    delete:
      summary: Delete index
      description: Deletes the signal index.
      responses:
        200:
          description: Indicates a successful call.
  /api/detection_engine/privileges:
    summary: Returns the user's Kibana space and signal index permissions, and whether the user is authenticated
    get:
      summary: Get privileges
      description: Returns user privileges for the {kib} space.
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                  has_all_requested:
                    type: boolean
                  cluster:
                    type: object
                    additionalProperties:
                      type: boolean
                  index:
                    type: object
                    additionalProperties:
                      type: object
                      additionalProperties:
                        type: boolean
                  application:
                    type: object
                  is_authenticated:
                    type: boolean
                  has_encryption_key:
                    type: boolean
  /api/detection_engine/rules:
    summary: Detection rules CRUD functions
    get:
      summary: Get rule
      description: Retrieves a single rule using the `rule_id` or `id` field.
      parameters:
        - name: id
          in: query
          required: false
          description: Retrieves the rule with a specific `id`.
          schema:
            type: string
        - name: rule_id
          in: query
          required: false
          description: Retrieves the rule with a specific `rule_id`.
          schema:
            type: string
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: object
    delete:
        summary: Delete rule
        description: Deletes a single rule using the `rule_id` or `id` field.
        parameters:
          - name: id
            in: query
            required: false
            description: The rule's `id` value.
            schema:
              type: string
          - name: rule_id
            in: query
            required: false
            description: The rule's `rule_id` value.
            schema:
              type: string
        responses:
          200:
            description: Indicates a successful call.
    put:
      summary: Update Rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Rule ID
                name:
                  type: string
                  description: Rule name
                description:
                  type: string
                  description: Rule description
                risk_score:
                  type: integer
                  description: Risk score (0 to 100)
                severity:
                  type: string
                  enum: [low, medium, high, critical]
                  description: Severity of the rule
                type:
                  type: string
                  enum: [query, threshold, eql, threat_match, saved_query, machine_learning]
                  description: Rule type
                query:
                  type: string
                  description: Query to execute (only required for 'query' and 'threshold' rule types)
                eql_query:
                  type: string
                  description: EQL query to execute (only required for 'eql' rule type)
                saved_id:
                  type: string
                  description: Saved object ID (only required for 'saved_query' rule type)
                machine_learning_job_id:
                  type: string
                  description: Machine learning job ID (only required for 'machine_learning' rule type)
                threat_query:
                  type: string
                  description: Threat query to execute (only required for 'threat_match' rule type)
                threshold:
                  type: object
                  properties:
                    field:
                      type: string
                      description: Field to aggregate on (only required for 'threshold' rule type)
                    value:
                      type: integer
                      description: Threshold value (only required for 'threshold' rule type)
                timeline_id:
                  type: string
                  description: Timeline template ID (optional)
                timeline_title:
                  type: string
                  description: Timeline template title (optional)
                actions:
                  type: array
                  items:
                    type: object
                    properties:
                      action_type_id:
                        type: string
                        description: The action type used for sending notifications
                      group:
                        type: string
                        description: Optionally groups actions by use cases
                      id:
                        type: string
                        description: The connector ID
                      params:
                        type: object
                        description: Object containing the allowed connector fields
                threats:
                  type: array
                  items:
                    type: object
                    properties:
                      framework:
                        type: string
                        description: Relevant attack framework
                      tactic:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          reference:
                            type: string
                      technique:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          reference:
                            type: string
                exceptions_list:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: ID of the exception container
                      list_id:
                        type: string
                        description: List ID of the exception container
                      namespace_type:
                        type: string
                        description: Determines the exceptions validity in rule's Kibana space
                      type:
                        type: string
                        description: The exception type
                threat_filters:
                  type: array
                  items:
                    type: object
                    description: Query and filter context array used to filter documents from the Elasticsearch index containing the threat values (only required for 'threat_match' rule type)
            threat_indicator_path:
              type: string
              description: Defines the path to the threat indicator in the indicator documents (optional)
            language:
              type: string
              enum: [kuery, lucene]
              description: Determines the query language (optional)
            filters:
              type: array
              items:
                type: object
              description: The query and filter context array used to define the conditions for when alerts are created from events (optional)
            index:
              type: array
              items:
                type: string
              description: Indices on which the rule functions (optional)
            risk_score_mapping:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  operator:
                    type: string
                  value:
                    type: string
              description: Overrides generated alerts' risk_score with a value from the source event
            rule_name_override:
              type: string
              description: Sets the source field for the alert's signal.rule.name value
            severity_mapping:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  operator:
                    type: string
                  severity:
                    type: string
                  value:
                    type: string
              description: Overrides generated alerts' severity with values from the source event
            timestamp_override:
              type: string
              description: Sets the time field used to query indices (optional)
            event_category_field:
              type: string
              description: Contains the event classification (optional, only for EQL rules)
            tiebreaker_field:
              type: string
              description: Sets a secondary field for sorting events (optional, only for EQL rules)
            timestamp_field:
              type: string
              description: Contains the event timestamp used for sorting a sequence of events (optional, only for EQL rules)
      responses:
        200:
          description: Rule updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Rule updated successfully
        400:
          description: Bad request (e.g. missing required fields, invalid data)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Error: Invalid request data"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Error: Internal server error"
  /api/detection_engine/rules/_export:
    summary: Exports rules to an `.ndjson` file
    post:
      summary: Export rules
      description: Exports rules to an `.ndjson` file. The following configuration items are also included in the `.ndjson` file - Actions, Exception lists. Prebuilt rules cannot be exported.
      parameters:
        - name: exclude_export_details
          in: query
          required: false
          description: Determines whether a summary of the exported rules is returned.
          schema:
            type: boolean
            default: false
        - name: file_name
          in: query
          required: false
          description: File name for saving the exported rules.
          schema:
            type: string
            default: export.ndjson
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                objects:
                  type: array
                  items:
                    type: object
                    properties:
                      rule_id:
                        type: string
                  description: Array of `rule_id` fields. Exports all rules when unspecified.
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: string
                format: binary
                description: An `.ndjson` file containing the returned rules.
  /api/detection_engine/rules/_find:
    get:
      summary: Find rules
      description: Retrieves a paginated subset of detection rules. By default, the first page is returned with 20 results per page.
      parameters:
        - name: page
          in: query
          required: false
          description: The page number to return.
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: The number of rules to return per page.
          schema:
            type: integer
        - name: sort_field
          in: query
          required: false
          description: Determines which field is used to sort the results.
          schema:
            type: string
        - name: sort_order
          in: query
          required: false
          description: Determines the sort order, which can be `desc` or `asc`.
          schema:
            type: string
        - name: filter
          in: query
          required: false
          description: Filters the returned results according to the value of the specified field, using the `alert.attributes.<field name>:<field value>` syntax.
          schema:
            type: string
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                  perPage:
                    type: integer
                  total:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
  /api/detection_engine/rules/_import:
    summary: Imports rules from an `.ndjson` file
    post:
      summary: Import rules
      description: Imports rules from an `.ndjson` file, including actions and exception lists.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The `.ndjson` file containing the rules.
      parameters:
        - name: overwrite
          in: query
          required: false
          description: Determines whether existing rules with the same `rule_id` are overwritten.
          schema:
            type: boolean
            default: false
        - name: overwrite_exceptions
          in: query
          required: false
          description: Determines whether existing exception lists with the same `list_id` are overwritten.
          schema:
            type: boolean
            default: false
        - name: overwrite_action_connectors
          in: query
          required: false
          description: Determines whether existing actions with the same `kibana.alert.rule.actions.id` are overwritten.
          schema:
            type: boolean
            default: false
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: object
  /api/detection_engine/tags:
    summary: Aggregates and returns rule tags
    get:
      summary: Aggregates and returns all unique tags from all rules
      responses:
        200:
          description: Indicates a successful call
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /api/detection_engine/signals:
    summary: Aggregates, queries, and returns alerts, and updates their statuses
  /api/detection_engine/signals/search:
    post:
      summary: Aggregates and returns alerts
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        200:
          description: Indicates a successful call
          content:
            application/json:
              schema:
                type: object
  /api/detection_engine/signals/status:
    post:
      summary: Sets the status of one or more alerts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                signal_ids:
                  type: array
                  items:
                    type: string
                query:
                  type: object
                status:
                  type: string
              oneOf:
                - required: ['signal_ids', 'status']
                - required: ['query', 'status']
      responses:
        200:
          description: Indicates a successful call
          content:
            application/json:
              schema:
                type: object
  /api/detection_engine/rules/prepackaged:
    summary: Loads and retrieves the status of Elastic prebuilt rules
    put:
      summary: Loads and updates Elastic prebuilt rules
      responses:
        200:
          description: Indicates a successful call
          content:
            application/json:
              schema:
                type: object
                properties:
                  rules_installed:
                    type: integer
                  rules_updated:
                    type: integer
    get:
      summary: Returns rule statuses
      responses:
        200:
          description: Indicates a successful call
          content:
            application/json:
              schema:
                type: object
                properties:
                  rules_custom_installed:
                    type: integer
                  rules_installed:
                    type: integer
                  rules_not_installed:
                    type: integer
                  rules_not_updated:
                    type: integer
  /api/detection_engine/rules/prepackaged/_status:
    get:
      summary: Get the status of Elastic prebuilt rules
      responses:
        200:
          description: Indicates a successful call
          content:
            application/json:
              schema:
                type: object
                properties:
                  rules_custom_installed:
                    type: integer
                  rules_installed:
                    type: integer
                  rules_not_installed:
                    type: integer
                  rules_not_updated:
                    type: integer
  /api/detection_engine/rules/_bulk_create:
    post:
      deprecated: true
      summary: Bulk create rules
      description: Creates new rules.
      requestBody:
        description: A JSON array of rules, where each rule contains the required fields.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Rule'
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
  /api/detection_engine/rules/_bulk_delete:
    delete:
      deprecated: true
      summary: Bulk delete rules
      description: Deletes multiple rules.
      requestBody:
        description: A JSON array of `id` or `rule_id` fields of the rules you want to delete.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  rule_id:
                    type: string
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
  /api/detection_engine/rules/_bulk_update:
    put:
      deprecated: true
      summary: Bulk update rules (PUT)
      description: Updates multiple rules using the `PUT` method.
      requestBody:
        description: A JSON array where each element includes the `id` or `rule_id` field of the rule you want to update and the fields you want to modify.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Rule'
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
    patch:
      deprecated: true
      summary: Bulk update rules (PATCH)
      description: Updates multiple rules using the `PATCH` method.
      requestBody:
        description: A JSON array where each element includes the `id` or `rule_id` field of the rule you want to update and the fields you want to modify.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Rule'
      responses:
        200:
          description: Indicates a successful call.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
  /api/detection_engine/rules/_bulk_action:
    post:
      summary: Applies a bulk action to multiple rules
      description: The bulk action is applied to all rules that match the filter or to the list of rules by their IDs.
      parameters:
        - name: dry_run
          in: query
          description: Enables dry run mode for the request call.
          required: false
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: A KQL search query to match the rules.
                  required: false
                ids:
                  type: array
                  items:
                    type: string
                  description: Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined.
                  required: false
                action:
                  type: string
                  enum:
                    - enable
                    - disable
                    - delete
                    - duplicate
                    - export
                    - edit
                  description: A bulk action to apply.
                  required: true
                edit:
                  $ref: '#/components/schemas/BulkEditAction'
                  required: false
                duplicate:
                  $ref: '#/components/schemas/BulkDuplicateAction'
                  required: false
      responses:
        200:
          description: OK
components:
  schemas:
    actions:
      type: object
      properties:
        action_type_id:
          type: string
          description: The action type used for sending notifications.
        group:
          type: string
          description: Optionally groups actions by use cases. Use `default` for alert notifications.
        id:
          type: string
          description: The connector ID.
        params:
          type: object
          description: Object containing the allowed connector fields, which varies according to the connector type.
    BulkDuplicateAction:
      type: object
      properties:
        include_exceptions:
          type: boolean
          description: Defines whether to include exceptions in a duplicated rule.
    BulkEditAction:
      type: object
      properties:
        type:
          type: string
          enum:
            - add_tags
            - delete_tags
            - set_tags
            - add_index_patterns
            - delete_index_patterns
            - set_index_patterns
            - set_timeline
            - set_schedule
          description: Defines what will be updated in rules.
        value:
          type: any
          description: value which will be applied in edit action.
    Rule:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
    throttle:
      type: string
      description: Defines the maximum interval in which a rule's actions are executed.
      enum:
        - rule
        - 1h
        - 1d
        - 7d
    threat:
      type: object
      properties:
        framework:
          type: string
          description: Relevant attack framework
        tactic:
          type: object
          properties:
            id:
              type: string
              description: Tactic ID
            name:
              type: string
              description: Tactic name
            reference:
              type: string
              description: Tactic reference
          required:
            - id
            - name
            - reference
        technique:
          type: array
          items:
            $ref: '#/components/schemas/technique'
          description: Array containing information on the attack techniques (optional)
      required:
        - framework
        - tactic
    technique:
      type: object
      properties:
        id:
          type: string
          description: Technique ID
        name:
          type: string
          description: Technique name
        reference:
          type: string
          description: Technique reference
        subtechnique:
          type: array
          items:
            $ref: '#/components/schemas/subtechnique'
          description: Array containing more specific information on the attack technique
      required:
        - id
        - name
        - reference
    subtechnique:
      type: object
      properties:
        id:
          type: string
          description: Subtechnique ID
        name:
          type: string
          description: Subtechnique name
        reference:
          type: string
          description: Subtechnique reference
      required:
        - id
        - name
        - reference