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

argus-cli cases autocreate DATA KEY TEMPLATE_FOLDER

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:

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."

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 Template Primer for more details

TEMPLATE_FOLDER

Directory where the templates are loaded from. the command will search for templates with filenames of the form: <key>.<language>.html within that directory.

See Template Primer for more details

--group-by: Identifiers in the data to group by (Unique cases will be created per group).

--sort-by: Identifiers in the data to sort by.

--timeout: Timeframe between new cases. If not specified a new case will be created every run.

--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 --case-title-en and --case-title-no

default : 'Autocreated based on group {group}'

--case-title-en

Title of the created case for customers preferring English. Can be used with python string formatting.

If this option is set, --case-title-no must be set as well and --case-title can not be used.

--case-title-no

Title of the created case for customers preferring Norwegian. Can be used with python string formatting.

If this option is set, --case-title-en must be set as well and --case-title can not be used.

--case-title-format

Sets the title format template. Can be either fmtstr or jinja.

fmtstr: short for “format string”, use python’s str.format syntax.
jinja: enables jinja2 syntax

default: fmtstr

--case-status

The status of the created case.

The value must be one of STATUSES

default : pendingCustomer

--case-priority

The priority of the created case.

The value must be one of PRIORITIES

default : medium

--case-type

The type of the created case.

The value must be one of CASE_TYPES

default : securityIncident

--case-service

The service of the created case.

default : ids

--case-watcher: Watcher that should be added to the case.

--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:

--case-watcher-from-field 'properties[property.name]'

--skip-notifications: Flag. If set, no notification will be sent on case creation.

--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.

--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.

--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.

--explicit-access: User(s) that should be given explicit (exclusive) access to new cases. Ignored if --internal-case is set.

--dry

Flag. If set, no data will be commited (i.e no case will be created).

Useful for testing autocreate scripts.

--test-data

Flag. If set, the case will be flagged as TEST_DATA.

Requires TECH privileges.

Useful for testing autocreate scripts.

--close-after-create: Flag. If set, the case will be closed immediately after creation.

--status-on-update <status>

If set, set existing cases to <status> whenever new events are attached to them.

This will have no effect on closed cases unless the --close-after-create option is set to reopen (default depending on other options, see --close-after-create). If that is the case, reopened cases will be set to <status>.

--closed-case-update <method>

Sets the action to take when attaching new events to an existing case that is closed.

<method> can be one of :

reopen : the existing closed case is reopened. This is the default, unless the --close-after-create flag is set.
silent : the new events are silently added to the existing closed case. This is the default if the --close-after-create flag is set.
new-case: creates a new case with the new events attached, bypassing any --timeout value. If --close-after-create is set, it applies to this new case.

--request-soc-analysis: Flag. If set, immediately request the “socAnalysis” workflow. If the “socAnalysis” workflow is already active, this request will be ignored.

--request-workflow <flow>: After creating/updating the case, request the specified workflow. If the workflow is already active, this will be ignored

--acknowledge-workflow <flow>: After creating/updating the case, acknowledge the specified workflow. If the workflow is not active, this will be ignored.

--workflow-comment <comment>

Use the specified comment when requesting/acknowledging workflow

Example:

--request-workflow customerUpdate --workflow-comment 'Needs review by SOC'

--enrich <enrichment1> [<enrichment2>, <...>]

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

see Using enrichments for more details.

--attach-events

Format for events attached to the case.

Must be json or csv

If left unset, no events will be attached.

--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 {"key": key, "value": value} form used by the API or, as a shortcut, the {key: value:} form.

Specify a JSON object or list to add multiple tags.

Examples:

# valid:
--tags '{"tag1" : "tag1-value", "tag2": "tag2-value"}'
# also valid:
--tags '[{"tag1": "tag1-value"}, {"key" :"tag2", "value": "tag2-value"}]'

--fields

Add fields to the created case. Fields should be specified as JSON data, and accept both the {"field": key, "value": value} form used by the API or, as a shortcut, the {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:

# valid:
--fields '{"field1" : "field1-value", "field1": "field2-value"}'
# also valid:
--fields '[{"field1": "field1-value"}, {"key" :"field2", "value": "field2-value"}]'

--silent-update: Flag. If set, no comment will be added to an existing case when new events are attached to it.

--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.

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

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:

{% if comment %}
    <p>New events matching the pattern has been found.</p>

    <ul>
    {% for event in data %}
        <li>{{ event.sourceIP }} -> {{ event.destinationIP }}: {{ event.properties.userName }} </li>
    {% endfor %}
    </ul>
{% else %}
    <h2>Summary</h2>

    <p>Some strange things are going on...</p>

    <ul>
    {%- for event in data %}
        <li>{{ event.sourceIP }} -> {{ event.destinationIP }}: {{ event.properties.userName }} </li>
    {%- endfor %}
    </ul>
{% 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:

the current week is {{current_time | week_num}}

Using enrichments

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

Multiple enrichments can be specified :

argus-cli cases autocreate --enrich ENRICHMENT1 ENRICHMENT2 [...]

Caution

--enrich is a multiple-value option, make sure you understand the Multiple-Value options Caveats

Note

the 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:

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) :

{%- 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 %}

<h1>events basic networks information:</h1>
{% for item in data %}
    {{ item["id"] }} :
    {{- networks_info(item) -}}

{% endfor %}