Adds embedded documentation to operators

headers/modsecurity/modsecurity.h

@@ -73,6 +73,11 @@
  */
 
 
+/**
+ * @defgroup ModSecurity_RefManual ModSecurity Reference Manual
+ *
+ */
+
 #ifdef __cplusplus
 #include <ctime>
 #include <iostream>

src/operators/begins_with.h

@@ -27,8 +27,40 @@ namespace modsecurity {
 namespace operators {
 
 class BeginsWith : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    Returns true if the parameter string is found at the beginning of the
+    input. Macro expansion is performed on the parameter string before
+    comparison.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @beginsWith string
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect request line that does not begin with "GET"
+    = SecRule REQUEST_LINE "!@beginsWith GET" "id:149"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     explicit BeginsWith(std::unique_ptr<RunTimeString> param)
         : Operator("BeginsWith", std::move(param)) { }
 

src/operators/contains.h

@@ -30,8 +30,39 @@ namespace modsecurity {
 namespace operators {
 
 class Contains : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    Returns true if the parameter string is found anywhere in the input.
+    Macro expansion is performed on the parameter string before comparison.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @contains string
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect ".php" anywhere in the request line
+    = SecRule REQUEST_LINE "@contains .php" "id:150"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     explicit Contains(std::unique_ptr<RunTimeString> param)
         : Operator("Contains", std::move(param)) { }
     bool evaluate(Transaction *transaction, Rule *rule,

src/operators/contains_word.h

@@ -27,8 +27,43 @@ namespace modsecurity {
 namespace operators {
 
 class ContainsWord : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    Returns true if the parameter string (with word boundaries) is found
+    anywhere in the input. Macro expansion is performed on the parameter
+    string before comparison.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @containsWord string
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect "select" anywhere in ARGS
+    = SecRule ARGS "@containsWord select" "id:151"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    The example would match on: -1 union *select* BENCHMARK(2142500,MD5(CHAR(115,113,108,109,97,112))) FROM wp_users WHERE ID=1 and (ascii(substr(user_login,1,1))&0x01=0) from wp_users where ID=1--
+    But not on:
+    Your site has a wide *select*ion of computers.
+    \endverbatim
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     explicit ContainsWord(std::unique_ptr<RunTimeString> param)
         : Operator("ContainsWord", std::move(param)) { }
 

src/operators/detect_sqli.h

@@ -25,8 +25,39 @@ namespace modsecurity {
 namespace operators {
 
 class DetectSQLi : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    Returns true if SQL injection payload is found. This operator uses
+    LibInjection to detect SQLi attacks.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @detectSQLi string
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect SQL Injection inside request uri data"
+    = SecRule REQUEST_URI "@detectSQLi" "id:152"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     DetectSQLi()
         : Operator("DetectSQLi") {
             m_match_message.assign("detected SQLi using libinjection.");

src/operators/detect_xss.h

@@ -24,8 +24,39 @@ namespace modsecurity {
 namespace operators {
 
 class DetectXSS : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    Returns true if XSS injection is found. This operator uses LibInjection
+    to detect XSS attacks.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @beginsWith string
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect XSS Injection inside request body
+    = SecRule REQUEST_BODY "@detectXSS" "id:12345,log,deny"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     DetectXSS()
         : Operator("DetectXSS") {
             m_match_message.assign("detected XSS using libinjection.");

src/operators/ends_with.h

@@ -27,8 +27,39 @@ namespace modsecurity {
 namespace operators {
 
 class EndsWith : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    Returns true if the parameter string is found at the end of the input.
+    Macro expansion is performed on the parameter string before comparison.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @endsWith string
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect request line that does not end with "HTTP/1.1"
+    = SecRule REQUEST_LINE "!@endsWith HTTP/1.1" "id:152"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     explicit EndsWith(std::unique_ptr<RunTimeString> param)
         : Operator("EndsWith", std::move(param)) {
             m_couldContainsMacro = true;

src/operators/eq.h

@@ -27,8 +27,49 @@ namespace modsecurity {
 namespace operators {
 
 class Eq : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    Performs numerical comparison and returns true if the input value is
+    equal to the provided parameter. Macro expansion is performed on the
+    parameter string before comparison.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @eq string
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect exactly 15 request headers
+    = SecRule &REQUEST_HEADERS_NAMES "@eq 15" "id:153"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    \endverbatim
+
+
+    Notes
+
+    \verbatim
+    - If a value is provided that cannot be converted to an integer
+    (i.e a string) this operator will treat that value as 0.
+    \endverbatim
+
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     explicit Eq(std::unique_ptr<RunTimeString> param)
         : Operator("Eq", std::move(param)) { }
     bool evaluate(Transaction *transaction, const std::string &input) override;

src/operators/fuzzy_hash.h

@@ -36,8 +36,44 @@ struct fuzzy_hash_chunk {
 };
 
 class FuzzyHash : public Operator {
+    /** @ingroup ModSecurity_Operator ModSecurity_RefManual ModSecurity_RefManualOp */
+    /**
+
+    Description
+
+    \verbatim
+    The fuzzyHash operator uses the ssdeep, which is a program for
+    computing context triggered piecewise hashes (CTPH). Also called fuzzy
+    hashes, CTPH can match inputs that have homologies. Such inputs have
+    sequences of identical bytes in the same order, although bytes in
+    between these sequences may be different in both content and length.
+    \endverbatim
+
+
+    Syntax
+
+    \verbatim
+    @fuzzyHash /path/to/ssdeep/hashes.txt threshold
+    \endverbatim
+
+
+    Examples
+
+    \verbatim
+    Detect SQL Injection inside request uri data"
+    = SecRule REQUEST_BODY "@fuzzyHash /path/to/ssdeep/hashes.txt 6" "id:192372,log,deny"
+    \endverbatim
+
+
+    Details
+
+    \verbatim
+    For further information on ssdeep, visit its site:
+    http://ssdeep.sourceforge.net/
+    \endverbatim
+
+    */
  public:
-    /** @ingroup ModSecurity_Operator */
     explicit FuzzyHash(std::unique_ptr<RunTimeString> param)
         : Operator("FuzzyHash", std::move(param)),
         m_head(NULL),