Skip to content

docs: document that SESSION requires setsid #5

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

Open
airween wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: document that SESSION requires setsid #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f9d2fa1
Document that SESSION requires setsid
airween Nov 1, 2026
0ceb34f
Skip the SESSION rules in the example if setsid didn't run
airween Nov 3, 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
24 changes: 19 additions & 5 deletions 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 @@ -1196,9 +1196,13 @@ This variable contains the local port that the web server (or reverse proxy) is

{{< secmeta v2="yes" v3="yes" >}}

This variable is a collection that contains session information. It becomes available only after setsid is executed. In ModSecurity v2 a selector is mandatory (SESSION:name or SESSION:/regex/). For where libModSecurity v3 stores the data, see GLOBAL.
This variable is a collection that contains session information. It must be initialized with the [setsid]({{% relref "3-reference-manual/3-5-actions#setsid" %}}) action before it is read or written. In ModSecurity v2 a selector is mandatory (SESSION:name or SESSION:/regex/). For where libModSecurity v3 stores the data, see GLOBAL.

The following example shows how to initialize SESSION using setsid, how to use setvar to increase the SESSION.score values, how to set the SESSION.blocked variable, and finally, how to deny the connection based on the <SESSION:blocked> value:
{{% notice warning %}}
Use SESSION only after setsid has run with a non-empty session token, for example by skipping the rules that use SESSION when SESSIONID is empty, as in the example below. libModSecurity v3 does not reject SESSION without setsid: the data is then stored without a session key, so it is shared by every transaction that does the same, whatever session it belongs to. In a build that uses LMDB, it can also overwrite, and be overwritten by, a variable with the same name in another collection that has no key either, for example GLOBAL used without initcol.
{{% /notice %}}

The following example shows how to initialize SESSION using setsid, how to skip the SESSION rules if there is no session, how to use setvar to increase the SESSION.score values, how to set the SESSION.blocked variable, and finally, how to deny the connection based on the <SESSION:blocked> value:

``` seclang
# Initialize session storage
Expand All @@ -1209,9 +1213,17 @@ SecRule REQUEST_COOKIES:PHPSESSID "!@rx ^$" \
nolog,\
setsid:%{REQUEST_COOKIES.PHPSESSID}"

# Skip the SESSION rules if setsid didn't run
SecRule SESSIONID "@rx ^$" \
"id:71,\
phase:2,\
pass,\
nolog,\
skipAfter:END_SESSION_RULES"

# Increment session score on attack
SecRule REQUEST_URI "@rx ^/cgi-bin/finger$" \
"id:71,\
"id:72,\
phase:2,\
pass,\
t:none,\
Expand All @@ -1220,10 +1232,12 @@ SecRule REQUEST_URI "@rx ^/cgi-bin/finger$" \
setvar:SESSION.score=+10"

# Detect too many attacks in a session
SecRule SESSION:score "@gt 50" "id:72,phase:2,pass,setvar:SESSION.blocked=1"
SecRule SESSION:score "@gt 50" "id:73,phase:2,pass,setvar:SESSION.blocked=1"

# Enforce session block
SecRule SESSION:blocked "@eq 1" "id:73,phase:2,deny,status:403"
SecRule SESSION:blocked "@eq 1" "id:74,phase:2,deny,status:403"

SecMarker END_SESSION_RULES
```

## SESSIONID
Expand Down
2 changes: 1 addition & 1 deletion content/3-reference-manual/3-5-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1033,7 +1033,7 @@ SecRule REQUEST_COOKIES:PHPSESSID "!@rx ^$" \

Note

After the initialization takes place, the variable SESSION will be available for use in the subsequent rules. This action understands application namespaces (configured using SecWebAppId), and will use one if it is configured.
After the initialization takes place, the variable SESSION will be available for use in the subsequent rules. Don't use SESSION before setsid has run; see [SESSION]({{% relref "3-reference-manual/3-3-variables#session" %}}) for what happens in libModSecurity v3 if you do. This action understands application namespaces (configured using SecWebAppId), and will use one if it is configured.

Setsid takes an individual variable, not a collection. Variables within an action, such as setsid, use the format [collection].[variable] .

Expand Down
Loading