# Google Pub/Sub Destination

## Overview

Destinations are integrations that receive alerts from rules, policies, system health notifications, and rule errors. Panther supports configuring a [Google Pub/Sub](https://cloud.google.com/pubsub?hl=en) topic as the destination where you will receive alerts.

## How to set up Google Pub/Sub alert destinations in Panther

### **Step 1: Create** required Google Cloud Platform (GCP) infrastructure

To enable Panther to publish alerts as messages to a Pub/Sub topic, you'll need a topic (either new or existing) and a credentials file. Panther supports authenticating to GCP using either Google Cloud [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) or a [service account](https://cloud.google.com/iam/docs/service-account-overview).

{% tabs %}
{% tab title="Service account authentication" %}

1. If you do not already have one, [create a Pub/Sub topic](https://cloud.google.com/pubsub/docs/create-topic#creating_a_topic) for the notifications.
   * You can create a topic using the `gcloud` CLI tool with the following command format: `gcloud pubsub topics create $TOPIC_ID`
2. [Enable the IAM API](https://console.cloud.google.com/apis/library/iam.googleapis.com).
3. [Create a new Google Cloud service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts). To create the account using the `gcloud` CLI tool, use the following command format:

   ```
   gcloud iam service-accounts create SA-NAME \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   ```

   * Make sure to take note of the account email address, as Panther will use this to access the infrastructure created for this GCS integration.
4. Assign the required IAM roles to the account.
   * The following permissions are required for the project where the Pub/Sub subscription and topic lives:

     <table data-header-hidden><thead><tr><th width="327.374982940047" align="center">Permission required</th><th width="294.15662026309724" align="center">Role</th><th width="208" align="center">Condition</th></tr></thead><tbody><tr><td align="center"><code>pubsub.topics.publish</code></td><td align="center"><code>roles/pubsub.publisher</code></td><td align="center"><em>topic-name</em></td></tr></tbody></table>

     * **Note:** You can set conditions or IAM policies on permissions for specific resources. This can be done either in the IAM page of the service account (as seen in the example screenshot below) or in the specific resource's page.\
       ![There are two section titles, "Service account details" and "Grant this service account access to project"](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-75737a631f3bba75435c67c5dd2e964e25223b7e%2FScreenshot%202025-03-11%20at%2010.11.44.png?alt=media)
     * **Note:** You can create the permissions using the `gcloud` CLI tool:
       * `gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" --role="roles/pubsub.publisher"`
5. [Generate a JSON key file](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for the service account, which will be used in Panther to authenticate to the GCP infrastructure.
   * To create a JSON key file using the gcloud CLI tool, run the following command format:\
     `gcloud iam service-accounts keys create $KEYFILE_PATH --iam-account=$SERVICE_ACCOUNT_EMAIL`
   * Alternative: You can run the above command in GCP's terminal instead of locally:
     1. Click the 3 dots icon menu in the top right, then click **Download**.
        * ![A dropdown menu is shown below a three-dots icon.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-6940cc677e233faedec16959c99926def5e052be%2Fimage.png?alt=media)
     2. Click the folder icon for Browse.
     3. Navigate to the key file and select it, then click **Download**.
        {% endtab %}

{% tab title="Workload Identity Federation authentication" %}

1. If you do not already have one, [create a Pub/Sub topic](https://cloud.google.com/pubsub/docs/admin#creating\\\\\\_a\\\\\\_topic) for the notifications.
   * You can create a topic using the `gcloud` CLI tool with the following command format: `gcloud pubsub topics create $TOPIC_ID`
2. [Enable the IAM API](https://console.cloud.google.com/apis/library/iam.googleapis.com).
3. [Configure Workload Identity Federation with AWS](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds):
   1. As you are [defining an attribute mapping(s) and condition](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#mappings-and-conditions), take note of the following examples:
      * Example [attribute mappings](https://cloud.google.com/iam/docs/workload-identity-federation#mapping):

<table><thead><tr><th width="250.04296875">Google</th><th width="437.63671875">AWS</th><th data-hidden></th></tr></thead><tbody><tr><td>google.subject</td><td>assertion.arn.extract('arn:aws:sts::{account_id}:')+":"+assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')</td><td></td></tr><tr><td>attribute.account</td><td>assertion.account</td><td></td></tr></tbody></table>

* Example [attribute condition](https://cloud.google.com/iam/docs/workload-identity-federation#conditions): `attribute.account=="<PANTHER_AWS_ACCOUNT_ID>"`

{% hint style="warning" %}
The value of the `google.subject` attribute [cannot exceed 127 characters](https://cloud.google.com/iam/docs/workload-identity-federation#mapping). You may use [Common Expression Language (CEL) expressions](https://cloud.google.com/iam/docs/workload-identity-federation#mapping) to transform or combine attributes from the token issued by AWS. The expression suggested above takes this into account and is an attempt at "distilling" the arn to a value that uniquely identifies Panther entities. For more information regarding the AWS attributes check "Example 2 - Called by user created with AssumeRole" from [this page](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html).
{% endhint %}

4. When you are [adding a provider to your identity pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#aws), select **AWS**.
5. Assign the required IAM roles to the account.

* The following permissions are required for the project where the Pub/Sub subscription and topic lives:

  <table data-header-hidden><thead><tr><th width="327.374982940047" align="center">Permission required</th><th width="294.15662026309724" align="center">Role</th><th width="208" align="center">Condition</th></tr></thead><tbody><tr><td align="center"><strong>Permissions required</strong></td><td align="center"><strong>Role</strong></td><td align="center"><strong>Scope</strong></td></tr><tr><td align="center"><code>pubsub.topics.publish</code></td><td align="center"><code>roles/pubsub.publisher</code></td><td align="center"><em>topic-name</em></td></tr></tbody></table>

  * **Note:** You can set conditions or IAM policies on permissions for specific resources. This can be done either in the IAM section in GCP (as seen in the example screenshot below) or in the specific resource's page.\
    ![In the Google Cloud console, an "IAM" navigation item is circled. In a slide-out panel, sections titled, "Add principals" and "Assign roles" are circled.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-d1fe568850252c3c65d8bea3c929d20422aedc2f%2FScreenshot%202025-03-11%20at%2010.33.30.png?alt=media)
  * **Note:** You can create the permissions using the `gcloud` CLI tool, where the `$PRINCIPAL_ID` may be something like:\
    `principalSet://iam.googleapis.com/projects/<THE_ACTUAL_GOOGLE_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<THE_ACTUAL_POOL_ID>/attribute.account/<THE_ACTUAL_PANTHER_AWS_ACCOUNT_ID>`
    * `gcloud projects add-iam-policy-binding $PROJECT_ID --member="$PRINCIPAL_ID" --role="roles/pubsub.publisher"`

6. [Download the credential configuration file](https://cloud.google.com/iam/docs/workload-download-cred-and-grant-access), which will be used in Panther to authenticate to the GCP infrastructure.

* To generate a credential configuration file using the gcloud CLI tool, use the following command format:\
  `gcloud iam workload-identity-pools create-cred-config projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID --aws --output-file=config.json`
  {% endtab %}
  {% endtabs %}

### Step 2: Configure the Google Pub/Sub alert destination in Panther

1. In the Panther Console, navigate to **Configure** > **Alert Destinations.**
2. Click **+ Add your first Destination**.
   * If you have already created Destinations, click **Create New** in the upper right side of the page to add a new Destination.
3. Click **Google Pub/Sub**.
4. Fill in the form to configure the Google Pub/Sub destination:
   * **Display Name**: Enter a descriptive name.
   * **Project ID**: Enter the ID of your project.
   * **File Upload**: Add the key file or credential configuration file you generated in [Step 1](#step-1-create-required-google-cloud-platform-gcp-infrastructure).
   * **Topic ID**: Enter the ID of your topic.
   * **Severity**: Select the severity level of alerts to send to this Destination.
   * **Alert Types**: Select the alert types to send to this Destination.
   * **Log Types**: By default, we will send alerts from all log types. Specify log types here if you want to only send alerts from specific log types.
   * **Allow Manual Dispatch**: Set this toggle ON if you'd like to be able to [manually dispatch alerts](https://docs.panther.com/alerts#manual-alert-dispatch) to this destination.

     <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-3fd7d0d99ee7612ad4d791c7b5de3ff2c6c8bf92%2FScreenshot%202025-03-24%20at%2011.26.54.png?alt=media" alt="Under a &#x22;Configure your GCP Pub/Sub Destination&#x22; header is a form with various fields, like Display Name, Project ID, and Topic ID. At the bottom is an &#x22;Add Destination&#x22; button." width="375"><figcaption></figcaption></figure>
5. Click **Add Destination**.
6. Click **Finish Setup** to complete your setup, or click **Send Test Alert** to test your setup.

## Additional Information on Destinations

For more information on alert routing order, modifying or deleting destinations, and workflow automation, please see the Panther docs: [Destinations](https://docs.panther.com/destinations).