Skip to content

docs: RULE can't be read from Lua in libModSecurity v3 #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fzipi merged 4 commits into from
Nov 2, 2026
Merged

docs: RULE can't be read from Lua in libModSecurity v3 #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
be7cb03
Document that RULE can't be read from Lua in libModSecurity v3
airween Nov 1, 2026
59e887b
Update content/3-reference-manual/3-2-configuration-directives.md
airween Nov 1, 2026
ddd7cab
Describe the RULE workaround in SecAction and SecRuleScript rules
airween Nov 1, 2026
2511690
Fix created issue link.
airween Nov 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions content/3-reference-manual/3-2-configuration-directives.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1172,6 +1172,31 @@ end

{{% notice note %}}

In libModSecurity v3, m.getvar() and m.getvars() can't read the [RULE]({{% relref "3-reference-manual/3-3-variables#rule" %}}) collection, because the Lua API has no access to the rule that runs the script. In libModSecurity 3.0.17 and earlier, calling them with RULE, or with any other variable name the Lua API doesn't know, aborts the process ([#3728](https://github.com/owasp-modsecurity/ModSecurity/issues/3728)); later versions return nil from m.getvar() and an empty table from m.getvars(), and write a debug log message. If a script started with the exec action needs a field of its rule, copy it into a transaction variable with setvar in the same rule (libModSecurity v3 runs setvar before exec), and read that variable from the script:

@fzipi fzipi Nov 1, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 airween Nov 1, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


``` seclang
SecRule ARGS "@rx attack" \
"id:100,\
phase:2,\
pass,\
setvar:tx.rule_id=%{RULE.id},\
exec:/path/to/script.lua"
```

``` lua
function main()
local rule_id = m.getvar("TX.rule_id");
m.log(4, "Called from rule " .. tostring(rule_id));
return nil;
end
```

This works in a SecRule. In a SecAction or a SecRuleScript rule, libModSecurity v3 currently expands %{RULE.id} to an empty string ([#3733](https://github.com/owasp-modsecurity/ModSecurity/issues/3733)), so set the value as a constant there, for example setvar:tx.rule_id=100. libModSecurity v3 runs the setvar actions of a SecRuleScript rule before the script, so the constant can be set in the SecRuleScript rule itself.

{{% /notice %}}

{{% notice note %}}

Go to <http://www.lua.org/> to find more about the Lua programming language. The reference manual too is available online, at <http://www.lua.org/manual/5.1/> (ModSecurity v2) and <http://www.lua.org/manual/5.2/> (libModSecurity v3).

{{% /notice %}}
Expand Down
2 changes: 1 addition & 1 deletion content/3-reference-manual/3-3-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1050,7 +1050,7 @@ This variable may not work as expected in embedded mode, as Apache sometimes han

This is a special collection that provides access to the id, rev, severity, msg, logdata, ver, maturity, and accuracy fields of the rule that triggered the action. It can be used to refer to only the same rule in which it resides; a field name is mandatory (RULE:id, or %{RULE.id} in macros), and inside a chain the fields are those of the chain starter.

libModSecurity v3 exposes only id, rev, severity, msg and logdata (ver, maturity and accuracy are not available); it also accepts a bare RULE, which returns all five, and a regular-expression selector.
libModSecurity v3 exposes only id, rev, severity, msg and logdata (ver, maturity and accuracy are not available); it also accepts a bare RULE, which returns all five, and a regular-expression selector. In libModSecurity v3, RULE can't be read from Lua; see [SecRuleScript]({{% relref "3-reference-manual/3-2-configuration-directives#secrulescript" %}}) for a workaround.

`SecRule &REQUEST_HEADERS:Host "@eq 0" "log,deny,id:59,setvar:tx.varname=%{RULE.id}"`

Expand Down
Loading