From 176698d8819d5c1f3961bd3614d8641356ead181 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 25 Nov 2024 18:43:08 -0800 Subject: [PATCH 1/2] [Security][OpenAPI] Improve exceptions intro --- .../scripts/openapi_bundle.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/kbn-securitysolution-exceptions-common/scripts/openapi_bundle.js b/packages/kbn-securitysolution-exceptions-common/scripts/openapi_bundle.js index 83c84d91daaf5..874e1096df892 100644 --- a/packages/kbn-securitysolution-exceptions-common/scripts/openapi_bundle.js +++ b/packages/kbn-securitysolution-exceptions-common/scripts/openapi_bundle.js @@ -59,7 +59,7 @@ const ROOT = resolve(__dirname, '..'); name: 'Security Exceptions API', 'x-displayName': 'Security exceptions', description: - "Exceptions API allows you to manage detection rule exceptions to prevent a rule from generating an alert from incoming events even when the rule's other criteria are met.", + "Exceptions are associated with detection and endpoint rules, and are used to prevent a rule from generating an alert from incoming events even when the rule's other criteria are met. They can be used to reduce the number of false positives, and to prevent trusted processes and network activity from generating unnecessary alerts. \n\nExceptions are made up of:\n\n* Exception containers: A container for related exceptions. In general, a single exception container contains all the exception items relevant for a subset of rules. For example, a container can be used to group together network-related exceptions that are relevant for a large number of network rules. The container can then be associated with all the relevant rules.\n* Exception items: The query (fields, values, and logic) used to prevent rules from generating alerts. When an exception item's query evaluates to true, the rule does not generate an alert.\nFor detection rules, you can also use lists to define rule exceptions. A list holds multiple values of the same Elasticsearch data type, such as IP addresses, which are used to determine when an exception prevents an alert from being generated.\n\nIMPORTANT: You cannot use lists with endpoint rule exceptions.\n\nNOTE: Only exception containers can be associated with rules. You cannot directly associate an exception item or a list container with a rule. To use list exceptions, create an exception item that references the relevant list container.\n\n## Exceptions requirements\n\nBefore you start working with exceptions that use value lists, you must create the `.lists` and `.items` data streams for the relevant Kibana space. To learn how to do this, go to Lists index endpoint.\nOnce these data streams are created, your role needs privileges to manage rules. Refer to Enable and access detections for a complete list of requirements.", }, ], }, From 3ea15b5835e70779f4e378e5a782a38d1db9a857 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 26 Nov 2024 07:45:08 -0800 Subject: [PATCH 2/2] [DOCS][API] Generate output --- oas_docs/output/kibana.yaml | 18 ++++++- ...eptions_api_2023_10_31.bundled.schema.yaml | 48 +++++++++++++++++-- 2 files changed, 62 insertions(+), 4 deletions(-) diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 208bced5d70f6..1c4fe52e26491 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -141,7 +141,23 @@ tags: - description: '' name: Security Entity Analytics API x-displayName: Security entity analytics - - description: Exceptions API allows you to manage detection rule exceptions to prevent a rule from generating an alert from incoming events even when the rule's other criteria are met. + - description: |- + Exceptions are associated with detection and endpoint rules, and are used to prevent a rule from generating an alert from incoming events even when the rule's other criteria are met. They can be used to reduce the number of false positives, and to prevent trusted processes and network activity from generating unnecessary alerts. + + Exceptions are made up of: + + * Exception containers: A container for related exceptions. In general, a single exception container contains all the exception items relevant for a subset of rules. For example, a container can be used to group together network-related exceptions that are relevant for a large number of network rules. The container can then be associated with all the relevant rules. + * Exception items: The query (fields, values, and logic) used to prevent rules from generating alerts. When an exception item's query evaluates to true, the rule does not generate an alert. + For detection rules, you can also use lists to define rule exceptions. A list holds multiple values of the same Elasticsearch data type, such as IP addresses, which are used to determine when an exception prevents an alert from being generated. + + IMPORTANT: You cannot use lists with endpoint rule exceptions. + + NOTE: Only exception containers can be associated with rules. You cannot directly associate an exception item or a list container with a rule. To use list exceptions, create an exception item that references the relevant list container. + + ## Exceptions requirements + + Before you start working with exceptions that use value lists, you must create the `.lists` and `.items` data streams for the relevant Kibana space. To learn how to do this, go to Lists index endpoint. + Once these data streams are created, your role needs privileges to manage rules. Refer to Enable and access detections for a complete list of requirements. name: Security Exceptions API x-displayName: Security exceptions - description: Lists API allows you to manage lists of keywords, IPs or IP ranges items. diff --git a/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml index bf290e872f915..3a764e816e8cb 100644 --- a/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml @@ -1900,8 +1900,50 @@ security: - BasicAuth: [] tags: - description: >- - Exceptions API allows you to manage detection rule exceptions to prevent a - rule from generating an alert from incoming events even when the rule's - other criteria are met. + Exceptions are associated with detection and endpoint rules, and are used + to prevent a rule from generating an alert from incoming events even when + the rule's other criteria are met. They can be used to reduce the number + of false positives, and to prevent trusted processes and network activity + from generating unnecessary alerts. + + + Exceptions are made up of: + + + * Exception containers: A container for related exceptions. In general, a + single exception container contains all the exception items relevant for a + subset of rules. For example, a container can be used to group together + network-related exceptions that are relevant for a large number of network + rules. The container can then be associated with all the relevant rules. + + * Exception items: The query (fields, values, and logic) used to prevent + rules from generating alerts. When an exception item's query evaluates to + true, the rule does not generate an alert. + + For detection rules, you can also use lists to define rule exceptions. A + list holds multiple values of the same Elasticsearch data type, such as IP + addresses, which are used to determine when an exception prevents an alert + from being generated. + + + IMPORTANT: You cannot use lists with endpoint rule exceptions. + + + NOTE: Only exception containers can be associated with rules. You cannot + directly associate an exception item or a list container with a rule. To + use list exceptions, create an exception item that references the relevant + list container. + + + ## Exceptions requirements + + + Before you start working with exceptions that use value lists, you must + create the `.lists` and `.items` data streams for the relevant Kibana + space. To learn how to do this, go to Lists index endpoint. + + Once these data streams are created, your role needs privileges to manage + rules. Refer to Enable and access detections for a complete list of + requirements. name: Security Exceptions API x-displayName: Security exceptions