.. _command-cases-autocreate-yaml:

autocreate-yaml
===============

The autocreate-yaml command combines the ``events search`` and
:ref:`cases autocreate <command-cases-autocreate>` commands in a single
configuration-based interface for automated case creation based on even data.

Usage
-----

.. program:: argus-cli cases autocreate-yaml

.. code-block:: bash

    argus-cli cases autocreate-yaml CONFIG

.. option:: CONFIG

  Path to the autoreport configuration file. see
  :ref:`command-cases-autocreate-yaml-config <command-cases-autocreate-yaml-config>`
  for information on the configuration format.

.. option:: --dry

   If set, perform a dry run (no data will be commited).

   Corresponds with the :option:`argus-cli cases autocreate --dry`.

.. option:: --test-data

   If set, create cases marked as test data.

   Corresponds with the :option:`argus-cli cases autocreate --test-data`.

.. option:: --base-time <base_time>

   Override the base time set in configuration. Can be used to run an autoreport for a
   past period.

.. option:: --time-frame <time_frame>

   Override the time frame set in configuration. Can be used to re-run an autoreport
   for a past period.

.. option:: --validate

   Flag. If set, only verify the the configuration file contains valid data and exit.

.. option::  --test-time-expr

   Flag. If set, only print information about how time variables have been calculated.

.. option:: --no-prod-excludes

   Flag. If set, do not exclude flags that are normally excluded by default during
   the search.

.. _command-cases-autocreate-yaml-flow:

Autoreport flow
---------------

The general flow of an autoreport is as follows:

First, an event search is ran using the criterias defined in the
:ref:`search section of the autoreport configuration <command-cases-autocreate-yaml-config-search>`,
for the time period defined by the "base time" and the "time frame" :

 - the "base time" is a reference point in time, and is usually - and by default - the
   time of running the autoreport.
 - the "time frame" is the size of the time window to search, relative to the "base time"

For instance, if the base time is ``now`` (the default) and the time frame is ``1 week``, events will be
searched in the period between "1 week before now" and "now". If the base time is changed
to ``one month ago``, events will be searched between "one week before exactly one month ago"
and "exactly one month ago".

The base time is controlled by the :ref:`base_time option <command-cases-autocreate-yaml-cfg-base_time>`,
but the default of ``now`` is suitable for most use cases. When testing an autoreport
or re-running one for a past period, it can be set with the :option:`--base-time` option
without editing the configuration file.

.. tip::

   use the :option:`--test-time-expr` to see how base time and time frame are computed.

The start and end times calculated based on the base time and time frame. as well as
other search option are passed to the ``events search`` command.

Second: nce the search has ran, ``autocreate-yaml`` feeds its results as well as all required
autoreporting options to the :ref:`cases autocreate <command-cases-autocreate>` command
and the regular autoreport flow takes place.

.. _command-cases-autocreate-yaml-config:

Configuration
-------------

structure
"""""""""

autoreport configuration is yaml file with the following structure :

.. code-block:: yaml

   key: "autoreport key"
   template_folder: "/path/to/templates" # optional if provided via command line
   # timing options
   base_time: "now" # optional, default to "now"
   time_frame: "1 week" # REQUIRED
   timeout: "1 day" # optional, default to "now"
   sort_by: # optional, no default
     - "properties[sorting.property]"
   search: # REQUIRED, all search options are optional and have no default
     min_severity: "high"
     exact_match_properties: true # optional, defaults to base_time
     min_count: 10 # optional
     enrich:
       - "enrichment1"
       - "enrichment2"
     customer:
       include:
         - "customer1"
         - "customer2"
       exclude:
         - "customer3"
     flag:
       include:
         - "FLAG1"
       exclude:
         - "FLAG2"
         - "FLAG3"
     properties:
       include:
         "property.1": "value1"
         "property.2": "value2"
       exclude:
          "property.3": "value3"
     # ... other search options
   case: # optional
     title:
       "en": "case title in english"
       "no": "case title in norwegian"
     # OR title: "title" for a non-localized case title
     group_by: # optional, no default
       - "properties[source.user]"
     status: "pendingCustomer" # defaults to "pendingCustomer"
     priority: "medium" # default sto "medium"
     service: "ids" # defaults to "ids"
     type: "securityIncident" # default to "securityIncident"
     catgeory: "case category" # no default
     close_after_create: false # defaults to false
     tags:
      "tag1": "tag1 value"
      "tag2": "tag2 value"
   workflows:
     request: "workflow name" # no default
     acknowledge: "workflow name" # no default
     comment: "comment body" # no default
   updates:
      closed_case: "silent" # one of "reopen", "silent", "new-case"
      status_on_update: "pendingCustomer"
   notifications:
     skip_notifications: false # default to false
     watcher: "watcher_name" # no default
     watcher_from_field: "properties[watcher_property.name]"

A more minimal example:

.. code-block:: yaml

   key: "my-autoreport"
   time_frame: "1 week"
   timeout: "1 day"
   min_severity: "high"
   search:
     customer:
       - "mnemonic"
     case:
       title: "high priority events today!"


top-level options
"""""""""""""""""

``autocreate-yaml`` specific options
''''''''''''''''''''''''''''''''''''

.. _command-cases-autocreate-yaml-cfg-base_time:

``base_time``
'''''''''''''

 - optional, defaults to ``now``.
 - controls the "base time" for searching events to autoreport on. The "base time" is the
   end of the event search window.
 - Expects a string value expressing a point in time (see :ref:`concepts-date-formats`).
 - Can be overridden when running an autoreport with the :option:`--base-time` option.

``time_frame``
''''''''''''''

 - **required**
 - controls the "time frame" from the events search - the start of the events search
   window.
 - Expects a string value expressing a point in time (see :ref:`concepts-date-formats`).
 - relative to :ref:`command-cases-autocreate-yaml-cfg-base_time`

Example: it :ref:`command-cases-autocreate-yaml-cfg-base_time` is set to ``now`` and
``time_frame`` is set to ``1 day``, the events search window will be between ``1 day``
before ``now`` and ``now``.


``default_prod_excluded_flags``
'''''''''''''''''''''''''''''''

 - optional
 - defaults to ``["NOTIFIED", "INITIAL_TUNING"]``
 - Controls flags that are excluded from search by default in a production settings.
 - For testing purposes, they can be "un-excluded" with :option:``--no-prod-excludes``

