Document ossec-regex -p for PCRE2 patterns

docs/programs/ossec-regex.rst

@@ -4,26 +4,80 @@
 ossec-regex
 ===========
 
-``ossec-regex`` is a simple program that will validate a regex expression.a
-The pattern should be enclosed in single quotes to help prevent any strange interactions with the shell.
+``ossec-regex`` reads lines from stdin and prints the ones that match a pattern.
+Put the pattern in single quotes so the shell does not change it.
+Lines shorter than two characters are ignored. A line that does not match prints nothing.
 
-The syntax for ``ossec-regex`` is simple: ``/var/ossec/bin/ossec-regex '<pattern>'``
-It then reads strings from stdin and outputs matches to stdout.
-``+OSRegex_Execute`` and ``+OS_Regex`` are printed if a match is successful.
+By default the pattern is :ref:`OSSEC regex and match <regex>` syntax.
+``-p`` tests the pattern as PCRE2, with the same flags as a ``<pcre2>`` rule
+(caseless, and no OSSEC syntax translation). Use ``-p`` for ``<pcre2>`` and
+``<match_pcre2>``. Without it, characters such as ``.``, ``*``, and ``{`` are
+rewritten before matching.
 
+Synopsis
+~~~~~~~~
 
-Example 1: A simple digit match:
-^^^^^^^^^^^^^~^^^^^^^^^^^^^^^^^^
+.. code-block:: console
+
+   ossec-regex [-hp] [--] <pattern>
+
+Options
+~~~~~~~
+
+.. program:: ossec-regex
+
+.. option:: -h, --help
+
+   Show help and exit.
+
+.. option:: -p, --pcre2
+
+   Match ``<pattern>`` as PCRE2. Compilation uses ``PCRE2_CASELESS``, the same
+   flag analysisd uses for ``<pcre2>`` and ``<match_pcre2>``.
+
+Output
+~~~~~~
+
+Without ``-p``, a match can print any of these lines:
+
+* ``+OSRegex_Execute``
+* ``+OS_Regex``
+* ``+OSMatch_Compile``
+* ``+OS_Match2``
+
+With ``-p``, a match prints ``+OSPcre2_Execute`` (the rule path) and
+``+OS_Pcre2`` (the one-shot helper, which also enables UTF matching).
+Capture groups from ``+OSPcre2_Execute`` are printed as ``-Substring``.
+A quantified group keeps its last capture.
+
+Examples
+~~~~~~~~
+
+Legacy OSSEC regex:
+
+.. code-block:: console
+
+   # /var/ossec/bin/ossec-regex '^\d\d\d'
+   333
+   +OSRegex_Execute: 333
+   +OS_Regex       : 333
+   f44
+   222
+   +OSRegex_Execute: 222
+   +OS_Regex       : 222
+
+PCRE2, as used by a ``<pcre2>`` rule:
 
 .. code-block:: console
 
-    # /var/ossec/bin/ossec-regex '^\d\d\d'
-    333
-    +OSRegex_Execute: 333
-    +OS_Regex       : 333
-    f44
-    222
-    +OSRegex_Execute: 222
-    +OS_Regex       : 222
+   # /var/ossec/bin/ossec-regex -p 'user=(\w+)'
+   login user=alice from 10.0.0.1
+   +OSPcre2_Execute: login user=alice from 10.0.0.1
+    -Substring: alice
+   +OS_Pcre2       : login user=alice from 10.0.0.1
 
+See also
+~~~~~~~~
 
+* :ref:`regex`
+* :ref:`ossec-regex-convert`

docs/syntax/regex.rst

@@ -14,8 +14,10 @@ Currently OSSEC supports three regex syntaxes:
 pcre2
 -----
 
-Information onthe syntax for pcre2 can be found in the `pcre <http://www.pcre.org/current/doc/html/>`_
+Information on the syntax for pcre2 can be found in the `pcre <http://www.pcre.org/current/doc/html/>`_
 documentation.
+Test a ``<pcre2>`` pattern with :ref:`ossec-regex` and the ``-p`` option.
+Without ``-p``, that program uses the legacy OSSEC regex syntax below.
 
 .. _os_regex: