[FR] Managing Multiple Rule Sets

docs/core_component_syncing_rules_and_data_from_elastic_security_to_vcs.md

@@ -126,6 +126,8 @@ jobs:
 
 Here **`kibana export-rules --directory` (`-d`)** is the **output** directory (unlike **`export-rules-from-repo`**, where **`-d`** loads **input** rules). Add **`--save-as-yaml` / `-sy`** to write YAML instead of TOML. For repo → NDJSON or per-rule YAML, see **`export-rules-from-repo`** in the [Quick Start](dac_quick_start_guide.md#syncing-with-kibana).
 
+When syncing more than one rule set from the same Kibana space, use `--custom-rules-only` / `-cro` or `--export-query` / `-eq` to keep each export intentionally scoped. For example, custom rules can be exported with `-cro`, customized Elastic prebuilt rules can be filtered with `alert.attributes.params.ruleSource.isCustomized: true and alert.attributes.params.immutable: true`, and unmodified Elastic prebuilt rules can be filtered with `alert.attributes.params.ruleSource.isCustomized: false and alert.attributes.params.immutable: true`. Avoid using `enabled` to classify rule ownership because it only represents whether the rule is active in Kibana. For more detail and examples, see [Managing custom and prebuilt rules together](dac_quick_start_guide.md#managing-custom-and-prebuilt-rules-together).
+
 ```bash
 # Export Rules from Elastic Security
 python -m detection_rules kibana export-rules -d test-export-rules --skip-errors

docs/core_components_and_governance_models_of_dac.md

@@ -59,6 +59,13 @@ For details on the various options, refer to those specific core components sect
 
 When the Version Control System (VCS) serves as the authoritative source, all rule changes originate from VCS, emphasizing a code-first approach to detection rule management. This model supports strict change control and full traceability of rule modifications, which is ideal for teams prioritizing rigorous oversight and auditability of detection rules.
 
+For teams managing both custom rules and Elastic prebuilt rules, the VCS-authoritative model treats the organization repository as the source of truth for every deployed rule set. Elastic prebuilt rule updates are pulled from the upstream `elastic/detection-rules` repository, custom rules are created in the organization's custom rules directory, and any prebuilt rule customization is reviewed as code before deployment to Elastic Security.
+
+|                                                                                        |
+| -------------------------------------------------------------------------------------- |
+| <img src="_static/multiple_rule_sets_vcs_authoritative.svg" alt="Managing custom and prebuilt rule sets with VCS as authoritative"/> |
+| <center>*Managing Multiple Rule Sets with VCS as Authoritative* </center> |
+
 #### Considerations
 
 Choosing VCS as the authoritative source requires establishing stringent procedures for rule creation, modification, and deployment, ensuring that all changes are versioned and reviewed before being synchronized to Elastic Security. This governance model relies heavily on CI/CD pipelines to manage deployments and maintain rule integrity across environments.
@@ -146,6 +153,13 @@ Dual syncing between Elastic Security and a Version Control System (VCS) embodie
 | <img src="_static/dual_sync_overall_diagram.png" style="width:5.94271in;height:5.84793in" alt="Dual Sync Diagram"/> |
 | <center>*Figure 2: Combining Multiple Options to Dual Sync Rules* </center>                                    |
 
+When managing custom rules and prebuilt rules together in a dual sync model, use scoped exports from Elastic Security to separate custom rules, customized prebuilt rules, and unmodified prebuilt rules before opening a reconciliation PR. This prevents an analyst's Kibana-side change from silently overwriting a VCS-side change, and it keeps prebuilt rule package updates distinct from local customizations.
+
+|                                                                                        |
+| -------------------------------------------------------------------------------------- |
+| <img src="_static/multiple_rule_sets_dual_sync.svg" alt="Managing custom and prebuilt rule sets with dual sync"/> |
+| <center>*Managing Multiple Rule Sets with Dual Sync* </center> |
+
 #### Considerations
 
 Implementing a dual syncing strategy requires careful planning and consideration of several factors to ensure its success. A successful dual syncing strategy involves integrating automation tools to handle the bidirectional flow of rule data. It requires a robust setup that can automatically compare rules by version or hash, ensuring that updates made within Elastic Security are synchronized back into VCS before final deployment. Utilizing the version lock file from the detection rules repository, or a bespoke versioning system, plays a pivotal role in managing this synchronization process seamlessly. Additionally, team-specific processes may be required to ensure production rules remain in sync.