Clarify active-response expect fields and fixed script argv.

docs/faq/active-response.rst

@@ -54,3 +54,27 @@ Where are example active-response configurations?
 
 See :ref:`manual-ar-unix`, :ref:`ossec_config.active-response`, and the bundled
 scripts reference at :ref:`manual-ar-scripts`.
+
+Why does my script see ``add`` and ``-`` instead of srcip/username?
+-------------------------------------------------------------------
+
+Active-response scripts always receive a fixed argument list. ``<expect>``
+only chooses which decoded fields are filled (vs ``-``); it does **not** put
+``srcip`` in ``$1``.
+
+======= ==========================================================
+Arg     Value
+======= ==========================================================
+``$1``  action (``add`` or ``delete``)
+``$2``  username from the alert, or ``-``
+``$3``  srcip from the alert, or ``-``
+``$4``  alert id
+``$5``  rule id
+``$6``  agent / location
+``$7``  filename, or ``-``
+======= ==========================================================
+
+So ``$1`` will be ``add`` even when expect is ``srcip, username``. Use ``$3``
+for the IP and ``$2`` for the user. List ``srcip`` / ``user`` (or ``username``)
+in ``<expect>`` so those fields are populated from the decoder. Username is
+taken from ``dstuser``, or ``srcuser`` if ``dstuser`` is absent.

docs/log_samples/web/urlscan.rst

@@ -35,8 +35,8 @@ Urlscan Log samples
   [11-28-2002 - 08:31:41] Requests containing the following character sequences will be rejected:
   [11-28-2002 - 08:31:41] '..'
   [11-28-2002 - 08:31:41] './'
-  [11-29-2002 - 15:22:37] Client at 24.69.73.3: URL contains high bit character. Request will be rejected. Site Instance='1', Raw URL='/scripts/mail.exe/2001¤ë¾ä.jpg'
-  [11-29-2002 - 15:22:47] Client at 24.69.73.3: URL contains high bit character. Request will be rejected. Site Instance='1', Raw URL='/scripts/mail.exe/2001¤ë¾ä.jpg'
+  [11-29-2002 - 15:22:37] Client at 24.69.73.3: URL contains high bit character. Request will be rejected. Site Instance='1', Raw URL='/scripts/mail.exe/2001¤ë¾ä.jpg'
+  [11-29-2002 - 15:22:47] Client at 24.69.73.3: URL contains high bit character. Request will be rejected. Site Instance='1', Raw URL='/scripts/mail.exe/2001¤ë¾ä.jpg'
   [11-29-2002 - 21:15:17] Client at 24.67.253.204: URL contains extension '.com', which is disallowed. Request will be rejected. Site Instance='1', Raw URL='/scripts/www.the5yearjournal.com'
   [12-02-2002 - 09:52:33] Client at 142.27.68.15: URL contains high bit character. Request will be rejected. Site Instance='1', Raw URL='/scripts/mail.exe/2001%C2%A4%C3%AB%C2%BE%C3%A4.jpg'
   [12-02-2002 - 09:52:43] Client at 142.27.68.15: URL contains high bit character. Request will be rejected. Site Instance='1', Raw URL='/scripts/mail.exe/2001%C2%A4%C3%AB%C2%BE%C3%A4.jpg'

docs/manual/ar/ar-custom.rst

@@ -32,7 +32,11 @@ inside /var/ossec/active-response/bin/ ).
 
 .. note::
 
-    If you do need a srcip or username, just add it, eg: <expect>srcip</expect>
+    If you do need a srcip or username, list them in expect, e.g.
+    ``<expect>srcip</expect>`` or ``<expect>srcip, username</expect>``.
+    ``user`` and ``username`` are equivalent. Expect does not change argv
+    order: ``$1`` is always the action (``add``/``delete``), ``$2`` the
+    username, and ``$3`` the srcip.
 
 Configure the Active response 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/manual/ar/ar-unix.rst

@@ -28,8 +28,10 @@ You can have as many commands as you want. Each one should be inside their own
   “/var/ossec/active-response/bin”.
 
   You don’t need to provide the whole path.
-- **expect**: The arguments this command is expecting (options are srcip and
-  username).
+- **expect**: Comma- or whitespace-separated fields required from the alert
+  (``srcip``, ``user`` / ``username``, ``filename``). This selects which
+  fields are filled; it does **not** reorder script arguments. Scripts always
+  receive ``action``, ``username``, ``srcip``, … (see :ref:`manual-ar-custom`).
 - **timeout_allowed**: Specifies if this command supports timeout.
 
 

docs/syntax/ossec_config.active-response.trst

@@ -18,12 +18,33 @@ Command Options
 
 - expect
 
-    The arguments this command is expecting (options are srcip and username). If a field is not within the ``expect`` option it will be passed as a dash (``-``) instead of the actual value. For instance, if ``srcip`` is required for an active-response script to work it **must** be inside of an ``expect`` option. ``expect`` is required.
+    Comma- or whitespace-separated fields this command needs from the alert. Valid values are
+    ``srcip``, ``user`` (alias ``username``), and ``filename``.
+
+    ``expect`` does **not** change script argument order. Active-response scripts
+    always receive:
+
+    1. action (``add`` / ``delete``)
+    2. username (or ``-``)
+    3. srcip (or ``-``)
+    4. alert id
+    5. rule id
+    6. agent / location
+    7. filename (or ``-``)
+
+    Fields listed in ``expect`` are filled from the decoded alert; fields omitted
+    from ``expect`` are passed as ``-``. If a listed field is missing from the
+    event, the active response is skipped. ``expect`` is required.
 
     .. note::
 
        ``expect`` is required, but it is not required to populate it. ``<expect></expect>`` is valid if no options need to be passed to the active-response script.
 
+    .. note::
+
+       ``username`` is accepted as an alias for ``user``. The username argument is
+       taken from the decoded ``dstuser`` field when present, otherwise ``srcuser``.
+
 - timeout_allowed
 
     Specifies if this command supports a timeout. This is optional, and defaults to ``yes``.