Overview
Email polling relies on accessing a dedicated email inbox using either IMAP or MSGraphAPI protocol. Cydarm's email poller service polls the inbox to look for unread emails. Any unread emails are downloaded and converted into Cydarm cases, then marked as read on the server.
A user with integration manager or administrator role permissions can configure the email poller from the Settings page on the Cydarm UI.
Prior to Cydarm version 0.8.37, the email poller was configured using YAML files on your server. If you have pre-existing email pollers configured, these will continue to work along side new ones. However only the new style of email pollers can be inspected via the Cydarm UI. Our recommendation is that you deactivate your older email pollers once you confirm that the new email pollers are working as expected.
If you self-host, information on the legacy email poller configuration can be found here. For hosted customers, please log a support ticket.
Configuration
- Navigate to the
Settings > Connectorspage. Connectors is located on the left hand panel of the Settings page. - Click the button to Create New Connector.
- Actuator and Connector Type: Select email poller for both fields.
- Name and Description: Enter a meaningful name and description for your email poller. On the next page of the form you will enter the specifics to connect to your IMAP or MSGraphAPI mailbox.
IMAP instructions
For your IMAP mailbox, you need the following fields:
|
Type |
IMAP |
| Server Hostname | e.g. imap.server.com:993 |
| Username | Often this is your email address e.g. sample@sample.com |
| Password | Email account password |
| Mailbox | Mailbox folder to monitor e.g. Inbox |
| Skip TLS hostname verification | Leave unchecked except in special circumstances such as the IMAP server uses a self-signed certificate |
MSGraphAPI instructions
To complete the configuration of a connector that will poll an email account via MSGraphAPI, you will need the following fields:
|
Type |
MSGraphAPI |
|
Server Hostname |
AzureTenantID (UUID) |
|
Username |
EntityID: This should be the UUID that serves as the Application ID of the Service Principal for the Enterprise Application that authenticates with the MSGraphAPI. |
|
Password |
Client Secret: In Entra ID, locate the Service Principal under App Registrations and generate a new Client Secret. This is the password you will paste into the field. |
|
Mailbox |
This should be in the format |
|
Skip TLS hostname verification |
Leave unchecked except in special circumstances |
Set the case defaults
In the lower part of the form, set the values that will apply by default to all cases created by this email poller:
Organization name- Severity
- Tags (optional - one or more tags to apply to every created case)
- ACL (if in doubt, use "<Organization name> case defaults")
Tags can be used to automate functions. For example, if you have a mailbox which receives vulnerability advisories for review, you could tag all cases created with a tag for vulnerabilities. You could then automatically add a vulnerability advisory review playbook via automated playbook addition.
Finally, there is a checkbox to activate the connector. If checked, then the connector will automatically be activated when you submit the form. You can activate and deactivate the connector later from the table view on the Settings > Connectors page.
Check status and test email poller
The Connectors page will list all available connectors including your new email poller. The status icon at the left will show a tick mark when it is successfully connected. Or a warning symbol if there is an error. The hover text on the warning symbol will describe the connection error to assist you with troubleshooting.
To test your email poller, send an email to the specified mailbox using these instructions.
For more detailed technical information please refer to our Cydarm API documentation.