diff --git a/docs/AI-for-security/api/ai-for-security-index.asciidoc b/docs/AI-for-security/api/ai-for-security-index.asciidoc new file mode 100644 index 0000000000..ce2229c421 --- /dev/null +++ b/docs/AI-for-security/api/ai-for-security-index.asciidoc @@ -0,0 +1,14 @@ +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[] + diff --git a/docs/AI-for-security/api/assistant-api-overview.asciidoc b/docs/AI-for-security/api/assistant-api-overview.asciidoc new file mode 100644 index 0000000000..af646679f0 --- /dev/null +++ b/docs/AI-for-security/api/assistant-api-overview.asciidoc @@ -0,0 +1,5 @@ +[[assistant-api-overview]] +[role="xpack"] +== Elastic AI Assistant API + +The Elastic AI Assistant API allows you to interact with and manage Elastic AI Assistant. diff --git a/docs/AI-for-security/api/chat-complete-api.asciidoc b/docs/AI-for-security/api/chat-complete-api.asciidoc new file mode 100644 index 0000000000..2c6ffd1352 --- /dev/null +++ b/docs/AI-for-security/api/chat-complete-api.asciidoc @@ -0,0 +1,235 @@ +[[chat-complete-api]] +=== Complete chat + +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 new file mode 100644 index 0000000000..4784035051 --- /dev/null +++ b/docs/AI-for-security/api/conversation-api-create.asciidoc @@ -0,0 +1,148 @@ +[[conversation-api-create]] +=== Create conversation + +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 new file mode 100644 index 0000000000..981676a3cc --- /dev/null +++ b/docs/AI-for-security/api/conversation-api-delete.asciidoc @@ -0,0 +1,44 @@ +[[conversation-api-delete]] +=== Delete conversation + +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 new file mode 100644 index 0000000000..99cb9b4305 --- /dev/null +++ b/docs/AI-for-security/api/conversation-api-find.asciidoc @@ -0,0 +1,110 @@ +[[conversation-api-find]] +=== Find conversations + +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 new file mode 100644 index 0000000000..67869b1efc --- /dev/null +++ b/docs/AI-for-security/api/conversation-api-get.asciidoc @@ -0,0 +1,63 @@ +[[conversation-api-get]] +=== Get conversation + +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 new file mode 100644 index 0000000000..89f935216f --- /dev/null +++ b/docs/AI-for-security/api/conversation-api-update.asciidoc @@ -0,0 +1,129 @@ +[[conversation-api-update]] +=== Update conversation + +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/siem-apis.asciidoc b/docs/siem-apis.asciidoc index e1fbaefd9c..a0a2f8e930 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -13,6 +13,7 @@ NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API end * <>: Create source event value lists for use with rule exceptions * <>: Import and export timelines * <>: Open and manage cases +* <>: Interact with and manage Elastic AI Assistant * <>: Create and manage asset criticality records Additionally, the {kib} <> is partially @@ -104,6 +105,8 @@ include::cases/api/actions-api/cases-actions-api-index.asciidoc[] include::management/api/management-api-index.asciidoc[] +include::AI-for-security/api/ai-for-security-index.asciidoc[] + include::advanced-entity-analytics/api/asset-criticality-api-index.asciidoc[] NOTE: For the {fleet} APIs, see the