[Security][Quality] Improve docs for Security detections and alerts

[nastasha-solomon]

Summary

Restructures the Detections and alerts section. Significant changes include: reduced duplication, improved navigation and cross-linking, more audience-centric guidance, and extensible structures.

The new structure:

Detections and alerts
├── Before you begin
│   ├── Turn on detections
│   ├── Detections privileges
│   ├── Detection rule concepts
│   └── Advanced data source configuration
│       ├── Cross-cluster search detection rules
│       └── Using LogsDB index mode with Elastic Security
│
├── MITRE ATT&CK coverage
│
├── Prebuilt rules
│   ├── Install prebuilt rules
│   ├── Update prebuilt rules
│   ├── Prebuilt rules in air-gapped environments
│   └── Customize prebuilt rules
│
├── Author rules
│   ├── Choose the right rule type
│   │   └── About building block rules
│   ├── Rule types
│   │   ├── ES|QL
│   │   ├── Custom query
│   │   ├── EQL
│   │   ├── Indicator match
│   │   ├── New terms
│   │   └── Machine learning
│   │   └── Threshold
│   ├── Using the UI
│   ├── Using the API
│   ├── Common rule settings
│   ├── Set rule data sources
│   ├── Write investigation guides
│   └── Validate and test rules
│
├── Manage detection rules
│
├── Monitor rule executions
│   └── Fill rule execution gaps
│
├── Reduce noise and false positives
│   ├── Tune detection rules
│   ├── Rule exceptions
│   │   ├── Create and manage value lists
│   │   ├── Add and manage exceptions
│   │   └── Create and manage shared exception lists
│   └── Alert suppression
│
└── Manage detection alerts
    ├── Visualize detection alerts
    ├── View detection alert details
    ├── Add detection alerts to cases
    └── Query alert indices

This PR addresses https://github.com/elastic/docs-content-internal/issues/797, which is the main issue tracking quality improvements to the Security detection docs. It also addresses some gaps and doc bugs that have been sitting in the backlog for 3453485384953794348 years.

Review requests

For technical reviewers

Please verify accuracy in the following areas:

Rule type pages (new)

Please review the following pages for accuracy and completeness. Most of the content is a direct port. The net-new content is fairly limited.

