Skip to main content

Notification Targets

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

When a policy violation is detected on Shisho Cloud, it can be viewed not only on the Shisho Cloud dashboard, but notifications can also be sent to external services.

Notifications from Shisho Cloud to Various Services

By default, all notifications are managed through workflows.

Notifications are specifically controlled by the notify block within the jobs of the workflow.

For instance, the workflow defined in the following manifest will send notifications to the notification group marked with the ID NGFOO:

jobs:
- name: check-with-foobar
id: check-with-foobar
decide:
# ...
notify:
rego: |
import data.shisho

notifications[n] {
n := shisho.notification.to_group(
"NGFOO",
"test"
)
}

Notification Targets

The entities capable of receiving notifications from Shisho Cloud are referred to as Notification Targets.

Currently Supported Notification Targets

At present, Shisho Cloud supports the following entities as Notification Targets:

  • Slack channels
  • Comments on GitHub Issues / Pull Requests
  • Email addresses
caution

When specifying Notification Targets, some individual settings may need to be adjusted. Please refer to the next section for detailed information.

Enabling Additional Settings for Notification Targets

Depending on the type of Notification Target, additional configurations may be necessary to receive actual notifications.

Setting up Slack Notifications

To receive notifications on a Slack channel, in addition to the steps outlined in Slack workspace integration process, you need to add the Shisho Cloud Slack App to the desired Slack channel on the Slack workspace side.

info

This configuration task has to be performed on Slack's side.

Begin by right-clicking on the Slack channel where you wish to receive notifications, and choose "View Channel Details".

This will redirect you to a new page. Here, select the Integrations tab and click on "Add an App".

From the list of Slack Apps that appears, click on "Add" and invite the Shisho Cloud Slack App to your Slack channel.

danger

If the Shisho Cloud Slack App does not appear in the list, it could suggest that the Shisho Cloud's integration with your Slack workspace is incomplete. Please follow the instructions in the Slack workspace integration process for proper set up.

Sending a Test Message to a Slack Channel

Before using the notification feature in an actual workflow, you can verify if the settings are correctly implemented by utilizing the "Send test message" feature to send a test message to the relevant Slack channel:

If everything is set up correctly, you should be able to see the test message as shown below:

If you can't find the test message, it could mean that the Slack workspace integration process wasn't done correctly or the Shisho Cloud Slack App has not been added to the intended Slack channel. If you still cannot receive the test message even after confirming both these steps, please consider contacting Flatt Security for further assistance.

Setting Up Email Notifications

Shisho Cloud generally prevents notifications to email addresses not linked to users in an organization. Therefore, merely including such email addresses in a notification group or policy will not send out notifications. If you wish to use such an email address as a Notification Target, it must also be added to the "Mail Sending Permission List".

info

Notifications to email addresses associated with users in an organization (the addresses used when registering with Shisho Cloud) are implicitly allowed, hence, they don't need to be explicitly added to the Mail Sending Permission List.

The Mail Sending Permission List can be managed from "Gear Icon ⚙️ > Mail Sending Permission List".

Mail Sending Permission List Management Screen

This section explains how to add email addresses to the Mail Sending Permission List. When you register a new email address, Shisho Cloud sends a confirmation email to verify the validity of the address. Ensure that you can access the received email or contact someone who can, before proceeding with this process.

1. Adding an Email Address

Clicking on "Add Email Address" on the top right will open a modal window. Enter the email address that you want to permit for notifications and click "Add" at the bottom right of the modal window.

If the addition was successful, the address will appear on the list. However, an address is not authorized for notifications just by being added to the list. Shisho Cloud sends a confirmation email to verify the validity of the added address. Please follow the link in this email to validate your email address. You can complete the validation process without logging into Shisho Cloud, as it only checks the accessibility of the provided email address.

The validity of the confirmation email sent by Shisho Cloud lasts 24 hours from when it's sent. If the confirmation hasn't been made once the email's validity expires, the status marker will turn red and the message displayed will change.

If the confirmation email has expired or a resend is required for some other reason, you can select "Resend Confirmation Email" from the menu on the far right. Resend is possible even before expiry, however, only the link in the most recent confirmation email remains valid under such circumstances. Using an expired link will prompt an error message, so be careful not to use outdated links.

Once the "Status" field is blank, it indicates that the email address has been authorized as a Notification Target.

info

In order to minimize chances of data leaks, it's recommended to remove from the Mail Sending Permission List any email addresses that are no longer in use. You can remove an address by selecting "Delete" from the menu on the far right of the address you want to remove. Deletion of an address does not involve sending any kind of confirmation email back to the email address. If you want to remove multiple email addresses at once, tick the check box on the left side of the addresses you want to remove to display the delete button.

note

If you've completed the Mail Sending Permission List setup, but still not receiving email notifications, please first check that the emails haven't been sorted into your spam folder. If that's not the case, please reach out to Flatt Security for further assistance.

(Advanced) Using from a Policy

The only requirement to send notifications to the supported Notification Targets is to pass the Notification object from the policy code to Shisho Cloud, in accordance with the API between Shisho Cloud and the policy code (e.g., API for Inline Rego Policies).

info

For this task, you can utilize the functions under the shisho.notification in our Rego SDK.

For example, actual code can look like this:

import data.shisho

# Send the string "test" as a comment to a specified GitHub Issue
import data.shisho

notifications[n] {
n := shisho.notification.to_github_issue(
"org-name",
"repository-name",
123456, # issue ID
"test", # message
)
}
info

If you're having trouble with the notification feature, please refer to our Frequently Asked Questions about "Workflows".