.. _command-cases-autocreate: autocreate ========== The autocreate command is used to create cases automatically from events in Argus. This is useful for automatically handling events that always get a case, enabling the SoC to use their time on more useful analysis. Usage ----- .. program:: argus-cli cases autocreate .. code-block:: bash argus-cli cases autocreate DATA KEY TEMPLATE_FOLDER .. option:: DATA The JSON event data used to create the events. Can be passed as a file, or piped to the command. Most use-cases will use the latter method, which looks like this: .. code-block:: bash argus-cli events search --format "json" 2018-11-01 2018-11-07 --include-customer mnemonic | argus-cli cases autocreate "scary-events" ./templates/ --group-by attackInfo[alarmID] --timeout "1 week" --case-title "This week, scary stuff happened." .. option:: KEY The key is an identifier for the autocreate instance. It is added to the resulting case as the value of the ``case-autocreate-key``, and is used to select the case template. See :ref:`autocreate-template-primer` for more details .. option:: TEMPLATE_FOLDER Directory where the templates are loaded from. the command will search for templates with filenames of the form: ``..html`` within that directory. See :ref:`autocreate-template-primer` for more details .. option:: --group-by Identifiers in the data to group by (Unique cases will be created per group). .. option:: --sort-by Identifiers in the data to sort by. .. option:: --timeout Timeframe between new cases. If not specified a new case will be created every run. .. option:: --case-title Title of the created case for all customers, regardless of their language preference. Can be used with python string formatting. If this option is used, the title set will be used for all customers, regardless of their language settings. Can not be used with :option:`--case-title-en` and :option:`--case-title-no` default : :code:`'Autocreated based on group {group}'` .. option:: --case-title-en Title of the created case for customers preferring English. Can be used with python string formatting. If this option is set, :option:`--case-title-no` must be set as well and :option:`--case-title` can not be used. .. option:: --case-title-no Title of the created case for customers preferring Norwegian. Can be used with python string formatting. If this option is set, :option:`--case-title-en` must be set as well and :option:`--case-title` can not be used. .. option:: --case-title-format Sets the title format template. Can be either ``fmtstr`` or ``jinja``. - ``fmtstr``: short for "format string", use python's :meth:`str.format ` syntax. - ``jinja``: enables jinja2 syntax default: ``fmtstr`` .. option:: --case-status The status of the created case. The value must be one of :data:`~argus_plugins.cases.utils.STATUSES` default : ``pendingCustomer`` .. option:: --case-priority The priority of the created case. The value must be one of :data:`~argus_plugins.cases.utils.PRIORITIES` default : ``medium`` .. option:: --case-type The type of the created case. The value must be one of :data:`~argus_plugins.cases.utils.CASE_TYPES` default : ``securityIncident`` .. option:: --case-service The service of the created case. default : ``ids`` .. option:: --case-watcher Watcher that should be added to the case. .. option:: --case-watcher-from-field String that points to where e-mail address for a case watcher is in the event. The format is like python's dictionary access. Example: .. code-block:: bash --case-watcher-from-field 'properties[property.name]' .. option:: --skip-notifications Flag. If set, no notification will be sent on case creation. .. option:: --initial-internal-comment Flag. If set, creates a new internal comment on case creation. This can be added with a block checking for ``internal`` in your template. .. option:: --internal-case .. warning:: **DEPRECATED**: This option is deprecated, and may be removed at any time. If you intend for the case to be reviewed by someone before publishing, use --send-to-qa instead. Flag. If set, makes new cases only visible internally for techs. .. option:: --send-to-qa Creates the case using normal parameters, but sets the case as unpublished on create. This will make it appear in the QA flow. Use this when you want someone to review the case before publishing to the customer. .. option:: --explicit-access User(s) that should be given explicit (exclusive) access to new cases. Ignored if :option:`--internal-case` is set. .. option:: --dry Flag. If set, no data will be commited (i.e no case will be created). Useful for testing autocreate scripts. .. option:: --test-data Flag. If set, the case will be flagged as ``TEST_DATA``. Requires ``TECH`` privileges. Useful for testing autocreate scripts. .. option:: --close-after-create Flag. If set, the case will be closed immediately after creation. .. option:: --status-on-update If set, set existing cases to ```` whenever new events are attached to them. This will have no effect on closed cases unless the :option:`--close-after-create` option is set to ``reopen`` (default depending on other options, see :option:`--close-after-create`). If that is the case, reopened cases will be set to ````. .. option:: --closed-case-update Sets the action to take when attaching new events to an existing case that is closed. ```` can be one of : - ``reopen`` : the existing closed case is reopened. This is the default, unless the :option:`--close-after-create` flag is set. - ``silent`` : the new events are silently added to the existing closed case. This is the default if the :option:`--close-after-create` flag is set. - ``new-case``: creates a new case with the new events attached, bypassing any :option:`--timeout` value. If :option:`--close-after-create` is set, it applies to this new case. .. option:: --request-soc-analysis Flag. If set, immediately request the "socAnalysis" workflow. If the "socAnalysis" workflow is already active, this request will be ignored. .. option:: --request-workflow After creating/updating the case, request the specified workflow. If the workflow is already active, this will be ignored .. option:: --acknowledge-workflow After creating/updating the case, acknowledge the specified workflow. If the workflow is not active, this will be ignored. .. option:: --workflow-comment Use the specified comment when requesting/acknowledging workflow Example: .. code-block:: bash --request-workflow customerUpdate --workflow-comment 'Needs review by SOC' .. option:: --enrich [, <...>] One or more enrichment(s) to perform on the event data. see :ref:`autocreate-using-enrichments` for more details. .. option:: --attach-events Format for events attached to the case. Must be ``json`` or ``csv`` If left unset, no events will be attached. .. option:: --tags .. note:: This option is deprecated. Use case fields with --fields instead. Add tags to the created case. Tags should be specified as JSON data, and accept both the :code:`{"key": key, "value": value}` form used by the API or, as a shortcut, the :code:`{key: value:}` form. Specify a JSON object or list to add multiple tags. Examples: .. code-block:: bash # valid: --tags '{"tag1" : "tag1-value", "tag2": "tag2-value"}' # also valid: --tags '[{"tag1": "tag1-value"}, {"key" :"tag2", "value": "tag2-value"}]' .. option:: --fields Add fields to the created case. Fields should be specified as JSON data, and accept both the :code:`{"field": key, "value": value}` form used by the API or, as a shortcut, the :code:`{field: value:}` form. .. important:: Case fields must be explicitly created and associated to cases before they can be added here. Contact Development if you want to use a new case field. Specify a JSON object or list to add multiple fields. Examples: .. code-block:: bash # valid: --fields '{"field1" : "field1-value", "field1": "field2-value"}' # also valid: --fields '[{"field1": "field1-value"}, {"key" :"field2", "value": "field2-value"}]' .. option:: --silent-update Flag. If set, no comment will be added to an existing case when new events are attached to it. .. option:: --use-fields If set, use case fields instead of tags to identify existing cases. .. note:: This option will be removed once tags are no longer in use at all. Use only for testing purposes in the interim period. .. _autocreate-template-primer: Template Primer --------------- All autocreate keys have to have an associated template. There are usually two template files; one for english and one for norwegian. The name of these are in the format: ``key.lang.html``. For example: ``spam.en.html`` and ``spam.no.html``. The template itself is written in HTML using Jinja2_ as the templating engine. This guide will only cover rudimentary Jinja2 to allow you to get started. For more comprehensive documentation, consult `Jinja's documentation`__ .. _Jinja2: https://jinja.palletsprojects.com/ __ Jinja2_ Creating a template ^^^^^^^^^^^^^^^^^^^ After a template file has been created, it is time to write some Jinja2 powered HTML! The template will be passed two variables from the program: * ``data`` - A list of JSON event objects * ``comment`` - A boolean indicating if this is a comment. These two variables are the only things needed to create your template! Here is an example of a simple template: .. code-block:: jinja {% if comment %}

