Repository navigation
DOC: SecRuleUpdateActionById and chain docs are errant for both 2.x and 3.x #2860
Description
The official doc for modsecurity 2.x and 3.x for both SecRuleUpdateActionById and chain are errant. They lead to errant rule writing and/or exposing underlying modsecurity bugs. I request clarification/rewrite of at least these two sections of both 2.x and 3.x docs.
This is a cascade issue from coreruleset/coreruleset#3080 (comment). I recommend reviewing that whole issue to understand the errant docs and gaps in information.
Doc Problems
SecRuleUpdateActionByIddoesn't organize limitations/workarounds together; e.g. modsec 2.xSecRuleUpdateActionByIdon rule chains has achainworkaround (see issue above) and limitation (see issue above) and may have additional behavior/workaround changes in 3.x (I can't test 3.x)chainhas wrong language, e.g. "Non-disruptive rules" should be "Non-disruptive actions"chainhas wrong facts, e.g. "they [non-disruptive actions] will be executed if the rule that contains them matches and not only when the entire chain matches". That statement is false since it has been proven in 2.x (can't test myself in 3.x) thatsetvardoes NOT "not only when the entire chain matches".- Coordinate
chainwithSecRuleUpdateActionByIddocs so they match each other's limitations/workarounds.
Docs problems of these areas exist in both 2.x and 3.x docs; sometimes similar, sometimes identical.
I recommend adding some rule + rule update examples to demonstrate how to use them correctly on each 2.x and 3.x. The issue above has premade examples.
Below is one suggestion for the 3.x docs.
Example 3.x docs for SecRuleUpdateActionById
...It has two limitations: it cannot be used to change the ID or phase of a rule. Only the actions that
can appear only once are overwritten. The actions that are allowed to appear multiple times in a list,
will be appended to the end of the list.
Example foo bar...
then 3 paragraphs and 2 examples under that is another limitation
Note : If the target rule is a chained rule, action updates may only be made to the main (first) rule in the chain.
These need to be combined together. Perhaps something like
...It has limitations
1. it cannot be used to change the ID or phase of a rule.
2. Only the actions that can appear only once are overwritten. The actions that are allowed to appear
multiple times in a list, will be appended to the end of the list.
3. If the target rule is a chained rule, action updates may only be made to the main (first) rule in the chain.
This is a tighter restriction than modsecurity 2.x.
Example foo bar...
Activity
martinhsv commentedon Jul 28, 2023
@diablodale ,
Thanks for raising these. I have corrected what you mentioned in (3) with the rest still to be addressed.
fzipi commentedon Oct 12, 2026
Revisiting this one. Item (3) was corrected in 2023; the
SecRuleUpdateActionByIdlimitations with chains and the wording of thechainsection are still open in the wiki. Documentation only, no code involved. Help wanted.diablodale commentedon Oct 20, 2026
@fzipi how could I? I think your team locked the wiki for public editing. And the hidden wiki repo doesn't have PRs.
fzipi commentedon Oct 20, 2026
We are changing that really soon 😄
diablodale commentedon Oct 20, 2026
Ping me here again when you have a way I can do a PR or push a commit.
I'll use claude to update the wiki docs and then "upload" for your review
fzipi commentedon Oct 26, 2026
@diablodale here's the ping 🙂 The wiki has moved to https://www.modsecurity.org/docs/, and its sources live in https://github.com/owasp-modsecurity/documentation, which accepts pull requests. Every page has an edit link to its source file.
The two sections from this issue:
chain:content/3-reference-manual/3-5-actions.mdSecRuleUpdateActionById:content/3-reference-manual/3-2-configuration-directives.mdv2 and v3 now share a single page per entry, with the v3 differences noted inline, so one PR can fix both. Corrections to the chain/update-action limitations and worked examples are very welcome.
fzipi commentedon Oct 26, 2026
@diablodale I opened owasp-modsecurity/documentation#2, which rewrites the
chainandSecRuleUpdateActionByIdsections based on what you found in coreruleset/coreruleset#3080:chain: a non-disruptive action runs once its rule and every rule before it in the chain have matched, not only when "the rule that contains them matches". There's also a worked three-rule example.SecRuleUpdateActionById: the chain caveats for both engines are now in one place. In v2, an update withoutchainunchains the rule (your case 5). Repeatchainonly on rules that already have it, which matches your recommendation. In v3, updates apply at run time to the chain starter only, so the chain can't be broken.The v3 behavior was checked against the regression suite. The v2 part comes from reading the source plus your 2.9.3 repro, so a review from you would be very welcome, especially of the v2 wording. Comments or suggested changes directly on the PR work too.