Overview

Actions are configured in the file cfg/actions.toml

The topic of actions is the most complex feature of malwatch and deserves its own section because they define the fate of detections. Any outcome which occurs as a result from a detection is an action. Actions are so powerful because they can easily be customised at a granular level. Custom actions can even be created by editing just a few source files.

Each action is comprised of a verb as well as acter. Each detection can have multiple actions. The lack of any verb for a detection means no actions can occur, this can be considered the same as a traditional whitelist as offered by alternative software.

The following verbs are included by default:

Verbs

Verb	Outcome
alert	Notification by means of one or more alerters. We bundle PagerDuty, e - mail and custom JSON.
quarantine	Move the detection to a different path.
exile	Uploads the detection to your s3 bucket and is removed after succcessful upload.
clean	Configurable sed based expressions remove malware automatically. Basic base64 encoded malware removal expressions are included as examples.

Loadouts

A loadout is any collection of verbs associated with a path or signature. For example [Signatures."eicar"] = ["alert"] is a loadout because it has assigned the alert verb to the eicar signature rule which will be applied upon detection.

A loadout can be imagined as similar to the row of weaponary used by aircraft, assuming all are used in optimal order when engaged.

Default Loadout

A set of actions which are automatically applied for each detection. Shown below is an example where every detection will trigger an alert and exile.

Default = ["alert", "exile"]

Command

Editing the cfg/actions.toml config file is strongly discouraged because the format / syntax can be complex. It is better to let malwatch edit the configuration using the actions { get | set | del } PATH SIGNATURE [ACTION...] command.

Let's try adding some verbs to a path. Doing this will override the default verbs:

malwatch actions set /var/www/html/index.php eicar quarantine

When considering the default loadout Default = ["alert", "exile"], the actions then become ["quarantine"] for the path /var/www/html/index.php

If we wanted to disable actions for that path, then the line would read as follows:

malwatch actions set /var/www/html/index.php eicar ""

The final empty quotes "" are important, otherwise malwatch will think eicar is an action instead of a signature name. The result would be no actions to be applied for /var/www/html/index.php upon detection of the eicar signature.

get

actions get prints the loadout for a given signature or path.

set

actions set sets verb(s) as the loadout for a given signature or path. Existing verbs in the loadout are overwritten.

del

actions del removes verb(s) to the loadout for a given signature or path. Any remaining verbs in the loadout remain.

What About...

Directories. Can they be used?

Yes but it is not recommended for skips. One might consider it better to spend more time managing an actions config instead of reducing a layer of security.

A whitelist and skip config at the same time?

An existing skip will take priority over all other definitions.

Verb conflicts? What will happen if I specify alert and invalid not-exist at the same time?

The actions command has logic to prevent multiple entries, ambiguity and typos. Verbs are even filtered upon loading the config just in case any were incorrectly manually specified.

Non existent path, will it work?

Paths can be transient, therefore their presence is not checked.