This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Notifications

Overview

Alert external endpoints (Email, GitHub, Slack, and more) about Anchore events such as policy evaluation results, vulnerability updates, and system errors with our new Notifications service. Configure notification endpoints and manage which specific events you need through Anchore Enterprise UI.

For more information on the Notifications Service in general, its concepts, and details on its configuration, please refer to the Notifications Service.

The following sections in this document describe the current endpoints available for configuration, the options provided for selecting events, the various actions you can do with a configuration (add, edit, test, and remove), and how to disable an endpoint as an admin.

Anchore Enterprise includes Notifications service to alert external endpoints about the system’s activity. Services that make up Anchore Enterprise generate events to record significant activity, such as an update, in the policy evaluation result or vulnerabilities for a tag, or an error analyzing an image. This service provides a mechanism to selectively notify events of interest to supported external endpoints. The actual notification itself depends on the endpoint - formatted message to Slack, email and MS Teams endpoints, tickets in GitHub and Jira endpoints, and JSON payload to webhook endpoint.

Glossary

Event
An information packet generated by Anchore Enterprise service to indicate some activity.
Endpoint
External tool capable of receiving messages such as Slack, GitHub, Jira, MS Teams, email or webhook.
Endpoint Configuration
Connection information of the endpoint used for sending messages.
Selector
Criteria for selecting events to be notified.

Installation

Anchore Enterprise Notifications is included with Anchore Enterprise, and is installed by default when deploying a trial quickstart with Docker Compose, or a production deployment Kubernetes.

Configuration

Enterprise Notifications Service

The service loads configuration from the notifications section of the config.yaml. See the following snippet of the configuration:

...
services:
  notifications:
    enabled: true
    require_auth: true
    endpoint_hostname: "<hostname>"
    listen: '0.0.0.0'
    port: 8228
    cycle_timers:
      notifications: 30
    # Set Anchore Enterprise UI base URL to receive UI links in notifications
    ui_url: "<enterprise-ui-url>"

The cycle_timers -> notifications controls how often the service checks for events in the system that need to be processed for notifications. Default is every 30 seconds.

The ui_url is used for constructing links to Enterprise UI pages in the notifications. Configure this property to the Enterprise UI’s base URL. This URL should be accessible from the endpoint receiving the notification for the links to work correctly. If the value is not set, the notification message is still be sent to the endpoint, but it won’t contain a clickable link to the Enterprise UI.

Note: Any changes to the configuration requires a restart of the service for the updates to take effect.

RBAC Permissions

In the Anchore Enterprise deployment, the table below lists the required actions and containing roles:

DescriptionActionRoles
List all the available notification endpoints and their statuslistNotificationEndpointsRead Only, Read Write
List all available configurations for an endpointlistNotificationEndpointConfigurationsRead Only, Read Write
Get an endpoint configuration and associated selectorsgetNotificationEndpointConfigurationRead Only, Read Write
Create an endpoint configuration and associated selectorscreateNotificationEndpointConfigurationRead Write
Update an endpoint configuration and associated selectorsupdateNotificationEndpointConfigurationRead Write
Delete an endpoint configuration and associated selectorsdeletetNotificationEndpointConfigurationRead Write

External Tools

To send notifications to an external tool/endpoint, the service requires connection information to that endpoint. See the following for the required information for each endpoint:

Concepts

Endpoint Status

All endpoints in the Notifications service can be toggled as Enabled or Disabled. The endpoint status reflects the eabled or disabled state. By default, the status for all endpoints is enabled by default. Setting the endpoint status to disabled stops all notifications from going out to any configurations of that specific endpoint. This is a system-wide setting that can only be updated by the admin account. It is read-only for remaining accounts.

Endpoint Configuration

The endpoint configuration is the connection information such as URL, user credentials, and so on for an endpoint. The service allows multiple configurations per endpoint. Endpoint configurations are scoped to the account.

Selector

