mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 18:51:07 -04:00
[Security Solution] Migrate legacy Detections API docs to OpenAPI specs (#212367)
**Partially resolves: #211808** ## Summary This is the first part of the migration effort, containing changes for: - CRUD endpoints - BULK Actions - Export / Import Rule - Find Rule - List Tags - Get Status - Install Rule I migrated the examples and the description of the fields. Some of the fields contained description that was very similar to the legacy, then I didn't change it. I only modified the descriptions where it was valuable. I also discovered some problems. For example the value for the 'query' field, always shows 'EQL query to execute'. I reported this to the docs team, in the 'next-api-reference' channel. Another issue was with 'related_integrations field', which also didn't show the long description. I also wrote about it to the docs team [here](https://elastic.slack.com/archives/C05UL5YC06B/p1740137094701209). In this PR I decided to try moving the description one level up, where it renders properly. # Testing 1. cd x-pack/solutions/security/plugins/security_solution 2. yarn openapi:bundle:detections 3. Take the bundled file (docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml) and load it into bump.sh console to see the changes. 4. Compare the changes with the [Legacy documentation](https://www.elastic.co/guide/en/security/current/rule-api-overview.html) You can also use this [link](https://bump.sh/jkelas/doc/kibana_wip/) where I deployed the generated bundled doc. --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Jacek Kolezynski
GitHub
parent
f6d12f8384
commit
2b01257343
43 changed files with 11663 additions and 645 deletions
|
|
@ -318,8 +318,62 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Create a new detection rule.
|
||||
*/
|
||||
* Create a new detection rule.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
You can create the following types of rules:
|
||||
|
||||
* **Custom query**: Searches the defined indices and creates an alert when a document matches the rule's KQL query.
|
||||
* **Event correlation**: Searches the defined indices and creates an alert when results match an [Event Query Language (EQL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html) query.
|
||||
* **Threshold**: Searches the defined indices and creates an alert when the number of times the specified field's value meets the threshold during a single execution. When there are multiple values that meet the threshold, an alert is generated for each value.
|
||||
For example, if the threshold `field` is `source.ip` and its `value` is `10`, an alert is generated for every source IP address that appears in at least 10 of the rule's search results. If you're interested, see [Terms Aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html) for more information.
|
||||
* **Indicator match**: Creates an alert when fields match values defined in the specified [Elasticsearch index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html). For example, you can create an index for IP addresses and use this index to create an alert whenever an event's `destination.ip` equals a value in the index. The index's field mappings should be [ECS-compliant](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html).
|
||||
* **New terms**: Generates an alert for each new term detected in source documents within a specified time range.
|
||||
* **ES|QL**: Uses [Elasticsearch Query Language (ES|QL)](https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html) to find events and aggregate search results.
|
||||
* **Machine learning rules**: Creates an alert when a machine learning job discovers an anomaly above the defined threshold.
|
||||
> info
|
||||
> To create machine learning rules, you must have the [appropriate license](https://www.elastic.co/subscriptions) or use a [cloud deployment](https://cloud.elastic.co/registration). Additionally, for the machine learning rule to function correctly, the associated machine learning job must be running.
|
||||
|
||||
To retrieve machine learning job IDs, which are required to create machine learning jobs, call the [Elasticsearch Get jobs API](https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-job.html). Machine learning jobs that contain `siem` in the `groups` field can be used to create rules:
|
||||
|
||||
```json
|
||||
...
|
||||
"job_id": "linux_anomalous_network_activity_ecs",
|
||||
"job_type": "anomaly_detector",
|
||||
"job_version": "7.7.0",
|
||||
"groups": [
|
||||
"auditbeat",
|
||||
"process",
|
||||
"siem"
|
||||
],
|
||||
...
|
||||
```
|
||||
|
||||
Additionally, you can set up notifications for when rules create alerts. The notifications use the [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html). Each action type requires a connector. Connectors store the information required to send notifications via external systems. The following connector types are supported for rule notifications:
|
||||
|
||||
* Slack
|
||||
* Email
|
||||
* PagerDuty
|
||||
* Webhook
|
||||
* Microsoft Teams
|
||||
* IBM Resilient
|
||||
* Jira
|
||||
* ServiceNow ITSM
|
||||
> info
|
||||
> For more information on PagerDuty fields, see [Send a v2 Event](https://developer.pagerduty.com/docs/events-api-v2/trigger-events/).
|
||||
|
||||
To retrieve connector IDs, which are required to configure rule notifications, call the [Find objects API](https://www.elastic.co/guide/en/kibana/current/saved-objects-api-find.html) with `"type": "action"` in the request payload.
|
||||
|
||||
For detailed information on Kibana actions and alerting, and additional API calls, see:
|
||||
|
||||
* [Alerting API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-alerting)
|
||||
* [Alerting and Actions framework](https://www.elastic.co/guide/en/kibana/current/alerting-getting-started.html)
|
||||
* [Connectors API](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-connectors)
|
||||
|
||||
*/
|
||||
createRule(props: CreateRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.post(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -420,8 +474,16 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Delete a detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* Delete a detection rule using the `rule_id` or `id` field.
|
||||
|
||||
The URL query must include one of the following:
|
||||
|
||||
* `id` - `DELETE /api/detection_engine/rules?id=<id>`
|
||||
* `rule_id`- `DELETE /api/detection_engine/rules?rule_id=<rule_id>`
|
||||
|
||||
The difference between the `id` and `rule_id` is that the `id` is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas `rule_id` is a stable rule identifier that can be assigned during rule creation.
|
||||
|
||||
*/
|
||||
deleteRule(props: DeleteRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.delete(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -671,7 +733,11 @@ If a record already exists for the specified entity, that record is overwritten
|
|||
- Actions
|
||||
- Exception lists
|
||||
> info
|
||||
> You cannot export prebuilt rules.
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
|
||||
*/
|
||||
exportRules(props: ExportRulesProps, kibanaSpace: string = 'default') {
|
||||
|
|
@ -1063,6 +1129,19 @@ finalize it.
|
|||
* Import detection rules from an `.ndjson` file, including actions and exception lists. The request must include:
|
||||
- The `Content-Type: multipart/form-data` HTTP header.
|
||||
- A link to the `.ndjson` file containing the rules.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
> info
|
||||
> To import rules with actions, you need at least Read privileges for the Action and Connectors feature. To overwrite or add new connectors, you need All privileges for the Actions and Connectors feature. To import rules without actions, you don’t need Actions and Connectors privileges. Refer to [Enable and access detections](https://www.elastic.co/guide/en/security/current/detections-permissions-section.html#enable-detections-ui) for more information.
|
||||
|
||||
> info
|
||||
> Rule actions and connectors are included in the exported file, but sensitive information about the connector (such as authentication credentials) is not included. You must re-add missing connector details after importing detection rules.
|
||||
|
||||
> You can use Kibana’s [Saved Objects](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html) UI (Stack Management → Kibana → Saved Objects) or the Saved Objects APIs (experimental) to [export](https://www.elastic.co/docs/api/doc/kibana/operation/operation-exportsavedobjectsdefault) and [import](https://www.elastic.co/docs/api/doc/kibana/operation/operation-importsavedobjectsdefault) any necessary connectors before importing detection rules.
|
||||
|
||||
> Similarly, any value lists used for rule exceptions are not included in rule exports or imports. Use the [Manage value lists](https://www.elastic.co/guide/en/security/current/value-lists-exceptions.html#manage-value-lists) UI (Rules → Detection rules (SIEM) → Manage value lists) to export and import value lists separately.
|
||||
|
||||
*/
|
||||
importRules(props: ImportRulesProps, kibanaSpace: string = 'default') {
|
||||
|
|
@ -1132,8 +1211,19 @@ finalize it.
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
*/
|
||||
* Install and update all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint allows you to install and update prebuilt detection rules and Timelines provided by Elastic.
|
||||
When you call this endpoint, it will:
|
||||
- Install any new prebuilt detection rules that are not currently installed in your system.
|
||||
- Update any existing prebuilt detection rules that have been modified or improved by Elastic.
|
||||
- Install any new prebuilt Timelines that are not currently installed in your system.
|
||||
- Update any existing prebuilt Timelines that have been modified or improved by Elastic.
|
||||
|
||||
This ensures that your detection engine is always up-to-date with the latest rules and Timelines,
|
||||
providing you with the most current and effective threat detection capabilities.
|
||||
|
||||
*/
|
||||
installPrebuiltRulesAndTimelines(kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.put(routeWithNamespace('/api/detection_engine/rules/prepackaged', kibanaSpace))
|
||||
|
|
@ -1181,8 +1271,15 @@ finalize it.
|
|||
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
|
||||
},
|
||||
/**
|
||||
* Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* Update specific fields of an existing detection rule using the `rule_id` or `id` field.
|
||||
|
||||
The difference between the `id` and `rule_id` is that the `id` is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas `rule_id` is a stable rule identifier that can be assigned during rule creation.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
patchRule(props: PatchRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.patch(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -1203,8 +1300,13 @@ finalize it.
|
|||
.send(props.body as object);
|
||||
},
|
||||
/**
|
||||
* Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
*/
|
||||
* Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
performRulesBulkAction(props: PerformRulesBulkActionProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.post(routeWithNamespace('/api/detection_engine/rules/_bulk_action', kibanaSpace))
|
||||
|
|
@ -1280,8 +1382,11 @@ finalize it.
|
|||
.query(props.query);
|
||||
},
|
||||
/**
|
||||
* Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
*/
|
||||
* Retrieve the status of all Elastic prebuilt detection rules and Timelines.
|
||||
|
||||
This endpoint provides detailed information about the number of custom rules, installed prebuilt rules, available prebuilt rules that are not installed, outdated prebuilt rules, installed prebuilt timelines, available prebuilt timelines that are not installed, and outdated prebuilt timelines.
|
||||
|
||||
*/
|
||||
readPrebuiltRulesAndTimelinesStatus(kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.get(routeWithNamespace('/api/detection_engine/rules/prepackaged/_status', kibanaSpace))
|
||||
|
|
@ -1311,8 +1416,16 @@ detection engine rules.
|
|||
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
|
||||
},
|
||||
/**
|
||||
* Retrieve a detection rule using the `rule_id` or `id` field.
|
||||
*/
|
||||
* Retrieve a detection rule using the `rule_id` or `id` field.
|
||||
|
||||
The URL query must include one of the following:
|
||||
|
||||
* `id` - `GET /api/detection_engine/rules?id=<id>`
|
||||
* `rule_id` - `GET /api/detection_engine/rules?rule_id=<rule_id>`
|
||||
|
||||
The difference between the `id` and `rule_id` is that the `id` is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas `rule_id` is a stable rule identifier that can be assigned during rule creation.
|
||||
|
||||
*/
|
||||
readRule(props: ReadRuleProps, kibanaSpace: string = 'default') {
|
||||
return supertest
|
||||
.get(routeWithNamespace('/api/detection_engine/rules', kibanaSpace))
|
||||
|
|
@ -1508,8 +1621,12 @@ detection engine rules.
|
|||
},
|
||||
/**
|
||||
* Update a detection rule using the `rule_id` or `id` field. The original rule is replaced, and all unspecified fields are deleted.
|
||||
> info
|
||||
> You cannot modify the `id` or `rule_id` values.
|
||||
|
||||
The difference between the `id` and `rule_id` is that the `id` is a unique rule identifier that is randomly generated when a rule is created and cannot be set, whereas `rule_id` is a stable rule identifier that can be assigned during rule creation.
|
||||
> warn
|
||||
> When used with [API key](https://www.elastic.co/guide/en/kibana/current/api-keys.html) authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
|
||||
|
||||
> If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
|
||||
|
||||
*/
|
||||
updateRule(props: UpdateRuleProps, kibanaSpace: string = 'default') {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue