diff --git a/docs/advanced-entity-analytics/api/asset-criticality-api-bulk-upsert.asciidoc b/docs/advanced-entity-analytics/api/asset-criticality-api-bulk-upsert.asciidoc new file mode 100644 index 0000000000..d1d86c9688 --- /dev/null +++ b/docs/advanced-entity-analytics/api/asset-criticality-api-bulk-upsert.asciidoc @@ -0,0 +1,78 @@ +[[asset-criticality-api-bulk-upsert]] +=== Bulk upsert (create or update) asset criticality records + +Create or update asset criticality records for multiple entities. + +If asset criticality records already exist for the entities specified in the request, this API overwrites those records with the specified values. + +If asset criticality records don't exist for the specified entities, new records are created. + +==== Request URL + +`POST :/api/asset_criticality/bulk` + +==== Request body + +A JSON object defining the asset criticality records. + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required +|`records` |Array |Array of asset criticality records to be created or updated. The maximum number of records is 1000. +|Yes +|`records.id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`. +|Yes +|`records.id_value` |String |The ID (host name or user name) of the entity specified in the `records.id_field` field. +|Yes +|`records.criticality_level` |String a|The asset criticality level to assign, which must be one of the following: + +* `low_impact` +* `medium_impact` +* `high_impact` +* `extreme_impact` + +For example, you can assign `extreme_impact` to business-critical entities, or `low_impact` to entities that pose minimal risk to your security posture. +|Yes +|============================================== + +===== Example requests + +[source,console] +-------------------------------------------------- +POST /api/asset_criticality/bulk +{ + "records": [ + { + "id_field": "host.name", + "id_value": "my_host", + "criticality_level": "medium_impact" + }, + { + "id_field": "host.name", + "id_value": "my_other_host", + "criticality_level": "low_impact" + } + ] +} +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. + +==== Example response + +Successful response + +[source,json] +-------------------------------------------------- +{ + "errors": [], + "stats": { + "successful": 2, + "failed": 0, + "total": 2 + } +} +-------------------------------------------------- diff --git a/docs/advanced-entity-analytics/api/asset-criticality-api-delete.asciidoc b/docs/advanced-entity-analytics/api/asset-criticality-api-delete.asciidoc new file mode 100644 index 0000000000..6604b2db28 --- /dev/null +++ b/docs/advanced-entity-analytics/api/asset-criticality-api-delete.asciidoc @@ -0,0 +1,64 @@ +[[delete-criticality-api-delete]] +=== Delete asset criticality record + +Delete a single asset criticality record by ID field and ID value. + +==== Request URL + +`DELETE :/api/asset_criticality` + +==== URL query parameters + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`. +|Yes +|`id_value` |String |The ID (host name or user name) of the entity specified in the `id_field` field. +|Yes + +|============================================== + +===== Example requests + +[source,console] +-------------------------------------------------- +DELETE /api/asset_criticality?id_field=host.name&id_value=my_host + +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. Check the response body to see if the record was deleted. + +==== Example responses + +*Example 1* + +If the record was deleted. + +[source,json] +-------------------------------------------------- +{ + "deleted": true, + "record": { + "id_field": "host.name", + "id_value": "my_host", + "criticality_level": "medium_impact", + "@timestamp": "2024-08-05T09:42:11.240Z" + } +} +-------------------------------------------------- + +*Example 2* + +If the record was not found and could not be deleted. + +[source,json] +-------------------------------------------------- +{ + "deleted": false +} +-------------------------------------------------- diff --git a/docs/advanced-entity-analytics/api/asset-criticality-api-get.asciidoc b/docs/advanced-entity-analytics/api/asset-criticality-api-get.asciidoc new file mode 100644 index 0000000000..1cb4752b7f --- /dev/null +++ b/docs/advanced-entity-analytics/api/asset-criticality-api-get.asciidoc @@ -0,0 +1,48 @@ +[[asset-criticality-api-get]] +=== Get asset criticality record + +Retrieve a single asset criticality record by ID field and ID value. + +==== Request URL + +`GET :/api/asset_criticality` + +==== URL query parameters + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`. +|Yes +|`id_value` |String |The ID (host name or user name) of the entity specified in the `id_field` field. +|Yes + +|============================================== + +===== Example requests + +[source,console] +-------------------------------------------------- +GET /api/asset_criticality?id_field=host.name&id_value=my_host + +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. +`404`:: + Indicates the criticality record was not found. + +==== Example response + +[source,json] +-------------------------------------------------- +{ + "id_field": "host.name", + "id_value": "my_host", + "criticality_level": "high_impact", + "@timestamp": "2024-08-02T11:15:34.290Z" +} +-------------------------------------------------- diff --git a/docs/advanced-entity-analytics/api/asset-criticality-api-index.asciidoc b/docs/advanced-entity-analytics/api/asset-criticality-api-index.asciidoc new file mode 100644 index 0000000000..8f6448e023 --- /dev/null +++ b/docs/advanced-entity-analytics/api/asset-criticality-api-index.asciidoc @@ -0,0 +1,11 @@ +include::asset-criticality-api-overview.asciidoc[] + +include::asset-criticality-api-upsert.asciidoc[] + +include::asset-criticality-api-bulk-upsert.asciidoc[] + +include::asset-criticality-api-get.asciidoc[] + +include::asset-criticality-api-list.asciidoc[] + +include::asset-criticality-api-delete.asciidoc[] diff --git a/docs/advanced-entity-analytics/api/asset-criticality-api-list.asciidoc b/docs/advanced-entity-analytics/api/asset-criticality-api-list.asciidoc new file mode 100644 index 0000000000..67dc37f549 --- /dev/null +++ b/docs/advanced-entity-analytics/api/asset-criticality-api-list.asciidoc @@ -0,0 +1,72 @@ +[[asset-criticality-api-list]] +=== List asset criticality records + +Retrieve a list of asset criticality records. + +Use the query parameters to filter and sort the results as needed. By default, the first page is returned, with 10 results per page. + +==== Request URL + +`GET :/api/asset_criticality/list` + +==== URL query parameters + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`sort_field` |String a|The field to sort the results by, which must be one of the following: + +* `id_value` +* `id_field` +* `criticality_level` +* `@timestamp` + +|No +|`sort_direction` |String |The order to sort the results in, which must be either `asc` or `desc`. +|No +|`page` |Number | The page number to return, which must be at least 1. Defaults to `1`. +|No +|`per_page` |Number |The number of results to return per page, which must be between 1 and 1000. Defaults to `10`. +|No +|`kuery` |String a|A KQL query to filter results by, for example `criticality_level:low_impact OR criticality_level:medium_impact` +|No +|============================================== + +===== Example requests + +[source,console] +-------------------------------------------------- +GET api/asset_criticality/list?kuery=criticality_level:high_impact%20OR%20criticality_level:medium_impact + +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. + +==== Example response + +[source,json] +-------------------------------------------------- +{ + "records": [ + { + "id_field": "host.name", + "id_value": "my_other_host", + "criticality_level": "medium_impact", + "@timestamp": "2024-08-02T14:40:35.705Z" + }, + { + "id_field": "host.name", + "id_value": "my_host", + "criticality_level": "high_impact", + "@timestamp": "2024-08-02T11:15:34.290Z" + } + ], + "total": 2, + "page": 1, + "per_page": 10 +} +-------------------------------------------------- diff --git a/docs/advanced-entity-analytics/api/asset-criticality-api-overview.asciidoc b/docs/advanced-entity-analytics/api/asset-criticality-api-overview.asciidoc new file mode 100644 index 0000000000..22c657b031 --- /dev/null +++ b/docs/advanced-entity-analytics/api/asset-criticality-api-overview.asciidoc @@ -0,0 +1,5 @@ +[[asset-criticality-api-overview]] +[role="xpack"] +== Asset criticality API + +You can manage <> records through the API. To use this API, you must first turn on the `securitySolution:enableAssetCriticality` <>. \ No newline at end of file diff --git a/docs/advanced-entity-analytics/api/asset-criticality-api-upsert.asciidoc b/docs/advanced-entity-analytics/api/asset-criticality-api-upsert.asciidoc new file mode 100644 index 0000000000..17e248da5a --- /dev/null +++ b/docs/advanced-entity-analytics/api/asset-criticality-api-upsert.asciidoc @@ -0,0 +1,63 @@ +[[asset-criticality-api-upsert]] +=== Upsert (create or update) asset criticality record + +Create or update an asset criticality record. + +If an asset criticality record already exists for the entity specified in the request, this API overwrites that record with the specified value. + +If an asset criticality record doesn't exist for the specified entity, a new record is created. + +==== Request URL + +`POST :/api/asset_criticality` + +==== Request body + +A JSON object defining the asset criticality record. + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required +|`id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`. +|Yes +|`id_value` |String |The ID (host name or user name) of the entity specified in the `id_field` field. +|Yes +|`criticality_level` |String a|The asset criticality level to assign, which must be one of the following: + +* `low_impact` +* `medium_impact` +* `high_impact` +* `extreme_impact` + +For example, you can assign `extreme_impact` to business-critical entities, or `low_impact` to entities that pose minimal risk to your security posture. +|Yes +|============================================== + +===== Example requests + +[source,console] +-------------------------------------------------- +POST /api/asset_criticality +{ + "id_field": "host.name", + "id_value": "my_host", + "criticality_level": "high_impact" +} +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. + +==== Example response + +[source,json] +-------------------------------------------------- +{ + "id_field": "host.name", + "id_value": "my_host", + "criticality_level": "high_impact", + "@timestamp": "2024-08-02T11:15:34.290Z" +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/advanced-entity-analytics/asset-criticality.asciidoc b/docs/advanced-entity-analytics/asset-criticality.asciidoc index 40f52656e7..111b0d5561 100644 --- a/docs/advanced-entity-analytics/asset-criticality.asciidoc +++ b/docs/advanced-entity-analytics/asset-criticality.asciidoc @@ -26,7 +26,7 @@ For example, you can assign **Extreme impact** to business-critical entities, or [discrete] == View and assign asset criticality -Entities do not have a default asset criticality level. You can either assign asset criticality to your entities individually, or <> it to multiple entities by importing a text file. +Entities do not have a default asset criticality level. You can either assign asset criticality to your entities individually, or <> it to multiple entities by importing a text file. Alternatively, you can assign and manage asset criticality records through the <>. When you assign, change, or unassign an individual entity's asset criticality level, that entity's risk score is immediately recalculated. diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index f5a0130079..e1fbaefd9c 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 +* <>: Create and manage asset criticality records Additionally, the {kib} <> is partially documented to enable opening and updating cases in external ticketing systems. @@ -103,5 +104,7 @@ include::cases/api/actions-api/cases-actions-api-index.asciidoc[] include::management/api/management-api-index.asciidoc[] +include::advanced-entity-analytics/api/asset-criticality-api-index.asciidoc[] + NOTE: For the {fleet} APIs, see the {fleet-guide}/fleet-api-docs.html[Fleet API Documentation].