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/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' 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..75cfb901 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 dont 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. diff --git a/docs/syntax/ossec_config.active-response.trst b/docs/syntax/ossec_config.active-response.trst index daabdf8f..e0412d7e 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- 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. ```` 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``.