New events matching the pattern has been found.

    {% for event in data %}
  • {{ event.sourceIP }} -> {{ event.destinationIP }}: {{ event.properties.userName }}
    • {% endfor %}
{% else %}

Summary

Some strange things are going on...

    {%- for event in data %}
  • {{ event.sourceIP }} -> {{ event.destinationIP }}: {{ event.properties.userName }}
    • {%- endfor %}
{% endif %} .. caution:: If the template does not contain a check for the ``comment`` variable, then every new event associated with an existing case will post the same (typically) longform text as the inital case. Because of this, it is always recommended to have an if-statement for comments in a template. Additionally, the variables ``current_time`` and ``timeout`` are available in cases templates in title templates (if the case title format is set to ``jinja`` only). ``current_time`` is the time at which the template is evaluated and ``timeout`` is the point in time that is the timeout cutoff. Both these variables are python ``datetime`` object. As a convenience, a ``week_num`` jinja filter has been added to translate this variables into a week number: .. code-block:: jinja the current week is {{current_time | week_num}} .. _autocreate-using-enrichments: Using enrichments ----------------- The autocreate command supports enriching event data from sources other than the events API through enrichments. Those enrichments are controlled by the :option:`argus-cli cases autocreate --enrich` option. Multiple enrichments can be specified : .. code-block:: bash argus-cli cases autocreate --enrich ENRICHMENT1 ENRICHMENT2 [...] .. caution:: ``--enrich`` is a multiple-value option, make sure you understand the :ref:`Multiple-Value options Caveats` .. note:: the :ref:`command-events-search` command also provides the ``--enrich`` option. When running an autocreate script, enrichments need only be used once (either in ``cases autocreate`` or in the ``events search`` providing the events), 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 `_ (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 `_ (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)" Usage in templates ^^^^^^^^^^^^^^^^^^ Enrichment data is added directly to the event objects accessible in the templates as data, under the ``["_enrichments_"]`` key. Here is an example template with two macros demonstrating the usage of the customer networks enrichments. It will display or not display the information depending on whether it is available, and will function regardless of the ``--enrich`` option value(s) used (``customer-networks-source``, ``customer-networks-destination``, both or not used at all) : .. code-block:: jinja {%- macro format_networks(customer_networks) -%} {%- for network in customer_networks -%} {{ network["networkAddress"]["address"] }}/{{ network["networkAddress"]["maskBits"] }} : "{{ network["description"] }}" {%- if loop.nextitem is defined -%} - {%- endif -%} {%- endfor -%} {%- endmacro -%} {% macro networks_info(event) %} {%- set src_net=event["_enrichments_"]["customer-networks"]["source"] -%} {%- set dst_net=event["_enrichments_"]["customer-networks"]["destination"] -%} {%- if src_net %}Source : {{ format_networks(src_net) }} {% endif -%} {%- if dst_net %}Destination: {{ format_networks(src_net) }}{% endif -%} {% endmacro %}

events basic networks information:

{% for item in data %} {{ item["id"] }} : {{- networks_info(item) -}} {% endfor %}