[airween]

Proposed changes

Document that the RULE collection can't be read from Lua in libModSecurity v3, and how to pass a rule field to a script instead, as agreed in owasp-modsecurity/ModSecurity#2527.

• Configuration directives, SecRuleScript: a new note in the Lua section:
  • m.getvar() and m.getvars() can't read RULE, because the Lua API has no access to the rule that runs the script;
  • up to 3.0.17, such a call, or one with any other unknown variable name, aborts the process (Lua m.getvar()/m.getvars() with an unknown variable name aborts the process ModSecurity#3728); later versions return nil or an empty table and write a debug log message;
  • the workaround: setvar:tx.rule_id=%{RULE.id} in the rule that runs the script with exec, and m.getvar("TX.rule_id") in the script, with an example of both.
• Variables, RULE: one sentence in the v3 paragraph, with a link to the note.

Closes owasp-modsecurity/ModSecurity#2527

Further comments

• m.getvar() and m.getvars() resolve the name with Variable::stringMatchResolve() and stringMatchResolveMulti() (src/variables/variable.h), whose lists have no RULE.
• The workaround depends on the action order: libModSecurity v3 runs setvar in executeActionsIndependentOfChainedRuleResult(), before exec runs in executeActionsAfterFullMatch() (src/rule_with_operator.cc). The regression test added in the fix for #3728 checks this (misc-lua-getvar-unknown-variable.json, case 6).
• The "later versions" sentence assumes that the fix for #3728 ships in the release after 3.0.17. If it ships later, the version needs to be updated before this is merged.

AI disclosure

Made with help of Claude Code, Opus 5.5

[fzipi]

I checked the note against the v3 code and #3730, and it's accurate: m.getvar()/m.getvars() resolve names through stringMatchResolve()/stringMatchResolveMulti(), which have no RULE; #3730 returns nil or an empty table and logs at level 2; and setvar runs in executeActionsIndependentOfChainedRuleResult() before exec runs in executeActionsAfterFullMatch(). Case 6 of the new regression test covers the workaround.

Approving on one condition: please merge this only after #3730 is merged, and check that the "later versions" wording matches the release #3730 lands in. Two small nits are inline.

The failing syntax-check job is lychee reporting a 404 on an existing web.archive.org link in this file, which this PR doesn't touch.

[fzipi]

Nit: since this note sits in the SecRuleScript section, readers may try the workaround there. In a SecRuleScript rule, the script is the operator, so that rule's own setvar runs after the script. Maybe add one sentence: for SecRuleScript, set the TX variable in an earlier rule.

[airween]

Thanks @fzipi! I've applied the tostring() suggestion.

About SecRuleScript, I checked it with a regression test, and it turned out differently from both of our guesses:

• The order isn't the problem. RuleScript::evaluate() (src/rule_script.cc) runs the setvar actions before m_lua.run(), and the debug log shows the same.
• But %{RULE.id} expands to an empty string there, so the script gets nil. The same happens in a SecAction. Only a SecRule works.

The cause is in RunTimeString::evaluate() (src/run_time_string.cc:62): it casts the rule to RuleWithOperator, and RuleScript and RuleUnconditional aren't one, so the RULE variable gets NULL. An earlier rule wouldn't help either, because %{RULE.id} there is the earlier rule's id. I've opened owasp-modsecurity/ModSecurity#3733 for it.

So I've added this to the note: the workaround works in a SecRule; in a SecAction or a SecRuleScript rule, set the value as a constant until #3733 is fixed, and in a SecRuleScript rule the constant can go in the rule itself, because its setvar runs before the script.