# 通知ターゲット

Shisho Cloud 上でポリシー違反が検出された際には、[Shisho Cloud 上のダッシュボード](/docs/ja/g/concepts/dashboard.md) 上での閲覧はもちろんのこと、外部サービスへの通知も可能です。

## Shisho Cloud から各種サービスへの通知

前提として、すべての通知はワークフローにより制御されています。

![](/docs/ja/_md-assets/005ec9db77-how-workflows-work.ja.png)

具体的に通知を制御するのは、ワークフローのジョブが含む **`notify` ブロック**です。

例えば以下のマニフェストで定義されるワークフローは、ID が `NGFOO` である[通知グループ](/docs/ja/g/concepts/notification-group.md)に対して通知を送出します:

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

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

## 通知ターゲット

ここで、Shisho Cloud から通知を送ることができる対象は、**通知ターゲット（Notification Target）** と呼ばれています。

### 現在サポートされている通知ターゲット

現在、Shisho Cloud では、以下を通知ターゲットとして指定できます:

- Slack チャンネル
- GitHub Issue / GitHub Pull Request のコメント
- メールアドレス

:::caution
通知ターゲットを指定する際に、個別で設定が必要になる場合があります。詳しくは次のセクションをご確認ください。
:::

## 通知ターゲットの追加設定を行う

通知ターゲットの種類によっては、実際に通知を受け取るために、追加で設定が必要になる場合があります。

### Slack 通知の設定をする

Slack チャンネルで通知を受け取るには、[Slack ワークスペースの連携手順](/docs/ja/g/getting-started/integrate-apps/slack.md) に加えて、以下の操作が必要です:

- Slack ワークスペース側にて、**Shisho Cloud** の Slack App を通知を受け取りたい Slack チャンネルに追加する

:::info
この設定は **Slack 側** にて行う必要があります。
:::

まずは Slack での通知を希望するチャンネルを右クリックし、"View Channel Details" を選択してください。

![](/docs/ja/_md-assets/fc0ed1590c-notification-slack-1.png)

すると下記の画面へ遷移します。
そこで、Integrations タブを選択し "Add an App" をクリックしてください。

![](/docs/ja/_md-assets/07b2c9b9d0-notification-slack-2.png)

すると Slack App 一覧が表示されます。
"Add" をクリックし**Shisho Cloud** なる Slack App を Slack チャンネルに招待してください。

![](/docs/ja/_md-assets/171bed6772-notification-slack-3.png)

:::warning
**Shisho Cloud** という名称の Slack App が表示されない場合、該当の Slack ワークスペースと Shisho Cloud との連携が完了していない可能性があります。
[Slack ワークスペースの連携手順](/docs/ja/g/getting-started/integrate-apps/slack.md) に設定してください。
:::

:::warning
Shisho Cloud と Slack ワークスペースの連携時に、Slack 側該当のメニューが見つからない場合は、Slack 側の UI 変更の可能性や、Slack ワークスペースのオーナー（管理者）が当該メニューへのアクセスを制限している可能性などが考えられます。
このような問題で、Shisho Cloud と Slack ワークスペースが連携できない場合は、サービス運営元（Flatt Security）にお問い合わせください。
:::

#### Slack チャンネルへテストメッセージを送信する

実際にワークフローで通知機能を利用する前に、必要な設定が完了しているか確認したい場合は、下記のテストメッセージの送信（Send test message）機能を利用して該当の Slack チャンネルにメッセージを送信してみてください:

![](/docs/ja/_md-assets/4cb1d01404-notification-test-message-1-ja.png)

設定が正常に完了している場合、下記のようなテストメッセージが確認できるはずです:

![](/docs/ja/_md-assets/fce3a13187-notification-test-message-on-slack.png)

もし確認できない場合は、[Slack ワークスペースの連携手順](/docs/ja/g/getting-started/integrate-apps/slack.md) と、Slack App の通知先 Slack チャンネルへの招待が完了していない可能性があります。
両方とも完了しているのに、それでもテストメッセージが受信できない場合は、サービス運営元（Flatt Security）にお問い合わせください。

### Email 通知の設定をする

Shisho Cloud では、**組織に所属しているユーザーと紐付いていないメールアドレス**への通知を原則禁止しています。そのため、[通知グループ](/docs/ja/g/concepts/notification-group.md)や[ポリシー](/docs/ja/g/concepts/notification.md)に**前述のようなメールアドレスを指定しただけでは通知が送出されません**。そのようなメールアドレスを通知ターゲットとして設定する場合、合わせて「**メール送信許可リスト**」にも登録する必要があります。

