github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 09:48:58 -04:00
Code Issues Projects Releases Packages Wiki Activity

[8.x] [Security Solution] Improve documentation for version and revision fields (#216074) (#216531)

Browse source 
# Backport

This will backport the following commits from `main` to `8.x`:
- [[Security Solution] Improve documentation for `version` and
`revision` fields
(#216074)](https://github.com/elastic/kibana/pull/216074)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Jacek
Kolezynski","email":"jacek.kolezynski@elastic.co"},"sourceCommit":{"committedDate":"2025-03-31T18:06:13Z","message":"[Security
Solution] Improve documentation for `version` and `revision` fields
(#216074)\n\n**Resolves:
https://github.com/elastic/security-docs/issues/3545**\n\n##
Summary\n\nI am fixing documentation for the version and revision
fields.\nI used this page as the base
documentation:\nhttps://docs.elastic.dev/security-solution/dev-docs/detections/rule-versions\n\nThe
changes:\n- by marking the RuleVersion as read-only I am making sure we
are\nproperly documenting that this field is not to be used in the
request.\nIt is only returned in the response.\n- by introducing
RuleRevision type and marking it as read-only, I am\ndoing the same for
this field, saying that this field is not supposed to\nbe used in the
request.\n- I am not changing any code in the app, as the ticket says we
shouldn't\ndo any breaking changes and the update of the version should
not cause\n400 error. Basically current behavior is kept: users can
still update\nthe version to whatever value they want, including going
backwards, and\nthe changes to revision field is completely ignored.\n-
I am adding a condensed description of these fields.\n\nI wanted to
introduce an internal link between these two fields, but I\ncouldn't
make it work in Bump.sh (even though this should work, normal\nMarkdown
links) so I abandoned this idea.\n\nYou can also use this
[link](https://bump.sh/jkelas2/doc/kibana_wip2)\nwhere I deployed the
generated bundled doc.\n\nScreenshots:\n\n<img width=\"664\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/34d82eb2-f7f0-4369-ad8e-2fd3c1f35447\"\n/>\n\n<img
width=\"660\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/dc7772af-0185-4850-816e-60be003775d6\"\n/>\n\n---------\n\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"63575a8320a7e021df79727ad66ed4cf01dd1e5f","branchLabelMapping":{"^v9.1.0$":"main","^v8.19.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:Detections
and Resp","Team: SecuritySolution","Feature:Rule
Management","APIDocs","Team:Detection Rule Management","Feature:Prebuilt
Detection Rules","backport:version","9.1
candidate","v9.1.0","v8.19.0"],"title":"[Security Solution] Improve
documentation for `version` and `revision`
fields","number":216074,"url":"https://github.com/elastic/kibana/pull/216074","mergeCommit":{"message":"[Security
Solution] Improve documentation for `version` and `revision` fields
(#216074)\n\n**Resolves:
https://github.com/elastic/security-docs/issues/3545**\n\n##
Summary\n\nI am fixing documentation for the version and revision
fields.\nI used this page as the base
documentation:\nhttps://docs.elastic.dev/security-solution/dev-docs/detections/rule-versions\n\nThe
changes:\n- by marking the RuleVersion as read-only I am making sure we
are\nproperly documenting that this field is not to be used in the
request.\nIt is only returned in the response.\n- by introducing
RuleRevision type and marking it as read-only, I am\ndoing the same for
this field, saying that this field is not supposed to\nbe used in the
request.\n- I am not changing any code in the app, as the ticket says we
shouldn't\ndo any breaking changes and the update of the version should
not cause\n400 error. Basically current behavior is kept: users can
still update\nthe version to whatever value they want, including going
backwards, and\nthe changes to revision field is completely ignored.\n-
I am adding a condensed description of these fields.\n\nI wanted to
introduce an internal link between these two fields, but I\ncouldn't
make it work in Bump.sh (even though this should work, normal\nMarkdown
links) so I abandoned this idea.\n\nYou can also use this
[link](https://bump.sh/jkelas2/doc/kibana_wip2)\nwhere I deployed the
generated bundled doc.\n\nScreenshots:\n\n<img width=\"664\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/34d82eb2-f7f0-4369-ad8e-2fd3c1f35447\"\n/>\n\n<img
width=\"660\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/dc7772af-0185-4850-816e-60be003775d6\"\n/>\n\n---------\n\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"63575a8320a7e021df79727ad66ed4cf01dd1e5f"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/216074","number":216074,"mergeCommit":{"message":"[Security
Solution] Improve documentation for `version` and `revision` fields
(#216074)\n\n**Resolves:
https://github.com/elastic/security-docs/issues/3545**\n\n##
Summary\n\nI am fixing documentation for the version and revision
fields.\nI used this page as the base
documentation:\nhttps://docs.elastic.dev/security-solution/dev-docs/detections/rule-versions\n\nThe
changes:\n- by marking the RuleVersion as read-only I am making sure we
are\nproperly documenting that this field is not to be used in the
request.\nIt is only returned in the response.\n- by introducing
RuleRevision type and marking it as read-only, I am\ndoing the same for
this field, saying that this field is not supposed to\nbe used in the
request.\n- I am not changing any code in the app, as the ticket says we
shouldn't\ndo any breaking changes and the update of the version should
not cause\n400 error. Basically current behavior is kept: users can
still update\nthe version to whatever value they want, including going
backwards, and\nthe changes to revision field is completely ignored.\n-
I am adding a condensed description of these fields.\n\nI wanted to
introduce an internal link between these two fields, but I\ncouldn't
make it work in Bump.sh (even though this should work, normal\nMarkdown
links) so I abandoned this idea.\n\nYou can also use this
[link](https://bump.sh/jkelas2/doc/kibana_wip2)\nwhere I deployed the
generated bundled doc.\n\nScreenshots:\n\n<img width=\"664\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/34d82eb2-f7f0-4369-ad8e-2fd3c1f35447\"\n/>\n\n<img
width=\"660\"
alt=\"image\"\nsrc=\"https://github.com/user-attachments/assets/dc7772af-0185-4850-816e-60be003775d6\"\n/>\n\n---------\n\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"63575a8320a7e021df79727ad66ed4cf01dd1e5f"}},{"branch":"8.x","label":"v8.19.0","branchLabelMappingKey":"^v8.19.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Jacek Kolezynski <jacek.kolezynski@elastic.co>
This commit is contained in:
Kibana Machine 2025-03-31 21:59:08 +02:00 • committed by GitHub
parent 79cc21e5b8
commit a75155043b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 143 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

20
oas_docs/output/kibana.serverless.yaml
View file

@ -50145,8 +50145,7 @@ components:
required_fields:
$ref: '#/components/schemas/Security_Detections_API_RequiredFieldArray'
revision:
minimum: 0
type: integer
$ref: '#/components/schemas/Security_Detections_API_RuleRevision'
rule_id:
$ref: '#/components/schemas/Security_Detections_API_RuleSignatureId'
rule_source:
@ -50492,6 +50491,15 @@ components:
- $ref: '#/components/schemas/Security_Detections_API_EsqlRule'
discriminator:
propertyName: type
Security_Detections_API_RuleRevision:
description: |
The rule's revision number.
It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
> info
> Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
minimum: 0
type: integer
Security_Detections_API_RuleSignatureId:
description: Could be any string, not necessarily a UUID
type: string
@ -50520,7 +50528,13 @@ components:
discriminator:
propertyName: type
Security_Detections_API_RuleVersion:
description: The rule's version number.
description: |
The rule's version number.
- For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules).
- For custom rules it is set to `1` when the rule is created.
> info
> It is not incremented on each update. Compare this to the `revision` field.
minimum: 1
type: integer
Security_Detections_API_SavedObjectResolveAliasPurpose:

20
oas_docs/output/kibana.yaml
View file

@ -35675,8 +35675,7 @@ components:
required_fields:
$ref: '#/components/schemas/Security_Detections_API_RequiredFieldArray'
revision:
minimum: 0
type: integer
$ref: '#/components/schemas/Security_Detections_API_RuleRevision'
rule_id:
$ref: '#/components/schemas/Security_Detections_API_RuleSignatureId'
rule_source:
@ -36022,6 +36021,15 @@ components:
- $ref: '#/components/schemas/Security_Detections_API_EsqlRule'
discriminator:
propertyName: type
Security_Detections_API_RuleRevision:
description: |
The rule's revision number.
It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
> info
> Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
minimum: 0
type: integer
Security_Detections_API_RuleSignatureId:
description: Could be any string, not necessarily a UUID
type: string
@ -36050,7 +36058,13 @@ components:
discriminator:
propertyName: type
Security_Detections_API_RuleVersion:
description: The rule's version number.
description: |
The rule's version number.
- For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules).
- For custom rules it is set to `1` when the rule is created.
> info
> It is not incremented on each update. Compare this to the `revision` field.
minimum: 1
type: integer
Security_Detections_API_SavedObjectResolveAliasPurpose:

21
x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.gen.ts
View file

@ -35,11 +35,28 @@ export type RuleDescription = z.infer<typeof RuleDescription>;
export const RuleDescription = z.string().min(1);
/**
* The rule's version number.
*/
* The rule's version number.
- For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules).
- For custom rules it is set to `1` when the rule is created.
> info
> It is not incremented on each update. Compare this to the `revision` field.
*/
export type RuleVersion = z.infer<typeof RuleVersion>;
export const RuleVersion = z.number().int().min(1);
/**
* The rule's revision number.
It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
> info
> Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
*/
export type RuleRevision = z.infer<typeof RuleRevision>;
export const RuleRevision = z.number().int().min(0);
export type QueryLanguage = z.infer<typeof QueryLanguage>;
export const QueryLanguage = z.enum(['kuery', 'lucene', 'eql', 'esql']);
export type QueryLanguageEnum = typeof QueryLanguage.enum;

18
x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml
View file

@ -24,7 +24,23 @@ components:
RuleVersion:
type: integer
minimum: 1
description: The rule's version number.
description: |
The rule's version number.
- For prebuilt rules it represents the version of the rule's content in the source [detection-rules](https://github.com/elastic/detection-rules) repository (and the corresponding `security_detection_engine` Fleet package that is used for distributing prebuilt rules).
- For custom rules it is set to `1` when the rule is created.
> info
> It is not incremented on each update. Compare this to the `revision` field.
RuleRevision:
type: integer
minimum: 0
description: |
The rule's revision number.
It represents the version of rule's object in Kibana. It is set to `0` when the rule is installed or created and then gets incremented on each update.
> info
> Not all updates to any rule fields will increment the revision. Only those fields that are considered static `rule parameters` can trigger revision increments. For example, an update to a rule's query or index fields will increment the rule's revision by `1`. However, changes to dynamic or technical fields like enabled or execution_summary will not cause revision increments.
QueryLanguage:
type: string

3
x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/rule_schemas.gen.ts
View file

@ -59,6 +59,7 @@ import {
RuleSignatureId,
IsRuleImmutable,
RuleSource,
RuleRevision,
RequiredFieldArray,
RuleQuery,
IndexPatternArray,
@ -166,7 +167,7 @@ export const ResponseFields = z.object({
updated_by: z.string(),
created_at: z.string().datetime(),
created_by: z.string(),
revision: z.number().int().min(0),
revision: RuleRevision,
required_fields: RequiredFieldArray,
execution_summary: RuleExecutionSummary.optional(),
});

3
x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/rule_schemas.schema.yaml
View file

@ -193,8 +193,7 @@ components:
created_by:
type: string
revision:
type: integer
minimum: 0
$ref: './common_attributes.schema.yaml#/components/schemas/RuleRevision'
# NOTE: For now, Required Fields are
# supported for prebuilt rules only. We don't want to allow users to edit these 3
# fields via the API. If we added them to baseParams.defaultable, they would

38
x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml
View file

@ -5115,8 +5115,7 @@ components:
required_fields:
$ref: '#/components/schemas/RequiredFieldArray'
revision:
minimum: 0
type: integer
$ref: '#/components/schemas/RuleRevision'
rule_id:
$ref: '#/components/schemas/RuleSignatureId'
rule_source:
@ -5505,6 +5504,25 @@ components:
- $ref: '#/components/schemas/EsqlRule'
discriminator:
propertyName: type
RuleRevision:
description: >
The rule's revision number.
It represents the version of rule's object in Kibana. It is set to `0`
when the rule is installed or created and then gets incremented on each
update.
> info
> Not all updates to any rule fields will increment the revision. Only
those fields that are considered static `rule parameters` can trigger
revision increments. For example, an update to a rule's query or index
fields will increment the rule's revision by `1`. However, changes to
dynamic or technical fields like enabled or execution_summary will not
cause revision increments.
minimum: 0
type: integer
RuleSignatureId:
description: 'Could be any string, not necessarily a UUID'
type: string
@ -5538,7 +5556,21 @@ components:
discriminator:
propertyName: type
RuleVersion:
description: The rule's version number.
description: >
The rule's version number.
- For prebuilt rules it represents the version of the rule's content in
the source [detection-rules](https://github.com/elastic/detection-rules)
repository (and the corresponding `security_detection_engine` Fleet
package that is used for distributing prebuilt rules).
- For custom rules it is set to `1` when the rule is created.
> info
> It is not incremented on each update. Compare this to the `revision`
field.
minimum: 1
type: integer
SavedObjectResolveAliasPurpose:

38
x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml
View file

@ -4109,8 +4109,7 @@ components:
required_fields:
$ref: '#/components/schemas/RequiredFieldArray'
revision:
minimum: 0
type: integer
$ref: '#/components/schemas/RuleRevision'
rule_id:
$ref: '#/components/schemas/RuleSignatureId'
rule_source:
@ -4499,6 +4498,25 @@ components:
- $ref: '#/components/schemas/EsqlRule'
discriminator:
propertyName: type
RuleRevision:
description: >
The rule's revision number.
It represents the version of rule's object in Kibana. It is set to `0`
when the rule is installed or created and then gets incremented on each
update.
> info
> Not all updates to any rule fields will increment the revision. Only
those fields that are considered static `rule parameters` can trigger
revision increments. For example, an update to a rule's query or index
fields will increment the rule's revision by `1`. However, changes to
dynamic or technical fields like enabled or execution_summary will not
cause revision increments.
minimum: 0
type: integer
RuleSignatureId:
description: 'Could be any string, not necessarily a UUID'
type: string
@ -4532,7 +4550,21 @@ components:
discriminator:
propertyName: type
RuleVersion:
description: The rule's version number.
description: >
The rule's version number.
- For prebuilt rules it represents the version of the rule's content in
the source [detection-rules](https://github.com/elastic/detection-rules)
repository (and the corresponding `security_detection_engine` Fleet
package that is used for distributing prebuilt rules).
- For custom rules it is set to `1` when the rule is created.
> info
> It is not incremented on each update. Compare this to the `revision`
field.
minimum: 1
type: integer
SavedObjectResolveAliasPurpose: