How to setup notifications from the Edgescan platform?

A guide to how to create events, why create an event, and what sort of configuration can I have for my events.

Version Number: v1.0.1

Published Date: 14 May 2024

____________________________________________________________________________

What are Edgescan Events?

In the realm of Edgescan, "Events" serve as pivotal moments that indicate significant occurrences within the platform. Picture yourself monitoring a specific asset, like a website or network component, for any adjustments. An Event signifies a notable change, such as the detection of a new host (indicating a new device connected to your network) or the identification of a vulnerability (highlighting a potential security weakness).

How do Events Work?

When an Event occurs, it can set off "Event Triggers" if certain conditions are met. Think of Event Triggers as personalized alarms that you set up to alert you about specific changes you care about. If an Event matches the conditions you've specified, it activates the Trigger, which then sends out a notification. The information sent in this notification is known as the "payload."

It's important to note that Events are always linked to a specific asset, referred to as the "target asset."

Can Anyone Set Up an Event Trigger?

Absolutely! Every user has the power to create multiple Event Triggers. However, you can only manage Event Triggers associated with your account. This means you can set them up, tweak them, or remove them as you see fit.

Starting with Default Events

To get you up and running, Edgescan provides a set of default Events for all new users. These are designed to keep you informed about significant actions and changes through updates in your activity feed or via email notifications.

These default Events are covered in more detail in the following article Edgescan default notifications.

Just like any other Event, these default notifications are fully customizable. You can modify or delete them to best suit your needs and preferences.

Navigating the Event Page

The Events Page on Edgescan can be found through the account drop-down menu. Here, you'll encounter "triggers," previously introduced as event triggers.

Events

Creating a Trigger

Creating a trigger is straightforward:

1. Click ‘Add event’ to open a new trigger in edit mode.
2. Use the ‘Cancel’ button to undo unsaved changes or delete a new, unsaved trigger.

Overview of Existing Events

Each trigger you create or have set up appears on the Events Page as a summary. This summary displays the trigger's label and how you'll be notified. Clicking on a trigger's summary opens it in edit mode for any adjustments or review.

Event Overview

Labelling Your Trigger

Trigger Label

• The label acts as a clear, easy-to-understand description of when the trigger will activate.
• You have the option to craft your own label or let Edgescan auto-generate one (The T button). This can be done by keeping the default label or selecting the auto-generate option.
• The label is typically included in the notification (event payload) sent out when the trigger activates.

Event Types

Triggers are designed to respond to specific types of events. The example below states that 'when a vulnerability is opened on Altoro Mutual, trigger an event.

Event Trigger Type

Here's a list of available event types and when they fire:

• Assessment Complete: Activates once an Edgescan analyst finishes evaluating an asset.
• Assessment Start: Triggers a set time before an assessment begins on an asset.
• Vulnerability Opened/Closed: Responds to the opening or closing of vulnerabilities on an asset during an evaluation.
• Host Discovered/Down: Activates upon the discovery of new hosts or when hosts go down on an asset in ASM.
• Port Opened/Closed: Triggers when changes in port status (opened/closed) are detected on an asset in ASM.
• Node Added: Fires when a note is added to either an asset or a vulnerability.
• Port Verification Complete: Informs users of the completion of a mapper port verification scan and any changes in port status (Open/Closed/Unchanged).
• Credentials Added Notification: Set to alert if credentials are added for one or more specified users on one or more specified assets.
• Asset Blocker Created: Fires when a blocker preventing asset evaluation is created.
• Asset Blocker Verified: Triggers when an Edgescan analyst confirms a blocker is still in place.
• Asset Blocker Resolved: Activates when a blocker is cleared.
• SLA Violation Event: Alerts users when a service level agreement threshold is breached.

Trigger Scope: Customizing Your Alerts

Trigger Scope

Triggers can be fine-tuned to activate under specific conditions related to asset visibility:

• All Assets: This setting allows the trigger to activate for any asset within your scope.
• Selected Assets: Choose specific assets for which the trigger should activate. This option is ideal for targeted monitoring.
• Assets Tagged: Use this setting to activate the trigger for assets marked with specific tags. You can decide whether any or all specified tags on an asset should match to activate the trigger.

Trigger Options: Setting Conditions

Setting Conditions

Different event types have unique conditions that can be set to refine when a trigger should activate, in our example above, the trigger will fire when a vulnerability is opened and risk level is at least medium.

• Assessment Start: Set a notification period ranging from 0 hours to 7 days before an assessment begins.
• Vulnerability Opened/Closed: Specify a minimum risk level (default is 'medium') for the vulnerability to trigger an alert.
• Host Discovered: Choose whether to include reactivated hosts in the trigger conditions.
• Port Opened/Closed: Define specific TCP or UDP port ranges to monitor for changes.
• Note Added: Specify user(s) whose note additions should activate the trigger.
• Credentials Added Notification: Trigger alerts when specified user(s) add credentials.

Display Options: Customizing Notification Content

Display options affect the detail level in the default payload for notifications, with more details included if set to true. These options vary by event type but follow a similar principle across the board.

Notification Content

Notification Options: Choosing How to be Alerted

Edgescan supports multiple notification methods (Email, Web-hook, SMS, and Feed), with customizable options for email and web-hook notifications.

Alert Options

Email Options

• Send to My Email: By default, triggers send notifications to the user's account email.
• Additional Email Addresses: Specify other emails to receive notifications.
• Subject Line: Customize the subject line of notification emails.

Email Options

Webhook Options

• URL: Specify the request URL, starting with 'http://' or 'https://'.
• HTTP Method: The default method is 'POST'.
• Additional Headers: Define any additional header-value pairs for the request.
• Validate SSL: Ensures the SSL certificate of the URL is verified.
• Use Payload: Choose between XML or JSON formats for the default payload, with specific options for Slack and Microsoft Teams integrations.

Webhook Options

Status Icons

Status icons appear to the left of the summary for each trigger. An asterisk ‘*’ indicates a trigger with unsaved changes.

Unsaved Trigger

Advanced Mode: Tailoring Triggers and Notifications

Advanced Mode elevates your control over event triggers and notification contents. Activate it by clicking the button at the top right of the edit pane.

Advanced Mode

In Advanced Mode, you can precisely define the conditions for triggering an event. This is done in a text area where conditions are expressed as a JSON object. This object combines logical operators and field comparisons within the event context. For specifics on operators and comparisons, refer to the Edgescan™ events API documentation.

Advanced Conditions

Advanced Mode also lets you dictate the format and content of notification payloads for all notification methods. Each method has a default payload format, but you can create a custom payload by selecting ‘Custom…’. Custom payloads use mustache templates, which you can start from an existing template and customize by clicking ‘Customize payload’. For more details on the available context for payload templates, consult the Edgescan API documentation.

For JSON payloads, our custom mustache renderer automatically inserts commas when using Array types.

Cloning Events

If you need a new event similar to an existing one, use the clone button to create a duplicate with all the original settings. This new event will have "(copy)" appended to its name, and you can then modify it as needed before saving, just like any other event.

Cloning Events

Cloned Event

Toggling Events

Each saved event comes with a toggle switch for easy activation or deactivation. This feature allows you to temporarily disable an event without deleting it, providing flexibility in how you manage event notifications:

• Toggle On: The switch will be to the right with a green background, indicating the event is active.
• Toggle Off: The switch moves to the left with a white background, signifying the event is inactive.

Toggled Events