DefectDojo DefectDojo | docs

メッセージングコネクタ (Pro)

利用可否: メッセージングコネクタはベータ機能です。Feature FlagsページでMessaging Connectorsを有効にしてください。アラートはルールによってルーティングされるため、Rules Engine 2.0も併せて有効にする必要があります。

メッセージングコネクタは、DefectDojoからチャットサービス、メールアドレス、またはAmazon SNSトピックへアラートを送信します。同じDownstream Connectorsページ上で、チケッティングコネクタやインシデント管理コネクタと並んで配置されており、設定方法も同様です。まず接続を一度作成し、その後何を送信するかを決めます。

チケッティングコネクタとメッセージングコネクタは、それぞれ異なる問いに答えます。チケッティングコネクタは1件の検出事項を時系列で追跡するチケットを作成・更新します。メッセージングコネクタは、新しい高・重大の検出事項を取り込んだインポートなど、今起きた出来事についてメッセージを投稿します。メッセージには遷移すべきステータスも、同期を保つべきチケットもないため、両者は別々に設定され、互いに影響しません。

送信できる内容

アラートはRules Engine 2.0によってルーティングされます。ルールは、いつ送信するか(トリガー)、どの検出事項が該当するか(条件)、そしてどこへメッセージを送るか(接続とチャンネルを指定する通知ノード)を決定します。

つまり、アラートで使えるフィルタは、ルールで使えるものと同じです。深刻度、スコープ、タグ、ステータス、その他ルール条件で表現できるあらゆる項目です。複数の異なるチャンネルへ送られる複数の異なるアラートは、単に複数のルールにすぎません。

4つのベンダー

VendorWhat you provideHow many destinations per connection
SlackSlackアプリのボットトークン複数。各送信先でチャンネルIDを指定します。
Microsoft TeamsPower AutomateのワークフローURL1つ。URLがチャンネルを決定します。
Email不要です。インスタンスのメールサーバーが使用されます。複数。各送信先で受信者を指定します。
Amazon SNS発行権限を持つAWSアクセスキー複数。各送信先でトピックARNを指定します。

いずれも設定方法は同じです。Connect > Downstreamの下で接続を追加し、その接続を指定するアラートを作成します。

Slack接続を設定する

ボットトークンを持つSlackアプリが必要です。すでにDefectDojo用のアプリがワークスペースにある場合は、それを再利用できます。

1. Slackアプリを作成する

  1. https://api.slack.com/appsにアクセスし、Create New Appを選択してからFrom scratchを選択します。
  2. アプリに名前を付け(例: DefectDojo)、投稿先のワークスペースを選びます。
  3. OAuth & Permissionsを開き、次のBot Token Scopesを追加します。
    • chat:write(必須): アプリがメッセージを投稿できるようにします。
    • chat:write.public(任意): 招待されなくても任意の公開チャンネルに投稿できるようにします。このスコープがない場合、使用したい各チャンネルにボットを招待する必要があります。
  4. Install to Workspaceを選択し、アプリを承認します。
  5. Bot User OAuth Tokenをコピーします。xoxb-で始まります。

