From aaaef2e789be7c41b13d999c2ed92612a6c92458 Mon Sep 17 00:00:00 2001 From: Georgii Gorbachev Date: Wed, 21 Jun 2023 20:12:04 +0200 Subject: [PATCH] [Security Solution] Improve READMEs for the Detection Engine health API (#160137) **Partially addresses:** https://github.com/elastic/kibana/issues/125642 ## Summary - fixes typos noticed by @maximpn in https://github.com/elastic/kibana/pull/159970#discussion_r1235076969 - adds additional docs for https://github.com/elastic/kibana/pull/159875 --- .../api/detection_engine_health/README.md | 4 +- .../api/detection_engine_health/README.md | 3 ++ .../logic/detection_engine_health/README.md | 48 +++++++++++++++++++ 3 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/api/detection_engine_health/README.md create mode 100644 x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/logic/detection_engine_health/README.md diff --git a/x-pack/plugins/security_solution/common/detection_engine/rule_monitoring/api/detection_engine_health/README.md b/x-pack/plugins/security_solution/common/detection_engine/rule_monitoring/api/detection_engine_health/README.md index 5456d3542aaff..81ee936e714fe 100644 --- a/x-pack/plugins/security_solution/common/detection_engine/rule_monitoring/api/detection_engine_health/README.md +++ b/x-pack/plugins/security_solution/common/detection_engine/rule_monitoring/api/detection_engine_health/README.md @@ -381,7 +381,7 @@ Minimal required parameters for the `POST` route: empty object. {} ``` -The `GET` route don't accept any parameters and use the default parameters instead: +The `GET` route doesn't accept any parameters and uses the default parameters instead: - interval: `last_day` - granularity: `hour` @@ -737,7 +737,7 @@ Minimal required parameters for the `POST` route: empty object. {} ``` -The `GET` route don't accept any parameters and use the default parameters instead: +The `GET` route doesn't accept any parameters and uses the default parameters instead: - interval: `last_day` - granularity: `hour` diff --git a/x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/api/detection_engine_health/README.md b/x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/api/detection_engine_health/README.md new file mode 100644 index 0000000000000..f8b13affd4082 --- /dev/null +++ b/x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/api/detection_engine_health/README.md @@ -0,0 +1,3 @@ +# Detection Engine health API + +See [README](../../../../../../common/detection_engine/rule_monitoring/api/detection_engine_health/README.md) in the common folder. diff --git a/x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/logic/detection_engine_health/README.md b/x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/logic/detection_engine_health/README.md new file mode 100644 index 0000000000000..8f19a0759c7eb --- /dev/null +++ b/x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/logic/detection_engine_health/README.md @@ -0,0 +1,48 @@ +# Detection Engine health logic + +See [README](../../../../../../common/detection_engine/rule_monitoring/api/detection_engine_health/README.md) in the common folder for info about the Detection Engine health API. + +This logic provides the following functionality via the `IDetectionEngineHealthClient` interface: + +- Calculating health snapshots for different "slices" of rules in the cluster: + - the whole cluster: all detection rules in all Kibana spaces + - a given space: all rules in the current Kibana space + - a given rule: an individual rule specified by id +- Installing assets for monitoring health, such as Kibana dashboards, etc. + +## Assets for monitoring health + +The assets' sources are located in the repo under `x-pack/plugins/security_solution/server/lib/detection_engine/rule_monitoring/logic/detection_engine_health/assets`. + +### Assets are installed on behalf of the internal user + +The important aspect to know about is that we install these assets via the saved objects `import()` method, and do it on behalf of the internal Kibana user (which is `kibana_system` by default). This user has privileges for writing saved objects out of the box, which allows our users to be able to install the assets without configuring any additional RBAC. + +See `createDetectionEngineHealthClient` and `installAssetsForMonitoringHealth` for the implementation details. + +### Assets' source files are JSON + +Another thing to consider is that the assets are stored as `.json` files in the repo. This has pros and cons, but the important benefit here is that it allows you to make changes in the assets faster. Especially it applies to Kibana dashboards, which are large objects, and it's hard to construct a dashboard manually in the code. + +### Updating the rule monitoring dashboard + +For example, let's talk about updating the `dashboard_rule_monitoring.json`. It is very convenient to be able to install this dashboard via calling the `_setup` endpoint, and then go edit it in Kibana, save it, export it, and update the source file based on the exported `.ndjson` file. + +Only a few adjustments would need to be done after that manually in the source file: + +- obviously, formatting to JSON +- the dashboard's id has to be updated to `security-detection-rule-monitoring-` +- you have to make sure the references to tags are specified correctly: + + ```json + { + "id": "fleet-managed-", + "name": "tag-ref-fleet-managed", + "type": "tag" + }, + { + "id": "security-solution-", + "name": "tag-ref-security-solution", + "type": "tag" + } + ```