# EventBridge

## Overview

[Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) is a serverless event bus that lets you receive, filter, transform, route, and deliver events. Within your environment, you may already be using EventBridge, as it supports receiving data from AWS services, custom applications, SaaS applications, and microservices.

### Supported targets

EventBridge supports many [targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html) Panther may plug into, including SNS topics, SQS queues, Firehose delivery streams, S3 buckets, and more. This enables many possible workflows. For example:

* Okta -> EventBridge -> AWS SNS Topic -> Panther SQS
  * By default, EventBridge nests the logs within a `detail` object. You will need to use EventBridge transformations to take advantage of Panther's native Okta schema. See [AWS's documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-transform-target-input.html) on how to create transformations.
* Custom Application -> EventBridge -> Firehose delivery stream -> S3 -> Panther
* AWS GuardDuty -> EventBridge -> AWS SNS Topic -> Panther SQS
  * See the example below for instructions on [sending GuardDuty findings to Panther via EventBridge](#end-to-end-example-send-guardduty-findings-to-panther-via-eventbridge).

## How to use EventBridge with Panther

See the steps below for a generally applicable workflow. 

For a specific example using EventBridge to send GuardDuty findings to Panther, see [the section below](#end-to-end-example-send-guardduty-findings-to-panther-via-eventbridge).

### Step 1: Create a Topic in Amazon SNS

1. Log in to your AWS Console and navigate to **Amazon SNS > Topics**. Click **Create Topic**.
   * If you already have an SNS topic created, skip to Step 2.
2. Fill out the Details:
   * **Type**: Select `Standard`.
   * **Name**: `panther-eventbridge-guard-duty`
3. Click **Create topic**.
4. Copy the ARN value and store it in a secure location, as you will need it in the next steps.
   * Example ARN: `arn:aws:sns:region:accountid:topic`

### Step 2: Create the SQS source in Panther

* Follow [Panther's documentation to create an SQS log source](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports/aws/sqs).

### Step 3: Create or modify a rule in EventBridge

#### Creating a rule

1. In AWS, navigate to EventBridge.
2. Navigate to **Events > Rules** then click **Create rule**.
   1. Define rule detail.
      * Provide a name, description, event bus and rule type.
   2. Build event pattern.
      * Choose the source of data and pattern to match against
   3. Select target(s).
      * Choose where to route the data that has been matched
   4. Configure tags (optional).
      * Choose to add a label to this AWS resource
3. On the "Review and Create" page, click **Create rule**.

#### Modifying an existing rule

1. In AWS, navigate to **Events > Rules** then click the rule you want to modify.
2. Click into the **Targets** tab and click **Edit**.
   1. Click **Add another target**.
   2. Use "AWS Service" as the Target type, "SNS topic" as the target, and then select the SNS topic you added the Panther Managed SQS to in the previous steps.
3. Click **Next**, click **Next**, then click **Update rule**.

Now that the data pipeline is complete, you will start seeing log events land in your Panther Console where you can adjust your Schema and create Detections that may trigger Alerts.

## End-to-end example: Send GuardDuty findings to Panther via EventBridge

The steps below are aimed at helping you quickly configure the necessary AWS resources to be used within EventBridge to allow you to perform advanced monitoring on your AWS GuardDuty data. 

Note that Panther has separate [documentation for GuardDuty integration via S3 or SQS](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/supported-logs/aws/guardduty) instead.

<figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FhQI65fKE9bNPnPYSW3tE%2Fimage.png?alt=media&#x26;token=f0e9a337-7da7-4fce-8eec-b0025faadfb1" alt="An Amazon EventBridge diagram "><figcaption></figcaption></figure>

### Data pipeline

The steps below walk through the following data pipeline:

GuardDuty -> EventBridge -> AWS SNS Topic -> Panther SQS

### Step 1: Create a topic in Amazon SNS

1. Log in to your AWS Console and navigate to **Amazon SNS > Topics**. Click **Create Topic**.
   * If you already have an SNS topic created, skip to Step 2.
2. Fill out the Details:
   * **Type**: Select `Standard`.
   * **Name**: `panther-eventbridge-guard-duty`
3. Click **Create topic**.
4. Copy the ARN value and store it in a secure location, as you will need it in the next steps.
   * Example ARN: `arn:aws:sns:region:accountid:topic`

### Step 2: Create the SQS source in Panther

* Follow [Panther's documentation to create an SQS log source](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports/aws/sqs).

### Step 3: Create a rule in EventBridge

These steps demonstrate how you can send GuardDuty findings to Panther through EventBridge. There is also an option to generate sample GuardDuty findings or write a rule to alert when someone assumes a role from TOR.

1. In your AWS console, navigate to GuardDuty to ensure it is enabled.
2. Navigate to EventBridge, then go to **Events > Rules**.
3. Click **Create rule**.
4. Fill in the rule detail section:
   * **Name**: Enter a descriptive name.
   * **Description**: Enter a description (e.g., `Filtering events from GuardDuty and sending them to Panther Managed SQS`)
   * **Event bus**: Set the dropdown menu to `default`*.*
   * **Enable the rule on the selected event bus**: Click the toggle to enable this setting.
   * **Rule type**: Select `Rule with an event pattern`.\
     ![](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2F9ZCxnnTQABomDAbVDHWY%2Fguardduty-rule-detail.png?alt=media\&token=7d81be84-e4d2-48c9-857a-0faf69bd0d7e)
5. Click **Next**.
6. On the "Build the event pattern" page, fill in the following:
   * **Event source**: Select `AWS events or EventBridge partner events`.
   * **Event pattern**:
     * **Event source**: Select `AWS services`.&#x20;
     * **AWS Service**: Select `GuardDuty`.
     * **Event type**: Select `GuardDuty Finding`.\
       ![](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2F1Fa7MjbyWgTGCNS83vni%2Fevent-pattern-guardduty.png?alt=media\&token=72dbb960-474a-4dbd-9ebf-cde22bb22a22)
7. Click **Next**.
8. On the "Select target(s)" page, fill in the form for Target 1:
   * **Target types**: Select `AWS service`.
   * **Select a target**: Select `SNS topic` from the dropdown menu.
   * **Topic**: Enter the topic you created in Step 1 (`panther-eventbridge-guard-duty`).
   * Under "Additional Settings":
     * **Configure target input**: Select `Part of the matched event`.
     * **Specify the part of the matched event**: Select `$.detail`
     * **Retry policy**: Leave the defaults for Retry options.
     * **Dead-letter queue**: Leave the default option.
   * Note that there is an opportunity to add additional targets here or layer Panther in!\
     ![](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FJN0YIuNtnBOrEovF9yCR%2Fguardduty-targets.png?alt=media\&token=855211ad-9219-449f-adc8-7958a5808566)
9. Click **Next**.
10. Optionally configure tags.
11. Click **Next**.
12. On the "Review and Create" page, click **Create rule**.

Now, when GuardDuty outlines a finding, that event will route to Panther where we can write a Detection to Alert us.

### Generate sample findings

Since GuardDuty allows you to generate sample findings, you may use those to test end-to-end.

1. In GuardDuty, navigate to **Settings > Sample Findings**.
2. Click **Generate Sample Findings** to test.

An example rule within Panther might look like the following if I wanted to know when someone accessed AWS via TOR:

```python
from panther_base_helpers import deep_get

def rule(event):
    return deep_get(event, 'detail', 'type') == 'Discovery:S3/TorIPCaller'

def title(event):
    return f"{event.get('detail-type')}: {deep_get(event, 'detail', 'type')} from principal id: {deep_get(event, 'detail', 'resource', 'accessKeyDetails', 'principalId')}"

def alert_context(event):
    return {
        "account": event.get('account'),
        "principalId": deep_get(event, 'detail', 'resource', 'accessKeyDetails', 'principalId'),
        "guardduty-finding-arn": deep_get(event, 'detail', 'arn')
    }
```