:::info
組織に所属しているユーザに紐付いているメールアドレス（Shisho Cloud に登録する際に用いたメールアドレス）への通知は暗黙的に許可されています。そのため、明示的にメール送信許可リストへ登録する必要はありません。
:::

メール送信許可リストは「歯車マーク :gear: > メール送信許可リスト」から操作が可能です。

![メール送信許可リストの管理画面](/docs/ja/_md-assets/f7316a475c-notification-email-allowlist-empty-ja.png)

ここではメール送信許可リストにメールアドレスを追加する方法を説明します。新たにメールアドレスを登録する場合、メールアドレスの有効性を確認するため Shisho Cloud から確認メールが送信されます。リストへメールアドレスを追加する際は受信したメールを確認できる、もしくは受信したメールを確認できる方へ連絡が取れる状態であることを確認してから操作を進めてください。

#### 1. メールアドレスを追加する

右上の「メールアドレスの追加」を押下するとモーダルが表示されます。そこに通知先として許可したいメールアドレスを入力し、モーダル右下の「追加」を押下してください。

![](/docs/ja/_md-assets/331d3e1336-notification-email-allowlist-add-modal-ja.png)

追加が成功すればリストに表示されます。しかし、**リストに追加されただけでは通知先として許可されません**。追加したメールアドレス宛てに Shisho Cloud からメールアドレスが有効であるかを確認するためのメールが送信されます。そのメールには確認リンクが含まれていますので、そのリンク先へアクセスしてメールアドレスの有効性を証明してください。メールアドレスへの疎通を確認するだけのため、Shisho Cloud へログインせず有効性を証明できます。

![](/docs/ja/_md-assets/44d7012ba3-notification-email-allowlist-unconfirmed-ja.png)

また、Shisho Cloud から送信される確認メールの有効期限は送信されてから**24 時間**です。確認メールの有効期限を過ぎてもメールアドレスの有効性が確認されていない場合はこのようにマークが赤くなり、表示されるメッセージも変わります。

![](/docs/ja/_md-assets/6f257b70e8-notification-email-allowlist-expired-ja.png)

このように有効期限が切れてしまった場合など、何らかの理由によって確認メールを再送信する必要がある場合は右端のメニューから「確認メールの再送信」を選択してください。確認メールの有効期限が切れていない状態でも再送信が可能ですが、その場合**つねに最新の確認メールに記載されているリンクのみが有効です**。過去の確認メールにあるリンクを使用しても無効なリンクとエラーが出ますのでご注意ください。

![](/docs/ja/_md-assets/a94354468a-notification-email-allowlist-resend-ja.png)

以下のように「状態」欄に何も表示がなくなれば、通知ターゲットとして許可されたメールアドレスであることを意味します。

![](/docs/ja/_md-assets/fe498f1999-notification-email-allowlist-accepted-ja.png)

:::info
情報流出の可能性を減らすため、利用しなくなったメールアドレスは都度メール送信許可リストから削除することを推奨します。削除したいメールアドレスの右端にあるメニューから「削除」を選択することで削除が可能です。削除の際は新規登録のようにメールアドレスの方へ確認メール等は送信されません。複数のメールアドレスを一度に削除する場合、削除したいメールアドレスの左端にあるチェックボックにチェックを入れてください。チェックを入れると削除ボタンが表示されます。
:::

:::note
もしメール送信許可リストの設定が完了してもメール通知が届かないようであれば、迷惑メールに振り分けられていないかをご確認の上、サービス運営元（Flatt Security）へお問い合わせください。
:::

## （発展）ポリシーからの使い方

サポートされている通知ターゲットへ通知を送るために必要なステップは、Shisho Cloud とポリシーコード間の API (例: [インライン Rego ポリシー向けの API](/docs/ja/g/api/rego.md)) に従って、[Notification](/docs/ja/g/api/objects/notification.md) オブジェクトをポリシーコードから Shisho Cloud に対して受け渡すことだけです。

:::info

この操作は、[Rego SDK 中の shisho.notification 以下](https://github.com/flatt-security/shisho-cloud-rego-libraries/blob/main/notification/notification.rego) の関数を用いて簡単に行なうことができます。

以下に実際のコード例を示します:

```rego
import data.shisho

# 指定した GitHub Issue のコメントとして、文字列 "test" を送信する
import data.shisho

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

:::

:::info
通知機能がうまく動作しない場合は、[よくある質問の『ワークフローに関して』](/docs/ja/g/faq/notifications/workflows.md)をご確認ください。
:::