Automatically perform tasks when a computer is added or changed (event-based tasks)

In this article, references to protecting virtual machines apply only to Deep Security On-Premise software installations.

Event-based tasks let you monitor protected computers for specific events and perform tasks based on certain conditions.

Create an event-based task

In Deep Security Manager, click Administration > Event-Based Tasks > New. The wizard that appears will guide you through the steps of creating a new task. You will be prompted for different information depending on the type of task.

Edit or stop an existing event-based task

To change the properties for an existing event-based task, go to click Administration > Event-Based Tasks. Select the event-based task from the list and click Properties.

Events that you can monitor

Computer Created (by System): A computer being added to the manager during synchronization with an Active Directory or Cloud Provider account, or the creation of a virtual machine on a managed ESXi server running a virtual appliance.
Computer Moved (by System):A virtual machine being moved from one vApp to another within the same ESXi, or a virtual machine on an ESXi being move from one datacenter to another or from one ESXi to another (including from an unmanaged ESXi server to a managed ESXi server running a virtual appliance.)
Agent-Initiated Activation: An agent is activated using agent-initiated activation.
IP Address Changed: A computer has begun using a different IP.
NSX Security Group Changed: The following situations will trigger this event (the event will be recorded on each affected VM):
- A VM is added to a group that is (indirectly) associated with the NSX Deep Security Service Profile
- A VM is removed from an NSX Group that is associated with the NSX Deep Security Service Profile
- An NSX Policy associated with the NSX Deep Security Service Profile is applied to an NSX Group
- An NSX Policy associated with the NSX Deep Security Service Profile is removed from an NSX Group
- An NSX Policy is associated with the NSX Deep Security Service Profile
- An NSX Policy is removed from the NSX Deep Security Service Profile
- An NSX Group that is associated with an NSX Deep Security Service Profile changes name
Computer Powered On (by System): Enables users to trigger activation by the VMware Virtual Machine power on event.

The Computer Powered On event is only compatible with virtual machines hosted on ESX environments in VMWare. Use this event cautiously because if a large number of computers are turned on at the same time, this event could cause a slowdown.

Conditions

You can require specific match conditions to be met in order for a task to be carried out. For example, you might require an AWS 'tag' of ProductionSystem to be present in an Amazon EC2 instance in order for the Activate Computer action (see Actions, below) to occur on it.

When adding conditions:

Click the "plus" button to add multiple conditions. In a multi-condition setup, ALL conditions must be met for the action to be carried out.
Use Java regular expression syntax (regex). Some examples of how to use regex are provided in the table below. For details on regex, see https://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html.

List of conditions and descriptions of each

Cloud Instance Image ID: AWS cloud instance AMI ID.
This match condition is only available for AWS instances added to the manager through Computers > Add > Add AWS Account.
Cloud Instance Metadata: The metadata being matched corresponds to AWS tags, Azure tags, or GCP labels that have been added to your AWS, Azure, or GCP instances.
This match condition is available for AWS instances and Azure or GCP VMs added to the manager through Computers > Add > [Add AWS Account, Add Azure Account, or Add GCP Account]. Metadata currently associated with a computer is displayed on the Overview page in its editor window. To define the conditions to match for, you must provide two pieces of information: the metadata key and the metadata value. For example, to match a computer which has a metadata key named "AlphaFunction" that has a value of "DServer", you would enter "AlphaFunction" and "DServer" (without the quotes). If you wanted match more than one possible condition, you could use regular expressions and enter "AlphaFunction" and ".*Server", or "AlphaFunction" and "D.*".
Cloud Instance Security Group Name: The security group the cloud instance applies to.
This match condition is only available for AWS cloud instances.
Cloud Account Name: The "Display Name" field in the Cloud Account properties window.
Cloud Vendor: The cloud environment vendor of the instance. This condition is used to match on instances from a specific cloud vendor. Currently, you can match on AWS, Azure, and GCP vendors.
Cloud Vendor only works if you added your cloud instances to the manager through Computers > Add > [Add AWS Account, Add Azure Account, or Add GCP Account].
Computer Name: The "Hostname" field in the computer properties window.
ESXi Name: The "Hostname" field of the ESXi server on which the VM computer is hosted. ESXi Name: The "Hostname" field of the ESXi server on which the VM computer is hosted.
Folder Name: The name of the folder or directory in which the computer is located in its local environment.
This match condition looks for a match against the name of any parent folder of the computer, including the root datacenter for vCenter server integrations. If you add a "*" character to the beginning of the regular expression, the condition must match the name on all parent folders. This is particularly useful when combined with negation in a regular expression. For example, if you want to match computers in folders that do not include "Linux" in the folder name, you could use a regular expression like *^((?!Linux).)*$.
GCP Network Tag: Network tags that have been added to GCP VMs.
If the GCP VM has multiple GCP network tags, and a match is found on any one of them, the VM is considered as matched.
NSX Security Group Name: The list of potential groups in this condition refers only to NSX Groups associated with NSX Policies associated with the NSX Deep Security Service Profile. The VM may be a member of other NSX Groups but for the purposes of this match, condition it is not relevant.
Platform: The operating system of the computer.
vCenter name: The "Name" field of the computer's vCenter properties that was added to Deep Security Manager.
These next two conditions match True or False conditions:
Appliance Protection Available: A Deep Security Virtual Appliance is available to protect VMs on the ESXi on which the VM is hosted. The VM may or may not be in a "Activated" state.
Appliance Protection Activated: A Deep Security Virtual Appliance is available to protect VMs on the ESXi on which the VM is hosted and the VM is "Activated".
This condition looks for matches to an IP in an IP list:
Last Used IP Address: The current or last known IP address of the computer.
Depending on the source of the new computer, some fields may not be available. For example, "Platform" would not be available for computers added as a result of the synchronization with an Active Directory.