(Fixes https://github.com/elastic/docs-content-internal/issues/239 by creating individual configuration guides for each rule type.)

• Custom query rules
• Event correlation (EQL) rules
• Threshold rules
• Indicator match rules
• New terms rules
• ES|QL rules
• Machine learning rules

Reference and decision guides (new or heavily rewritten to improve clarity and findability)

Page	What to verify
Detections and alerts	The sections about where to start and the detection program lifecycle for accuracy and fixes added for #1210
Detection rule concepts	Mental model for rules, key component explanations, and glossary
Common rule settings	All shared field descriptions for completeness and accuracy
Choose the right rule type	Comparison table accuracy
Reduce noise and false positives	Decision table, key distinctions table, scenario walkthrough
Using the API	API endpoint paths and links for Stack and Serverless

Other rewritten pages

Page	What to verify
Write investigation guides	Markdown syntax table, Osquery steps, best practices
Set rule data sources	Per-rule index pattern behavior, cold/frozen tier filter accuracy
Validate and test rules	DaC workflow accuracy
Suppress detection alerts	Info added to fix #1545 and https://github.com/elastic/security-docs-internal/issues/22
Prebuilt rules	Info added to fix elastic/security-docs#3035, elastic/kibana#109016, #3994
Create and manage value lists	Info added to fix elastic/security-docs#3754 and elastic/security-docs#4929

---

For editorial reviewers

Please check the following items for logical flow and navigation between pages and glaring style/formatting errors.

Hub pages
Please spot-check navigation and descriptions for the following:

• Before you begin
• Prebuilt rules
• Author rules
• Advanced data source configuration
• Rule type guides
• MITRE ATT&CK coverage

Restructured pages

• Manage detection rules - Refocused page on flows tied to editing rules.
• Monitor rule executions - Descoped page to only cover content related to monitoring rules.
• Fill rule execution gaps - Centralized feature docs for filling gaps rules.
• Suppress detection alerts - Improved structure and refined certain sections that were overly complex. Also fixes [Website]: suppressed alerts count toward the maximum number of alerts defined by xpack.alerting.rules.run.alerts.max #1545.

Prebuilt rules pages
Content from Use Elastic prebuilt rules and Update modified and unmodified Elastic prebuilt rules was moved around into three buckets: install, update, and customize prebuilt rule. To help convey capabilities provided at certain subscription levels, added comparison tables and specified when certain flows were gated behind subscriptions.

• Install Elastic prebuilt rules
• Update Elastic prebuilt rules
• Customize Elastic prebuilt rules

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

Cursor, Claude

[github-actions]

Vale Linting Results

Summary: 9 warnings, 55 suggestions found

⚠️ Warnings (9)

File	Line	Rule	Message
solutions/security/detect-and-alert/common-rule-settings.md	117	Elastic.Spelling	'subtechniques' is a possible misspelling.
solutions/security/detect-and-alert/esql.md	23	Elastic.DontUse	Don't use '...'.
solutions/security/detect-and-alert/esql.md	162	Elastic.DontUse	Don't use '...'.
solutions/security/detect-and-alert/indicator-match.md	16	Elastic.Spelling	'operationalizing' is a possible misspelling.
solutions/security/detect-and-alert/prebuilt-rules-airgapped.md	21	Elastic.Spelling	'prebundled' is a possible misspelling.
solutions/security/detect-and-alert/query-alert-indices.md	63	Elastic.Spelling	'triaged' is a possible misspelling.
solutions/security/detect-and-alert/validate-and-test-rules.md	24	Elastic.Spelling	'auditability' is a possible misspelling.
solutions/security/detect-and-alert/view-detection-alert-details.md	40	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
troubleshoot/security/detection-rules.md	192	Elastic.DontUse	Don't use 'note that'.

💡 Suggestions (55)

File	Line	Rule	Message
explore-analyze/alerting/alerts/rule-types.md	16	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
reference/glossary/index.md	259	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
reference/glossary/index.md	425	Elastic.Wordiness	Consider using 'to' instead of 'in order to'.
solutions/security/detect-and-alert/about-building-block-rules.md	20	Elastic.WordChoice	Consider using 'run, start' instead of 'execute', unless the term is in the UI.
solutions/security/detect-and-alert/common-rule-settings.md	202	Elastic.WordChoice	Consider using 'run, start' instead of 'execute', unless the term is in the UI.
solutions/security/detect-and-alert/common-rule-settings.md	281	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'see', unless the term is in the UI.
solutions/security/detect-and-alert/common-rule-settings.md	291	Elastic.Wordiness	Consider using 'because' instead of 'since'.
solutions/security/detect-and-alert/custom-query.md	22	Elastic.WordChoice	Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI.
solutions/security/detect-and-alert/custom-query.md	92	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/detection-rule-concepts.md	32	Elastic.WordChoice	Consider using 'run, start' instead of 'execute', unless the term is in the UI.
solutions/security/detect-and-alert/detection-rule-concepts.md	65	Elastic.Wordiness	Consider using 'tell' instead of 'inform'.
solutions/security/detect-and-alert/detection-rule-concepts.md	85	Elastic.WordChoice	Consider using 'run, start' instead of 'Execute', unless the term is in the UI.
solutions/security/detect-and-alert/detection-rule-concepts.md	87	Elastic.WordChoice	Consider using 'run, start' instead of 'Execute', unless the term is in the UI.
solutions/security/detect-and-alert/detection-rule-concepts.md	111	Elastic.WordChoice	Consider using 'run, start' instead of 'execute', unless the term is in the UI.
solutions/security/detect-and-alert/detection-rule-concepts.md	135	Elastic.WordChoice	Consider using 'run, start' instead of 'execute', unless the term is in the UI.
solutions/security/detect-and-alert/esql.md	23	Elastic.Ellipses	In general, don't use an ellipsis.
solutions/security/detect-and-alert/esql.md	162	Elastic.Ellipses	In general, don't use an ellipsis.
solutions/security/detect-and-alert/fill-rule-gaps.md	15	Elastic.WordChoice	Consider using 'efficiently' instead of 'simply', unless the term is in the UI.
solutions/security/detect-and-alert/indicator-match.md	20	Elastic.Semicolons	Use semicolons judiciously.
solutions/security/detect-and-alert/indicator-match.md	20	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
solutions/security/detect-and-alert/indicator-match.md	20	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/indicator-match.md	133	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/manage-detection-alerts.md	153	Elastic.WordChoice	Consider using 'run, start' instead of 'Execute', unless the term is in the UI.
solutions/security/detect-and-alert/manage-detection-rules.md	82	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
solutions/security/detect-and-alert/manage-detection-rules.md	84	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'Disable', unless the term is in the UI.
solutions/security/detect-and-alert/manage-detection-rules.md	94	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
solutions/security/detect-and-alert/manage-detection-rules.md	185	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/mitre-attack-coverage.md	79	Elastic.WordChoice	Consider using 'deactivated, deselected, hidden, turned off, unavailable' instead of 'disabled', unless the term is in the UI.
solutions/security/detect-and-alert/new-terms.md	83	Elastic.HeadingColons	Capitalize ': f'.
solutions/security/detect-and-alert/new-terms.md	111	Elastic.HeadingColons	Capitalize ': n'.
solutions/security/detect-and-alert/new-terms.md	135	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/prebuilt-rules-airgapped.md	231	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/prebuilt-rules.md	34	Elastic.Semicolons	Use semicolons judiciously.
solutions/security/detect-and-alert/prebuilt-rules.md	80	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/prebuilt-rules.md	80	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/query-alert-indices.md	43	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	47	Elastic.FirstPerson	Use caution when using first-person pronouns such as 'my.'
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	92	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	104	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	104	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/set-rule-data-sources.md	40	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/set-rule-data-sources.md	62	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/using-the-rule-builder.md	69	Elastic.WordChoice	Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI.
solutions/security/detect-and-alert/view-detection-alert-details.md	19	Elastic.Wordiness	Consider using 'act' instead of 'Take action'.
solutions/security/detect-and-alert/view-detection-alert-details.md	151	Elastic.Versions	Use 'or later' instead of 'or higher' when referring to versions.
solutions/security/detect-and-alert/view-detection-alert-details.md	198	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/view-detection-alert-details.md	227	Elastic.WordChoice	Consider using 'refer to (if it's a document), view (if it's a UI element)' instead of 'See', unless the term is in the UI.
solutions/security/detect-and-alert/view-detection-alert-details.md	228	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/view-detection-alert-details.md	230	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/view-detection-alert-details.md	231	Elastic.Versions	Use 'or later' instead of 'or higher' when referring to versions.
solutions/security/detect-and-alert/visualize-detection-alerts.md	117	Elastic.Semicolons	Use semicolons judiciously.
solutions/security/detect-and-alert/visualize-detection-alerts.md	152	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/get-started/automatic-migration.md	138	Elastic.Repetition	"the" is repeated.
solutions/security/get-started/configure-advanced-settings.md	93	Elastic.Semicolons	Use semicolons judiciously.
troubleshoot/security/detection-rules.md	206	Elastic.Wordiness	Consider using 'also' instead of 'In addition'.

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[github-actions]

🔍 Preview links for changed docs

• solutions/security/detect-and-alert/advanced-data-source-configuration.md
• solutions/security/detect-and-alert/alert-suppression.md
• solutions/security/detect-and-alert/author-rules.md
• solutions/security/detect-and-alert/before-you-begin.md
• solutions/security/detect-and-alert/choose-the-right-rule-type.md
• solutions/security/detect-and-alert/common-rule-settings.md
• solutions/security/detect-and-alert/custom-query.md
• solutions/security/detect-and-alert/customize-prebuilt-rules.md
• solutions/security/detect-and-alert/detection-rule-concepts.md
• solutions/security/detect-and-alert/eql.md

More links …

• solutions/security/detect-and-alert/esql.md
• solutions/security/detect-and-alert/fill-rule-gaps.md
• solutions/security/detect-and-alert/indicator-match.md
• solutions/security/detect-and-alert/install-prebuilt-rules.md
• solutions/security/detect-and-alert/machine-learning.md
• solutions/security/detect-and-alert/mitre-attack-coverage.md
• solutions/security/detect-and-alert/new-terms.md
• solutions/security/detect-and-alert/prebuilt-rules.md
• solutions/security/detect-and-alert/reduce-noise-and-false-positives.md
• solutions/security/detect-and-alert/rule-types.md
• solutions/security/detect-and-alert/set-rule-data-sources.md
• solutions/security/detect-and-alert/threshold.md
• solutions/security/detect-and-alert/update-prebuilt-rules.md
• solutions/security/detect-and-alert/using-the-api.md
• solutions/security/detect-and-alert/using-the-rule-builder.md
• solutions/security/detect-and-alert/validate-and-test-rules.md
• solutions/security/detect-and-alert/write-investigation-guides.md
• explore-analyze/alerting/alerts/alerting-setup.md
• explore-analyze/alerting/alerts/rule-types.md
• manage-data/data-store/data-streams/logs-data-stream-configure.md
• manage-data/data-store/data-streams/logs-data-stream-integrations.md
• manage-data/data-store/data-streams/logs-data-stream.md
• reference/glossary/index.md
• reference/security/fields-and-object-schemas/alert-schema.md
• solutions/security/advanced-entity-analytics/anomaly-detection.md
• solutions/security/advanced-entity-analytics/machine-learning-job-rule-requirements.md
• solutions/security/cloud/d4c/get-started-with-d4c.md
• solutions/security/detect-and-alert.md
• solutions/security/detect-and-alert/about-building-block-rules.md
• solutions/security/detect-and-alert/add-manage-exceptions.md
• solutions/security/detect-and-alert/create-manage-shared-exception-lists.md
• solutions/security/detect-and-alert/create-manage-value-lists.md
• solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md
• solutions/security/detect-and-alert/detections-privileges.md
• solutions/security/detect-and-alert/manage-detection-alerts.md
• solutions/security/detect-and-alert/manage-detection-rules.md
• solutions/security/detect-and-alert/monitor-rule-executions.md
• solutions/security/detect-and-alert/prebuilt-rules-airgapped.md
• solutions/security/detect-and-alert/query-alert-indices.md
• solutions/security/detect-and-alert/rule-exceptions.md
• solutions/security/detect-and-alert/tune-detection-rules.md
• solutions/security/detect-and-alert/using-logsdb-index-mode-with-elastic-security.md
• solutions/security/detect-and-alert/view-detection-alert-details.md
• solutions/security/detect-and-alert/visualize-detection-alerts.md
• solutions/security/endpoint-response-actions/configure-third-party-response-actions.md
• solutions/security/endpoint-response-actions/isolate-host.md
• solutions/security/esql-for-security.md
• solutions/security/get-started/automatic-migration.md
• solutions/security/get-started/configure-advanced-settings.md
• solutions/security/get-started/elastic-security-requirements.md
• solutions/security/get-started/elastic-security-ui.md
• solutions/security/get-started/get-started-cloud-security.md
• solutions/security/get-started/get-started-detect-with-siem.md
• solutions/security/get-started/get-started-endpoint-security.md
• solutions/security/investigate/add-osquery-response-actions.md
• solutions/security/investigate/timeline-templates.md
• solutions/security/manage-elastic-defend/endpoint-protection-rules.md
• troubleshoot/security/detection-rules.md
• solutions/security/detect-and-alert/turn-on-detections.md

[nastasha-solomon]

f47b72e adds annotated examples to all rule type guides. Thanks again @Mikaayenson for your help with this!

[dhurley14]

This is an awesome undertaking thank you @nastasha-solomon! I left some nits. LGTM!