.. _command-events-search:

search
======

The ``events search`` command is used to search for aggregated events.

Usage
-----

.. program:: argus-cli events search

parameters
^^^^^^^^^^

.. code-block:: bash

    argus-cli events search START END TEMPLATE_FOLDER

.. option:: START

   Start date/time of the search window

   Uses the :ref:`flexible date format <concepts-date-formats>`

.. option:: END

   End date/time of the search window

   Uses the :ref:`flexible date format <concepts-date-formats>`

options
^^^^^^^

general options
"""""""""""""""

.. option:: --no-exact-match-property

   flag. Turns of exact matching of properties, which is on by default.

.. option:: --min-severity <severity>

   Minimum severity of events.

   valid values are defined in :data:`~argus_plugins.events.utils.SEVERITIES`

.. option:: --min-count <count>

   Minimum aggregated count of events.

.. option:: --enrich <enrichment1> [<enrichment2>, <...>]

   One or more enrichment(s) to perform on the event data.

   see :ref:`events-search-using-enrichments` for more details.

.. option:: --limit <limit>

   Amount of items to fetch per request ("page size").

   Defaults to ``500``.

   .. note:: a high value can negatively impact the service and cause timeouts.

   .. note:: to stop after fetching the number of items specified, use the
        :option:`--no-paginate` option.

.. option:: --no-paginate

   flag. If set, pagination will be disabled and only the amount of results specified
   by :option:`--limit` will be fetched.

.. option:: --progress

   flag. If set, a progress bar will be displayed while fetching events.


filtering options
"""""""""""""""""

These options allow filtering the search results by including or excluding certain field
values.

.. caution::

   these are all multiple-value options, see : :ref:`multiple-value option caveats <caveat-multiple-value-options>`

.. option:: --[include|exclude]-customer <customer1> [<customer2>, ...]

   Customer(s) to include/exclude.

.. option:: --[include|exclude]-flag <flag1> [<flag2>, ...]

   Flag(s) to include/exclude.

   valid values are defined in :data:`~argus_plugins.events.utils.FLAGS`

.. option:: --[include|exclude]-alarm <alarm_id1> [<alarm_id2>, ...]

   Alarm ID(s) to include/exclude.

.. option:: --[include|exclude]-ip <ip1> [<ip2>, <...>]

   IP Address(es) to include/exclude.

.. option:: --[include|exclude]-[source|destination]-ip <ip1> [<ip2>, ...]

   Source/Destination IP Address(es) to include/exclude.

.. option:: --[source|destination]-ip-min-bits <mask>

   Subnet mask to filter source/destination IP addresses on.

.. option:: --[include|exclude]-signature <signature1> [<signature2>, ...]

   Signature(s) to include/exclude.

.. option:: --[include|exclude]-properties <property1> [<property2>, ...]

   Propertie(s) to include/exclude.

.. option:: --[include|exclude]-attack-category-id <attack_category_id1> [<attack_category_id2>, ...]

   Attack category ID(s) to include/exclude.

.. _events-search-using-enrichments:


Using enrichments
-----------------

The search command supports enriching event data from sources other than the
events API through enrichments. Those enrichments are controlled by the :option:`argus-cli events search --enrich` option.

Multiple enrichments can be specified :

.. code-block:: bash

    argus-cli events search --enrich ENRICHMENT1 ENRICHMENT2 [...]

.. caution:: ``--enrich`` is a multiple-value option, make sure you understand the :ref:`Multiple-Value options Caveats<caveat-multiple-value-options>`

.. note::

   the :ref:`command-cases-autocreate` command also provides the ``--enrich`` option.
   When running an autocreate script, enrichments need only be used once (either in the ``events search`` providing the events or ``cases autocreate``),
   there is **no need** to use the option in both commands.

All enrichments add data to the selected events under the ``"_enrichments_"``
key. To know precisely where each enrichment add data, refer to the table below.

Available enrichments
^^^^^^^^^^^^^^^^^^^^^

Currently, these enrichments can be used with the autocreate script:

.. csv-table::
   :header: "name", "key", "description"

   ``customer-networks-source``, ``event["_enrichments_"][""customer-networks"]["source"]``, "Adds the results of a search of the customer networks API for the source address of the event.

   The results are a list of dictionaries, as returned by the customer networks API and defined in `API documentation : customer networks service <https://portal.mnemonic.no/spa/swagger?module=customernetworks>`_ (see models → CustomerNetwork).

   Results are sorted by netmask descending, so that the first result will be the most specific and the last one will be the least specific (for example, a /24 network will be listed before a /8 network)"
   ``customer-networks-destination``, ``event["_enrichments_"][""customer-networks"]["destination"]``, "Adds the results of a search of the customer networks API for the destination address of the event.

   The results are a list of dictionaries, as returned by the customer networks API and defined in `API documentation : customer networks service <https://portal.mnemonic.no/spa/swagger?module=customernetworks>`_ (see models → CustomerNetwork).

   Results are sorted by netmask descending, so that the first result will be the most specific and the last one will be the least specific (for example, a /24 network will be listed before a /8 network)"