[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
│   ├── Requirements and privileges
│   ├── Detections privileges
│   └── Advanced data source configuration
│       ├── Cross-cluster search detection rules
│       └── Using LogsDB index mode with Elastic Security
│
├── Prebuilt rules
│   ├── Install prebuilt rules
│   ├── Update prebuilt rules
│   ├── Prebuilt rules in air-gapped environments
│   ├── Customize prebuilt rules
│   └── MITRE ATT&CK coverage
│
├── Author rules
│   ├── Choose the right rule type
│   │   └── About building block rules
│   ├── Rule types
│   │   ├── EQL
│   │   ├── Custom query
│   │   ├── Threshold
│   │   ├── Indicator match
│   │   ├── New terms
│   │   ├── ES|QL
│   │   └── Machine learning
│   ├── Using the rule builder
│   ├── 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: 11 warnings, 36 suggestions found

⚠️ Warnings (11)

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	111	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/indicator-match.md	24	Elastic.Spelling	'data's' is a possible misspelling.
solutions/security/detect-and-alert/manage-detection-rules.md	166	Elastic.DontUse	Don't use 'just'.
solutions/security/detect-and-alert/new-terms.md	34	Elastic.QuotesPunctuation	Place punctuation inside closing quotation marks.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	102	Elastic.Spelling	'deduplicates' is a possible misspelling.
solutions/security/detect-and-alert/tune-detection-rules.md	17	Elastic.DontUse	Don't use 'just'.
solutions/security/detect-and-alert/validate-and-test-rules.md	24	Elastic.Spelling	'auditability' is a possible misspelling.
troubleshoot/security/detection-rules.md	192	Elastic.DontUse	Don't use 'note that'.

💡 Suggestions (36)

File	Line	Rule	Message
solutions/security/detect-and-alert/before-you-begin.md	25	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/common-rule-settings.md	94	Elastic.WordChoice	Consider using 'can, might' instead of 'may', 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/customize-prebuilt-rules.md	15	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
solutions/security/detect-and-alert/customize-prebuilt-rules.md	56	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	23	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	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	84	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	86	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	103	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	127	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	111	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	22	Elastic.Wordiness	Consider using 'also' instead of 'In addition'.
solutions/security/detect-and-alert/manage-detection-rules.md	27	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	96	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	166	Elastic.Semicolons	Use semicolons judiciously.
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/monitor-rule-executions.md	21	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/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/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	90	Elastic.Wordiness	Consider using 'all' instead of 'all of '.
solutions/security/detect-and-alert/reduce-noise-and-false-positives.md	102	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	102	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.

---

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/requirements-privileges.md

[yctercero]

Just a mental note so I don't forget we might need to update this for serverless UIAM stuff.

[yctercero]

This is cool. Would be great to get the trade team's insight on this section.

[nastasha-solomon]

Yes, that's the plan! In my next phase of improving the rule guides, I'm hoping to add more prescriptive guidance for writing queries and annotated examples from our library of prebuilt rules.

[yctercero]

Nitpick suggestion: maybe worth just sticking to having a section on what the rule is best fit for? If not we're repeating this in each rule type page.

[nastasha-solomon]

Valid suggestion, but I still think there's benefits to being overly prescriptive in this section and repeating the pattern across all of the rule type guides. The main benefits being:

• Speeds up decision-making - Lets users confirm or reject a rule type's fit before reading through the lower-level configuration details.
• Reduces misconfigurations - Should prevent users from making common mistakes early on, such as choosing threshold when event order matters.
• Creates connected navigation - Each "not best fit" bullet links to the right alternative, turning seven standalone pages into an interconnected decision tree.
• Matches practitioner thinking - Rule selection is usually elimination ("can this handle sequences?"), not feature comparison. The negative framing fits that mindset.
• Lowers the learning curve - When users visit any one page, they're able to indirectly learn the other available rule types and the use cases they're good fits for.