[Security Solution] Adds customized_fields and has_base_version fields to rule_source object schema (#234793)

**Resolves: elastic/security-team#12507
(internal)

## Summary

Adds two new fields to the existing `rule_source` object in our rule
schema as described in #230856.
Also updates and adds test coverage for the new field logic.

The new fields are:

- `customized_fields`: an array of objects containing rule field names
that have been modified from the base version of the prebuilt rule.
- Defaults to empty array if prebuilt rule is not customized or if base
version did not exist during diff calculation.
- `has_base_version`: a boolean field that specifies if the base version
of a prebuilt rule was able to be fetched and used during the
customization calculation.

This PR also adds related telemetry fields as described in
#230856. This includes a
`customizations` object field which contains a slimmed down version of
`customized_fields` and has a `num_functional_fields` number field that
is created in the telemetry task pipeline by comparing the customized
fields array to a constant list of field names that we are defining as
"functional". This source of truth list can be found in the
`x-pack/solutions/security/plugins/security_solution/common/detection_engine/constants.ts`
file

### Examples

```json
{
  "rule_source": {
    "type": "external",
    "is_customized": true,
    /* New fields */
    "customized_fields": [
      {
        "field_name": "tags",
      },
      {
        "field_name": "query",
      }
    ],
    "has_base_version": true
  }
}
```

```json
"customizations": {
  "customized_fields": ["tags", "query"],
  "num_functional_fields": 2,
}
```

## How to test telemetry

Link to internal staging with example data: ([internal
staging](https://analytics-staging.sde.elastic.dev/app/discover#/?_g=(filters:!(),refreshInterval:(pause:!t,value:60000),time:(from:'2025-09-26T15:59:24.512Z',to:'2025-09-26T16:08:58.435Z'))&_a=(columns:!(),dataSource:(dataViewId:'4ca97040-d095-11ec-95a5-011050c1180f',type:dataView),filters:!(),interval:auto,query:(language:kuery,query:'customizations.num_functional_fields%20%3E%200'),sort:!(!('@timestamp',desc)),viewMode:documents)))

1. Set the prebuilt rule task type to something shorter than `1hr` in
this file:
`x-pack/solutions/security/plugins/security_solution/server/lib/telemetry/tasks/prebuilt_rule_alerts.ts`
2. Add the following to `kibana.dev.yml`:
```
telemetry.enabled: true
telemetry.optIn: true

// (Optional for checking to see if its working)
logging:
  root:
    appenders: [default]
    level: warn
  loggers:
    - name: plugins.securitySolution
      level: debug
    - name: plugins.ruleRegistry
    - name: plugins.taskManager
```
3. Start up both Elasticsearch and kibana (Has to be done _after_
updating task interval as task objects are stored in ES)
4. Install prebuilt rules
5. Modify prebuilt rules with different field customizations and enable
those rules
6. Generate alerts that match these rules (resolver script generator,
dev tools, query modification, etc.)
7. View the alerts getting sent to the internal staging telemetry
cluster (https://analytics-staging.sde.elastic.dev) in the
`detections_alert_telemetry_elastic*` index
8. Use the new `customizations` field to filter out/in customized rule
alerts

## Checklist

Check the PR satisfies following conditions. 

Reviewers should verify this PR satisfies this list as well.

- [x]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
- [x] [Flaky Test
Runner](https://ci-stats.kibana.dev/trigger_flaky_test_runner/1) was
used on any tests changed
- [x] [Rule customization
tests](https://buildkite.com/elastic/kibana-flaky-test-suite-runner/builds/9317)

---------

Co-authored-by: Elastic Machine <[email protected]>
Co-authored-by: Georgii Gorbachev <[email protected]>

Author: 3 people

oas_docs/output/kibana.serverless.yaml

@@ -70783,10 +70783,28 @@ components:
         - endpoint_host_isolation_exceptions
         - endpoint_blocklists
       type: string
+    Security_Detections_API_ExternalRuleCustomizedFields:
+      description: An array of customized field names — that is, fields that the user has modified from their base value. Defaults to an empty array.
+      items:
+        type: object
+        properties:
+          field_name:
+            description: Name of a user-modified field in the rule object.
+            type: string
+        required:
+          - field_name
+      type: array
+    Security_Detections_API_ExternalRuleHasBaseVersion:
+      description: Determines whether an external/prebuilt rule has its original, unmodified version present when the calculation of its customization status is performed (`rule_source.is_customized` and `rule_source.customized_fields`).
+      type: boolean
     Security_Detections_API_ExternalRuleSource:
       description: Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
       type: object
       properties:
+        customized_fields:
+          $ref: '#/components/schemas/Security_Detections_API_ExternalRuleCustomizedFields'
+        has_base_version:
+          $ref: '#/components/schemas/Security_Detections_API_ExternalRuleHasBaseVersion'
         is_customized:
           $ref: '#/components/schemas/Security_Detections_API_IsExternalRuleCustomized'
         type:
@@ -70796,6 +70814,8 @@ components:
       required:
         - type
         - is_customized
+        - has_base_version
+        - customized_fields
     Security_Detections_API_FindRulesSortField:
       enum:
         - created_at

oas_docs/output/kibana.yaml

@@ -83976,10 +83976,28 @@ components:
         - endpoint_host_isolation_exceptions
         - endpoint_blocklists
       type: string
+    Security_Detections_API_ExternalRuleCustomizedFields:
+      description: An array of customized field names — that is, fields that the user has modified from their base value. Defaults to an empty array.
+      items:
+        type: object
+        properties:
+          field_name:
+            description: Name of a user-modified field in the rule object.
+            type: string
+        required:
+          - field_name
+      type: array
+    Security_Detections_API_ExternalRuleHasBaseVersion:
+      description: Determines whether an external/prebuilt rule has its original, unmodified version present when the calculation of its customization status is performed (`rule_source.is_customized` and `rule_source.customized_fields`).
+      type: boolean
     Security_Detections_API_ExternalRuleSource:
       description: Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.
       type: object
       properties:
+        customized_fields:
+          $ref: '#/components/schemas/Security_Detections_API_ExternalRuleCustomizedFields'
+        has_base_version:
+          $ref: '#/components/schemas/Security_Detections_API_ExternalRuleHasBaseVersion'
         is_customized:
           $ref: '#/components/schemas/Security_Detections_API_IsExternalRuleCustomized'
         type:
@@ -83989,6 +84007,8 @@ components:
       required:
         - type
         - is_customized
+        - has_base_version
+        - customized_fields
     Security_Detections_API_FindRulesSortField:
       enum:
         - created_at

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

@@ -89,6 +89,25 @@ export const IsRuleImmutable = z.boolean();
 export type IsExternalRuleCustomized = z.infer<typeof IsExternalRuleCustomized>;
 export const IsExternalRuleCustomized = z.boolean();
 
+/**
+ * Determines whether an external/prebuilt rule has its original, unmodified version present when the calculation of its customization status is performed (`rule_source.is_customized` and `rule_source.customized_fields`).
+ */
+export type ExternalRuleHasBaseVersion = z.infer<typeof ExternalRuleHasBaseVersion>;
+export const ExternalRuleHasBaseVersion = z.boolean();
+
+/**
+ * An array of customized field names — that is, fields that the user has modified from their base value. Defaults to an empty array.
+ */
+export type ExternalRuleCustomizedFields = z.infer<typeof ExternalRuleCustomizedFields>;
+export const ExternalRuleCustomizedFields = z.array(
+  z.object({
+    /**
+     * Name of a user-modified field in the rule object.
+     */
+    field_name: z.string(),
+  })
+);
+
 /**
  * Type of rule source for internally sourced rules, i.e. created within the Kibana apps.
  */
@@ -104,6 +123,8 @@ export type ExternalRuleSource = z.infer<typeof ExternalRuleSource>;
 export const ExternalRuleSource = z.object({
   type: z.literal('external'),
   is_customized: IsExternalRuleCustomized,
+  has_base_version: ExternalRuleHasBaseVersion,
+  customized_fields: ExternalRuleCustomizedFields,
 });
 
 /**

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

@@ -70,6 +70,22 @@ components:
       type: boolean
       description: Determines whether an external/prebuilt rule has been customized by the user (i.e. any of its fields have been modified and diverged from the base value).
 
+    ExternalRuleHasBaseVersion:
+      type: boolean
+      description: Determines whether an external/prebuilt rule has its original, unmodified version present when the calculation of its customization status is performed (`rule_source.is_customized` and `rule_source.customized_fields`).
+
+    ExternalRuleCustomizedFields:
+      type: array
+      description: An array of customized field names — that is, fields that the user has modified from their base value. Defaults to an empty array.
+      items:
+        type: object
+        properties:
+          field_name:
+            type: string
+            description: Name of a user-modified field in the rule object.
+        required:
+          - field_name
+
     InternalRuleSource:
       description: Type of rule source for internally sourced rules, i.e. created within the Kibana apps.
       type: object
@@ -91,9 +107,15 @@ components:
             - external
         is_customized:
           $ref: '#/components/schemas/IsExternalRuleCustomized'
+        has_base_version:
+          $ref: '#/components/schemas/ExternalRuleHasBaseVersion'
+        customized_fields:
+          $ref: '#/components/schemas/ExternalRuleCustomizedFields'
       required:
         - type
         - is_customized
+        - has_base_version
+        - customized_fields
 
     RuleSource:
       description: Discriminated union that determines whether the rule is internally sourced (created within the Kibana app) or has an external source, such as the Elastic Prebuilt rules repo.

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/model/rule_schema/rule_response_schema.test.ts

@@ -259,6 +259,8 @@ describe('rule_source', () => {
     payload.rule_source = {
       type: 'external',
       is_customized: true,
+      customized_fields: [{ field_name: 'name' }],
+      has_base_version: true,
     };
 
     const result = RuleResponse.safeParse(payload);

x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/rule_to_import.test.ts

@@ -1056,6 +1056,8 @@ describe('RuleToImport', () => {
         rule_source: {
           type: 'external',
           is_customized: true,
+          customized_fields: [{ field_name: 'name' }],
+          has_base_version: true,
         },
       });
 

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

@@ -6315,12 +6315,36 @@ components:
         - endpoint_host_isolation_exceptions
         - endpoint_blocklists
       type: string
+    ExternalRuleCustomizedFields:
+      description: >-
+        An array of customized field names — that is, fields that the user has
+        modified from their base value. Defaults to an empty array.
+      items:
+        type: object
+        properties:
+          field_name:
+            description: Name of a user-modified field in the rule object.
+            type: string
+        required:
+          - field_name
+      type: array
+    ExternalRuleHasBaseVersion:
+      description: >-
+        Determines whether an external/prebuilt rule has its original,
+        unmodified version present when the calculation of its customization
+        status is performed (`rule_source.is_customized` and
+        `rule_source.customized_fields`).
+      type: boolean
     ExternalRuleSource:
       description: >-
         Type of rule source for externally sourced rules, i.e. rules that have
         an external source, such as the Elastic Prebuilt rules repo.
       type: object
       properties:
+        customized_fields:
+          $ref: '#/components/schemas/ExternalRuleCustomizedFields'
+        has_base_version:
+          $ref: '#/components/schemas/ExternalRuleHasBaseVersion'
         is_customized:
           $ref: '#/components/schemas/IsExternalRuleCustomized'
         type:
@@ -6330,6 +6354,8 @@ components:
       required:
         - type
         - is_customized
+        - has_base_version
+        - customized_fields
     FindRulesSortField:
       enum:
         - created_at

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

@@ -5645,12 +5645,36 @@ components:
         - endpoint_host_isolation_exceptions
         - endpoint_blocklists
       type: string
+    ExternalRuleCustomizedFields:
+      description: >-
+        An array of customized field names — that is, fields that the user has
+        modified from their base value. Defaults to an empty array.
+      items:
+        type: object
+        properties:
+          field_name:
+            description: Name of a user-modified field in the rule object.
+            type: string
+        required:
+          - field_name
+      type: array
+    ExternalRuleHasBaseVersion:
+      description: >-
+        Determines whether an external/prebuilt rule has its original,
+        unmodified version present when the calculation of its customization
+        status is performed (`rule_source.is_customized` and
+        `rule_source.customized_fields`).
+      type: boolean
     ExternalRuleSource:
       description: >-
         Type of rule source for externally sourced rules, i.e. rules that have
         an external source, such as the Elastic Prebuilt rules repo.
       type: object
       properties:
+        customized_fields:
+          $ref: '#/components/schemas/ExternalRuleCustomizedFields'
+        has_base_version:
+          $ref: '#/components/schemas/ExternalRuleHasBaseVersion'
         is_customized:
           $ref: '#/components/schemas/IsExternalRuleCustomized'
         type:
@@ -5660,6 +5684,8 @@ components:
       required:
         - type
         - is_customized
+        - has_base_version
+        - customized_fields
     FindRulesSortField:
       enum:
         - created_at

x-pack/solutions/security/plugins/security_solution/docs/testing/test_plans/detection_response/prebuilt_rules/prebuilt_rule_customization.md

@@ -48,6 +48,7 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
     - [**Scenario: prebuilt rule's `is_customized` is set to true after it is customized when base version is missing**](#scenario-prebuilt-rules-is_customized-is-set-to-true-after-it-is-customized-when-base-version-is-missing)
     - [**Scenario: prebuilt rule's `is_customized` stays unchanged after it is saved unchanged when base version is missing**](#scenario-prebuilt-rules-is_customized-stays-unchanged-after-it-is-saved-unchanged-when-base-version-is-missing)
     - [**Scenario: prebuilt rule's `is_customized` value is not affected by specific fields when base version is missing**](#scenario-prebuilt-rules-is_customized-value-is-not-affected-by-specific-fields-when-base-version-is-missing)
+    - [**Scenario: prebuilt rule's `customized_fields` resets to an empty array if rule was previously edited with base version present**](#scenario-prebuilt-rules-customized_fields-resets-to-an-empty-array-if-rule-was-previously-edited-with-base-version-present)
   - [Calculating the Modified badge in the UI](#calculating-the-modified-badge-in-the-ui)
     - [**Scenario: Modified badge should appear on the rule details page when prebuilt rule is customized**](#scenario-modified-badge-should-appear-on-the-rule-details-page-when-prebuilt-rule-is-customized)
     - [**Scenario: Modified badge should not appear on the rule details page when prebuilt rule isn't customized**](#scenario-modified-badge-should-not-appear-on-the-rule-details-page-when-prebuilt-rule-isnt-customized)
@@ -83,6 +84,8 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
 - [Common terminology](./prebuilt_rules_common_info.md#common-terminology).
 - **Rule source**, or **`ruleSource`**: a rule field that defines the rule's origin. Can be `internal` or `external`. Currently, custom rules have `internal` rule source and prebuilt rules have `external` rule source.
 - **`is_customized`**: a field within `ruleSource` that exists when rule source is set to `external`. It is a boolean value based on if the rule has been changed from its base version.
+- **`customized_fields`**: a field within `ruleSource` that exists when rule source is set to `external`. It is an array of objects containing field names that have been changed from their base version counterparts.
+- **`has_base_version`**: a field within `ruleSource` that exists when rule source is set to `external`. It is a boolean value based on if the rule had a matching base version during rule source calculation.
 - **non-semantic change**: a change to a rule field that is functionally different. We normalize certain fields so for a time-related field such as `from`, `1m` vs `60s` are treated as the same value. We also trim leading and trailing whitespace for query fields.
 - **rule customization**: a change to a customizable field of a prebuilt rule. Full list of customizable rule fields can be found in [Common information about prebuilt rules](./prebuilt_rules_common_info.md#customizable-rule-fields).
 - **insufficient license**: a license or a product tier that doesn't allow rule customization. In Serverless environments customization is only allowed on Security Essentials product tier. In non-Serverless environments customization is only allowed on Trial and Enterprise licenses.
@@ -245,6 +248,8 @@ Given a prebuilt rule installed
 When user customizes the prebuilt rule by changing the <field_name> field so it differs from the base version
 Then the rule's `is_customized` value should be `true`
 And ruleSource should be "external"
+And the rule's `customized_fields` value should contain <field_name>
+And the rule's `has_base_version` value should be true
 ```
 
 #### **Scenario: prebuilt rule's `is_customized` stays unchanged after it is saved unchanged**
@@ -253,10 +258,12 @@ And ruleSource should be "external"
 
 ```Gherkin
 Given a prebuilt rule installed
-And the prebuilt rule doesn't have a matching base version
+And the prebuilt rule has a matching base version
 When user opens the corresponding rule editing page
 And saves the form unchanged
 Then the rule's `is_customized` value should stay unchanged (non-customized rule stays non-customized)
+And the rule's `customized_fields` value should be an empty array
+And the rule's `has_base_version` value should be true
 ```
 
 **Examples:**
@@ -272,6 +279,8 @@ Given a prebuilt rule installed
 And it is non-customized
 When a user changes the <field_name> field so it differs from the base version
 Then the rule's `is_customized` value should remain `false`
+And the rule's `customized_fields` value should be an empty array
+And the rule's `has_base_version` value should be true
 ```
 
 **Examples:**
@@ -308,6 +317,8 @@ Given a prebuilt rule installed
 And it is customized
 When a user changes the rule fields to match the base version
 Then the rule's `is_customized` value should be false
+And the rule's `customized_fields` value should be an empty array
+And the rule's `has_base_version` value should be true
 ```
 
 ### Detecting rule customizations when base version is missing
@@ -324,6 +335,8 @@ And the prebuilt rule doesn't have a matching base version
 When user customizes the prebuilt rule by changing the <field_name> field so it differs from the base version
 Then the rule's `is_customized` value should be `true`
 And ruleSource should be "external"
+And the rule's `customized_fields` value should be an empty array
+And the rule's `has_base_version` value should be false
 ```
 
 **Examples:**
@@ -340,12 +353,10 @@ And the prebuilt rule doesn't have a matching base version
 When user opens the corresponding rule editing page
 And saves the form unchanged
 Then the rule's `is_customized` value should stay unchanged (non-customized rule stays non-customized)
+And the rule's `customized_fields` value should be an empty array
+And the rule's `has_base_version` value should be false
 ```
 
-**Examples:**
-
-`<field_name>` = all customizable rule fields
-
 #### **Scenario: prebuilt rule's `is_customized` value is not affected by specific fields when base version is missing**
 
 **Automation**: one integration test per field.
@@ -356,6 +367,8 @@ And the prebuilt rule doesn't have a matching base version
 And it is non-customized
 When a user changes the <field_name> field so it differs from the base version
 Then the rule's `is_customized` value should remain `false`
+And the rule's `customized_fields` value should be an empty array
+And the rule's `has_base_version` value should be false
 ```
 
 **Examples:**
@@ -367,6 +380,21 @@ Then the rule's `is_customized` value should remain `false`
 | revision |
 | meta |
 
+#### **Scenario: prebuilt rule's `customized_fields` resets to an empty array if rule was previously edited with base version present**
+
+**Automation**: one integration test.
+
+```Gherkin
+Given a prebuilt rule installed
+And the prebuilt rule has a populated `customized_fields` value
+And the prebuilt rule doesn't have a matching base version
+When user opens the corresponding rule editing page
+And saves the form unchanged
+Then the rule's `is_customized` value should remain true
+And the rule's `customized_fields` value should be an empty array
+And the rule's `has_base_version` value should be false
+```
+
 ### Calculating the Modified badge in the UI
 
 #### **Scenario: Modified badge should appear on the rule details page when prebuilt rule is customized**

x-pack/solutions/security/plugins/security_solution/docs/testing/test_plans/detection_response/prebuilt_rules/prebuilt_rule_import.md

@@ -274,6 +274,7 @@ When the user imports these rules
 Then the rules should be created
 And the created rules should be correctly identified as prebuilt or custom
 And the created rules' is_customized field should be correctly calculated
+And the created rules' customized_fields field should be correctly calculated
 And the created rules' parameters should match the import payload
 ```
 
@@ -292,6 +293,7 @@ When the user imports these rules
 Then the rules should be updated
 And the updated rules should be correctly identified as prebuilt or custom
 And the updated rules' is_customized field should be correctly calculated
+And the created rules' customized_fields field should be correctly calculated
 And the updated rules' parameters should match the import payload
 ```