https://modsecurity.org/docs/3-reference-manual/index.htmlThe rule language and configuration reference for ModSecurity v2 and libModSecurity v3. Each directive, variable, transformation, action and operator is documented once. The metadata table under each entry shows the ModSecurity v2 version it first appeared in, and whether libModSecurity v3 supports it. Badge legend: Badge Meaning since 2.7.0 available from that release on supported available, first release not recorded not implemented yet accepted by the parser or planned, but not functional in libModSecurity v3 not supported not available in that engine unknown not verified yetHugoen-UShttps://modsecurity.org/docs/3-reference-manual/3-1-processing-phases/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-1-processing-phases/index.htmlModSecurity, in both v2 and v3, allows rules to be placed in one of the following five phases of an HTTP transaction: Phase Name Runs after Data available 1 Request headers (REQUEST_HEADERS) the request line and headers have been read REQUEST_*, ARGS_GET, REQUEST_HEADERS, REQUEST_COOKIES 2 Request body (REQUEST_BODY) the request body has been read, if SecRequestBodyAccess is On everything in phase 1 plus ARGS_POST, ARGS, REQUEST_BODY, FILES*, XML, JSON 3 Response headers (RESPONSE_HEADERS) the response status and headers are known plus RESPONSE_STATUS, RESPONSE_HEADERS 4 Response body (RESPONSE_BODY) the response body has been read, if SecResponseBodyAccess is On and the MIME type is inspected plus RESPONSE_BODY 5 Logging (LOGGING) the response has been sent everything; disruptive actions have no effect In ModSecurity v2 the phases are hooks in the Apache request cycle. In libModSecurity v3 the phases are the process*() calls the connector (for example ModSecurity-nginx) makes on a transaction: processConnection, processURI, processRequestHeaders, processRequestBody, processResponseHeaders, processResponseBody and processLogging. The rule semantics are the same; the differences are listed at the end of this page.https://modsecurity.org/docs/3-reference-manual/3-2-configuration-directives/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-2-configuration-directives/index.htmlThe following section outlines all of the ModSecurity directives. Most of the ModSecurity directives can be used inside the various Apache Scope Directives such as VirtualHost, Location, LocationMatch, Directory, etc… There are others, however, that can only be used once in the main configuration file. This information is specified in the Scope sections below. The first version to use a given directive is given in the Version sections below. These rules, along with the Core rules files, should be contained in files outside of the httpd.conf file and called up with Apache “Include” directives. This allows for easier updating/migration of the rules. If you create your own custom rules that you would like to use with the Core rules, you should create a file called - modsecurity_crs_15_customrules.conf and place it in the same directory as the Core rules files. By using this file name, your custom rules will be called up after the standard ModSecurity Core rules configuration file but before the other Core rules. This allows your rules to be evaluated first which can be useful if you need to implement specific “allow” rules or to correct any false positives in the Core rules as they are applied to your site.https://modsecurity.org/docs/3-reference-manual/3-3-variables/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-3-variables/index.htmlThe following variables are supported in ModSecurity v2 and libModSecurity v3. Each entry states which engine supports it; where the two engines behave differently, the difference is described in the entry. ARGS ModSecurity v2supported libModSecurity v3supported ARGS is a collection and can be used on its own (means all arguments including the POST Payload), with a static parameter (matches arguments with that name), or with a regular expression (matches all arguments with name that matches the regular expression). To look at only the query string or body arguments, see the ARGS_GET and ARGS_POST collections.https://modsecurity.org/docs/3-reference-manual/3-4-transformation-functions/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-4-transformation-functions/index.htmlTransformation functions are used to alter input data before it is used in matching (i.e., operator execution). The input data is never modified, actually—whenever you request a transformation function to be used, ModSecurity will create a copy of the data, transform it, and then run the operator against the result. Note There are no default transformation functions, as there were in the first generation of ModSecurity (1.x).https://modsecurity.org/docs/3-reference-manual/3-5-actions/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-5-actions/index.htmlEach action belongs to one of five groups: Disruptive actions - Cause ModSecurity to do something. In many cases something means block transaction, but not in all. For example, the allow action is classified as a disruptive action, but it does the opposite of blocking. There can only be one disruptive action per rule (if there are multiple disruptive actions present, or inherited, only the last one will take effect), or rule chain (in a chain, a disruptive action can only appear in the first rule). Note Disruptive actions will NOT be executed if the SecRuleEngine is set to DetectionOnly. If you are creating exception/whitelisting rules that use the allow action, you should also add the ctl:ruleEngine=On action to execute the action.https://modsecurity.org/docs/3-reference-manual/3-6-operators/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-6-operators/index.htmlThis section documents the operators currently available in ModSecurity. ModSecurity v2 and libModSecurity v3 both look operator names up case-insensitively (@ipmatch, @ipMatch and @IPMATCH all resolve to the same operator); the spellings below are the documented ones. beginsWith Returns true if the parameter string is found at the beginning of the input. Macro expansion is performed on the parameter string before comparison.https://modsecurity.org/docs/3-reference-manual/3-7-macro-expansion/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-7-macro-expansion/index.htmlMacros allow for using placeholders in rules that will be expanded out to their values at runtime. Only variable expansion is supported; the syntax is the same in ModSecurity v2 and libModSecurity v3. Format: %{VARIABLE} %{COLLECTION.VARIABLE} Macro expansion can be used in actions such as initcol, setsid, setuid, setvar, setenv, logdata and msg. Operators that are evaluated at runtime support expansion in their parameter; the entries in Operators note where this applies. Such operators include @beginsWith, @endsWith, @contains, @within, @streq, @eq, @ge, @gt, @le and @lt. You can use macro expansion in operators that are “compiled” at load time, such as @rx, but the pattern is then recompiled on every evaluation, which has an impact on efficiency.https://modsecurity.org/docs/3-reference-manual/3-8-persistent-storage/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-8-persistent-storage/index.htmlFive collections can hold data persistently, that is, data available to multiple requests: GLOBAL, RESOURCE, IP, SESSION and USER. They are available in both ModSecurity v2 and libModSecurity v3, but the storage behind them differs (see below). Every collection contains several built-in variables that are available and are read-only unless otherwise specified: CREATE_TIME - date/time of the creation of the collection. IS_NEW - set to 1 if the collection is new (not yet persisted) otherwise set to 0. KEY - the value of the initcol variable (the client’s IP address in the example). LAST_UPDATE_TIME - date/time of the last update to the collection. TIMEOUT - date/time in seconds when the collection will be updated on disk from memory (if no other updates occur). This variable may be set if you wish to specify an explicit expiration time (default is 3600 seconds, configurable with SecCollectionTimeout). The TIMEOUT is updated every time that the values of an entry is changed. UPDATE_COUNTER - how many times the collection has been updated since creation. UPDATE_RATE - is the average rate updates per minute since creation. To create a collection to hold session variables (SESSION) use action setsid. To create a collection to hold user variables (USER) use action setuid. To create a collection to hold client address variables (IP), global data or resource-specific data, use action initcol.https://modsecurity.org/docs/3-reference-manual/3-9-miscellaneous-topics/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-9-miscellaneous-topics/index.htmlThe topics on this page apply to ModSecurity v2 running as an Apache module. libModSecurity v3 has no Apache dependency; the equivalent integration points belong to the connector (for example the modsecurity_transaction_id directive of ModSecurity-nginx, which ties the audit log entry to the NGINX access log). Logging in Apache via mod_log_config ModSecurity v2 registers the M log handler with mod_log_config, so any ModSecurity variable can be written to the Apache access log as %{VARIABLE}M. A collection member is addressed with a dot, as in %{TX.ANOMALY_SCORE}M; the colon form used in rules is not accepted there. ModSecurity asks Apache to run its logging hook before mod_log_config, so the access log entry is written after phase 5 has run and the audit log record has been written, and every variable set during the transaction is available to it.https://modsecurity.org/docs/3-reference-manual/3-10-recommended-base-configuration/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://modsecurity.org/docs/3-reference-manual/3-10-recommended-base-configuration/index.htmlEach release ships a modsecurity.conf-recommended file with the engine settings an administrator is expected to own: engine mode, body handling, limits, logging and file locations. Rule sets such as the OWASP CRS build on top of it and must not repeat these settings. Both code lines carry their own copy: ModSecurity v2: modsecurity.conf-recommended (v2.9.15) libModSecurity v3: modsecurity.conf-recommended (v3.0.17) Copy the file to your configuration directory as modsecurity.conf, together with unicode.mapping from the same tree, and include it before any rule set. Distribution packages install both files for you (see the installation chapter). The sections below walk through the file as shipped in v2.9.15; the examples are reformatted per the site’s conventions and the v3 differences are called out where they occur.