The services provides a mechanism to selectively choose notifications and route them to a configured endpoint. This is achieved using a Selector, which is a collection of filtering criteria. Each event is processed against a Selector to determine whether it is a match or not. If the Selector matches the event, a notification is sent to the configured endpoint by the service.

For a quick list of useful notifications and associated Selector configurations, see Quick Selection.

A Selector encapsulates the following distinct filtering criteria: scope, level, type, and resource type. Some allow a limited set of values, and others wildcards. The value for each criteria has to be set for the matching to compute correctly.

Scope

Allowed values: account, global

Events are scoped to the account responsible for the event creation.

  • account scope matches events associated with a user account.
  • global scope matches events of any and all users. global scope is limited to admin account only. Non-admin account users can only specify account as the scope.
Level

Allowed values: info, error, *

Events are associated with a level that indicates whether the underlying activity is informational or resulted in an error. - info matches informational events such as policy evaluation or vulnerabilities update, image analysis completion and so on.

  • error matches failures such as image analysis failure.
  • * will match all events.
Type

Allowed values: strings with or without regular expressions

Event types have a structured format <category>.<subcategory>.<event>. Thus, * matches all types of events. Category is indicative of the origin of the event.

  • system.* matches all system events.
  • user.* matches events that are relevant to individual consumption.
  • Omitting an asterisk will do an exact match. See the GET /event_types route definition in the external API for the list of event types.
Resource Type

Allowed values: *, image_digest, image_tag, image_reference, repository, feeds, feed, feed_group, *

In most cases, events are generated during an operation involving a resource. Resource type is metadata of that resource. For instance image_tag is the resource type in a policy evaluation update event. * matches all resource types if you are uncertain what resource type to use.

Quick Selection

The following Selector configurations are for notifying a few interesting events.

ReceiveScopeLevelTypeResource Type
Policy evaluation and vulnerabilities updatesaccount*user.checks.**
User errorsaccounterroruser.**
User infosaccountinfouser.**
Everything user relatedaccount*user.**
System errorsaccounterrorsystem.**
System infosaccountinfosystem.**
Everything system relatedaccount*system.**
Allaccount***
All for every account (admin account only)global***

Notifications UI Walkthrough

alt_text

Supported Endpoints

Email
Send notifications to a specific SMTP mail service.
GitHub
Version control for software development using Git.
JIRA
Issue tracking and agile product management software by Atlassian.
Slack
Team collaboration software tools and online services by Slack Technologies.
Teams
Team collaboration software tools and online services by Microsoft.
Webhook
Send notifications to a specific API endpoint.

Event Selector Options

alt_text

When adding or editing a configuration, selecting which events to be notified on can be as easy as choosing one of the above three options: All Notification Events, Policy & Vulnerability Events, or Error Events.

Advanced users can select Add Custom Selector for more granularity:

alt_text

In the example shown, we configure to be notified on all system info events affecting any resource associated with the user’s account. For an in-depth explanation on the provided properties and their possible values, view our Selector documentation.

Adding a Configuration

alt_text

If you haven’t already defined a configuration for an endpoint, simply click Let’s Add One! as shown above. Once you have, add additional configurations with Add New Configuration as shown below.

alt_text

Upon doing so, a modal will appear with various properties shown on the left side. Note that based on the type of endpoint, these properties may differ.

To view the various requirements, check the documentation for Email, GitHub, JIRA, Slack, and Teams.

alt_text

For more information on adding a custom selector, please view our Selector documentation.

Prior to saving your new configuration, feel free to test with the Test Configuration button. Then save with OK.

Note: If OK is not enabled, be sure all required fields have been filled out.

Editing a Configuration

alt_text

The process to edit a configuration entry is started by clicking Edit which is found within the Actions column as shown above.

alt_text

The various fields available for editing are the same shown when adding the configuration. For additional info on a specific field, hover over the provided question icon circled with an orange ring next to the field name.

At any time, you can select Cancel to disregard any changes you’ve made.

For testing any new changes prior to saving them, click Test Configuration.

