Adds embedded documentation to variables

src/variables/args.h

@@ -30,6 +30,64 @@ class Transaction;
 namespace Variables {
 
 class Args_DictElement : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ARGS
+
+    \verbatim
+    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.
+
+    Some variables are actually collections, which are expanded into more
+    variables at runtime. The following example will examine all request
+    arguments:
+
+    = SecRule ARGS dirty "id:7"
+
+    Sometimes, however, you will want to look only at parts of a collection.
+    This can be achieved with the help of the selection operator(colon). The
+    following example will only look at the arguments named p (do note that, in
+    general, requests can contain multiple arguments with the same name):
+
+    = SecRule ARGS:p dirty "id:8"
+
+    It is also possible to specify exclusions. The following will examine all
+    request arguments for the word dirty, except the ones named z (again, there
+    can be zero or more arguments named z):
+
+    = SecRule ARGS|!ARGS:z dirty "id:9"
+
+    There is a special operator that allows you to count how many variables
+    there are in a collection. The following rule will trigger if there is more
+    than zero arguments in the request (ignore the second parameter for the
+    time being):
+
+    = SecRule &ARGS !^0$ "id:10"
+
+    And sometimes you need to look at an array of parameters, each with a
+    slightly different name. In this case you can specify a regular expression
+    in the selection operator itself. The following rule will look into all
+    arguments whose names begin with id_:
+
+    = SecRule ARGS:/^id_/ dirty "id:11"
+
+    Note : Using ARGS:p will not result in any invocations against the operator
+    if argument p does not exist.
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit Args_DictElement(std::string dictElement)
         : Variable("ARGS" + std::string(":") + std::string(dictElement)),

src/variables/args_combined_size.h

@@ -30,6 +30,30 @@ class Transaction;
 namespace Variables {
 
 class ArgsCombinedSize : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ARGS_COMBINED_SIZE
+
+    \verbatim
+    Contains the combined size of all request parameters. Files are excluded
+    from the calculation. This variable can be useful, for example, to create a
+    rule to ensure that the total size of the argument data is below a certain
+    threshold. The following rule detects a request whose para- meters are more
+    than 2500 bytes long:
+
+    = SecRule ARGS_COMBINED_SIZE "@gt 2500" "id:12"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     ArgsCombinedSize()
         : Variable("ARGS_COMBINED_SIZE") { }

src/variables/args_get.h

@@ -30,6 +30,24 @@ class Transaction;
 namespace Variables {
 
 class ArgsGet_DictElement : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ARGS_GET
+
+    \verbatim
+    ARGS_GET is similar to ARGS, but contains only query string parameters.
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit ArgsGet_DictElement(std::string dictElement)
         : Variable("ARGS_GET" + std::string(":") + std::string(dictElement)),

src/variables/args_get_names.h

@@ -30,6 +30,24 @@ class Transaction;
 namespace Variables {
 
 class ArgsGetNames_DictElement : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ARGS_GET_NAMES
+
+    \verbatim
+    ARGS_GET_NAMES is similar to ARGS_NAMES, but contains only the names of query string parameters.
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit ArgsGetNames_DictElement(std::string dictElement)
         : Variable("ARGS_GET_NAMES" + std::string(":") +

src/variables/args_names.h

@@ -30,6 +30,30 @@ class Transaction;
 namespace Variables {
 
 class ArgsNames_DictElement : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ARGS_NAMES
+
+    \verbatim
+    Contains all request parameter names. You can search for specific parameter
+    names that you want to inspect. In a positive policy scenario, you can also
+    whitelist (using an inverted rule with the exclamation mark) only the
+    authorized argument names. This example rule allows only two argument names:
+    p and a:
+
+    = SecRule ARGS_NAMES "!^(p|a)$" "id:13"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit ArgsNames_DictElement(std::string dictElement)
         : Variable("ARGS_NAMES" + std::string(":") +

src/variables/args_post.h

@@ -30,6 +30,25 @@ class Transaction;
 namespace Variables {
 
 class ArgsPost_DictElement : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ARGS_POST
+
+    \verbatim
+    ARGS_POST is similar to ARGS, but only contains arguments from the POST
+    body.
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit ArgsPost_DictElement(std::string dictElement)
         : Variable("ARGS_POST" + std::string(":") + std::string(dictElement)),

src/variables/args_post_names.h

@@ -30,6 +30,25 @@ class Transaction;
 namespace Variables {
 
 class ArgsPostNames_DictElement : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ARGS_POST_NAMES
+
+    \verbatim
+    ARGS_POST_NAMES is similar to ARGS_NAMES, but contains only the names of
+    request body parameters.
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit ArgsPostNames_DictElement(std::string dictElement)
         : Variable("ARGS_POST_NAMES" + std::string(":") +

src/variables/auth_type.h

@@ -30,6 +30,29 @@ class Transaction;
 namespace Variables {
 
 class AuthType : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: AUTH_TYPE
+
+    \verbatim
+    This variable holds the authentication method used to validate a user, if
+    any of the methods built into HTTP are used. In a reverse-proxy deployment,
+    this information will not be available if the authentication is handled in
+    the backend web server.
+
+    = SecRule AUTH_TYPE "Basic" "id:14"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     AuthType()
         : Variable("AUTH_TYPE") { }

src/variables/duration.h

@@ -29,6 +29,26 @@ class Transaction;
 namespace Variables {
 
 class Duration : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: DURATION
+
+    \verbatim
+    Contains the number of milliseconds elapsed since the beginning of the
+    current transaction. Available starting with 2.6.0.
+
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit Duration(std::string _name)
         : Variable(_name),

src/variables/env.h

@@ -29,6 +29,36 @@ class Transaction;
 namespace Variables {
 
 class Env : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: ENV
+
+    \verbatim
+    Collection that provides access to environment variables set by ModSecurity
+    or other server modules. Requires a single parameter to specify the name of
+    the desired variable.
+
+    = # Set environment variable
+    = SecRule REQUEST_FILENAME "printenv" "phase:2,id:15,pass,setenv:tag=suspicious"
+    =
+    = # Inspect environment variable
+    = SecRule ENV:tag "suspicious" "id:16"
+    =
+    = # Reading an environment variable from other Apache module (mod_ssl)
+    = SecRule TX:ANOMALY_SCORE "@gt 0" "phase:5,id:16,msg:'%{env.ssl_cipher}'"
+
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit Env(std::string _name)
         : Variable(_name) { }

src/variables/files.h

@@ -30,6 +30,28 @@ class Transaction;
 namespace Variables {
 
 class Files_DictElement : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: FILES
+
+    \verbatim
+    Contains a collection of original file names (as they were called on the
+    remote user’s filesys- tem). Available only on inspected
+    multipart/form-data requests.
+
+    = SecRule FILES "@rx \.conf$" "id:17"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     explicit Files_DictElement(std::string dictElement)
         : Variable("FILES" + std::string(":") +

src/variables/files_combined_size.h

@@ -30,6 +30,27 @@ class Transaction;
 namespace Variables {
 
 class FilesCombinedSize : public Variable {
+    /** @ingroup ModSecurity_Variables ModSecurity_RefManual ModSecurity_RefManualVar */
+    /**
+
+    Description
+
+    Name: FILES_COMBINED_SIZE
+
+    \verbatim
+    Contains the total size of the files transported in request body. Available
+    only on inspected multipart/form-data requests.
+
+    = SecRule FILES_COMBINED_SIZE "@gt 100000" "id:18"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
     FilesCombinedSize()
         : Variable("FILES_COMBINED_SIZE") { }