[Security Solution][Endpoint] Update OpenAPI docs for kill-process …

…action to include option applicable only to SentinelOne (elastic#192111) ## Summary - Add `process_name` to the `kill-process` response action for use with SentinelOne hosts only.
davismcphee · Sep 5, 2024 · c213832 · c213832
1 parent 666ab3d
commit c213832
Show file tree

Hide file tree

Showing 9 changed files with 240 additions and 58 deletions.
diff --git a/x-pack/plugins/security_solution/common/api/endpoint/README.md b/x-pack/plugins/security_solution/common/api/endpoint/README.md
@@ -0,0 +1,63 @@
+## Elastic Defend related APIs developer reference
+
+
+### Directory structure and files
+
+- All the OpenAPI schemas are located under this directory and organized by sub-directories that reflect the API domain.
+- Note that the sub-directory names for individual APIs are defined using snake_case to match the associated API path.
+- The `model/` directory stores common schemas for re-use across multiple APIs. 
+
+- Each API has at least the following set of files:
+
+```
+index.ts
+<api_route_name>.ts
+<api_route_name>.gen.ts
+<api_route_name>.schema.yaml
+```
+
+#### `index.ts` file
+
+The `index.ts` file found under each API directory exports both the generated and the kibana config schemas.
+
+
+#### `<api_route_name>.ts` file
+
+This file contains the Kibana `schema` definition that is used on the server side when the route is registered. This file is manually updated whenever needed.
+
+
+#### `<api_route_name>.schema.yaml` file
+
+This file defines and describes the API using the OpenAPI standard.
+
+
+#### `<api_route_name>.gen.ts` file
+
+This is a generated file and should not be updated manually. It contains schema validation code generated using the [Zod library](https://github.com/colinhacks/zod).
+
+
+
+
+
+### Making changes
+
+1. Update the OpenAPI schema YML file and/or the Kibana schema file (see References below for help with OpenAPI YAML format)
+2. Generate/re-generate the Zod schema validation modules:
+```shell
+yarn --cwd x-pack/plugins/security_solution openapi:generate
+```
+3. Create a new bundle with the updated APIs:
+```shell
+yarn --cwd x-pack/plugins/security_solution openapi:bundle:endpoint-management
+```
+4. Ensure that the newly generated files are commited to source
+
+
+
+### References
+
+- [Kibana OpenAPI generator Usage Guide](https://github.com/elastic/kibana/blob/main/packages/kbn-openapi-generator/docs/USAGE_GUIDE.md)
+- [Open API documentation](https://spec.openapis.org/oas/v3.0.3#document-structure)
+- [Swagger documentation](https://swagger.io/docs/specification/basic-structure/)
+
+
diff --git a/...ty_solution/common/api/endpoint/actions/response_actions/kill_process/kill_process.gen.ts b/...ty_solution/common/api/endpoint/actions/response_actions/kill_process/kill_process.gen.ts
@@ -14,14 +14,30 @@
  *   version: 2023-10-31
  */
 
-import type { z } from '@kbn/zod';
+import { z } from '@kbn/zod';
 
-import { KillOrSuspendActionSchema, SuccessResponse } from '../../../model/schema/common.gen';
+import { SuccessResponse, BaseActionSchema, Pid, EntityId } from '../../../model/schema/common.gen';
+
+export type KillProcessRouteRequestBody = z.infer<typeof KillProcessRouteRequestBody>;
+export const KillProcessRouteRequestBody = BaseActionSchema.merge(
+  z.object({
+    parameters: z.union([
+      Pid,
+      EntityId,
+      z.object({
+        /**
+         * Valid for SentinelOne agent type only
+         */
+        process_name: z.string().min(1).optional(),
+      }),
+    ]),
+  })
+);
 
 export type EndpointKillProcessActionRequestBody = z.infer<
   typeof EndpointKillProcessActionRequestBody
 >;
-export const EndpointKillProcessActionRequestBody = KillOrSuspendActionSchema;
+export const EndpointKillProcessActionRequestBody = KillProcessRouteRequestBody;
 export type EndpointKillProcessActionRequestBodyInput = z.input<
   typeof EndpointKillProcessActionRequestBody
 >;

diff --git a/...lution/common/api/endpoint/actions/response_actions/kill_process/kill_process.schema.yaml b/...lution/common/api/endpoint/actions/response_actions/kill_process/kill_process.schema.yaml
@@ -15,11 +15,31 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '../../../model/schema/common.schema.yaml#/components/schemas/KillOrSuspendActionSchema'
+              $ref: '#/components/schemas/KillProcessRouteRequestBody'
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
                 $ref: '../../../model/schema/common.schema.yaml#/components/schemas/SuccessResponse'
+
+components:
+  schemas:
+    KillProcessRouteRequestBody:
+      allOf:
+        - $ref: '../../../model/schema/common.schema.yaml#/components/schemas/BaseActionSchema'
+        - type: object
+          required:
+            - parameters
+          properties:
+            parameters:
+              oneOf:
+                - $ref: "../../../model/schema/common.schema.yaml#/components/schemas/Pid"
+                - $ref: "../../../model/schema/common.schema.yaml#/components/schemas/EntityId"
+                - type: object
+                  properties:
+                    process_name:
+                      type: string
+                      minLength: 1
+                      description: Valid for SentinelOne agent type only
diff --git a/...ution/common/api/endpoint/actions/response_actions/suspend_process/suspend_process.gen.ts b/...ution/common/api/endpoint/actions/response_actions/suspend_process/suspend_process.gen.ts
@@ -14,14 +14,21 @@
  *   version: 2023-10-31
  */
 
-import type { z } from '@kbn/zod';
+import { z } from '@kbn/zod';
 
-import { KillOrSuspendActionSchema, SuccessResponse } from '../../../model/schema/common.gen';
+import { SuccessResponse, BaseActionSchema, Pid, EntityId } from '../../../model/schema/common.gen';
+
+export type SuspendProcessRouteRequestBody = z.infer<typeof SuspendProcessRouteRequestBody>;
+export const SuspendProcessRouteRequestBody = BaseActionSchema.merge(
+  z.object({
+    parameters: z.union([Pid, EntityId]),
+  })
+);
 
 export type EndpointSuspendProcessActionRequestBody = z.infer<
   typeof EndpointSuspendProcessActionRequestBody
 >;
-export const EndpointSuspendProcessActionRequestBody = KillOrSuspendActionSchema;
+export const EndpointSuspendProcessActionRequestBody = SuspendProcessRouteRequestBody;
 export type EndpointSuspendProcessActionRequestBodyInput = z.input<
   typeof EndpointSuspendProcessActionRequestBody
 >;

diff --git a/.../common/api/endpoint/actions/response_actions/suspend_process/suspend_process.schema.yaml b/.../common/api/endpoint/actions/response_actions/suspend_process/suspend_process.schema.yaml
@@ -15,11 +15,25 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '../../../model/schema/common.schema.yaml#/components/schemas/KillOrSuspendActionSchema'
+              $ref: '#/components/schemas/SuspendProcessRouteRequestBody'
       responses:
         '200':
           description: OK
           content:
             application/json:
               schema:
                 $ref: '../../../model/schema/common.schema.yaml#/components/schemas/SuccessResponse'
+
+components:
+  schemas:
+    SuspendProcessRouteRequestBody:
+      allOf:
+        - $ref: '../../../model/schema/common.schema.yaml#/components/schemas/BaseActionSchema'
+        - type: object
+          required:
+            - parameters
+          properties:
+            parameters:
+              oneOf:
+                - $ref: "../../../model/schema/common.schema.yaml#/components/schemas/Pid"
+                - $ref: "../../../model/schema/common.schema.yaml#/components/schemas/EntityId"
diff --git a/x-pack/plugins/security_solution/common/api/endpoint/model/schema/common.gen.ts b/x-pack/plugins/security_solution/common/api/endpoint/model/schema/common.gen.ts
@@ -162,19 +162,15 @@ export const NoParametersRequestSchema = z.object({
   body: BaseActionSchema,
 });
 
-export type KillOrSuspendActionSchema = z.infer<typeof KillOrSuspendActionSchema>;
-export const KillOrSuspendActionSchema = BaseActionSchema.merge(
-  z.object({
-    parameters: z.union([
-      z.object({
-        pid: z.number().int().min(1).optional(),
-      }),
-      z.object({
-        entity_id: z.string().min(1).optional(),
-      }),
-    ]),
-  })
-);
+export type Pid = z.infer<typeof Pid>;
+export const Pid = z.object({
+  pid: z.number().int().min(1).optional(),
+});
+
+export type EntityId = z.infer<typeof EntityId>;
+export const EntityId = z.object({
+  entity_id: z.string().min(1).optional(),
+});
 
 export type ProtectionUpdatesNoteResponse = z.infer<typeof ProtectionUpdatesNoteResponse>;
 export const ProtectionUpdatesNoteResponse = z.object({

diff --git a/x-pack/plugins/security_solution/common/api/endpoint/model/schema/common.schema.yaml b/x-pack/plugins/security_solution/common/api/endpoint/model/schema/common.schema.yaml
@@ -173,25 +173,19 @@ components:
         body:
           $ref: '#/components/schemas/BaseActionSchema'
 
-    KillOrSuspendActionSchema:
-      allOf:
-        - $ref: '#/components/schemas/BaseActionSchema'
-        - type: object
-          required:
-            - parameters
-          properties:
-            parameters:
-              oneOf:
-                - type: object
-                  properties:
-                    pid:
-                      type: integer
-                      minimum: 1
-                - type: object
-                  properties:
-                    entity_id:
-                      type: string
-                      minLength: 1
+    Pid:
+      type: object
+      properties:
+        pid:
+          type: integer
+          minimum: 1
+
+    EntityId:
+      type: object
+      properties:
+        entity_id:
+          type: string
+          minLength: 1
 
     ProtectionUpdatesNoteResponse:
       type: object

diff --git a/...docs/openapi/ess/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml b/...docs/openapi/ess/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml
@@ -220,7 +220,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/KillOrSuspendActionSchema'
+              $ref: '#/components/schemas/KillProcessRouteRequestBody'
         required: true
       responses:
         '200':
@@ -296,7 +296,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/KillOrSuspendActionSchema'
+              $ref: '#/components/schemas/SuspendProcessRouteRequestBody'
         required: true
       responses:
         '200':
@@ -741,6 +741,12 @@ components:
         type: string
       minItems: 1
       type: array
+    EntityId:
+      type: object
+      properties:
+        entity_id:
+          minLength: 1
+          type: string
     ExecuteRouteRequestBody:
       allOf:
         - type: object
@@ -832,7 +838,7 @@ components:
       $ref: '#/components/schemas/NoParametersRequestSchema'
     IsolateRouteRequestBody:
       $ref: '#/components/schemas/NoParametersRequestSchema'
-    KillOrSuspendActionSchema:
+    KillProcessRouteRequestBody:
       allOf:
         - type: object
           properties:
@@ -854,14 +860,12 @@ components:
           properties:
             parameters:
               oneOf:
+                - $ref: '#/components/schemas/Pid'
+                - $ref: '#/components/schemas/EntityId'
                 - type: object
                   properties:
-                    pid:
-                      minimum: 1
-                      type: integer
-                - type: object
-                  properties:
-                    entity_id:
+                    process_name:
+                      description: Valid for SentinelOne agent type only
                       minLength: 1
                       type: string
           required:
@@ -980,6 +984,12 @@ components:
               $ref: '#/components/schemas/PendingActionDataType'
         - additionalProperties: true
           type: object
+    Pid:
+      type: object
+      properties:
+        pid:
+          minimum: 1
+          type: integer
     ProtectionUpdatesNoteResponse:
       type: object
       properties:
@@ -1020,6 +1030,32 @@ components:
     SuccessResponse:
       type: object
       properties: {}
+    SuspendProcessRouteRequestBody:
+      allOf:
+        - type: object
+          properties:
+            agent_type:
+              $ref: '#/components/schemas/AgentTypes'
+            alert_ids:
+              $ref: '#/components/schemas/AlertIds'
+            case_ids:
+              $ref: '#/components/schemas/CaseIds'
+            comment:
+              $ref: '#/components/schemas/Comment'
+            endpoint_ids:
+              $ref: '#/components/schemas/EndpointIds'
+            parameters:
+              $ref: '#/components/schemas/Parameters'
+          required:
+            - endpoint_ids
+        - type: object
+          properties:
+            parameters:
+              oneOf:
+                - $ref: '#/components/schemas/Pid'
+                - $ref: '#/components/schemas/EntityId'
+          required:
+            - parameters
     Timeout:
       description: The maximum timeout value in milliseconds (optional)
       minimum: 1