Configuring Watcher to Send Email

edit

Configuring Watcher to Send Email

edit

You can configure Watcher to send email from any SMTP email service. Email messages can contain basic HTML tags. You can control which tags are allowed by Configuring HTML Sanitization Options.

Configuring Email Accounts

edit

You configure the accounts Watcher can use to send email in your elasticsearch.yml configuration file. Each account configuration has a unique name and specifies all of the SMTP information needed to send email from that account. You can also specify defaults for all emails that are sent through the account. For example, you can set defaults for the from and bcc fields to ensure that all emails are sent from the same address and always blind copied to the same address.

If your email account is configured to require two step verification, you need to generate and use a unique App Password to send email from Watcher. Authentication will fail if you use your primary password.

If you configure multiple email accounts, you specify which account the email should be sent with in the email action. If there is only one account configured, you do not have to specify the account attribute in the action definition. However, if you configure multiple accounts and omit the account attribute, there is no guarantee which account will be used to send the email.

To add an email account, set the watcher.actions.email.service.account property in elasticsearch.yml. See Email Account Attributes for the supported attributes.

Currently, neither Watcher nor Shield provide a mechanism to encrypt settings in elasticsearch.yml. Because the email account credentials appear in plain text, you should limit access to elasticsearch.yml to the user that you use to run Elasticsearch.

For example, the following snippet configures a single Gmail account named work.

watcher.actions.email.service.account:
    work:
        profile: gmail
        email_defaults:
            from: 'John Doe <john.doe@host.domain>'
            bcc: archive@host.domain
        smtp:
            auth: true
            starttls.enable: true
            host: smtp.gmail.com
            port: 587
            user: <username>
            password: <password>

The email profile defines a strategy for building a MIME message. As with almost every standard out there, different email systems interpret the MIME standard differently and have slightly different ways of structuring MIME messages. Watcher provides three email profiles: standard (default), gmail, and outlook.

If you are using Gmail or Outlook, we recommend using the corresponding profile. Use the standard profile if you are using some other email system. For more information about configuring Watcher to work with different email systems, see:

Table 1. Email Account Attributes

Name Required Default Description

profile

no

standard

The profile to use to build the MIME messages that are sent from the account. Valid values: standard (default), gmail and outlook.

email_defaults.*

no

-

An optional set of email attributes to use as defaults for the emails sent from the account. See Email Action Attributes for the supported attributes. for the possible email attributes)

smtp.auth

no

false

When true, attempt to authenticate the user using the AUTH command.

smtp.host

yes

-

The SMTP server to connect to.

smtp.port

no

25

The SMTP server port to connect to.

smtp.user

yes

-

The user name for SMTP.

smtp.password

no

-

The password for the specified SMTP user.

smtp.starttls.enable

no

false

When true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must configured so that the client will trust the server’s certificate. Defaults to false.

smtp.*

no

-

SMTP attributes that enable fine control over the SMTP protocol when sending messages. See com.sun.mail.smtp for the full list of SMTP properties you can set. Note that all timeouts (writetimeout, connection_timeout and timeout) are configured to two minutes by default.

Sending Email From Gmail

edit

Use the following email account settings to send email from the Gmail SMTP service:

watcher.actions.email.service.account:
    gmail_account:
        profile: gmail
        smtp:
            auth: true
            starttls.enable: true
            host: smtp.gmail.com
            port: 587
            user: <username>
            password: <password>

If you get an authentication error that indicates that you need to continue the sign-in process from a web browser when Watcher attempts to send email, you need to configure Gmail to Allow Less Secure Apps to access your account.

If two-step verification is enabled for your account, you must generate and use a unique App Password to send email from Watcher.See Sign in using App Passwords for more information.

Sending Email from Outlook.com

edit

Use the following email account settings to send email action from the Outlook.com SMTP service:

watcher.actions.email.service.account:
    outlook_account:
        profile: outlook
        smtp:
            auth: true
            starttls.enable: true
            host: smtp-mail.outlook.com
            port: 587
            user: <username>
            password: <password>

You need to use a unique App Password if two-step verification is enabled. See App passwords and two-step verification for more information.

Sending Email from Amazon SES (Simple Email Service)

edit

Use the following email account settings to send email from the Amazon Simple Email Service (SES) SMTP service:

watcher.actions.email.service.account:
    ses_account:
        smtp:
            auth: true
            starttls.enable: true
            starttls.required: true
            host: email-smtp.us-east-1.amazonaws.com 
            port: 587
            user: <username>
            password: <password>

smtp.host varies depending on the region

You need to use your Amazon SES SMTP credentials to send email through Amazon SES. For more information, see Obtaining Your Amazon SES SMTP Credentials. You might also need to verify your email address or your whole domain at AWS.

Sending Email from Microsoft Exchange

edit

Use the following email account settings to send email action from Microsoft Exchange:

watcher.actions.email.service.account:
    exchange_account:
        profile: outlook
        email_defaults:
            from: <email address of service account> 
        smtp:
            auth: true
            starttls.enable: true
            host: <your exchange server>
            port: 587
            user: <email address of service account> 
            password: <password>

Some organizations configure Exchange to validate that the from field is a valid local email account.

Many organizations support use of your email address as your username, though it is a good idea to check with your system administrator if you receive authentication-related failures.

Configuring HTML Sanitization Options

edit

The email action supports sending messages with an HTML body. However, for security reasons, Watcher sanitizes the HTML.

You can control which HTML features are allowed or disallowed by configuring the watcher.actions.email.html.sanitization.allow and watcher.actions.email.html.sanitization.disallow settings in elasticsearch.yml. You can specify individual HTML elements and the feature groups described in the following table. By default, Watcher allows the following features: body, head, _tables, _links, _blocks, _formatting and img:embedded.

Name Description

_tables

All table related elements: <table>, <th>, <tr> and <td>.

_blocks

The following block elements: <p>, <div>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <ul>, <ol>, <li> and <blockquote>.

_formatting

The following inline formatting elements: <b>, <i>, <s>, <u>, <o>, <sup>, <sub>, <ins>, <del>, <strong>, <strike>, <tt>, <code>, <big>, <small>, <br>, <span> and <em>.

_links

The <a> element with an href attribute that points to a URL using the following protocols: http, https and mailto.

_styles

The style attribute on all elements. Note that CSS attributes are also sanitized to prevent XSS attacks.

img or img:all

All images (external and embedded).

img:embedded

Only embedded images. Embedded images can only use the cid: URL protocol in their src attribute.

For example, the following settings allow the HTML to contain tables and block elements, but disallow <h4>, <h5> and <h6> tags.

watcher.actions.email.html.sanitization:
    allow: _tables, _blocks
    disallow: h4, h5, h6

To disable sanitization entirely, add the following setting to elasticsearch.yml:

watcher.actions.email.html.sanitization.enabled: false