From 304af409f11061637c1a56a481c206f313237929 Mon Sep 17 00:00:00 2001 From: "Scott R. Shinn" Date: Tue, 4 Aug 2026 18:32:22 -0400 Subject: [PATCH 1/3] Clarify active-response expect fields and fixed script argv. Document that expect selects srcip/user/username/filename without reordering arguments, and add an FAQ for the common add/- confusion. --- docs/faq/active-response.rst | 24 +++++++++++++++++++ docs/manual/ar/ar-custom.rst | 6 ++++- docs/manual/ar/ar-unix.rst | 6 +++-- docs/syntax/ossec_config.active-response.trst | 23 +++++++++++++++++- 4 files changed, 55 insertions(+), 4 deletions(-) diff --git a/docs/faq/active-response.rst b/docs/faq/active-response.rst index cfb55e69..f27ec348 100644 --- a/docs/faq/active-response.rst +++ b/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. ```` +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 ```` so those fields are populated from the decoder. Username is +taken from ``dstuser``, or ``srcuser`` if ``dstuser`` is absent. diff --git a/docs/manual/ar/ar-custom.rst b/docs/manual/ar/ar-custom.rst index 70a49b77..fa557fd1 100644 --- a/docs/manual/ar/ar-custom.rst +++ b/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: srcip + If you do need a srcip or username, list them in expect, e.g. + ``srcip`` or ``srcip, username``. + ``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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/manual/ar/ar-unix.rst b/docs/manual/ar/ar-unix.rst index 723d732a..88668e0d 100644 --- a/docs/manual/ar/ar-unix.rst +++ b/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-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. diff --git a/docs/syntax/ossec_config.active-response.trst b/docs/syntax/ossec_config.active-response.trst index daabdf8f..35b203de 100644 --- a/docs/syntax/ossec_config.active-response.trst +++ b/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-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. ```` 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``. From 8f55375119b8093bbf7e77e5b9f37a762e74bd42 Mon Sep 17 00:00:00 2001 From: "Scott R. Shinn" Date: Tue, 4 Aug 2026 18:35:05 -0400 Subject: [PATCH 2/3] Note that AR expect tokens may be whitespace-separated. --- docs/manual/ar/ar-unix.rst | 2 +- docs/syntax/ossec_config.active-response.trst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manual/ar/ar-unix.rst b/docs/manual/ar/ar-unix.rst index 88668e0d..75cfb901 100644 --- a/docs/manual/ar/ar-unix.rst +++ b/docs/manual/ar/ar-unix.rst @@ -28,7 +28,7 @@ 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**: Comma-separated fields required from the alert +- **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`). diff --git a/docs/syntax/ossec_config.active-response.trst b/docs/syntax/ossec_config.active-response.trst index 35b203de..e0412d7e 100644 --- a/docs/syntax/ossec_config.active-response.trst +++ b/docs/syntax/ossec_config.active-response.trst @@ -18,7 +18,7 @@ Command Options - expect - Comma-separated fields this command needs from the alert. Valid values are + 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 From f190b863f1940033b63adff177c4fd7601602236 Mon Sep 17 00:00:00 2001 From: "Scott R. Shinn" Date: Tue, 4 Aug 2026 18:40:53 -0400 Subject: [PATCH 3/3] Convert urlscan.rst log sample to UTF-8 for Sphinx CI. The file was ISO-8859-1; Python 3.12 Sphinx failed with UnicodeDecodeError on byte 0xa4 while building HTML. --- docs/log_samples/web/urlscan.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/log_samples/web/urlscan.rst b/docs/log_samples/web/urlscan.rst index 2bdf03a8..2410214a 100644 --- a/docs/log_samples/web/urlscan.rst +++ b/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'