To save your changes, click OK. If OK is not enabled, be sure all required fields have been filled out.

Testing a Configuration

alt_text

When viewing your configurations, testing is easy - just look under the Actions column and click Test for that entry.

alt_text

Otherwise, when adding or editing a configuration, search for the test button pictured above. It can be found near the bottom of the modal, next to the Cancel and OK buttons.

Removing a Configuration

alt_text

To remove a specific notification configuration, simply click on the Remove button (as shown above) within the Actions column for that entry.

Select Yes to proceed with the deletion process or No to cancel. Please note that once you agree to remove the configuration, you won’t be able to recover it.

Admin-specific Actions

alt_text

Disabling Endpoints

As an admin, navigate to System > Notifications and click on the toggle visible in the lower-right corner of the specific endpoint you’re aiming to disable.

By default, all endpoints (such as Email, Slack, and Webhook) are enabled out of the box. Disabling a specific endpoint requires admin privileges as it ensures all notifications are stopped from going out to any configuration for that endpoint system-wide.

Note that users are still able to add, edit, test, and remove notification configuration items, but no event messages will be sent for that endpoint until it is re-enabled.

1 - Slack

Notifications to Slack are in the form of messages to a channel.

Requirements

Do the following to receive Slack notifications.

  1. An Incoming Webhook URL is required. Follow instructions to create one.
  2. Copy the Incoming Webhook URL.
  3. Create a Slack endpoint configuration in the Notifications service either via Enterprise UI or the API directly.

2 - GitHub

Notifications to GitHub are in the form of new issues in a repository.

Requirements

Do the following to receive GitHub notifications.

  1. Provide the following required GitHub account and repository-related information.
    • Username of the account for creating issues.
    • Token with repository access. Follow instructions to create a new Access Token in the account used for creating issues.
    • Name of the repository where the issues are created.
    • Owner of the repository.
    • (Optional) GitHub API URL, defaults to https://api.github.com if not specified.
    • (Optional) milestone assigned to the issue.
    • (Optional) one or more labels assigned to the issue.
    • (Optional) one or more GitHub users assigned to the issue.
  2. Create a GitHub endpoint configuration in the Notifications service either via Enterprise UI, or the API directly.

3 - Jira

Notifications to Jira are in the form of new issues in a project.

Requirements

Do the following to receive Jira notifications.

  1. Provide the following required Jira account and project related information.
    • URL of the Jira project.
    • Username of the account for creating issues.
    • API token or password depending on the Jira project.
      • For Jira Cloud projects an API token is required. Follow instructions to create a new API token for the account creating issues.
      • For Jira Self-managed projects password of the account creating issues is required.
    • Project key, same as the prefix in the issue identifier. For instance, issue TEST-1 has the project key TEST.
    • Type of the issue created such as Bug, Task, Story, and so on.
    • (Optional) priority assigned to the issue such as Low, Medium, High, and so on.
    • (Optional) one or more labels to be assigned to the issue.
    • (Optional) Jira user to be assigned to the issue.
  2. Create a Jira endpoint configuration in the Notifications service either via Enterprise UI, or the API directly.

4 - SMTP

Notifications to SMTP server are in the form of html and plain text message packets.

Requirements

Do the following to receive SMTP notifications.

  1. Provide the following required SMTP server information.
    • Host name/address
    • Port number
    • From address
    • To address
    • (Optional) username
    • (Optional) password
    • (Optional) use tls to encrypt connection
  2. Create an SMTP endpoint configuration in the Notifications service either via Enterprise UI, or the API directly.

5 - Microsoft Teams

Notifications to Microsoft Teams are in the form of messages to a channel.

Requirements

Do the following to receive Microsoft Teams notifications.

  1. An incoming webhook URL is required. See the Microsoft instructions to create one.
  2. Copy the incoming webhook URL.
  3. Create a Microsoft Teams endpoint configuration in the Notifications service either via Enterprise UI, or the API directly.