[modsecurity] Update documentation by ilyannn · Pull Request #17410 · elastic/integrations

ilyannn · 2026-02-13T18:47:30Z

Summary

Add service_info.md knowledge base with reviewed, fact-checked integration details
Rewrite documentation using elastic-package update documentation to follow the new template structure
Add docs_structure_enforced validation
Bump version to 1.23.0

Breaking Changes in Docs

Compared to the previous docs, we:

fix the error where the docs referred to ModSecurity v3 with Apache, even though the original issue referred to v2
use modsec-audit.json file name in examples rather than modsec_audit.json
do not describe the importance of SecAuditLogType Serial as critical
only suggest ABFHJZ parts as an example (was ABDEFHIJZ previously)

Kibana rendering

Note the code in numbered list looks like this but this apparently how our rendering works (perhaps we should reduce the indent of code in the lists in this case?). GitHub does not like this formatting either.

Test plan

elastic-package check passes (tested with both system and dev builds)
Verify README renders correctly in Kibana integration UI
Review generated documentation for accuracy against service_info.md ground truth

Closes https://github.com/elastic/integration-experience/issues/456

🤖 These documentation changes have been largely GenAI-generated as per our protocol. Additionally, Claude Code was used for factual review and as a harness for editing/commit/PR generation under our editorial supervision.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-02-13T18:49:31Z

Vale Linting Results

Summary: 9 warnings, 5 suggestions found

⚠️ Warnings (9)

File	Line	Rule	Message
packages/modsecurity/_dev/build/docs/README.md	69	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
packages/modsecurity/_dev/build/docs/README.md	69	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
packages/modsecurity/_dev/build/docs/README.md	91	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
packages/modsecurity/docs/README.md	69	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
packages/modsecurity/docs/README.md	69	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
packages/modsecurity/docs/README.md	91	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
packages/modsecurity/docs/README.md	188	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'using' instead of 'via'.
packages/modsecurity/docs/knowledge_base/service_info.md	65	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.
packages/modsecurity/docs/knowledge_base/service_info.md	87	Elastic.Latinisms	Latin terms and abbreviations are a common source of confusion. Use 'and so on' instead of 'etc'.

💡 Suggestions (5)

File	Line	Rule	Message
packages/modsecurity/_dev/build/docs/README.md	3	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
packages/modsecurity/_dev/build/docs/README.md	91	Elastic.Semicolons	Use semicolons judiciously.
packages/modsecurity/docs/README.md	3	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.
packages/modsecurity/docs/README.md	91	Elastic.Semicolons	Use semicolons judiciously.
packages/modsecurity/docs/knowledge_base/service_info.md	87	Elastic.Semicolons	Use semicolons judiciously.

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.

Replace Latin term "via" with "using"/"through" and "see" with "get" per Elastic docs style guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add ModSecurity v2 for Apache (v2.9.x) to compatibility section - Soften Part K exclusion from "must"/"CRITICAL" to recommendation - Clarify event.original requires preserve_original_event enabled - Fix inconsistent SecAuditLogParts in troubleshooting section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Reflects factual corrections in service_info.md: - Compatibility section now notes v2 Apache test coverage - Part K exclusion softened to recommendation - Validation step clarifies event.original requires opt-in - Consistent SecAuditLogParts across setup and troubleshooting Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove two Gemini-generated AI disclaimers not present in other integration docs. Replace "via" with "using" per Elastic style guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Align troubleshooting recommendation with setup section. Part H (audit trailer) contains useful action and timing data. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove link to this same integration doc page and generic Elastic Agent Troubleshooting link from vendor documentation sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

elastic-vault-github-plugin-prod · 2026-02-13T23:31:22Z

🚀 Benchmarks report

To see the full report comment with /test benchmark fullreport

… vendor sections The Apache support was added in PR elastic#3363 for ModSecurity v2 (2.9.x), not v3 with the Apache connector. Updated compatibility to reflect what is actually tested. Removed duplicate vendor resource sections and circular self-referencing links. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

elasticmachine · 2026-02-13T23:53:04Z

Pinging @elastic/integration-experience (Team:Integration-Experience)

mjwolf

This looks good! Thanks for working on it.
There's just one list that should be removed. It was a mistake in the generator that it was added

Co-authored-by: Michael Wolf <michael.wolf@elastic.co>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

elasticmachine · 2026-02-22T20:58:23Z

💚 Build Succeeded

Buildkite Build
Commit: 97e1203

History

💔 Build #38624 failed 8d9868c
💚 Build #38334 succeeded 28bb601
💚 Build #38264 succeeded 5ecf0a7
💚 Build #38228 succeeded e97c706
💚 Build #38227 succeeded 189179c

cc @ilyannn

jrmolin

please fix the reasonable vale recommendations

ilyannn · 2026-02-24T22:09:18Z

please fix the reasonable vale recommendations

Which ones do you consider reasonable? I think I already fixed everything I could.

theletterf · 2026-02-25T09:27:18Z

Most of those are false positives we need to fix in the Vale rules. We can disregard.

elastic-vault-github-plugin-prod · 2026-02-25T11:06:37Z

Package modsecurity - 1.23.0 containing this change is available at https://epr.elastic.co/package/modsecurity/1.23.0/

theletterf · 2026-02-25T17:46:00Z

Alas, we don't accept apache as a valid syntax highlighting value. Opening a PR to fix this.

