Anchore Enterprise Notifications

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.

Overview

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.

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>"
    authorization_handler: external
    authorization_handler_config:
      endpoint: "<rbac-authorizer-endpoint>"

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 an Anchore Enterprise RBAC-enabled deployment, the table below lists the required actions and containing roles:

Description Action Roles
List all the available notification endpoints and their status listNotificationEndpoints Read Only, Read Write
List all available configurations for an endpoint listNotificationEndpointConfigurations Read Only, Read Write
Get an endpoint configuration and associated selectors getNotificationEndpointConfiguration Read Only, Read Write
Create an endpoint configuration and associated selectors createNotificationEndpointConfiguration Read Write
Update an endpoint configuration and associated selectors updateNotificationEndpointConfiguration Read Write
Delete an endpoint configuration and associated selectors deletetNotificationEndpointConfiguration Read 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.

Receive Scope Level Type Resource Type
Policy evaluation and vulnerabilities updates account * user.checks.* *
User errors account error user.* *
User infos account info user.* *
Everything user related account * user.* *
System errors account error system.* *
System infos account info system.* *
Everything system related account * system.* *
All account * * *
All for every account (admin account only) global * * *

See it in action

Enterprise UI

To learn more about configuring Notifications service in the Enterprise UI, see Notifications.

Last modified March 24, 2022