``autocreate`` options
'''''''''''''''''''''''

These options map directly to :ref:`cases autocreate <command-cases-autocreate>`
command-line options:


 - ``template_folder``:
    - corresponds with :option:`argus-cli cases autocreate TEMPLATE_FOLDER`
    - optional, but :option:``--template-folder`` must be used if not set
 - ``timeout``
   - corresponds with :option:`argus-cli cases autocreate --timeout`

   .. warning::

      the :option:`argus-cli cases autocreate --timeout` is relative to the current time,
      but ``autocreate-yaml`` calculates the timeout relative to :ref:`command-cases-autocreate-yaml-cfg-base_time`
 - ``sort_by``:
    - corresponds with :option:`argus-cli cases autocreate --sort-by`
    - value must be formatted as a yaml list
 - ``initial_internal_comment``:
    - corresponds with :option:`argus-cli cases autocreate --initial-internal-comment`
 - ``internal_case``:
    - **DEPRECATED**
    - corresponds with :option:`argus-cli cases autocreate --internal-case`

   .. warning::

      for historical reasons, :option:`argus-cli cases autocreate --internal-case` creates
      cases in a way sends them to the QA queue. Do not use this setting for testing
      purposes - use the ``test_data`` setting or the :option`--test-data` option instead.

 - ``explicit_access``:
    - corresponds with :option:`argus-cli cases autocreate --explicit-access`
    - value must be formatted as a yaml list
 - ``attach_events``:
    - corresponds with :option:`argus-cli cases autocreate --attach-events`
 - ``test_data``
    - corresponds with :option:`argus-cli cases autocreate --test-data`
    - can be overriden with :option:`--test-data` **unless set to true**

.. _command-cases-autocreate-yaml-config-search:

``search`` section
""""""""""""""""""

All search options map to ``argus-cli events search`` command-line options -
see  ``argus-cli events search --help``.

Command-line options that follow the ``include``/``exclude`` pattern, such as
``--include-customer``, ``--exclude-customer`` can be be expressed as:

.. code-block:: yaml

   <option>:
     include:
       - "<value1>"
       - "<value2>"
     exclude:
       - "<value3>"

For example:

.. code-block:: yaml

   customer:
     include:
       - "mnemonic"
     exclude:
       - "demo"
       - "globex"

iI equivalent to ``argus-cli events search --include-customer mnemonic --exclude-customer demo globex``.

All ``include``/``exclude`` are supported, as well as:

 - ``exact_match_properties``
 - ``min_severity``
 - ``min_count``
 - ``enrich``


``case`` section
""""""""""""""""

All cases options correspond with :ref:`cases autocreate <command-cases-autocreate>`
options:

``title`` corresponds with :option:`argus-cli cases autocreate --case-title`,
:option:`argus-cli cases autocreate --case-title-en` and :option:`argus-cli cases autocreate --case-title-no`:

for a non-localized title, use:

.. code-block::

   title: "case title"

which is equivalent to ``argus-cli cases autocreate --case-title "case title"``.

For a localized title:

.. code-block::

   title:
     "en": "english case title"
     "no": "norwegian case title"

``argus-cli cases autocreate --case-title-en "english case title" --case-title-no "norwegian case title"``.

Other options map more directly to :ref:`cases autocreate <command-cases-autocreate>`
options:

 - ``group_by``:
   - corresponds with :option:`argus-cli cases autocreate --group-by`
   - value must be formatted as a yaml list
 - ``title_format``:  :option:`argus-cli cases autocreate --case-title-format`
 - ``status``:  :option:`argus-cli cases autocreate --case-status`
 - ``priority``:  :option:`argus-cli cases autocreate --case-priority`
 - ``type``:  :option:`argus-cli cases autocreate --case-type`
 - ``service``:  :option:`argus-cli cases autocreate --case-service`
 - ``tags``:
    - :option:`argus-cli cases autocreate --tags`
    - example:

    .. code-block:: yaml

       tags:
         "tag1": "value 1"
         "tag2": "value 2"
 - ``fields``:
    - :option:`argus-cli cases autocreate --fields`
    - example:

    .. code-block:: yaml

       fields:
         "field1": "value 1"
         "field2": "value 2"
 - ``close_after_create``: :option:`argus-cli cases autocreate --close-after-create`
 - ``use_fields``: :option:`argus-cli cases autocreate --use-fields`


``notifications`` section
"""""""""""""""""""""""""

Notifications options map directly to  :ref:`cases autocreate <command-cases-autocreate>`
options:

 - ``watcher``: :option:`argus-cli cases autocreate --case-watcher`
 - ``watcher_from_field``: :option:`argus-cli cases autocreate --case-watcher-from-field`
 - ``skip_notifications``: :option:`argus-cli cases autocreate --skip-notifications`

``workflows`` section
"""""""""""""""""""""

Workflows options map to  :ref:`cases autocreate <command-cases-autocreate>`
options as follows:

 - ``request``: :option:`argus-cli cases autocreate --request-workflow`
 - ``acknowledge``: :option:`argus-cli cases autocreate --acknowledge-workflow`
 - ``comment``: :option:`argus-cli cases autocreate --workflow-comment`

``updates`` section
"""""""""""""""""""

Updates options correspond to :ref:`cases autocreate <command-cases-autocreate>`
options that control the behavior of the tool on "updates" (situations when events
are added to an already existing case, as opposed to the creation of a new case):

 - ``closed_case``: :option:`argus-cli cases autocreate --closed-case-update`
 - ``silent``: :option:`argus-cli cases autocreate --silent-update`
 - ``status_on_update``: :option:`argus-cli cases autocreate --status-on-update`