Java regex examples

To match:	Use this:
any string (but not nothing)	.+
empty string (no text)	^$
Folder Alpha	Folder\ Alpha
FIN-1234	FIN-\d+ or FIN-.*
RD-ABCD	RD-\w+ or RD-.*
AB or ABC or ABCCCCCCCCCC	ABC*
Microsoft Windows 2003 or Windows XP	.Windows.
Red Hat 7 or Some_Linux123	.Red.\|.Linux.\|

Actions

The following actions can be taken depending on which of the above events is detected:

Activate Computer: Deep Security protection is activated on the computer.
- Delay activation by (minutes): Activation is delayed by a specified number of minutes.

If the event-based task is intended to apply protection to a VM that is being vMotioned to an ESXi protected by a Deep Security Virtual Appliance, add a delay before activation to allow any pending VMware administrative tasks to complete. The amount of delay varies depending on your environment.

Deactivate Computer:Deep Security protection is deactivated on the computer.
Assign Policy: The new computer is automatically assigned a policy. (The computer must be activated first.)
Assign Relay Group: The new computer is automatically assigned a relay group from which to receive security updates.
Assign to Computer Group: The computer is placed in one of the computer groups on the Computers page.

Order of execution

When using event based tasks, you should create and use conditions that are unique to each task. This is because when identical conditions are encountered, Deep Security will process them in a specific order, and this order does not take into account the number of conditions within a task to rank said tasks against each other.

For example, if the server01.example.com computer on a Windows Server 2012 platform encountered the following event-based tasks:

The event-based task with more conditions is not automatically executed first. Instead, the "Platform" condition is matched twice, and the event-based tasks are executed based on the name of the task and your database type.

PostgreSQL: "a task", "A task", "b task", "B task"
Oracle: "A task", "B task", "a task", "b task" (ASCIIBetical order)
Microsoft SQL Server: Depends on the locale of the operating system.

However, keep in mind that this order does not stop on the first match, and instead stops on the last match. This, in practice, means that if you're using Oracle, the example above would be assigned a policy by the "catch-All EBT" because using ASCIIBetical order dictates that the "c" in "catch" comes after "S" in "Specific".

To avoid unexpected results, use a specific naming convention for your event-based tasks, such as CamelCase.

The order of task names is actually dictated by what collation scheme you use for the column "name" of the table "scheduledtasks" within your database. For example, Oracle uses the collation scheme "NLS_COMP:BINARY" and "NLS_SORT:BINARY" as its default collation scheme for all columns, and that sorts task name strings in ASCIIBetical order.

Temporarily disable an event-based task

To prevent an existing event-based task from running, right-click it and then click Disable . For example, you may want to temporarily disable an event-based task while you perform certain administrative duties during which you don't want any activity to occur.

To re-enable an event-based task, right-click it and then click Enable.