diff --git a/docs/AI-for-security/api/ai-for-security-index.asciidoc b/docs/AI-for-security/api/ai-for-security-index.asciidoc deleted file mode 100644 index b7f5ea8772..0000000000 --- a/docs/AI-for-security/api/ai-for-security-index.asciidoc +++ /dev/null @@ -1,21 +0,0 @@ -include::assistant-api-overview.asciidoc[] - -include::chat-complete-api.asciidoc[] - -include::conversation-api-create.asciidoc[] - -include::conversation-api-delete.asciidoc[] - -include::conversation-api-find.asciidoc[] - -include::conversation-api-get.asciidoc[] - -include::conversation-api-update.asciidoc[] - -include::prompts-api-find.asciidoc[] - -include::bulk-actions-prompts-api.asciidoc[] - -include::anonymization-fields-api-find.asciidoc[] - -include::bulk-actions-anonymization-fields-api.asciidoc[] diff --git a/docs/AI-for-security/api/anonymization-fields-api-find.asciidoc b/docs/AI-for-security/api/anonymization-fields-api-find.asciidoc deleted file mode 100644 index ed601429b0..0000000000 --- a/docs/AI-for-security/api/anonymization-fields-api-find.asciidoc +++ /dev/null @@ -1,275 +0,0 @@ -[[anonymization-fields-api-find]] -=== Find anonymization fields - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Retrieve a list of anonymization fields that can be included in the LLM context. - -[discrete] -=== Request URL - -`GET :/api/security_ai_assistant/anonymization_fields/_find` - -==== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`page` |Number |The page number to return. Defaults to `1`. -|No -|`per_page` |Number |The number of items to return per page. Defaults to `10`. -|No -|`filter` |String |The filter query to apply on the request. -|No -|`sort_field` |String a|The field to sort the results by. Valid values are: - -* `anonymized` -* `allowed` -* `updated_at` -* `created_at` - -|No -|`sort_order` |String a|The order to sort the results in. Valid values are: - -* `asc` -* `desc` - -|No -|`fields` |String a|Defines the fields of the document to return in the response. For example, if set to `name` and `allowed`, the rest of the fields are omitted from the response. - -|No - -|============================================== - -[discrete] -=== Example requests - -*Example 1* - -Get a list of all anonymization fields. - -[source,console] --------------------------------------------------- -GET api/security_ai_assistant/anonymization_fields/_find?page=1&per_page=100 --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON anonymization field object with a unique `id`. - -*Example 1* - -Anonymization fields response payload: - -[source,json] --------------------------------------------------- -{ - "perPage": 100, - "page": 1, - "total": 100, - "data": [ - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "_id", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "lR12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "@timestamp", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "lh12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "cloud.availability_zone", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "lx12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "cloud.provider", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "mB12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "cloud.region", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "mR12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "destination.ip", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "mh12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "dns.question.name", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "mx12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "dns.question.type", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "nB12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "event.category", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "nR12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "event.dataset", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "nh12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.executable", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "xx12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.exit_code", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "yB12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.Ext.memory_region.bytes_compressed_present", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "yR12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.Ext.memory_region.malware_signature.all_names", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "yh12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.Ext.memory_region.malware_signature.primary.matches", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "yx12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.Ext.memory_region.malware_signature.primary.signature.name", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "zB12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.Ext.token.integrity_level_name", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "zR12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.hash.md5", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "zh12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.hash.sha1", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "zx12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "process.hash.sha256", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "0B12SZEBYaDeA-NhmkwG" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "user.risk.calculated_score_norm", - "allowed": true, - "anonymized": false, - "namespace": "default", - "id": "-B12SZEBYaDeA-NhmkwG" - } - ] -} --------------------------------------------------- - diff --git a/docs/AI-for-security/api/assistant-api-overview.asciidoc b/docs/AI-for-security/api/assistant-api-overview.asciidoc deleted file mode 100644 index 1d815c3672..0000000000 --- a/docs/AI-for-security/api/assistant-api-overview.asciidoc +++ /dev/null @@ -1,11 +0,0 @@ -[[assistant-api-overview]] -[role="xpack"] -== Elastic AI Assistant API - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -The Elastic AI Assistant API allows you to interact with and manage Elastic AI Assistant. diff --git a/docs/AI-for-security/api/bulk-actions-anonymization-fields-api.asciidoc b/docs/AI-for-security/api/bulk-actions-anonymization-fields-api.asciidoc deleted file mode 100644 index 225bf99e28..0000000000 --- a/docs/AI-for-security/api/bulk-actions-anonymization-fields-api.asciidoc +++ /dev/null @@ -1,240 +0,0 @@ -[[bulk-actions-anonymization-fields-api]] -=== Bulk anonymization field actions - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Apply a bulk action (create, update, or delete) to multiple anonymization fields. The bulk action is applied to all anonymization fields that match the filter or to the list of anonymization fields by their IDs. - -[discrete] -===== Request URL - -`POST :/api/security_ai_assistant/anonymization_fields/_bulk_action` - -[discrete] -===== Request body - -A JSON object with the following properties: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required -| `create` | <> | Array of anonymization field objects to create. | No -| `delete` | String[] | Array of IDs of the anonymization fields to delete. | No -| `update` | <> | Array of anonymization field objects with the fields to update. | No - -|============================================== - - -[[bulk-create-anonymization-fields-schema]] -[discrete] -==== BulkCreateAction object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`field` |String |A field's name. |Yes -|`allowed` |Boolean |Defines whether the field will get sent to the LLM. |Yes -|`anonymized` |Boolean |Defines whether the field will be anonymized if sent to the LLM. Defaults to `false`. |Yes -|============================================== - - -[discrete] -[[bulk-update-anonymization-fields-schema]] -==== BulkUpdateAction object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`allowed` |Boolean |Defines whether the field will get sent to the LLM. |No -|`anonymized` |Boolean |Defines whether the field will be anonymized if sent to the LLM. Defaults to `false`. |No -|============================================== - - -[discrete] -===== Example requests - -*Example 1* - -The following request creates two anonymization fields: - -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/anonymization_fields/_bulk_action -{ - "create": [ - { - "field": "agent.type", - "allowed": true, - "anonymized": false - }, - { - "field": "agent.name", - "allowed": true, - "anonymized": true - } - ] -} --------------------------------------------------- - -[discrete] -===== Response code - -`200`:: - Indicates a successful call. - -[discrete] -===== Response payload - -JSON object containing the action's outcome: - -- `attributes.summary.total`: Total number of anonymization fields matching the bulk action -- `attributes.summary.succeeded`: Number of successful outcomes (number of anonymization fields that were created, deleted, or updated) -- `attributes.summary.failed`: Number of failed outcomes -- `attributes.summary.skipped`: Number of anonymization fields that were skipped due to various reasons (explained below) -- `attributes.results.created`: Anonymization field objects that were created during the action's execution -- `attributes.results.updated`: Anonymization field objects that were updated during the action's execution -- `attributes.results.deleted`: Anonymization field objects that were deleted during the action's execution -- `attributes.results.skipped`: Anonymization fields that were skipped during the action's execution - -An anonymization field can only be `skipped` when the bulk action to be performed on it results in nothing being done. For example, if the `update` action is used to update a field that already has the specified value. Objects returned in `attributes.results.skipped` will only include an anonymization field's `id`, `name`, and `skip_reason`. - -[source,json] --------------------------------------------------- -{ - "success": true, - "anonymization_fields_count": 2, - "attributes": { - "results": { - "updated": [], - "created": [ - { - "timestamp": "2024-08-13T20:54:23.125Z", - "createdAt": "2024-08-13T20:54:23.125Z", - "field": "agent.type", - "allowed": true, - "anonymized": false, - "updatedAt": "2024-08-13T20:54:23.125Z", - "id": "cB2FTZEBYaDeA-NhPHqW" - }, - { - "timestamp": "2024-08-13T20:54:23.125Z", - "createdAt": "2024-08-13T20:54:23.125Z", - "field": "agent.name", - "allowed": true, - "anonymized": true, - "updatedAt": "2024-08-13T20:54:23.125Z", - "id": "cR2FTZEBYaDeA-NhPHqW" - } - ], - "deleted": [], - "skipped": [] - }, - "summary": { - "failed": 0, - "succeeded": 2, - "skipped": 0, - "total": 2 - } - } -} --------------------------------------------------- - -*Example 2: Partial failure* - -The following request: - -* deletes the anonymization field with the ID value of `cR2FTZEBYaDeA-NhPHqW` -* updates the `allowed` value for the anonymization field with the ID of `lh12SZEBYaDeA-NhmkwG` -* updates the `anonymized` value for the anonymization field with the ID of `lR12SZEBYaDeA-NhmkwG` - -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/anonymization_fields/_bulk_action -{ - "delete": { - "ids": [ - "cR2FTZEBYaDeA-NhPHqW" - ] - }, - "update": [ - { - "id": "lh12SZEBYaDeA-NhmkwG", - "allowed": false - }, - { - "id": "lR12SZEBYaDeA-NhmkwG", - "anonymized": true - } - ] -} --------------------------------------------------- - -[discrete] -===== Response code - -`500`:: - Indicates partial bulk action failure. - -[discrete] -===== Response payload - -If the processing of any anonymization fields fails, the response outputs a partial error, with the ID and/or name of the affected anonymization field and the corresponding error message. The response also includes successfully processed anonymization fields, in the same format as a successful `200` request. - -[source,json] --------------------------------------------------- -{ - "message": "Bulk delete partially failed", - "status_code": 500, - "attributes": { - "errors": [ - { - "message": "Some error happened here", - "status_code": 500, - "anonymization_fields": [ - { - "id": "cR2FTZEBYaDeA-NhPHqW", - "field": "test" - } - ] - } - ], - "results": { - "updated": [ - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "@timestamp", - "allowed": false, - "anonymized": false, - "updatedAt": "2024-08-13T21:00:37.502Z", - "namespace": "default" - }, - { - "timestamp": "2024-08-13T01:59:55.141Z", - "createdAt": "2024-08-13T01:59:55.141Z", - "field": "_id", - "allowed": true, - "anonymized": true, - "updatedAt": "2024-08-13T21:00:37.502Z", - "namespace": "default" - } - ], - "created": [], - "deleted": [], - "skipped": [] - }, - "summary": { - "failed": 1, - "succeeded": 1, - "skipped": 0, - "total": 2 - } - } -} --------------------------------------------------- diff --git a/docs/AI-for-security/api/bulk-actions-prompts-api.asciidoc b/docs/AI-for-security/api/bulk-actions-prompts-api.asciidoc deleted file mode 100644 index be9cdfd25d..0000000000 --- a/docs/AI-for-security/api/bulk-actions-prompts-api.asciidoc +++ /dev/null @@ -1,244 +0,0 @@ -[[bulk-actions-prompts-api]] -=== Bulk prompt actions - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Apply a bulk action (create, update, or delete) to multiple prompts. The bulk action is applied to all prompts that match the filter or to the list of prompts by their IDs. - -[discrete] -===== Request URL - -`POST :/api/security_ai_assistant/prompts/_bulk_action` - -[discrete] -===== Request body - -A JSON object with the following properties: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required -| `create` | <> | Array of prompt objects to create. | No -| `delete` | String[] | Array of IDs of the prompts to delete. | No -| `update` | <> | Array of prompt objects with the fields to update. | No - -|============================================== - - -[[bulk-create-object-schema]] -[discrete] -==== BulkCreateAction object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`name` |String |Short prompt title. |Yes -|`id` |String |Prompt ID. |Yes -|`promptType` |String a|Prompt type. Valid values are: - -* `system` -* `quick` -|Yes -|`consumer` |String |Solution application that the prompt belongs to. For example `securitySolutionUI`, `ml` |Yes -|`content` |String |Prompt text to send to LLM. |Yes -|`color` |String |Sets the display color for quick prompts in the UI. |No -|`categories` |String[] |Array of prompt categories. |No -|============================================== - - -[discrete] -[[bulk-update-object-schema]] -==== BulkUpdateAction object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`id` |String |Prompt ID. |Yes -|`content` |String |Prompt text to send to LLM. |No -|`color` |String |Sets the display color for quick prompts in the UI. |No -|`categories` |String[] |Array of prompts categories. |No -|============================================== - - -[discrete] -===== Example requests - -*Example 1* - -The following request creates a new quick prompt: - -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/prompts/_bulk_action -{ - "create": [ - { - "name": "test", - "id": "test", - "content": "some test content", - "color": "#D36086", - "categories": [], - "promptType": "quick", - "consumer": "securitySolutionUI" - } - ] -} --------------------------------------------------- - -[discrete] -===== Response code - -`200`:: - Indicates a successful call. - -[discrete] -===== Response payload - -JSON object containing the action's outcome: - -- `attributes.summary.total`: Total number of prompts matching the bulk action -- `attributes.summary.succeeded`: Number of successful outcomes (number of prompts that were created, deleted, or updated) -- `attributes.summary.failed`: Number of failed outcomes -- `attributes.summary.skipped`: Number of prompts that were skipped due to various reasons (explained below) -- `attributes.results.created`: Prompt objects that were created during the action's execution -- `attributes.results.updated`: Prompt objects that were updated during the action's execution -- `attributes.results.deleted`: Prompt objects that were deleted during the action's execution -- `attributes.results.skipped`: Prompt that were skipped during the action's execution - -A prompt can only be `skipped` when the bulk action to be performed on it results in nothing being done. For example, if the `update` action is used to update a field that already has the specified value. Objects returned in `attributes.results.skipped` only include a prompt's `id`, `name`, and `skip_reason`. - -[source,json] --------------------------------------------------- -{ - "success": true, - "prompts_count": 1, - "attributes": { - "results": { - "updated": [], - "created": [ - { - "timestamp": "2024-08-13T20:24:08.610Z", - "users": [ - { - "id": "testuser", - "name": "elastic" - } - ], - "content": "some test content", - "updatedAt": "2024-08-13T20:24:08.610Z", - "id": "0B1pTZEBYaDeA-NhjHej", - "name": "test", - "promptType": "quick", - "color": "#D36086", - "categories": [], - "consumer": "securitySolutionUI" - } - ], - "deleted": [], - "skipped": [] - }, - "summary": { - "failed": 0, - "succeeded": 1, - "skipped": 0, - "total": 1 - } - } -} --------------------------------------------------- - -*Example 2: Partial failure* - -The following request deletes prompt by ID "8bc7dad0-9320-11ec-9265-8b772383a08d" and updates another prompt by ID "2-R12SZEBYaDeA-NhnUyW" with the new values for content, color and categories: -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/prompts/_bulk_action -{ - "delete": { - "ids": [ - "8bc7dad0-9320-11ec-9265-8b772383a08d" - ] - }, - "update": [ - { - "content": "As an expert in security operations and incident response, provide a breakdown of the attached alert and summarize what it might mean for my organization.", - "id": "2-R12SZEBYaDeA-NhnUyW", - "color": "#F68FBE", - "categories": [ - "alert" - ] - } - ] -} --------------------------------------------------- - -[discrete] -===== Response code - -`500`:: - Indicates partial bulk action failure. - -[discrete] -===== Response payload - -If the processing of any prompts fails, the response outputs a partial error, with the ID and/or name of the affected prompt and the corresponding error message. The response also includes successfully processed prompts, in the same format as a successful `200` request. - -[source,json] --------------------------------------------------- -{ - "message": "Bulk delete partially failed", - "status_code": 500, - "attributes": { - "errors": [ - { - "message": "Some error happened here", - "status_code": 500, - "prompts": [ - { - "id": "8bc7dad0-9320-11ec-9265-8b772383a08d", - "name": "Prompt title" - } - ] - } - ], - "results": { - "updated": [ - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0", - "name": "elastic" - } - ], - "content": "As an expert in security operations and incident response, provide a breakdown of the attached alert and summarize what it might mean for my organization.", - "isDefault": true, - "updatedAt": "2024-08-13T20:45:14.763Z", - "name": "Alert summarization", - "promptType": "quick", - "color": "#F68FBE", - "categories": [ - "alert" - ], - "consumer": "securitySolutionUI" - } - ], - "created": [], - "deleted": [], - "skipped": [] - }, - "summary": { - "failed": 1, - "succeeded": 1, - "skipped": 0, - "total": 2 - } - } -} --------------------------------------------------- diff --git a/docs/AI-for-security/api/chat-complete-api.asciidoc b/docs/AI-for-security/api/chat-complete-api.asciidoc deleted file mode 100644 index 6ff8cb7213..0000000000 --- a/docs/AI-for-security/api/chat-complete-api.asciidoc +++ /dev/null @@ -1,241 +0,0 @@ -[[chat-complete-api]] -=== Complete chat - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -The complete chat API allows you to communicate with the configured large language model (LLM) and, if needed, persist the result as a conversation (create new or extend existing). - -[discrete] -=== Request URL - -`POST :/api/security_ai_assistant/chat/complete` - -[discrete] -=== Request body - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`conversationId` |String |Conversation ID to append to messages and use as context. Refer to conversation APIs. |No -|`connectorId` |String |ID for an LLM connector: a Kibana integration with the specific LLM provider. |Yes -|`promptId` |String |Default conversation prompt ID. |No -|`persist` |Boolean |Defines if the conversation should be created, or updated (if `conversationId` is provided). |Yes -|`isStream` |Boolean |Define the type of the response. If `isStream` equals `true`, the result will be returned as streaming chunks. |No -|`messages` |<> |Array of conversation messages. |Yes -|`model` |String |Name of a specific LLM to use. |No -|`responseLanguage` |String |Defines the language for the LLM to respond in. |No -|============================================== - -[discrete] -[[message-obj]] -=== `messages` object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`role` |String |Message role. Can be "user", "assistant" or "system". |Yes -|`content` |String |Message content to send to LLM. |Yes -|`data` |Object |JSON object to include as context for the model. |No -|`fields_to_anonymize` |Array |List of fields in the `data` object to anonymize. |No -|============================================== - -[discrete] -=== Example requests - -*Example 1* - -Sends a message to the LLM. The data is anonymized with central anonymization applied and extended with a list of fields to anonymize. - -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/chat/complete -{ - "connectorId": "my-gpt4o-ai", - "persist": false, - "messages": [ - { - "role": "user", - "content": "Evaluate the event from the context and format your output neatly in markdown syntax for my Elastic Security case.\nAdd your description, recommended actions and bulleted triage steps. Use the MITRE ATT&CK data provided to add more context and recommendations from MITRE, and hyperlink to the relevant pages on MITRE's website. Be sure to include the user and host risk score data from the context. Your response should include steps that point to Elastic Security specific features, including endpoint response actions, the Elastic Agent OSQuery manager integration (with example osquery queries), timelines and entity analytics and link to all the relevant Elastic Security documentation.", - "data": { - "event.category": "process", - "process.pid": 69516, - "host.os.version": 14.5, - "host.os.name": "macOS" - }, - "fields_to_anonymize": [ - "host.os.name" - ] - } - ] -} --------------------------------------------------- - -*Example 2* - -Sends a message to the LLM within an existing conversation and provides data as context. The data is anonymized with central anonymization applied and extended with a list of fields to anonymize. Adds the LLM response with the role `assistant` to the existing conversation. - -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/chat/complete -{ - "connectorId": "my-gpt4o-ai", - "conversationId": "df071e68-3c8e-4c0d-b0e7-1557e80c0319", - "persist": true, - "messages": [ - { - "role": "user", - "content": "Evaluate the event from the context and format your output neatly in markdown syntax for my Elastic Security case.\nAdd your description, recommended actions and bulleted triage steps. Use the MITRE ATT&CK data provided to add more context and recommendations from MITRE, and hyperlink to the relevant pages on MITRE's website. Be sure to include the user and host risk score data from the context. Your response should include steps that point to Elastic Security specific features, including endpoint response actions, the Elastic Agent OSQuery manager integration (with example osquery queries), timelines and entity analytics and link to all the relevant Elastic Security documentation.", - "data": { - "event.category": "process", - "process.pid": 69516, - "host.os.version": 14.5, - "host.os.name": "macOS", - "host.name": "test-MBP", - "process.name": "biomesyncd", - "user.name": "usertest", - "process.working_directory": "/", - "event.module": "system", - "process.executable": "/usr/libexec/biomesyncd", - "process.args": "/usr/libexec/biomesyncd", - "message": "Process biomesyncd (PID: 69516) by user usertest STOPPED" - }, - "fields_to_anonymize": [ - "host.os.name", - "event.module" - ] - } - ] -} --------------------------------------------------- - -*Example 3* - -Sends a message to the LLM. Creates a new conversation and adds the LLM response with the role `assistant`. - -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/chat/complete -{ - "connectorId": "my-gpt4o-ai", - "persist": true, - "messages": [ - { - "role": "user", - "content": "Evaluate the event from the context and format your output neatly in markdown syntax for my Elastic Security case.\nAdd your description, recommended actions and bulleted triage steps. Use the MITRE ATT&CK data provided to add more context and recommendations from MITRE, and hyperlink to the relevant pages on MITRE's website. Be sure to include the user and host risk score data from the context. Your response should include steps that point to Elastic Security specific features, including endpoint response actions, the Elastic Agent OSQuery manager integration (with example osquery queries), timelines and entity analytics and link to all the relevant Elastic Security documentation.", - } - ] -} --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON object with an LLM response, and a conversation `id` if `persist` was set to true. - -*Example 1* - -Conversation response payload: - -[source,json] --------------------------------------------------- -{ - "connector_id": "my-gpt4o-ai", - "data": "### Elastic Security Case: Process Stopped Event\n\n#### Description\nA process named `biomesyncd` with PID `69516` was stopped by the user `2fede99b-5ec7-4274-b990-469b4110f7ba` on the host `e4d4dc93-754e-4282-ac84-94fe72071ab1` running `dc00f5d9-bdf3-4517-b7ef-de5a89f0d071` version `14.5`. The executable path for the process is `/usr/libexec/biomesyncd`.\n\n#### Recommended Actions\n1. **Investigate the process**: Determine if the process `biomesyncd` is legitimate or potentially malicious.\n2. **Check user activity**: Review the actions performed by the user `2fede99b-5ec7-4274-b990-469b4110f7ba` around the time the process was stopped.\n3. **Analyze host behavior**: Examine the host `e4d4dc93-754e-4282-ac84-94fe72071ab1` for any other suspicious activities or anomalies.\n\n#### Triage Steps\n- **Review Process Details**:\n - Verify the legitimacy of the process `biomesyncd`.\n - Check the process arguments and executable path.\n- **User Activity Analysis**:\n - Investigate the user `2fede99b-5ec7-4274-b990-469b4110f7ba` for any unusual behavior.\n- **Host Analysis**:\n - Check for other suspicious processes or activities on the host `e4d4dc93-754e-4282-ac84-94fe72071ab1`.\n\n#### MITRE ATT&CK Context\n- **Technique**: [T1059.001 - Command and Scripting Interpreter: PowerShell](https://attack.mitre.org/techniques/T1059/001/)\n- **Tactic**: Execution\n\n#### Elastic Security Features\n- **Endpoint Response Actions**: Use Elastic Security's endpoint response actions to isolate the host or terminate suspicious processes.\n- **Elastic Agent OSQuery Manager Integration**: Utilize OSQuery to gather more information about the host and processes.\n - Example OSQuery Query:\n ```sql\n SELECT * FROM processes WHERE name = 'biomesyncd';\n ```\n- **Timelines**: Create a timeline to visualize the sequence of events and correlate with other activities.\n- **Entity Analytics**: Use entity analytics to assess the risk score of the user and host.\n\n#### Elastic Security Documentation\n- \[Endpoint Security\]\(https:\//www.elastic.co/guide/en/security/current/endpoint-security.html\)\n- \[OSQuery Manager\]\(https:\//www.elastic.co/guide/en/security/current/osquery-manager.html\)\n- \[Timelines\]\(https:\//www.elastic.co/guide/en/security/current/timelines.html\)\n- \[Entity Analytics\]\(https:\//www.elastic.co/guide/en/security/current/entity-analytics.html\)\n\n### ESQL Query\n```sql\nFROM process\nWHERE process.name == \"biomesyncd\"\n AND process.pid == 69516\n AND user.name == \"2fede99b-5ec7-4274-b990-469b4110f7ba\"\n AND host.name == \"e4d4dc93-754e-4282-ac84-94fe72071ab1\"\n AND host.os.version == \"14.5\"\n```\n\nThis query can be used in an Elastic Security timeline or detection rule to detect the stopping of the `biomesyncd` process by the specified user on the specified host.", - "trace_data": { - "transactionId": "293ad93379ace883", - "traceId": "eeedce3430c9ded8fb8dc38dcfd96eb4" - }, - "replacements": { - "dc00f5d9-bdf3-4517-b7ef-de5a89f0d071": "macOS", - }, - "status": "ok", - "conversationId": "df071e68-3c8e-4c0d-b0e7-1557e80c0319" -} --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON object with an LLM response and a conversation ID if `persist` was set to `true`. - -*Example 2* - -Conversation response payload: - -[source,json] --------------------------------------------------- -{ - "connector_id": "my-gpt4o-ai", - "data": "### Elastic Security Case: Process Stopped Event\n\n#### Description\nA process named `biomesyncd` with PID `69516` was stopped by the user `2fede99b-5ec7-4274-b990-469b4110f7ba` on the host `e4d4dc93-754e-4282-ac84-94fe72071ab1` running `dc00f5d9-bdf3-4517-b7ef-de5a89f0d071` version `14.5`. The executable path for the process is `/usr/libexec/biomesyncd`.\n\n#### Recommended Actions\n1. **Investigate the process**: Determine if the process `biomesyncd` is legitimate or potentially malicious.\n2. **Check user activity**: Review the actions performed by the user `2fede99b-5ec7-4274-b990-469b4110f7ba` around the time the process was stopped.\n3. **Analyze host behavior**: Examine the host `e4d4dc93-754e-4282-ac84-94fe72071ab1` for any other suspicious activities or anomalies.\n\n#### Triage Steps\n- **Review Process Details**:\n - Verify the legitimacy of the process `biomesyncd`.\n - Check the process arguments and executable path.\n- **User Activity Analysis**:\n - Investigate the user `2fede99b-5ec7-4274-b990-469b4110f7ba` for any unusual behavior.\n- **Host Analysis**:\n - Check for other suspicious processes or activities on the host `e4d4dc93-754e-4282-ac84-94fe72071ab1`.\n\n#### MITRE ATT&CK Context\n- **Technique**: [T1059.001 - Command and Scripting Interpreter: PowerShell](https://attack.mitre.org/techniques/T1059/001/)\n- **Tactic**: Execution\n\n#### Elastic Security Features\n- **Endpoint Response Actions**: Use Elastic Security's endpoint response actions to isolate the host or terminate suspicious processes.\n- **Elastic Agent OSQuery Manager Integration**: Utilize OSQuery to gather more information about the host and processes.\n - Example OSQuery Query:\n ```sql\n SELECT * FROM processes WHERE name = 'biomesyncd';\n ```\n- **Timelines**: Create a timeline to visualize the sequence of events and correlate with other activities.\n- **Entity Analytics**: Use entity analytics to assess the risk score of the user and host.\n\n#### Elastic Security Documentation\n- \[Endpoint Security\]\(https:\//www.elastic.co/guide/en/security/current/endpoint-security.html\)\n- \[OSQuery Manager\]\(https:\//www.elastic.co/guide/en/security/current/osquery-manager.html\)\n- \[Timelines\]\(https:\//www.elastic.co/guide/en/security/current/timelines.html\)\n- \[Entity Analytics\]\(https:\//www.elastic.co/guide/en/security/current/entity-analytics.html\)\n\n### ESQL Query\n```sql\nFROM process\nWHERE process.name == \"biomesyncd\"\n AND process.pid == 69516\n AND user.name == \"2fede99b-5ec7-4274-b990-469b4110f7ba\"\n AND host.name == \"e4d4dc93-754e-4282-ac84-94fe72071ab1\"\n AND host.os.version == \"14.5\"\n```\n\nThis query can be used in an Elastic Security timeline or detection rule to detect the stopping of the `biomesyncd` process by the specified user on the specified host.", - "trace_data": { - "transactionId": "293ad93379ace883", - "traceId": "eeedce3430c9ded8fb8dc38dcfd96eb4" - }, - "replacements": { - "dc00f5d9-bdf3-4517-b7ef-de5a89f0d071": "macOS", - "e4d4dc93-754e-4282-ac84-94fe72071ab1": "test-MBP", - "2fede99b-5ec7-4274-b990-469b4110f7ba": "usertest", - "661a7e8f-42c3-4f8c-a1bc-6ff1aa750034": "system" - }, - "status": "ok", - "conversationId": "df071e68-3c8e-4c0d-b0e7-1557e80c0319" -} --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON object with an LLM response, and a conversation ID if `persist` was set to `true`. - -*Example 3* - -Conversation response payload: - -[source,json] --------------------------------------------------- -{ - "connector_id": "my-gpt4o-ai", - "data": "### Elastic Security Case: Process Stopped Event\n\n#### Description\nA process named `biomesyncd` with PID `69516` was stopped by the user `2fede99b-5ec7-4274-b990-469b4110f7ba` on the host `e4d4dc93-754e-4282-ac84-94fe72071ab1` running `dc00f5d9-bdf3-4517-b7ef-de5a89f0d071` version `14.5`. The executable path for the process is `/usr/libexec/biomesyncd`.\n\n#### Recommended Actions\n1. **Investigate the process**: Determine if the process `biomesyncd` is legitimate or potentially malicious.\n2. **Check user activity**: Review the actions performed by the user `2fede99b-5ec7-4274-b990-469b4110f7ba` around the time the process was stopped.\n3. **Analyze host behavior**: Examine the host `e4d4dc93-754e-4282-ac84-94fe72071ab1` for any other suspicious activities or anomalies.\n\n#### Triage Steps\n- **Review Process Details**:\n - Verify the legitimacy of the process `biomesyncd`.\n - Check the process arguments and executable path.\n- **User Activity Analysis**:\n - Investigate the user `2fede99b-5ec7-4274-b990-469b4110f7ba` for any unusual behavior.\n- **Host Analysis**:\n - Check for other suspicious processes or activities on the host `e4d4dc93-754e-4282-ac84-94fe72071ab1`.\n\n#### MITRE ATT&CK Context\n- **Technique**: [T1059.001 - Command and Scripting Interpreter: PowerShell](https://attack.mitre.org/techniques/T1059/001/)\n- **Tactic**: Execution\n\n#### Elastic Security Features\n- **Endpoint Response Actions**: Use Elastic Security's endpoint response actions to isolate the host or terminate suspicious processes.\n- **Elastic Agent OSQuery Manager Integration**: Utilize OSQuery to gather more information about the host and processes.\n - Example OSQuery Query:\n ```sql\n SELECT * FROM processes WHERE name = 'biomesyncd';\n ```\n- **Timelines**: Create a timeline to visualize the sequence of events and correlate with other activities.\n- **Entity Analytics**: Use entity analytics to assess the risk score of the user and host.\n\n#### Elastic Security Documentation\n- \[Endpoint Security\]\(https:\//www.elastic.co/guide/en/security/current/endpoint-security.html\)\n- \[OSQuery Manager\]\(https:\//www.elastic.co/guide/en/security/current/osquery-manager.html\)\n- \[Timelines\]\(https:\//www.elastic.co/guide/en/security/current/timelines.html\)\n- \[Entity Analytics\]\(https:\//www.elastic.co/guide/en/security/current/entity-analytics.html\)\n\n### ESQL Query\n```sql\nFROM process\nWHERE process.name == \"biomesyncd\"\n AND process.pid == 69516\n AND user.name == \"2fede99b-5ec7-4274-b990-469b4110f7ba\"\n AND host.name == \"e4d4dc93-754e-4282-ac84-94fe72071ab1\"\n AND host.os.version == \"14.5\"\n```\n\nThis query can be used in an Elastic Security timeline or detection rule to detect the stopping of the `biomesyncd` process by the specified user on the specified host.", - "trace_data": { - "transactionId": "783ad93379ace778", - "traceId": "bbbdce3430c9ded8fb8dc38dcfd96eb4" - }, - "status": "ok", - "conversationId": "cb071e68-3c8e-4c0d-b0e7-1557e80c0316" -} --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON object with an LLM response, and a conversation ID if `persist` was set to `true`. diff --git a/docs/AI-for-security/api/conversation-api-create.asciidoc b/docs/AI-for-security/api/conversation-api-create.asciidoc deleted file mode 100644 index 5df8ee9a8e..0000000000 --- a/docs/AI-for-security/api/conversation-api-create.asciidoc +++ /dev/null @@ -1,154 +0,0 @@ -[[conversation-api-create]] -=== Create conversation - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Create a new Elastic AI Assistant conversation. - -[discrete] -=== Request URL - -`POST :/api/security_ai_assistant/current_user/conversations` - -[discrete] -=== Request body - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`title` |String |Conversation title. If you set it to "New chat", the AI will generate a title. |Yes -|`category` |String |Can be "assistant", "insights", or not defined. |No -|`isDefault` |Boolean |Define if conversation is a system conversation which cannot be deleted. Defaults to false. |No -|`excludeFromLastConversationStorage` |Boolean |Defines if conversation can appear as the latest conversation. |No -|`apiConfig` |<> |Conversation configuration. |No -|`messages` |<> |Array of conversation messages. |No -|`replacements` |Key, Value(String, String)|List of the fields with anonymization. |No -|============================================== - -[discrete] -[[create-apiconfig-obj]] -== `apiConfig` object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`connectorId` |String |Kibana connector ID. |Yes -|`actionTypeId` |String |Kibana connector action type ID. |Yes -|`defaultSystemPromptId` |String |Default system prompt ID. |Yes -|`model` |String |Specific LLM name. |No -|============================================== - -[discrete] -[[create-message-obj]] -== `messages` object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`role` |String |Message role. Can be "user", "assistant", or "system". |Yes -|`content` |String |Message content to send to LLM. |Yes -|`isError` |Boolean |Define if the message is an error message instead of an LLM response. |No -|`timestamp` |String |Timestamp when the message was sent. |No -|============================================== - -[discrete] -=== Example requests - -*Example 1* - -Creates a new conversation. - -[source,console] --------------------------------------------------- -POST api/security_ai_assistant/current_user/conversations -{ - "title": "The conversation title.", - "category": "assistant", - "messages": [ - { - "content": "test content", - "role": "user", - "isError": false, - "timestamp": "2019-12-13T16:40:33.400Z", - "traceData": { - "traceId": "1234", - "transactionId": "2" - } - } - ], - "apiConfig": { - "actionTypeId": ".gen-ai", - "connectorId": "86ab-471c-a00b-25b7e20c2d12", - "defaultSystemPromptId": "Default", - "model": "gpt-4o" - }, - "isDefault": false, - "excludeFromLastConversationStorage": true, - "replacements": { - "field1": "914beb92-86ab-471c-a00b" - } -} --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON conversation object with a unique `id`. - -*Example 1* - -Conversation response payload: - -[source,json] --------------------------------------------------- -{ - "id": "07805df2-6462-451a-b534-78da47873c42", - "title": "The conversation title.", - "category": "assistant", - "timestamp": "2024-07-29T06:58:15.670Z", - "updatedAt": "2024-07-29T06:58:15.670Z", - "createdAt": "2024-07-29T06:58:15.670Z", - "replacements": { - "field1": "914beb92-86ab-471c-a00b" - }, - "users": [ - { - "name": "elastic" - } - ], - "messages": [ - { - "content": "test content", - "role": "user", - "timestamp": "2019-12-13T16:40:33.400Z", - "traceData": { - "transactionId": "2", - "traceId": "1234" - } - } - ], - "apiConfig": { - "connectorId": "86ab-471c-a00b-25b7e20c2d12", - "actionTypeId": ".gen-ai", - "defaultSystemPromptId": "Default", - "model": "gpt-4o" - }, - "isDefault": false, - "excludeFromLastConversationStorage": true, - "namespace": "default" -} --------------------------------------------------- - diff --git a/docs/AI-for-security/api/conversation-api-delete.asciidoc b/docs/AI-for-security/api/conversation-api-delete.asciidoc deleted file mode 100644 index a84ffc5bba..0000000000 --- a/docs/AI-for-security/api/conversation-api-delete.asciidoc +++ /dev/null @@ -1,50 +0,0 @@ -[[conversation-api-delete]] -=== Delete conversation - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Delete an existing Elastic AI Assistant conversation by conversation ID. - -[discrete] -=== Request URL - -`DELETE :/api/security_ai_assistant/current_user/conversations/{id}` - - -[discrete] -=== Example requests - -*Example 1* - -Deletes an Elastic AI Assistant conversation with an `id` value of `df071e68-3c8e-4c0d-b0e7-1557e80c0319`: - -[source,console] --------------------------------------------------- -DELETE api/security_ai_assistant/current_user/conversations/df071e68-3c8e-4c0d-b0e7-1557e80c0319 - --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -An empty JSON object. - -*Example 1* - -Response payload: - -[source,json] --------------------------------------------------- -{} --------------------------------------------------- - diff --git a/docs/AI-for-security/api/conversation-api-find.asciidoc b/docs/AI-for-security/api/conversation-api-find.asciidoc deleted file mode 100644 index 8a7c9f1c8e..0000000000 --- a/docs/AI-for-security/api/conversation-api-find.asciidoc +++ /dev/null @@ -1,116 +0,0 @@ -[[conversation-api-find]] -=== Find conversations - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Retrieve a list of Elastic AI Assistant conversations for the current user. - -[discrete] -=== Request URL - -`GET :/api/security_ai_assistant/current_user/conversations/_find` - -==== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`page` |Number |The page number to return. Defaults to `1`. -|No -|`per_page` |Number |The number of items to return per page. Defaults to `10`. -|No -|`filter` |String |The filter query to apply on the request. -|No -|`sort_field` |String a|The field to sort the results by. Valid values are: - -* `title` -* `description` -* `updated` -* `created` - -|No -|`sort_order` |String a|The order to sort the results in. Valid values are: - -* `asc` -* `desc` - -|No -|`fields` |String a|Defines the fields of the document to return in the response. - -|No - -|============================================== - -[discrete] -=== Example requests - -*Example 1* - -Get a list of the current user's conversations. - -[source,console] --------------------------------------------------- -GET api/security_ai_assistant/current_user/conversations/_find?page=1&per_page=100 --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON conversation object with a unique `id`. - -*Example 1* - -Conversation response payload: - -[source,json] --------------------------------------------------- -{ - "perPage": 20, - "page": 1, - "total": 1, - "data": [ - { - "timestamp": "2024-08-02T07:19:08.124Z", - "createdAt": "2024-08-02T07:19:08.124Z", - "users": [ - { - "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0", - "name": "elastic" - } - ], - "title": "The conversation title.", - "category": "assistant", - "apiConfig": { - "connectorId": "86ab-471c-a00b-25b7e20c2d12", - "actionTypeId": ".gen-ai", - "defaultSystemPromptId": "Default", - "model": "gpt-4o" - }, - "isDefault": true, - "messages": [ - { - "timestamp": "2019-12-13T16:40:33.400Z", - "content": "test content", - "role": "user" - } - ], - "updatedAt": "2024-08-02T07:39:45.129Z", - "replacements": {}, - "namespace": "default", - "id": "a696901d-efff-4871-acbe-8123af841932" - } - ] -} --------------------------------------------------- - diff --git a/docs/AI-for-security/api/conversation-api-get.asciidoc b/docs/AI-for-security/api/conversation-api-get.asciidoc deleted file mode 100644 index 07d932eb2d..0000000000 --- a/docs/AI-for-security/api/conversation-api-get.asciidoc +++ /dev/null @@ -1,69 +0,0 @@ -[[conversation-api-get]] -=== Get conversation - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Retrieve an existing Elastic AI Assistant conversation by conversation ID. - -[discrete] -=== Request URL - -`GET :/api/security_ai_assistant/current_user/conversations/{id}` - -[discrete] -=== Example requests - -*Example 1* - -Retrieves an Elastic AI Assistant conversation with an `id` value of `a696901d-efff-4871-acbe-8123af841932`: - -[source,console] --------------------------------------------------- -GET api/security_ai_assistant/current_user/conversations/a696901d-efff-4871-acbe-8123af841932 --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON conversation object with a unique `id`. - -*Example 1* - -Conversation response payload: - -[source,json] --------------------------------------------------- -{ - "timestamp": "2024-08-02T07:19:08.124Z", - "createdAt": "2024-08-02T07:19:08.124Z", - "users": [ - { - "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0", - "name": "elastic" - } - ], - "title": "Welcome", - "category": "assistant", - "apiConfig": { - "connectorId": "my-gpt4o-ai", - "actionTypeId": ".gen-ai" - }, - "isDefault": true, - "messages": [], - "updatedAt": "2024-08-02T07:19:08.124Z", - "replacements": {}, - "namespace": "default", - "id": "a696901d-efff-4871-acbe-8123af841932" -} --------------------------------------------------- - diff --git a/docs/AI-for-security/api/conversation-api-update.asciidoc b/docs/AI-for-security/api/conversation-api-update.asciidoc deleted file mode 100644 index eb2c5b9a93..0000000000 --- a/docs/AI-for-security/api/conversation-api-update.asciidoc +++ /dev/null @@ -1,135 +0,0 @@ -[[conversation-api-update]] -=== Update conversation - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Update an existing Elastic AI Assistant conversation by conversation ID. - -==== Request URL - -`PUT :/api/security_ai_assistant/current_user/conversations/{id}` - -==== Request body - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required -|`id` |String |Conversation ID to update. |Yes -|`title` |String |Conversation title. If you set it to "New chat", the AI will generate a title. |No -|`apiConfig` |<> |Conversation configuration. |No -|`messages` |<> |Array of conversation messages. |No -|`replacements` |Key, Value(String, String)|List of the fields with anonymization. |No -|============================================== - - -[discrete] -[[update-ApiConfig-obj]] -== `apiConfig` object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`connectorId` |String |Kibana connector ID. |No -|`actionTypeId` |String |Kibana connector action type ID. |No -|`defaultSystemPromptId` |String |Default system prompt ID. |No -|`model` |String |LLM specific model. |No -|============================================== - -[discrete] -[[update-message-obj]] -== `messages` object - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`role` |String |Message role. Can be "user", "assistant", or "system". |Yes -|`content` |String |Message content to send to LLM. |Yes -|`isError` |Boolean |Define if the message is an error message instead of an LLM response. |No -|`timestamp` |String |Timestamp when the message was sent. |No -|============================================== - -[discrete] -=== Example requests - -*Example 1* - -Updates an existing Elastic AI Assistant conversation with an `id` value of `a696901d-efff-4871-acbe-8123af841932` - -[source,console] --------------------------------------------------- -PUT api/security_ai_assistant/current_user/conversations/a696901d-efff-4871-acbe-8123af841932 -{ - "id": "a696901d-efff-4871-acbe-8123af841932", - "title": "The conversation title.", - "messages": [ - { - "content": "test content", - "role": "user", - "isError": false, - "timestamp": "2019-12-13T16:40:33.400Z" - } - ], - "apiConfig": { - "actionTypeId": ".gen-ai", - "connectorId": "86ab-471c-a00b-25b7e20c2d12", - "defaultSystemPromptId": "Default", - "model": "gpt-4o" - } -} --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON conversation object with a unique `id`. - -*Example 1* - -Conversation response payload: - -[source,json] --------------------------------------------------- -{ - "timestamp": "2024-08-02T07:19:08.124Z", - "createdAt": "2024-08-02T07:19:08.124Z", - "users": [ - { - "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0", - "name": "elastic" - } - ], - "title": "The conversation title.", - "category": "assistant", - "apiConfig": { - "connectorId": "86ab-471c-a00b-25b7e20c2d12", - "actionTypeId": ".gen-ai", - "defaultSystemPromptId": "Default", - "model": "gpt-4o" - }, - "isDefault": true, - "messages": [ - { - "timestamp": "2019-12-13T16:40:33.400Z", - "content": "test content", - "role": "user" - } - ], - "updatedAt": "2024-08-02T07:39:45.129Z", - "replacements": {}, - "namespace": "default", - "id": "a696901d-efff-4871-acbe-8123af841932" -} --------------------------------------------------- - diff --git a/docs/AI-for-security/api/prompts-api-find.asciidoc b/docs/AI-for-security/api/prompts-api-find.asciidoc deleted file mode 100644 index bdc641e8c5..0000000000 --- a/docs/AI-for-security/api/prompts-api-find.asciidoc +++ /dev/null @@ -1,250 +0,0 @@ -[[prompts-api-find]] -=== Find prompts - -.New API Reference -[sidebar] --- -For the most up-to-date API details, refer to {api-kibana}/group/endpoint-security-ai-assistant-api[AI Assistant APIs]. --- - -Retrieve a list of Elastic AI Assistant prompts. - -[discrete] -=== Request URL - -`GET :/api/security_ai_assistant/prompts/_find` - -==== URL query parameters - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`page` |Number |The page number to return. Defaults to `1`. -|No -|`per_page` |Number |The number of items to return per page. Defaults to `10`. -|No -|`filter` |String |The filter query to apply on the request. -|No -|`sort_field` |String a|The field to sort the results by. Valid values are: - -* `name` -* `is_default` -* `updated_at` -* `created_at` - -|No -|`sort_order` |String a|The order to sort the results in. Valid values are: - -* `asc` -* `desc` - -|No -|`fields` |String a|Defines the fields of the document to return in the response. - -|No - -|============================================== - -[discrete] -=== Example requests - -*Example 1* - -Get a list of the system and quick (user) prompts for all consumers. - -[source,console] --------------------------------------------------- -GET api/security_ai_assistant/prompts/_find?page=1&per_page=100&filter=consumer%3A* --------------------------------------------------- - -[discrete] -=== Response code - -`200` - Indicates a successful call. - -[discrete] -=== Response payload - -A JSON prompt object with a unique `id`. - -*Example 1* - -Prompts response payload: - -[source,json] --------------------------------------------------- -{ - "perPage": 100, - "page": 1, - "total": 9, - "data": [ - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "As an expert in security operations and incident response, provide a breakdown of the attached alert and summarize what it might mean for my organization.", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "-R12SZEBYaDeA-NhnUyW", - "name": "Alert summarization", - "promptType": "quick", - "color": "#F68FBE", - "categories": [ - "alert" - ], - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0", - "name": "elastic" - } - ], - "content": "As an expert user of Elastic Security, please generate an accurate and valid ESQL query to detect the use case below. Your response should be formatted to be able to use immediately in an Elastic Security timeline or detection rule. Take your time with the answer, check your knowledge really well on all the functions I am asking for. For ES|QL answers specifically, you should only ever answer with what's available in your private knowledge. I cannot afford for queries to be inaccurate. Assume I am using the Elastic Common Schema and Elastic Agent.\n\nEnsure the answers are formatted in a way which is easily copyable as a separate code block in markdown.", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "-h12SZEBYaDeA-NhnUyW", - "name": "ES|QL Query Generation", - "promptType": "quick", - "color": "#9170B8", - "categories": [ - "knowledge-base" - ], - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "As an expert user of Elastic Security, please generate an accurate and valid EQL query to detect the use case below. Your response should be formatted to be able to use immediately in an Elastic Security timeline or detection rule. If Elastic Security already has a prebuilt rule for the use case, or a similar one, please provide a link to it and describe it.", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "-x12SZEBYaDeA-NhnUyW", - "name": "Query generation", - "promptType": "quick", - "color": "#7DDED8", - "categories": [ - "detection-rules" - ], - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "As an expert user of Elastic Security, please suggest a workflow, with step by step instructions on how to:", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "_B12SZEBYaDeA-NhnUyW", - "name": "Workflow suggestions", - "promptType": "quick", - "color": "#36A2EF", - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "As an expert user of Elastic Security, Elastic Agent, and Ingest pipelines, please list accurate and formatted, step by step instructions on how to ingest the following data using Elastic Agent and Fleet in Kibana and convert it to the Elastic Common Schema:", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "_R12SZEBYaDeA-NhnUyW", - "name": "Custom data ingestion helper", - "promptType": "quick", - "color": "#F3D371", - "categories": [ - "event" - ], - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "I have the following query from a previous SIEM platform. As an expert user of Elastic Security, please suggest an Elastic EQL equivalent. I should be able to copy it immediately into an Elastic security timeline.", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "_h12SZEBYaDeA-NhnUyW", - "name": "Query conversion", - "promptType": "quick", - "color": "#BADA55", - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "Which Fleet enabled Elastic Agent integration should I use to collect logs and events from:", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "_x12SZEBYaDeA-NhnUyW", - "name": "Agent integration advice", - "promptType": "quick", - "color": "#FFA500", - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "You are a helpful, expert assistant who answers questions about Elastic Security. Do not answer questions unrelated to Elastic Security.\nIf you answer a question related to KQL, EQL, or ES|QL, it should be immediately usable within an Elastic Security timeline; please always format the output correctly with back ticks. Any answer provided for Query DSL should also be usable in a security timeline. This means you should only ever include the \"filter\" portion of the query.", - "isDefault": true, - "isNewConversationDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "AB12SZEBYaDeA-NhnU2W", - "name": "Default system prompt", - "promptType": "system", - "consumer": "securitySolutionUI" - }, - { - "timestamp": "2024-08-13T01:59:56.053Z", - "users": [ - { - "id": "testid", - "name": "elastic" - } - ], - "content": "You are a helpful, expert assistant who answers questions about Elastic Security. Do not answer questions unrelated to Elastic Security.\nProvide the most detailed and relevant answer possible, as if you were relaying this information back to a cyber security expert.\nIf you answer a question related to KQL, EQL, or ES|QL, it should be immediately usable within an Elastic Security timeline; please always format the output correctly with back ticks. Any answer provided for Query DSL should also be usable in a security timeline. This means you should only ever include the \"filter\" portion of the query.", - "isDefault": true, - "updatedAt": "2024-08-13T01:59:56.053Z", - "id": "AR12SZEBYaDeA-NhnU2W", - "name": "Enhanced system prompt", - "promptType": "system", - "consumer": "securitySolutionUI" - } - ] -} --------------------------------------------------- - diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index a46a879f82..624aaa45ea 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -18,7 +18,7 @@ NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API end * {api-kibana}/group/endpoint-security-lists-api[Lists API]: Create source event value lists for use with rule exceptions * {api-kibana}/group/endpoint-security-timeline-api[Timeline API]: Import and export timelines * {api-kibana}/group/endpoint-cases[Cases API]: Open and manage cases -* <>: Interact with and manage Elastic AI Assistant +* {api-kibana}/group/endpoint-security-ai-assistant-api[Elastic AI Assistant API]: Interact with and manage Elastic AI Assistant * {api-kibana}/group/endpoint-security-entity-analytics-api[Entity Analytics API]: Manage Entity Analytics features, such as asset criticality and entity store. Additionally, the {kib} {api-kibana}/group/endpoint-connectors[Connectors API] enables opening and updating cases in external ticketing systems. @@ -97,8 +97,6 @@ include::detections/api/det-api-index.asciidoc[] include::detections/api/signals-migration-api.asciidoc[] -include::AI-for-security/api/ai-for-security-index.asciidoc[] - NOTE: For the {fleet} APIs, see the {fleet-guide}/fleet-api-docs.html[Fleet API Documentation].