# Spectra Analyze Alerts — Subscriptions, Delivery Methods & Notifications

> Set up Spectra Analyze alert subscriptions to receive real-time email or in-app notifications when malware classification or analysis results change.

The Alerts feature allows real-time monitoring to track changes in malware classification and analysis results. It automates notifications for specific events, allowing users to utilize their time more efficiently and be informed of malware status changes on-the-go.

![The action menu on the Alerts page with Configure option highlighted](./images/analyze-alerts-page.png)

Users can receive notifications about changes related to the samples on the appliance and in Spectra Intelligence. The notifications make it easy to monitor and track various malware analysis activities even when the users are away from the appliance. Users can choose how often they want to be notified, and where they want to receive the notifications. [Unresolved](#marking-alerts-as-resolved) alerts are indicated by a red badge on the alerts indicator in the top right of the interface, and by blue stripes to the left of the alerts grid.

The conditions that define when an alert should be generated are called **subscriptions**. Every subscription can be associated with one or more **delivery methods**.

Users can create and modify alert subscriptions from the [Subscriptions and Actions Management page](#managing-alerts). It is also possible to [create alert subscriptions for individual samples](#creating-a-new-alert-subscription) in the GUI.

Every alert subscription can have one or more delivery methods. Users can create and modify actions from the [Subscriptions and Actions Management page](./alerts.md#managing-alerts). When an alert is triggered, the notification is delivered to the destination(s) specified in the associated action(s).

If an alert subscription doesn’t have any associated delivery methods, the alert will only be visible on the Alerts page. The Alerts page provides an overview of all events on the appliance, including the ones generated by user-defined subscriptions. Users can filter the Alerts page to display only the alerts related to specific alert subscriptions.

**Important notes about the Alerts feature**

1. Alerts are sent only if there is a new event matching the conditions configured in the subscription. Alerts cannot be sent for events that occurred before a subscription was created.
2. Multiple alerts triggered for one subscription in the selected notification period will be aggregated and sent in a single email message.
3. The SMTP service must be configured on the appliance in order to receive emails about new alerts.
4. The maximum amount of hashes that the user can add to one subscription is 1000.
5. Only SHA1 hashes can be added to alert subscriptions.
6. The maximum amount of subscriptions a user can create is 10 000. This limit is not user-configurable. When the limit is reached, a notification appears in the GUI, warning the user that some old subscriptions should be removed in order to create new ones.
7. Alert subscriptions are private and visible only to the user who created them. When other users are logged into their accounts, they will not be able to see or modify subscriptions created by other users.

## Alert Types

The following table lists the currently supported types of alerts (notifications). To set up an alert and get notified when it is triggered, users have to [create a new subscription](./alerts.md#creating-a-new-alert-subscription).

| Alert Type                    | Alert Trigger                                                                                                                                                                                                                  |
|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Analysis Alerts               | Analysis Alerts include notifications for Static Analysis, Threat Intelligence and RL Cloud Sandbox, tracking the progress of automated analysis. It also covers third-party sandbox integrations like Cuckoo and Joe Sandbox. |
| Classification change         | A sample’s threat status has changed (e.g., from “suspicious” to “malicious”).                                                                                                                                                 |
| Sample available for download | A previously unavailable sample has become available for download from the Spectra Intelligence cloud.                                                                                                                         |
| YARA matches                  | A new sample has matched one or more YARA rulesets. [YARA Retroactive Hunting matches](./yara-retro.md) are also included.                                                                                                     |

## Managing Alert Subscriptions and Delivery Methods

Users can view and manage their alert subscriptions from the [Alerts Configuration](#managing-alerts) page.

To access the page, click *Configure* on the Alerts page.

Alternatively, select **User menu > User profile** from the main menu. This opens the [User Settings](./initial-configuration.md#user-settings) page.

Alternatively, click *Configure* on the Alerts page.

The *Alerts Configuration* page is divided into two sections: *Alerts* and *Delivery Methods*.

All currently active subscriptions are listed in the *Alerts* section. Users can modify existing subscriptions by clicking *Edit*, or [create new ones](#creating-a-new-alert-subscription) by clicking **New Alert**.

![List of active alert subscriptions on the User Settings page](./images/analyze-alerts-configuration.png)

Similarly, all actions that can be associated with alert subscriptions are listed in the *Delivery Methods* section. Users can modify existing actions by clicking *Edit*, or [create new ones](#creating-a-delivery-method) by clicking **New Method**.

### Creating a New Alert Subscription

To create a new alert subscription, open the *Alerts Configuration* page, and click **New Alert**.

The *New Subscription* dialog allows users to choose one or more event types and the associated delivery methods. Users can also add a custom name and description to every subscription, which makes it easier to distinguish between subscriptions and quickly check their scope.

In order to associate an alert subscription with a delivery method, users must first [create some delivery methods](#creating-a-delivery-method). When a delivery method is associated with an alert subscription, the details configured for the delivery method apply to that particular subscription. Any method can be associated with any number of active alert subscriptions. Likewise, any subscription can have more than one delivery method associated with it.

For example, if an action can define that email should be sent to *test@user.example* every 2 hours, any associated alert subscription will send alerts to that particular address at that particular frequency.

Saving the alert subscription makes it active on the appliance.

![Dialog for creating a new alert subscription](images/analyze-subscription-dialog.png)

### Event Types

Depending on the selected event types, additional options become available in the *New Subscription* dialog.

**Analysis Alerts**

Subscribe to notifications for ReversingLabs services (Static Analysis, Threat Intelligence and RL Cloud Sandbox) and third-party services. Available alert stages depend on the analysis method and may include *Started*, *Finished*, and/or *Failed*.

**Classification Changes**

The Classification Changes event type allows choosing which changes in sample threat status will trigger an alert (for example, from goodware and suspicious to malicious). It is possible to select multiple threat status values in both configuration fields.

![Dialog for creating a new Classification change alert subscription](images/analyze-alerts-classification-changes.png)

There are several optional checkboxes that allow setting up more fine-grained alerting criteria.

1. **On Risk Score change** - becomes visible for this event type when threat status values that support it are selected. Selecting the checkbox sends an alert when there is a transition in the [risk score](/General/AnalysisAndClassification/Classification/#risk-score) of a sample (for example, from low (6) to medium (7)), even if the threat status does not change.

   For example, a sample's risk score can increase from 6 to 9, but the sample will still be classified as malicious. The alert is not sent when the risk score transition is within the same severity range (for example, medium (8) to medium (7)). Transitions in risk score values for goodware samples do not generate alerts.

2. **On threat name change** - selecting it will send an alert when the threat name of a sample changes, even if its threat status remains unchanged.

3. **Notify on specific hash(es)** - when this checkbox is selected, an additional *Sample hash values* text field becomes available. If any SHA1 hashes are entered into the text field, the alert is sent only for classification changes to those samples. When this checkbox is not selected, and no SHA1 hashes are provided, the alert is sent for classification changes to all samples on the appliance.

**Sample Available for Download**

The Sample available for download event type requires users to provide a list of at most 100 SHA1 hashes to monitor for availability.

If **Fetch and analyze** is enabled, samples will automatically be downloaded to the appliance when they become available.

**YARA Matches**

The YARA Matches event type accepts a list of YARA rulesets that a sample should match to trigger the alert. There is an autocomplete pull-down list with names of all YARA rulesets on the appliance. The maximum number of YARA rulesets is 20.

### Creating a Delivery Method

To create a new delivery method, open the *Alerts Configuration* page, and click **New Delivery Method**.

The *New Delivery Method* dialog allows users to choose the delivery method (where to send alerts about triggered events) and set the notification frequency (how often the alerts should be sent). Users can also add a custom name for every action.

Currently supported delivery methods include *E-mail* and *Syslog*.

Clicking *Save* saves the method, making it visible in the *Delivery Methods* section and available when creating or modifying an alert subscription

![Dialog for creating a delivery method](images/analyze-alerts-delivery-method.png)

#### Creating a New Email Delivery Method

When the *E-mail* method is selected, an additional checkbox **Deliver to logged in user** becomes available. Selecting this checkbox will send alerts to the currently logged-in user, in addition to other email addresses provided in the *Additional email addresses* field. Each address should be in its own line in the text field.

The SMTP service must be configured on the appliance in order to receive alert emails from it. Appliance administrators should make sure the settings are properly configured in the **Administration > Configuration > SMTP** dialog.

When delivered to the configured address, the alert email contains information about which subscriptions have new alerts, and how many new alerts were generated for each subscription. The email also contains a link for each subscription. The link leads to the Alerts page on the appliance, filtered to display only alerts for the specified subscription.

#### Creating a New Syslog Delivery Method

When the *Syslog* method is selected, additional options become available in the dialog.

**Host** - requires the user to input the host address of the syslog server that should receive alerts

**Port** - requires the user to configure the port on which the syslog server should listen for alerts.

**Transport protocol** - allows choosing which communication protocol should be used to send alerts to the syslog server. Supported protocols are TCP and UDP. The protocol selected here affects which port number can be configured in the previous field

The **Message format** option allows users to customize how the alerts will appear in the logs. Users can combine any number of supported fields with custom text to adjust the contents of each alert. The default format (``*{sha1} - {alert_type} - {description}*``) is already configured here when creating a new action.

**Custom Message Examples**

```
{sha1} - {alert_type} - {description}

b8b3b60c13d3fbb6e1932dab72264410bab0a2ce - classification_change - Threat Status changed from 2 to 1 via Spectra Intelligence
```

```
The alert {label} was triggered on sample {sha1}

The alert New Malicious Detection was triggered on sample b8b3b60c13d3fbb6e1932dab72264410bab0a2ce
```

```
New {alert_type} alert received on file {sha1} with status {threat_status}

New classification_change alert received on file b8b3b60c13d3fbb6e1932dab72264410bab0a2ce with status 1
```

**Supported Message Fields**

| FIELD NAME             | DESCRIPTION                                                  | TYPE          |
| ---------------------- | ------------------------------------------------------------ | ------------- |
| alert_type             | Type of the triggered alert - can be one of the currently supported types: classification_change, sample_available, ticloud_analysis_complete, ticloud_upload_complete, cuckoo_analysis_complete, yara_match | string        |
| category               | File category of the sample for which the alert was triggered, expressed as a number. The numbers correspond to the following categories: 0 - Other, 1 - Application, 2 - Mobile, 3 - Document, 4 - Web, 5 - Archive, 6 - Media, 7 - Email | integer       |
| classification         | Classification of the sample in human-readable format. | string       |
| threat_status          | Threat status assigned to the sample that triggered the alert, expressed as a number. The numbers correspond to the following threat statuses: 0 - No Threats Found, 1- Good, 2 - Suspicious, 3 - Malicious | integer       |
| classification_reason  | Reason for the classification that the sample received, expressed as a number. The numbers correspond to the following classification reasons: 0 - No Threats Found, 1 - Antivirus, 2 - Signature, 3 - Certificate, 4 - Format, 5 - Exploit, 6 - YARA, 7 - RHA1, 128 - User, 256 - Cloud | integer       |
| threat_name            | Detected malware threat name for the sample that triggered the alert (for example, Win32.Trojan.Adams). | string        |
| classification_source  | Source of the classification for the sample that triggered the alert, expressed as a number. The numbers correspond to the following sources: 0 - None, 1 - Spectra Intelligence, 2 - [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis), 4 - User, 257 - Spectra Intelligence from Parent, 258 - Spectra Core from Parent, 260 - User from Parent, 513 - Spectra Intelligence from Child, 514 - Spectra Core from Child, 516 - User from Child | integer       |
| description            | The full description of the triggered alert, as displayed in the *Details* column on the Alerts page. Depending on the alert, it may include the username of the user who submitted the sample for analysis, the analysis duration, analysis parameters, or the reasons the analysis failed (for example, "Static Intelligence Analysis Started for 72bbd2513901b1bda0f3a0fdc257d347531a8e7a by admin" or "Threat Intelligence analysis complete with classification Goodware."). | string | | string        |
| factor                 | The risk score value, expressed as a number from 0 to 10, where 0 indicates the most trusted samples, and 10 indicates the most dangerous threats. | integer       |
| family_name            | The malware family name part of the threat name detected for the sample (for example, Marsdaemon, Orcus, Androrat…). | string        |
| file_size              | Size of the sample for which the alert was triggered, expressed in bytes. | integer       |
| file_subtype           | Subtype of the sample for which the alert was triggered, as detected by ReversingLabs static analysis (for example, TIFF, Clojure, HTML…). [See full list of file subtypes](./advanced-search.md#supported-file-types-and-subtypes) | string        |
| file_type              | Type of the sample for which the alert was triggered, as detected by ReversingLabs static analysis (for example, Document, Image, PE…). [See full list of file types](./advanced-search.md#supported-file-types-and-subtypes) | integer       |
| hostname               | Hostname of the system on which the sample that triggered the alert was analyzed or submitted. |
| identification_name    | Identification of the sample for which the alert was triggered, as detected by ReversingLabs static analysis. Identification is not generated for all file types and subtypes; it is an optional field in the static analysis report that indicates a more detailed (usually signature-based) file detection. | string        |
| identification_version | Version of the identified file format for the sample that triggered the alert (for example, Generic, 1.0, Container…). This is an optional field that is not generated for all file types and subtypes. | string        |
| json                   | Returns all available information about the alert, serialized in JSON format. | string        |
| label                  | Name of the alert subscription provided in the *Name* field of the *New Subscription* dialog. Users can modify the name for all alert subscriptions on the appliance. | string        |
| malware_type           | The malware type part of the threat name detected for the sample that triggered the alert (for example, Trojan, Adware, Rootkit…). | string        |
| platform               | The platform part of the threat name detected for the sample that triggered the alert (for example, Win32, Script-PHP, Linux…). | string        |
| sha1                   | SHA1 hash of the sample for which the alert was triggered.   | string        |
| subplatform            | The subplatform part of the threat name detected for the sample that triggered the alert (for example, HTML, Macro, PDF…). The subplatform part is present in the threat name only for specific platforms (ByteCode, Document, Script). | string        |
| timestamp              | Date and time when the alert was triggered.                  | UTC timestamp |
| uuid                   | Unique string identifying the triggered alert.               | string        |

### Modifying Existing Alert Subscriptions

Only the user who created a subscription can modify it.

To modify an existing alert subscription, click the *Edit* link next to the subscription name in the *Subscriptions* tab on the *Subscriptions and Actions Management* page. The dialog that opens is the same as for [creating a new subscription](#creating-a-new-alert-subscription).

Here you can enable more, or modify any existing event types, or add/remove delivery methods.

If a YARA ruleset with an active subscription gets deleted from the appliance, the dialog will warn the user when modifying the subscription for the missing ruleset.

### Deactivating Alert Subscriptions

There are several ways to deactivate an existing alert subscription.

1. Click the *Edit* link next to the subscription name in the *Subscriptions* tab. In the dialog that opens, modify the *Actions* field and remove all selected actions from it. The subscription itself remains on the appliance, and can be reactivated at any point by adding new actions.
2. Click the *Delete* link next to the subscription name in the *Subscriptions* tab. This completely removes the subscription from the appliance. Alerts for the removed subscription will no longer be sent.

## Managing Alerts

The Alerts page displays all generated events on the appliance. Users receive alert emails only for those events that match the criteria defined in their subscriptions.

Alerts are displayed in a list and sorted by the time when they occurred (in descending order, with newest alerts at the top). The list contains information about every alert, including:

- alert resolution status (unresolved alerts are indicated by a blue stripe to the left of the table)
- type of alert;
- threat status indicator of the sample associated with the alert;
- time when the alert was triggered;
- full notification text
- threat name (if detected);
- file format and size;

![Overview of the Alerts page](images/analyze-alerts-page.png)

Clicking the sample name in the notification column opens the [Sample Details](./Sample%20Details/sample-details-summary.md) page for the selected sample. Clicking any of the sample rows will expand it, showing additional information about a sample like in other pages on the appliance.

The action menu (☰) to the right of the *Resolved* column contains the *Configure* item, which opens the [Subscriptions and Actions Management page](#managing-alerts).

The total amount of triggered alerts on the appliance is displayed in the pagination section at the bottom of the page.

### Filtering Alerts

The toolbar above the list of alerts allows the users to filter alerts:

- by status (All, Resolved, Unresolved)
- by event type (All, Classification change, Sample available for download, YARA match, Cuckoo analysis complete, Spectra Intelligence upload complete, Spectra Intelligence analysis complete);
- by classification of the sample associated with an alert (All, Unknown, Goodware, Suspicious, Malicious);
- by the time when the alert was triggered (All, Custom, Today, Last Week…);
- by user or by alert subscription

When a subscription is deleted from the appliance, it is no longer visible in the user/subscription filtering menu. However, alerts triggered by that subscription will still be visible when the *My Alerts* option is selected.

![Subscriptions menu that allows filtering alerts by user-created subscriptions](images/analyze-alerts-my-alerts.png)

Filters can be combined to get a more precise overview of the triggered alerts (for example, show all YARA match alerts for subscriptions created this week that returned malicious samples).

When the *Classification change* alert type is selected in the toolbar, there is an additional option to choose which classification changes should be listed (for example, from no threats found to malicious or from suspicious to malicious).

For the *YARA match* alert type, an additional field *Enter ruleset name* becomes available, allowing users to display only the alerts related to a specific YARA ruleset.

### Exporting Alerts

The *Export* pull-down menu in the toolbar allows copying the list of SHA1 hashes or exporting the list of alerts as a CSV file. Users can select which columns should be included in the exported CSV file.

Only the current page will be copied/exported, not the entire list of all alerts on the appliance. The number of alerts per page - that is, the number of alerts that will be included in each exported file - can be increased or decreased in the navigation bar at the bottom of the Alerts page.

### Marking Alerts as Resolved

When an incoming alert has been acknowledged and dealt with, it is possible to mark it as *Resolved* to keep the Alerts page up-to-date. To mark an alert as *Resolved*, select the *Resolve* option in the action menu on the right. The blue highlight will then be removed from the alert.

![Triple bar menu on the Alerts page with the Resolve option highlighted](images/analyze-alerts-resolve.png)

It is also possible to resolve multiple alerts at once. This is done by selecting several alerts and choosing the *Resolve selected* option from the topmost action menu (☰) in the Alerts page toolbar.

Only the current page of alerts can be resolved. Up to 1000 alerts can be resolved at once by increasing the amount of alerts per page in the navigation toolbar to 1000, then selecting and resolving all alerts on the page.

When the selected alerts are resolved, a notification appears with the total number of resolved alerts. If some alerts had previously been resolved, the appliance will detect this and will not count them towards the total.

Filtering the Alerts page by resolution status will show only resolved alerts, hide resolved alerts, or show all alerts on the appliance. The filter can also be used to show and export all resolved alerts as described in the [Exporting Alerts](#exporting-alerts) section.

Users can also undo the alert resolution by clicking *Unresolve* (for a single alert) or *Unresolve Selected* (for multiple alerts) in the action menu on the Alerts page.

### Automatically Removing Alerts

**Only appliance administrators can enable this option.** Users who would like to enable this option should contact their appliance administrator.

Depending on the number of alert subscriptions configured on the appliance, alerts can quickly accumulate, making it difficult to browse the Alerts page.

To prevent this, appliance administrators can define how long the alerts should be kept on the appliance. When the alerts are older than the configured period, they are automatically removed from the appliance.

The alert retention period can be configured in the **Administration > Configuration > Alert Management** dialog. By default, alerts are kept for 3 months and automatically deleted after that period. Other supported options are 1 month and 6 months.

## Monitoring Samples with Alerts

Apart from creating and editing alert subscriptions on the [Subscriptions and Actions Management page](#managing-alerts), users can quickly modify subscriptions by adding new samples from different sections of the GUI. This is useful for adding interesting samples to an existing alert, or for creating a new alert that will monitor the activity on multiple samples.

The following table lists the interface sections where samples can be added to a subscription using the *Subscribe* option, or removed from a subscription using the *Unsubscribe* option. The table also indicates which sections support bulk actions (adding/removing multiple samples to/from a subscription).

| Section                          | Supported Alert Types                                | Bulk Actions |
| -------------------------------- | ---------------------------------------------------- | ------------ |
| Advanced Search Results - Local  | Classification change, Sample available for download | Yes          |
| Advanced Search Results - Cloud  | Classification change, Sample available for download | Yes          |
| YARA ruleset matches             | Classification change, Sample available for download | Yes          |
| Sample Details                   | Classification change, Sample available for download | No           |
| Sample Details > RHA results     | Classification change, Sample available for download | Yes          |
| Sample Details > Extracted Files | Classification change, Sample available for download | Yes          |
| Tags                             | Classification change, Sample available for download | Yes          |

To start monitoring a sample, open the action menu (☰) on the right side of the sample and select the *Subscribe* option.

![Section of the Spectra Analyze Web Interface with Subscribe option highlighted in the Sample Actions menu](images/analyze-alerts-subscribe.png)

This opens the *Subscribe to Hash Alert* dialog that allows creating a new alert or selecting an existing alert from the pull-down list.

Supported alert types are **Classification change** and **Sample available for download**. The dialog for creating a new alert is the same as in the [Creating a New Alert Subscription](#creating-a-new-alert-subscription) section.

If an existing alert is chosen in the pull-down list, the SHA1 hash of the selected sample is automatically added to the alert subscription. Users can then modify other fields in the subscription dialog, such as actions, before clicking *Submit* to save changes.

### Subscribing to Samples in Bulk

It is also possible to add more than one sample to an existing subscription, or to create a new subscription that will monitor several samples.

When multiple samples are selected on a page, the bulk actions menu (☰) is available in the header row of the sample list. To add the selected samples to an alert subscription, click the *Subscribe* item in the bulk actions menu.

Sample hashes can also be added to an existing alert subscription manually. To do that, access the *Subscriptions* tab on the [Subscriptions and Actions Management page](#managing-alerts) and click the *Edit* link next to the desired subscription.

In the dialog that opens, paste the SHA1 sample hashes into the *Sample hash values* text field and click *Submit*. Each hash should be in its own line in the text field.

### Removing Samples from Alert Subscriptions

Samples can also be removed from existing subscriptions. To remove one or more samples, use the *Unsubscribe* item from the sample action menu (or the bulk actions menu, if two or more samples are selected). A dialog appears, prompting the user to confirm the action.

Clicking *Unsubscribe* in the confirmation dialog removes the selected sample hashes from all subscriptions to which they were added. The subscriptions themselves are not removed or deactivated, and if they were configured to monitor other samples, the alerts will still be sent out for those samples.

Alternatively, samples can be removed from alert subscriptions manually, by editing the subscription from the *Subscriptions* tab. Click the *Edit* link next to a subscription, and in the dialog that opens, remove sample hashes from the *Sample hash values* text field.

## Tracking Unknown Hashes with Alerts

When searching for sample hashes on the appliance, the results can sometimes include unknown hashes. Those are hashes of samples that have not yet been found in the ReversingLabs system, or that are not available locally. (Note: this does not refer to hashes found in the system, but classified as Unknown.)

If the list of search results includes unknown hashes, they will be listed separately and accessible by clicking the *Not Found* filter/tab on the search results page. Users can subscribe to those hashes and get notified when they appear in the ReversingLabs system for the first time.

Supported alert types for unknown hashes are **Classification change** and **Sample available for download**. Unknown hashes can be added to new or existing alert subscriptions in the same way as described in the [Monitoring Samples with Alerts](#monitoring-samples-with-alerts) section.

## Setting Up Alerts for New YARA Ruleset Matches

The list of YARA rulesets on the YARA page also integrates with the Alerts feature. Apart from subscribing to individual samples from the list of matches on a YARA ruleset, it is also possible to subscribe to rulesets themselves. This type of alert is triggered when there is a new match for the subscribed ruleset.

To subscribe to a YARA ruleset from the YARA page, open the action menu (☰) on the right side of the ruleset and select the *Subscribe* option.

This opens the [New Alert dialog](#creating-a-new-alert-subscription) with the YARA Matches event type enabled, and the selected YARA ruleset automatically filled in.

Alternatively, users can create YARA ruleset match alert subscriptions from the [Alerts Configuration page](#managing-alerts).