2. DefectDojoで接続を追加する

  1. Connect > Downstreamに移動します。
  2. MessagingセクションでSlackのタイルを見つけ、Add Configurationを選択します。
  3. 以下を入力します。
    • Location: SlackワークスペースのURL(例: https://your-workspace.slack.com)。これは表示とリンクにのみ使用されます。
    • Identifier: この接続を他と区別するラベル(例: Security workspace)。
    • Bot Token: コピーしたxoxb-トークン。
  4. 保存します。DefectDojoはすぐにSlackに対してトークンを検証するため、誤ったトークンや失効したトークンは、アラートが最初に発火するときではなく、ここで報告されます。

必要な数だけSlack接続を追加できます。複数のワークスペースに送信するには、それぞれ別の接続を作成します。

3. チャンネルIDを確認する

Slackの送信先には、チャンネル名ではなくチャンネルIDを指定します。

  1. Slackでチャンネルを開き、上部にあるチャンネル名を選択します。
  2. Aboutタブの一番下までスクロールします。
  3. Channel IDをコピーします。C0123456789のような形式です。

アプリがchat:write.publicスコープを持っていない場合は、チャンネルにアプリを招待する必要もあります。チャンネル内で/invite @your-app-nameと入力してください。

Microsoft Teams接続を設定する

TeamsではPower AutomateのワークフローURLを使用します。従来のOffice 365コネクタは廃止されており、この方式ではアプリ登録もテナント管理者の同意も不要です。チャンネルへの権限を持つ人がフローを作成し、返されたURLを貼り付けるだけです。

1つの接続は1つのチャンネルにのみ投稿します。 ワークフローURLがメッセージの送信先を決定するため、2つ目のチャンネルが必要な場合は、2つ目の送信先ではなく2つ目の接続が必要になります。

1. ワークフローを作成する

  1. Teamsで投稿先のチャンネルを開き、チャンネル名の横にある**…メニューからWorkflows**を選択します。
  2. Post to a channel when a webhook request is receivedテンプレートを選びます。
  3. チームとチャンネルを確認し、Add workflowを選択します。
  4. ワークフローが返すURLをコピーします。Microsoft Power AutomateホストのURLで、長いhttps://アドレスです。

このURLはパスワードとして扱ってください。これを持っている人は誰でもそのチャンネルに投稿できます。

2. DefectDojoで接続を追加する

  1. Connect > Downstreamに移動します。
  2. MessagingセクションでMicrosoft Teamsのタイルを見つけ、Add Configurationを選択します。
  3. 以下を入力します。
    • Location: TeamsまたはMicrosoft 365のURL。これは表示とリンクにのみ使用されます。
    • Instance Label: この接続が送信するチャンネルを示すラベル(例: Security / Alerts)。
    • Workflow URL: コピーしたURL。
  4. 保存します。

DefectDojoは保存時にURLの形式(https://であり、Microsoftのワークフローホスト上にあること)を確認しますが、実際に投稿はしません。ワークフローURLはメッセージを送信する以外に検証する方法がなく、保存時にチャンネルへ予期しないメッセージが届くのは、後で気づくよりも悪い結果です。準備ができたらSend test messageを使用してください。

Teamsの送信先には任意項目が1つあり、それはチャンネルラベルで、配信記録にラベルを付けるだけのものです。送信先はすでにワークフローURLによって決定されています。

Email接続を設定する

Emailには認証情報が不要です。DefectDojoは、このインスタンスがすでに通知に使用しているメールサーバーを通じて送信するため、新たに設定するものはなく、SMTPの設定が誤りうる箇所が二重になることもありません。

  1. Connect > Downstreamに移動します。
  2. MessagingセクションでEmailのタイルを見つけ、Add Configurationを選択します。
  3. 以下を入力します。
    • Location: 表示する送信者ID(例: mailto:defectdojo@example.com)。
    • Instance Label: この接続を他と区別するラベル。
  4. 保存します。

このインスタンスにメールサーバーまたは送信者アドレスが設定されていない場合、保存は失敗します。この接続経由で送信するものが何も外に出ていかないためです。まずSettings > System SettingsでSMTPを設定してください。

受信者は接続ではなくアラート側で設定するため、1つのEmail接続をすべてのアラートに使い回せます。1つのメール送信先には最大50件のアドレスを指定できます。それを超える場合は配布用アドレスを使用してください。

Amazon SNS接続を設定する

SNSは他の3つとは種類が異なります。DefectDojoは1つのメッセージをトピックに発行し、AWSがそれを購読先(メールアドレス、SMS番号、Lambda関数、HTTPSエンドポイント、SQSキューなど)へ配信します。DefectDojoはどれが購読しているかを関知しません。

1. 発行可能なアクセスキーを作成する

  1. AWSコンソールで、DefectDojo用のIAMユーザーまたはロールを作成(または選択)します。
  2. 使用するトピックに対してsns:Publishを許可するポリシーをアタッチします。すべてのトピックを許可するより、トピックARNを明示的に指定する方が望ましいです。
  3. アクセスキーを作成し、両方の値をコピーします。AWSはシークレットアクセスキーを一度しか表示しません。

トピックがKMSキーで暗号化されている場合、同じプリンシパルにそのキーに対するkms:GenerateDataKeyとkms:Decryptも必要です。これがないと、すべての発行が拒否されます。

2. DefectDojoで接続を追加する

  1. Connect > Downstreamに移動します。
  2. MessagingセクションでAmazon SNSのタイルを見つけ、Add Configurationを選択します。
  3. 以下を入力します。
    • Location: 表示とリンクにのみ使用するURL(例: AWSコンソールのURL)。
    • Instance Label: この接続を他と区別するラベル(例: Production AWS account)。
    • Access Key ID: AKIAIOSFODNN7EXAMPLEのようなキーID。
    • Secret Access Key: シークレットの値。
  4. 保存します。

DefectDojoはすぐにAWSに対して認証情報を確認するため、誤ったキーや削除済みのキーは、アラートが最初に発火するときではなく、ここで報告されます。この確認は認証情報が有効であることのみを確認するもので、特定のトピックへの発行が許可されているかどうかは、送信先を設定する際に確認されます。

リージョンを入力する項目はありません。 リージョンはトピックARNの一部であるため、1つの接続で複数のリージョンにあるトピックへ発行できます。また、ARNと矛盾しうる別の設定項目も存在しません。

3. トピックARNを確認する

SNSの送信先には、トピックのARNを指定します。

  1. SNSコンソールでトピックを開きます。
  2. ページ上部のARNをコピーします。arn:aws:sns:us-east-1:123456789012:security-alertsのような形式です。

TeamsのワークフローURLとは異なり、ARNは秘密情報ではありません。ARNはトピックを示すだけであり、発行するには接続上の認証情報が必要です。そのため、1つのSNS接続で多数のトピックに対応できます。

FIFOトピック(.fifoで終わるARN)はサポートされていません。FIFOトピックにはメッセージグループと重複排除IDが必要ですが、これらは順序を保証するための仕組みであり、アラートには提供する手段がありません。標準トピックを使用してください。

テストメッセージを送信する

メッセージング送信先が設定されている場所であればどこでも、Send test messageは実際のアラートと全く同じ経路で短いメッセージを配信し、ベンダーからの応答を報告します。

これは、間違えやすい点を確認するために使用します。Slackの場合はチャンネルIDが正しく、ボットがそこに投稿できるか。Teamsの場合はワークフローURLがまだ機能しているか。Emailの場合はアドレスに配信可能か。SNSの場合はそのキーがそのトピックに発行できるか。ベンダー自身の応答がそのまま伝えられるため、Slackの招待漏れは汎用的な失敗ではなく、ボットを招待するよう伝えるメッセージとして表示されます。

テストが成功すると、自動的に無効化された接続も解除されます(接続が機能しなくなった場合を参照)。

アラートを作成する

作成方法は2通りあります。どちらも最終的にはRules Engine 2.0のルールを生成します。

アラートページ

インポートによる新規検出事項を通知するという一般的なケース向けの、簡単な方法です。

  1. Connect > Downstreamに移動し、メッセージング接続でCreate Alertを選択するか、Messaging Alertsを直接開きます。
  2. New Alertを選択し、以下を入力します。
    • Name: このアラートの用途(例: New highs to the security channel)。
    • Alert: 何についてのアラートか。現時点ではNew findings from an importのみが選択肢です。
    • Send over: 使用するメッセージング接続。
    • Where it delivers: ベンダー固有の送信先フィールド。SlackのチャンネルID、任意のTeamsチャンネルラベル、メールアドレスのリスト、またはSNSトピックARN。
    • Severity: 下限の深刻度。Critical onlyからEvery severityまで選択できます。
    • Mode: Simulateは送信せずに何が送信されるはずだったかを記録し、Liveは実際に送信します。
  3. Create Alertを選択します。

このページには作成したアラートが一覧表示され、トリガー、深刻度の下限、および各アラートを有効・無効にするトグルが表示されます。

誰かのチャンネルに実際に届く前に、アラートが何を捕捉するかを確認したい場合はSimulateから始めてください。ルールは実行され、配信は記録されますが、何も送信されません。

アラートはルールであるため、同じ一覧からルールエディタで開くこともできます。2つ目の分岐や2つ目のメッセージなど、フォームでは表現できない内容にルールが編集された場合、一覧はフォームではなくルールエディタを提供します。追加した作業がフォームによって黙って失われることはありません。

ルールエディタ

フォームでカバーされないあらゆる内容に対応する、完全な方法です。

  1. Automation > Rules Engine 2.0に移動し、ルールを作成します。
  2. トリガーを追加します。新規インポートされた検出事項に関するアラートには、Findingイベントトリガーのcreatedを使用します。インポートはバッチ処理されるため、1回のインポートは検出事項ごとではなく1件のアラートを生成します。
  3. 該当条件(例: 高以上の深刻度)を追加します。
  4. 使用したいベンダーのメッセージノード(Send a Slack Message、Send a Microsoft Teams Message、Send an Email、またはPublish to an SNS Topic)を追加し、以下を設定します。
    • Connection: 作成したメッセージング接続。
    • Destination: ベンダーの送信先。SlackのチャンネルID、任意のTeamsチャンネルラベル、Emailの受信者、またはSNSのトピックARN。
  5. ルールを保存し、有効化します。

条件に一致する検出事項がない場合は何も送信されません。そのため、高以上に絞り込んだルールは、低のみの検出事項を取り込んだインポートでは沈黙したままです。

Messaging Connectors以前に作成されたルール

メッセージノードは接続を経由してのみ送信します。以前は、接続が選択されていない場合、Slack・Teams・Emailの各ノードはSettings > Notificationsにあるインスタンス全体の設定にフォールバックしていましたが、現在はそうしません。

そのように書かれたルールは動作し続けますが、メッセージノードは「接続が指定されていない」というスキップされた配信を記録します。修正するには、ルールを開き、ノード上で接続と送信先を選択して保存してください。すでに記録された配信は、ノードが接続を指定していれば配信一覧から再実行できます。

接続はすべてのメッセージノードで必須項目であるため、ルールエディタはルールを保存する前に接続の指定を求めます。

接続が機能しなくなった場合

失効したボットトークン、削除されたワークフロー、削除されたAWSアクセスキーは、それを使用するすべてのアラートを失敗させます。DefectDojoはすべてのイベントで同じ失敗を記録する代わりに、送信先ごとに連続した認証情報エラーをカウントし、一定回数に達すると送信を停止します。接続は、どの送信先が無効化されたか、その理由とともに報告します。

復旧するには、まず認証情報を修正します(Slackアプリを再インストールして新しいトークンを貼り付ける、Teamsのワークフローを再作成して新しいURLを貼り付ける、または新しいAWSアクセスキーを作成する)。その後、その送信先にテストメッセージを送信すると成功時に再有効化されるか、再有効化アクションを直接使用します。

これを引き起こすのは認証情報の失敗のみです。SlackのチャンネルIDが誤っている、ボットが招待されていない、メールアドレスが存在しない、またはIAMポリシーが特定のトピックへの発行を許可していないといった理由でメッセージが拒否されても、何も無効化されません。認証情報自体は問題なく、送信先やポリシーを修正すればすぐに機能するはずだからです。

アラートと通知の併用

メッセージングコネクタは通知機能を置き換えるものではありません。Settings > Notificationsにあるインスタンス全体のSlack・Teams・Emailの設定、個人通知、通知マトリクスは、設定どおりにすべて引き続き動作します。これらはDefectDojo自体のイベントを知らせるものであり、メッセージングコネクタは、あなたが作成したルールが送信するものです。

注意点が1つあります。アラートが、インスタンス全体の設定がすでに通知しているのと同じチャンネルやアドレスに投稿する場合、その送信先には両方のメッセージが届きます。特定の送信先に対しては、どちらか一方のみを設定してください。

制限事項

  • メッセージの文言はまだカスタマイズできません。アラートはDefectDojo組み込みの文言を使用します。
  • メッセージは一方向です。DefectDojoは返信を読み取らず、メッセージ内にボタンやインタラクティブな要素はありません。
  • スレッド、メッセージの編集、個々のユーザーへのダイレクトメッセージはサポートされていません。個人通知は引き続き既存の通知システムを使用します。
  • 1つのTeams接続は1つのチャンネルにのみ送信します。チャンネルを指定するのはワークフローURLだからです。
  • SNSメッセージはプレーンテキストです。1つのトピックは同時にEmail、SMS、Lambda、HTTPSの購読者に配信できるため、すべてに適した単一の形式は存在せず、プロトコルごとの個別バリアントも発行されません。
  • SNS FIFOトピックはサポートされていません。
  • レポートなどの添付ファイルはまだ送信できません。アラートはDefectDojoへのリンクを含むメッセージです。
  • アラートページはインポートによる新規検出事項をカバーします。それ以外はルールエディタで構築します。