[Security Solution][Entity Analytics] Move OpenAPI Risk Engine schema…

…e to common/api folder (#169440)

# Summary
* Splits into one file per route
* Places reused components into a common.yml file


### Related Issues
This is a followup to [this
comment](https://github.com/elastic/kibana/pull/162400/files#r1282548131).

x-pack/plugins/security_solution/common/api/risk_engine/calculation_route_schema.yml

@@ -0,0 +1,91 @@
+openapi: 3.0.0
+
+info:
+  version: 1.0.0
+  title: Risk Scoring API
+  description: These APIs allow the consumer to manage Entity Risk Scores within Entity Analytics.
+
+servers:
+  - url: 'http://{kibana_host}:{port}'
+    variables:
+      kibana_host:
+        default: localhost
+      port:
+        default: '5601'
+
+paths:
+  /api/risk_scores/calculation:
+    post:
+      summary: Trigger calculation of Risk Scores
+      description: Calculates and persists a segment of Risk Scores, returning details about the calculation.
+      requestBody:
+        description: Details about the Risk Scores being calculated
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RiskScoresCalculationRequest'
+        required: true
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RiskScoresCalculationResponse'
+        '400':
+          description: Invalid request
+
+components:
+  schemas:
+    RiskScoresCalculationRequest:
+      type: object
+      required:
+        - data_view_id
+        - identifier_type
+        - range
+      properties:
+        after_keys:
+          description: Used to calculate a specific "page" of risk scores. If unspecified, the first "page" of scores is returned. See also the `after_keys` key in a risk scores response.
+          allOf:
+            - $ref: 'common.yml#/components/schemas/AfterKeys'
+        data_view_id:
+          $ref: 'common.yml#/components/schemas/DataViewId'
+          description: The identifier of the Kibana data view to be used when generating risk scores. If a data view is not found, the provided ID will be used as the query's index pattern instead.
+        debug:
+          description: If set to `true`, the internal ES requests/responses will be logged in Kibana.
+          type: boolean
+        filter:
+          $ref: 'common.yml#/components/schemas/Filter'
+          description: An elasticsearch DSL filter object. Used to filter the data being scored, which implicitly filters the risk scores calculated.
+        page_size:
+          $ref: 'common.yml#/components/schemas/PageSize'
+        identifier_type:
+          description: Used to restrict the type of risk scores calculated.
+          allOf:
+            - $ref: 'common.yml#/components/schemas/IdentifierType'
+        range:
+          $ref: 'common.yml#/components/schemas/DateRange'
+          description: Defines the time period over which scores will be evaluated. If unspecified, a range of `[now, now-30d]` will be used.
+        weights:
+          $ref: 'common.yml#/components/schemas/RiskScoreWeights'
+
+    RiskScoresCalculationResponse:
+      type: object
+      required:
+        - after_keys
+        - errors
+        - scores_written
+      properties:
+        after_keys:
+          description: Used to obtain the next "page" of risk scores. See also the `after_keys` key in a risk scores request. If this key is empty, the calculation is complete.
+          allOf:
+            - $ref: 'common.yml#/components/schemas/AfterKeys'
+        errors:
+          type: array
+          description: A list of errors encountered during the calculation.
+          items:
+            type: string
+        scores_written:
+          type: number
+          format: integer
+          description: The number of risk scores persisted to elasticsearch.

x-pack/plugins/security_solution/common/api/risk_engine/common.yml

@@ -0,0 +1,199 @@
+openapi: 3.0.0
+
+components:
+  schemas:
+
+    AfterKeys:
+      type: object
+      properties:
+        host:
+          type: object
+          additionalProperties:
+            type: string
+        user:
+          type: object
+          additionalProperties:
+            type: string
+      example:
+        host:
+          'host.name': 'example.host'
+        user:
+          'user.name': 'example_user_name'
+
+    DataViewId:
+      description: The identifier of the Kibana data view to be used when generating risk scores.
+      example: security-solution-default
+      type: string
+
+    Filter:
+      description: An elasticsearch DSL filter object. Used to filter the risk inputs involved, which implicitly filters the risk scores themselves.
+      $ref: 'https://cloud.elastic.co/api/v1/api-docs/spec.json#/definitions/QueryContainer'
+
+    PageSize:
+      description: Specifies how many scores will be involved in a given calculation. Note that this value is per `identifier_type`, i.e. a value of 10 will calculate 10 host scores and 10 user scores, if available. To avoid missed data, keep this value consistent while paginating through scores.
+      default: 1000
+      type: number
+
+    DateRange:
+      description: Defines the time period on which risk inputs will be filtered.
+      type: object
+      required:
+        - start
+        - end
+      properties:
+        start:
+          $ref: '#/components/schemas/KibanaDate'
+        end:
+          $ref: '#/components/schemas/KibanaDate'
+
+    KibanaDate:
+      type: string
+      oneOf:
+        - format: date
+        - format: date-time
+        - format: datemath
+      example: '2017-07-21T17:32:28Z'
+
+    IdentifierType:
+      type: string
+      enum:
+        - host
+        - user
+
+    RiskScore:
+      type: object
+      required:
+        - '@timestamp'
+        - id_field
+        - id_value
+        - calculated_level
+        - calculated_score
+        - calculated_score_norm
+        - category_1_score
+        - category_1_count
+        - inputs
+      properties:
+        '@timestamp':
+          type: string
+          format: 'date-time'
+          example: '2017-07-21T17:32:28Z'
+          description: The time at which the risk score was calculated.
+        id_field:
+          type: string
+          example: 'host.name'
+          description: The identifier field defining this risk score. Coupled with `id_value`, uniquely identifies the entity being scored.
+        id_value:
+          type: string
+          example: 'example.host'
+          description: The identifier value defining this risk score. Coupled with `id_field`, uniquely identifies the entity being scored.
+        calculated_level:
+          type: string
+          example: 'Critical'
+          description: Lexical description of the entity's risk.
+        calculated_score:
+          type: number
+          format: double
+          description: The raw numeric value of the given entity's risk score.
+        calculated_score_norm:
+          type: number
+          format: double
+          minimum: 0
+          maximum: 100
+          description: The normalized numeric value of the given entity's risk score. Useful for comparing with other entities.
+        category_1_score:
+          type: number
+          format: double
+          description: The contribution of Category 1 to the overall risk score (`calculated_score`). Category 1 contains Detection Engine Alerts.
+        category_1_count:
+          type: number
+          format: integer
+          description: The number of risk input documents that contributed to the Category 1 score (`category_1_score`).
+        inputs:
+          type: array
+          description: A list of the highest-risk documents contributing to this risk score. Useful for investigative purposes.
+          items:
+            $ref: '#/components/schemas/RiskScoreInput'
+
+    RiskScoreInput:
+      description: A generic representation of a document contributing to a Risk Score.
+      type: object
+      properties:
+        id:
+          type: string
+          example: 91a93376a507e86cfbf282166275b89f9dbdb1f0be6c8103c6ff2909ca8e1a1c
+          description: The unique identifier (`_id`) of the original source document
+        index:
+          type: string
+          example: .internal.alerts-security.alerts-default-000001
+          description: The unique index (`_index`) of the original source document
+        category:
+          type: string
+          example: category_1
+          description: The risk category of the risk input document.
+        description:
+          type: string
+          example: 'Generated from Detection Engine Rule: Malware Prevention Alert'
+          description: A human-readable description of the risk input document.
+        risk_score:
+          type: number
+          format: double
+          minimum: 0
+          maximum: 100
+          description: The weighted risk score of the risk input document.
+        timestamp:
+          type: string
+          example: '2017-07-21T17:32:28Z'
+          description: The @timestamp of the risk input document.
+
+    RiskScoreWeight:
+      description: "Configuration used to tune risk scoring. Weights can be used to change the score contribution of risk inputs for hosts and users at both a global level and also for Risk Input categories (e.g. 'category_1')."
+      type: object
+      required:
+        - type
+      properties:
+        type:
+          type: string
+        value:
+          type: string
+        host:
+          type: number
+          format: double
+          minimum: 0
+          maximum: 1
+        user:
+          type: number
+          format: double
+          minimum: 0
+          maximum: 1
+      example:
+        type: 'risk_category'
+        value: 'category_1'
+        host: 0.8
+        user: 0.4
+
+    RiskScoreWeights:
+      description: 'A list of weights to be applied to the scoring calculation.'
+      type: array
+      items:
+        $ref: '#/components/schemas/RiskScoreWeight'
+      example:
+        - type: 'risk_category'
+          value: 'category_1'
+          host: 0.8
+          user: 0.4
+        - type: 'global_identifier'
+          host: 0.5
+          user: 0.1
+
+    RiskEngineInitStep:
+      type: object
+      required:
+        - type
+        - success
+      properties:
+        type:
+          type: string
+        success:
+          type: boolean
+        error:
+          type: string

x-pack/plugins/security_solution/common/api/risk_engine/engine_disable_route_schema.yml

@@ -0,0 +1,37 @@
+openapi: 3.0.0
+
+info:
+  version: 1.0.0
+  title: Risk Scoring API
+  description: These APIs allow the consumer to manage Entity Risk Scores within Entity Analytics.
+
+servers:
+  - url: 'http://{kibana_host}:{port}'
+    variables:
+      kibana_host:
+        default: localhost
+      port:
+        default: '5601'
+
+paths:
+  /internal/risk_score/engine/disable:
+    post:
+      summary: Disable the Risk Engine
+      requestBody:
+        content:
+          application/json: {}
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RiskEngineDisableResponse'
+
+components:
+  schemas:
+    RiskEngineDisableResponse:
+      type: object
+      properties:
+        success:
+          type: boolean

x-pack/plugins/security_solution/common/api/risk_engine/engine_enable_route_schema.yml

@@ -0,0 +1,37 @@
+openapi: 3.0.0
+
+info:
+  version: 1.0.0
+  title: Risk Scoring API
+  description: These APIs allow the consumer to manage Entity Risk Scores within Entity Analytics.
+
+servers:
+  - url: 'http://{kibana_host}:{port}'
+    variables:
+      kibana_host:
+        default: localhost
+      port:
+        default: '5601'
+
+paths:
+  /internal/risk_score/engine/enable:
+    post:
+      summary: Enable the Risk Engine
+      requestBody:
+        content:
+          application/json: {}
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RiskEngineEnableResponse'
+
+components:
+  schemas:
+    RiskEngineEnableResponse:
+      type: object
+      properties:
+        success:
+          type: boolean