Create a new security trigger

Introduction

This page explains how to create a security "trigger," a set of rules that will "fire" an email or a web request after a security event happens

Previously, you could view security events, like login attempts and invalid password entries, in the audit log. With the 2021.15 release, you can automatically trigger an action based on security events.

Default security triggers

On the Triggers page, there are six pre-built triggers in the Security Triggers section.

Notify when a user account is locked
Notify when a user enters an invalid one-time password
Notify when a user enters an invalid password
Notify when a user successfully changed their password
Notify when a user successfully logs into this instance

To see exactly how these triggers are constructed, see the default security triggers reference section.

Create a new security trigger

1. Open the Triggers page

Navigate to Administration page > Triggers.

2. Click Create Security Trigger

Add a new trigger by clicking the Create Trigger drop-down. Then select Create Security Event Trigger.

3. Name your trigger

In the window, enter a name for your new trigger in the Name field.

4. Add the condition for this trigger to the IF section

First, decide on the condition you'd like to use. Which security event will cause your trigger to fire?

For some ideas, click + to open a shortcut menu. This menu includes ready-made event filters. Click a filter to add it to the Event Filter text box.

You can also click Show Reference to read more information about security triggers.

5. Add an action in the THEN section

To complete your trigger, add at least one action.

There are two types of actions available for security events: Send Email and Perform Web Request.

Send Email

An SMTP (email) action automatically sends an email when its event conditions are met. For each trigger, you can specify the message's To, From, Subject, HTML Body, and Body contents.

Note: The use of SMTP actions does not require configuring advanced mail options, but messages will come from and go to the default addresses.

Perform Web Request

Automatically perform a web request when the trigger's conditions are met. This can be used to automatically update another application with information based upon the event.

6. Click Save

Click Save and the window closes. Your trigger appears listed on the page and is automatically enabled. To disable your trigger, click the toggle button in the Enabled column.

Default security triggers reference

In this section, you can see how the default security triggers are defined. On the Triggers page, click Clone next to one of these trigger names to create a copy. From there, edit the Event Filter, Subject, or HTML Body fields to suit your organization.

Notify when a user account is locked

This trigger sends an email when a user has been locked out of their account.

Event Filter	Event.EventType = 'LoginAttempt' AND Event.OperationResult = 'LockedOut'
Action	Email
Subject
HTML Body	false
Body	{Event.UserName} has been locked out of their account. Details: User Name: {Event.UserName} User Source: {Event.UserSource} IP address: {Event.NetworkAddress} Time: {Event.Time}

Notify when a user enters an invalid one-time password

If a user enters a wrong one-time password (used in two-factor authentication or multifactor authentication setups), the trigger will send an email.

Event Filter	Event.EventType = 'LoginAttempt' AND Event.OperationResult = 'OneTimePasswordInvalid'
Action	Email
Subject	{Event.UserName} entered an invalid one-time password for their ScreenConnect account
HTML Body	false
Body	{Event.UserName} has entered an invalid one-time password for their ScreenConnect account. Details: User Name: {Event.UserName} User Source: {Event.UserSource} IP address: {Event.NetworkAddress} Time: {Event.Time}

Notify when a user enters an invalid password

If a user enters a wrong one-time password (used in two-factor authentication or multifactor authentication setups), the trigger will send an email.

Event Filter	Event.EventType = 'LoginAttempt' AND Event.OperationResult = 'PasswordInvalid'
	Email
Subject	{Event.UserName} entered an invalid password for their ScreenConnect account
HTML Body	false
Body	{Event.UserName} has entered an invalid password for their ScreenConnect account. Details: User Name: {Event.UserName} User Source: {Event.UserSource} IP address: {Event.NetworkAddress} Time: {Event.Time}

Notify when a user successfully changed their password

Event Filter	Event.EventType = 'ChangePasswordAttempt' AND Event.OperationResult = 'Success'
	Email
Subject	{Event.UserName} changed their password for their ScreenConnect account
HTML Body	false
Body	{Event.UserName} has successfully changed the password for their ScreenConnect account. Details: User Name: {Event.UserName} User Source: {Event.UserSource} IP address: {Event.NetworkAddress} Time: {Event.Time}

Notify when a user successfully logs into this instance

Event Filter	Event.EventType = 'LoginAttempt' AND Event.OperationResult = 'Success'
	Email
Subject	{Event.UserName} successfully logged into their ScreenConnect account
HTML Body	false
Body	{Event.UserName} has successfully logged into their ScreenConnect account Details: User Name: {Event.UserName} User Source: {Event.UserSource} IP address: {Event.NetworkAddress} Time: {Event.Time}

What's next

Test your triggers by performing the security event you selected. For example, if your security trigger is supposed to fire an email when someone logs in with an incorrect password, try logging into your instance with a bad password. You should expect to see the email arrive in your inbox within a few minutes. If it doesn't, double-check your trigger condition and test your mail settings.