12e7fe50bb
## Summary
This is a follow up considered critical addition to:
https://github.com/elastic/kibana/pull/102280
This adds a key of `xpack.securitySolution.alertMergeStrategy` to `kibana.yml` which allows users to change their merge strategy between their raw events and the signals/alerts that are generated. This also adds additional security keys to the docker container that were overlooked in the past from security solutions.
The values you can use and add to to `xpack.securitySolution.alertMergeStrategy` are:
* missingFields (The default)
* allFields
* noFields
## missingFields
The default merge strategy we are using starting with 7.14 which will merge any primitive data types from the [fields API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-fields.html#search-fields-param) into the resulting signal/alert. This will copy over fields such as `constant_keyword`, `copy_to`, `runtime fields`, `field aliases` which previously were not copied over as long as they are primitive data types such as `keyword`, `text`, `numeric` and are not found in your original `_source` document. This will not copy copy `geo points`, `nested objects`, and in some cases if your `_source` contains arrays or top level objects or conflicts/ambiguities it will not merge them. This will _not_ merge existing values between `_source` and `fields` for `runtime fields` as well. It only merges missing primitive data types.
## allFields
A very aggressive merge strategy which should be considered experimental. It will do everything `missingFields` does but in addition to that it will merge existing values between `_source` and `fields` which means if you change values or override values with `runtime fields` this strategy will attempt to merge those values. This will also merge in most instances your nested fields but it will not merge `geo` data types due to ambiguities. If you have multi-fields this will choose your default field and merge that into `_source`. This can change a lot your data between your original `_source` and `fields` when the data is copied into an alert/signal which is why it is considered an aggressive merge strategy.
Both these strategies attempts to unbox single array elements when it makes sense and assumes you only want values in an array when it sees them in `_source` or if it sees multiple elements within an array.
## noFields
The behavior before https://github.com/elastic/kibana/pull/102280 was introduced and is a do nothing strategy. This should only be used if you are seeing problems with alerts/signals being inserted due to conflicts and/or bugs for some reason with `missingFields`. We are not anticipating this, but if you are setting `noFields` please reach out to our [forums](https://discuss.elastic.co/c/security/83) and let us know we have a bug so we can fix it. If you are encountering undesired merge behaviors or have other strategies you want us to implement let us know on the forums as well.
The missing keys added for docker are:
* xpack.securitySolution.alertMergeStrategy
* xpack.securitySolution.alertResultListDefaultDateRange
* xpack.securitySolution.endpointResultListDefaultFirstPageIndex
* xpack.securitySolution.endpointResultListDefaultPageSize
* xpack.securitySolution.maxRuleImportExportSize
* xpack.securitySolution.maxRuleImportPayloadBytes
* xpack.securitySolution.maxTimelineImportExportSize
* xpack.securitySolution.maxTimelineImportPayloadBytes
* xpack.securitySolution.packagerTaskInterval
* xpack.securitySolution.validateArtifactDownloads
I intentionally skipped adding the other `kibana.yml` keys which are considered either experimental flags or are for internal developers and are not documented and not supported in production by us.
## Manual testing of the different strategies
First add this mapping and document in the dev tools for basic tests
```json
# Mapping with two constant_keywords and a runtime field
DELETE frank-test-delme-17
PUT frank-test-delme-17
{
"mappings": {
"dynamic": "strict",
"runtime": {
"host.name": {
"type": "keyword",
"script": {
"source": "emit('changed_hostname')"
}
}
},
"properties": {
"@timestamp": {
"type": "date"
},
"host": {
"properties": {
"name": {
"type": "keyword"
}
}
},
"data_stream": {
"properties": {
"dataset": {
"type": "constant_keyword",
"value": "datastream_dataset_name_1"
},
"module": {
"type": "constant_keyword",
"value": "datastream_module_name_1"
}
}
},
"event": {
"properties": {
"dataset": {
"type": "constant_keyword",
"value": "event_dataset_name_1"
},
"module": {
"type": "constant_keyword",
"value": "event_module_name_1"
}
}
}
}
}
}
# Document without an existing host.name
PUT frank-test-delme-17/_doc/1
{
"@timestamp": "2021-06-30T15:46:31.800Z"
}
# Document with an existing host.name
PUT frank-test-delme-17/_doc/2
{
"@timestamp": "2021-06-30T15:46:31.800Z",
"host": {
"name": "host_name"
}
}
# Query it to ensure the fields is returned with data that does not exist in _soruce
GET frank-test-delme-17/_search
{
"fields": [
{
"field": "*"
}
]
}
```
For all the different key combinations do the following:
Run a single detection rule against the index:
<img width="1139" alt="Screen Shot 2021-06-30 at 9 49 12 AM" src="https://user-images.githubusercontent.com/1151048/123997522-b8dc6600-d98d-11eb-9407-5480d5b2cc8a.png">
Ensure two signals are created:
<img width="1376" alt="Screen Shot 2021-06-30 at 10 26 03 AM" src="https://user-images.githubusercontent.com/1151048/123997739-f17c3f80-d98d-11eb-9eb9-90e9410f0cde.png">
If your `kibana.yml` or `kibana.dev.yml` you set this key (or omit it as it is the default):
```yml
xpack.securitySolution.alertMergeStrategy: 'missingFields'
```
When you click on each signal you should see that `event.module` and `event.dataset` were copied over as well as `data_stream.dataset` and `data_stream.module` since they're `constant_keyword`:
<img width="877" alt="Screen Shot 2021-06-30 at 10 20 44 AM" src="https://user-images.githubusercontent.com/1151048/123997961-31432700-d98e-11eb-96ee-06524f21e2d6.png">
However since this only merges missing fields, you should see that in the first record the `host.name` is the runtime field defined since `host.name` does not exist in `_source` and that in the second record it still shows up as `host_name` since we do not override merges right now:
First:
<img width="887" alt="Screen Shot 2021-06-30 at 10 03 31 AM" src="https://user-images.githubusercontent.com/1151048/123998398-b2022300-d98e-11eb-87be-aa5a153a91bc.png">
Second:
<img width="838" alt="Screen Shot 2021-06-30 at 10 03 44 AM" src="https://user-images.githubusercontent.com/1151048/123998413-b4fd1380-d98e-11eb-9821-d6189190918f.png">
When you set in your `kibana.yml` or `kibana.dev.yml` this key:
```yml
xpack.securitySolution.alertMergeStrategy: 'noFields'
```
Expect that your `event.module`, `event.dataset`, `data_stream.module`, `data_stream.dataset` are all non-existent since we do not copy anything over from `fields` at all and only use things within `_source`:
<img width="804" alt="Screen Shot 2021-06-30 at 9 58 25 AM" src="https://user-images.githubusercontent.com/1151048/123998694-f8578200-d98e-11eb-8d71-a0858d3ed3e7.png">
Expect that `host.name` is missing in the first record and has the default value in the second:
First:
<img width="797" alt="Screen Shot 2021-06-30 at 9 58 37 AM" src="https://user-images.githubusercontent.com/1151048/123998797-10c79c80-d98f-11eb-81b6-5174d8ef14f2.png">
Second:
<img width="806" alt="Screen Shot 2021-06-30 at 9 58 52 AM" src="https://user-images.githubusercontent.com/1151048/123998816-158c5080-d98f-11eb-87a0-0ac2f58793b3.png">
When you set in your `kibana.yml` or `kibana.dev.yml` this key:
```yml
xpack.securitySolution.alertMergeStrategy: 'allFields'
```
Expect that `event.module` and `event.dataset` were copied over as well as `data_stream.dataset` and `data_stream.module` since they're `constant_keyword`:
<img width="864" alt="Screen Shot 2021-06-30 at 10 03 15 AM" src="https://user-images.githubusercontent.com/1151048/123999000-48364900-d98f-11eb-9803-05349744ac10.png">
Expect that both the first and second records contain the runtime field since we merge both of them:
<img width="887" alt="Screen Shot 2021-06-30 at 10 03 31 AM" src="https://user-images.githubusercontent.com/1151048/123999078-58e6bf00-d98f-11eb-83bd-dda6b50fabcd.png">
### Checklist
Delete any items that are not applicable to this PR.
- [x] If a plugin configuration key changed, check if it needs to be allowlisted in the [cloud](https://github.com/elastic/cloud) and added to the [docker list](
|
||
|---|---|---|
| .buildkite | ||
| .ci | ||
| .github | ||
| api_docs | ||
| config | ||
| dev_docs | ||
| docs | ||
| examples | ||
| licenses | ||
| packages | ||
| plugins | ||
| rfcs | ||
| scripts | ||
| src | ||
| tasks/config | ||
| test | ||
| typings | ||
| utilities | ||
| vars | ||
| x-pack | ||
| .backportrc.json | ||
| .bazelignore | ||
| .bazeliskversion | ||
| .bazelrc | ||
| .bazelrc.common | ||
| .bazelversion | ||
| .browserslistrc | ||
| .editorconfig | ||
| .eslintignore | ||
| .eslintrc.js | ||
| .fossa.yml | ||
| .gitattributes | ||
| .gitignore | ||
| .i18nrc.json | ||
| .node-version | ||
| .npmrc | ||
| .nvmrc | ||
| .prettierignore | ||
| .prettierrc | ||
| .stylelintignore | ||
| .stylelintrc | ||
| .telemetryrc.json | ||
| .yarnrc | ||
| api-documenter.json | ||
| BUILD.bazel | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| FAQ.md | ||
| github_checks_reporter.json | ||
| Gruntfile.js | ||
| Jenkinsfile | ||
| jest.config.integration.js | ||
| jest.config.js | ||
| kibana.d.ts | ||
| LICENSE.txt | ||
| NOTICE.txt | ||
| package.json | ||
| preinstall_check.js | ||
| README.md | ||
| renovate.json5 | ||
| RISK_MATRIX.mdx | ||
| SECURITY.md | ||
| STYLEGUIDE.mdx | ||
| tsconfig.base.json | ||
| tsconfig.browser.json | ||
| tsconfig.json | ||
| tsconfig.refs.json | ||
| tsconfig.types.json | ||
| TYPESCRIPT.md | ||
| WORKSPACE.bazel | ||
| yarn.lock | ||
Kibana
Kibana is your window into the Elastic Stack. Specifically, it's a browser-based analytics and search dashboard for Elasticsearch.
- Getting Started
- Documentation
- Version Compatibility with Elasticsearch
- Questions? Problems? Suggestions?
Getting Started
If you just want to try Kibana out, check out the Elastic Stack Getting Started Page to give it a whirl.
If you're interested in diving a bit deeper and getting a taste of Kibana's capabilities, head over to the Kibana Getting Started Page.
Using a Kibana Release
If you want to use a Kibana release in production, give it a test run, or just play around:
- Download the latest version on the Kibana Download Page.
- Learn more about Kibana's features and capabilities on the Kibana Product Page.
- We also offer a hosted version of Kibana on our Cloud Service.
Building and Running Kibana, and/or Contributing Code
You might want to build Kibana locally to contribute some code, test out the latest features, or try out an open PR:
- CONTRIBUTING.md will help you get Kibana up and running.
- If you would like to contribute code, please follow our STYLEGUIDE.md.
- For all other questions, check out the FAQ.md and wiki.
Documentation
Visit Elastic.co for the full Kibana documentation.
For information about building the documentation, see the README in elastic/docs.
Version Compatibility with Elasticsearch
Ideally, you should be running Elasticsearch and Kibana with matching version numbers. If your Elasticsearch has an older version number or a newer major number than Kibana, then Kibana will fail to run. If Elasticsearch has a newer minor or patch number than Kibana, then the Kibana Server will log a warning.
Note: The version numbers below are only examples, meant to illustrate the relationships between different types of version numbers.
| Situation | Example Kibana version | Example ES version | Outcome |
|---|---|---|---|
| Versions are the same. | 5.1.2 | 5.1.2 | 💚 OK |
| ES patch number is newer. | 5.1.2 | 5.1.5 | ⚠️ Logged warning |
| ES minor number is newer. | 5.1.2 | 5.5.0 | ⚠️ Logged warning |
| ES major number is newer. | 5.1.2 | 6.0.0 | 🚫 Fatal error |
| ES patch number is older. | 5.1.2 | 5.1.0 | ⚠️ Logged warning |
| ES minor number is older. | 5.1.2 | 5.0.0 | 🚫 Fatal error |
| ES major number is older. | 5.1.2 | 4.0.0 | 🚫 Fatal error |
Questions? Problems? Suggestions?
- If you've found a bug or want to request a feature, please create a GitHub Issue. Please check to make sure someone else hasn't already created an issue for the same topic.
- Need help using Kibana? Ask away on our Kibana Discuss Forum and a fellow community member or Elastic engineer will be glad to help you out.