* [modsecurity] Update documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Update changelog PR link to elastic#17410 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix Vale linting warnings in modsecurity docs Replace Latin term "via" with "using"/"through" and "see" with "get" per Elastic docs style guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Update modsecurity service_info.md with factual corrections - Add ModSecurity v2 for Apache (v2.9.x) to compatibility section - Soften Part K exclusion from "must"/"CRITICAL" to recommendation - Clarify event.original requires preserve_original_event enabled - Fix inconsistent SecAuditLogParts in troubleshooting section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Regenerate modsecurity docs from corrected knowledge base Reflects factual corrections in service_info.md: - Compatibility section now notes v2 Apache test coverage - Part K exclusion softened to recommendation - Validation step clarifies event.original requires opt-in - Consistent SecAuditLogParts across setup and troubleshooting Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Remove AI disclaimers and fix Vale style violations Remove two Gemini-generated AI disclaimers not present in other integration docs. Replace "via" with "using" per Elastic style guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add validated AI-assisted disclaimer to modsecurity docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Use consistent SecAuditLogParts ABFHJZ across docs Align troubleshooting recommendation with setup section. Part H (audit trailer) contains useful action and timing data. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Remove 'Note that' from compatibility section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Remove self-referential and misplaced links from docs Remove link to this same integration doc page and generic Elastic Agent Troubleshooting link from vendor documentation sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix compatibility: list v2 for Apache instead of v3, remove duplicate vendor sections The Apache support was added in PR elastic#3363 for ModSecurity v2 (2.9.x), not v3 with the Apache connector. Updated compatibility to reflect what is actually tested. Removed duplicate vendor resource sections and circular self-referencing links. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Review feedback Co-authored-by: Michael Wolf <michael.wolf@elastic.co> * Rebuild docs to remove generated use-case list Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Michael Wolf <michael.wolf@elastic.co>

ilyannn and others added 2 commits February 13, 2026 19:45

[modsecurity] Update documentation

f73a5bb

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Update changelog PR link to elastic#17410

48810c0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ilyannn and others added 8 commits February 13, 2026 20:47

Fix Vale linting warnings in modsecurity docs

e99246e

Replace Latin term "via" with "using"/"through" and "see" with "get" per Elastic docs style guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove AI disclaimers and fix Vale style violations

321e29e

Remove two Gemini-generated AI disclaimers not present in other integration docs. Replace "via" with "using" per Elastic style guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add validated AI-assisted disclaimer to modsecurity docs

2026205

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Use consistent SecAuditLogParts ABFHJZ across docs

0e627c7

Align troubleshooting recommendation with setup section. Part H (audit trailer) contains useful action and timing data. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove 'Note that' from compatibility section

926eadf

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove self-referential and misplaced links from docs

189179c

Remove link to this same integration doc page and generic Elastic Agent Troubleshooting link from vendor documentation sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ilyannn self-assigned this Feb 13, 2026

ilyannn marked this pull request as ready for review February 13, 2026 23:53

ilyannn requested a review from a team as a code owner February 13, 2026 23:53

ilyannn added 2 commits February 16, 2026 09:02

Merge branch 'main' into update-modsecurity-documentation

5ecf0a7

Merge branch 'main' into update-modsecurity-documentation

28bb601

mjwolf reviewed Feb 19, 2026

View reviewed changes

Comment thread packages/modsecurity/_dev/build/docs/README.md Outdated

ilyannn and others added 2 commits February 22, 2026 22:09

Review feedback

5c2fb6f

Co-authored-by: Michael Wolf <michael.wolf@elastic.co>

Merge branch 'main' into update-modsecurity-documentation

8d9868c

ilyannn requested a review from mjwolf February 22, 2026 20:26

Rebuild docs to remove generated use-case list

97e1203

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ilyannn removed their assignment Feb 22, 2026

jrmolin approved these changes Feb 24, 2026

View reviewed changes

ilyannn self-assigned this Feb 25, 2026

theletterf approved these changes Feb 25, 2026

View reviewed changes

theletterf merged commit 9febc2d into elastic:main Feb 25, 2026
11 checks passed

theletterf mentioned this pull request Feb 25, 2026

Fix false positives in Latinisms, WordChoice, and Wordiness rules elastic/vale-rules#109

Merged

6 tasks

theletterf mentioned this pull request Feb 25, 2026

Remove apache code fence #17578

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[modsecurity] Update documentation#17410

[modsecurity] Update documentation#17410
theletterf merged 16 commits intoelastic:mainfrom
ilyannn:update-modsecurity-documentation

ilyannn commented Feb 13, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 13, 2026 •

edited

Loading

Uh oh!

elastic-vault-github-plugin-prod bot commented Feb 13, 2026 •

edited

Loading

Uh oh!

elasticmachine commented Feb 13, 2026

Uh oh!

mjwolf left a comment

Uh oh!

Uh oh!

elasticmachine commented Feb 22, 2026

Uh oh!

jrmolin left a comment

Uh oh!

ilyannn commented Feb 24, 2026 •

edited

Loading

Uh oh!

theletterf commented Feb 25, 2026

Uh oh!

Uh oh!

elastic-vault-github-plugin-prod bot commented Feb 25, 2026

Uh oh!

theletterf commented Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

ilyannn commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking Changes in Docs

Kibana rendering

Test plan

Uh oh!

github-actions bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

elastic-vault-github-plugin-prod bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Benchmarks report

Uh oh!

elasticmachine commented Feb 13, 2026

Uh oh!

mjwolf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

elasticmachine commented Feb 22, 2026

💚 Build Succeeded

History

Uh oh!

jrmolin left a comment

Choose a reason for hiding this comment

Uh oh!

ilyannn commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theletterf commented Feb 25, 2026

Uh oh!

Uh oh!

elastic-vault-github-plugin-prod bot commented Feb 25, 2026

Uh oh!

theletterf commented Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ilyannn commented Feb 13, 2026 •

edited

Loading

github-actions bot commented Feb 13, 2026 •

edited

Loading

elastic-vault-github-plugin-prod bot commented Feb 13, 2026 •

edited

Loading

ilyannn commented Feb 24, 2026 •

edited

Loading