> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarion.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS via EventBridge and SNS

> Connect your AWS account to Clarion for CloudTrail events, CloudWatch alarms, GuardDuty findings, and IAM agent tools.

This guide walks you through connecting your AWS account to Clarion. By the end, Clarion will receive CloudTrail events, CloudWatch alarms, and GuardDuty findings — and have IAM permissions to run agent tools (CloudTrail lookup, Route 53, CloudWatch queries).

***

## Prerequisites

* An AWS account with admin or IAM-capable permissions.
* Access to the Clarion dashboard.

***

## Step 0 — Generate a Webhook URL in Clarion

Before configuring AWS subscriptions, open your Clarion workspace and generate a webhook URL.

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/webhook-url.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=fab543e1ccd5f66bd09eac72f30eff31" alt="" width="2030" height="472" data-path="images/aws/webhook-url.png" />

You will use this URL as the HTTPS subscription endpoint for your SNS topics in the steps below.

<Tip>
  Keep this URL handy — you'll need it for CloudTrail, CloudWatch, and GuardDuty setup. Clarion also requires the exact SNS topic ARN for each topic that publishes to the webhook.
</Tip>

<Warning>
  SNS messages are accepted only from topic ARNs saved in Clarion. Existing AWS monitors with no saved SNS topic ARN must be updated before Clarion can confirm subscriptions or receive notifications.
</Warning>

***

## Step 1 — CloudTrail via EventBridge

Send CloudTrail management events (API calls and console sign-ins) to Clarion through an SNS topic and an EventBridge rule.

<Note>
  This path sends the CloudTrail event body through EventBridge and SNS. Clarion does not need S3 bucket access for this delivery mode.
</Note>

### 1.1 Create an SNS topic

1. Open the Amazon SNS console and go to **Topics**.
2. Create a new **Standard** topic (e.g. `clarion-cloudtrail`).
3. Copy the topic ARN, paste it into Clarion's SNS topic ARN field for the CloudTrail monitor, and save the monitor.

<Warning>
  Currently encryption of the topic is not supported, but Amazon SNS provides in-transit encryption by default.
</Warning>

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/sns-create-topic.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=5b33b17ffb01b7893d821b0a5f6145c9" alt="" width="3048" height="1034" data-path="images/aws/sns-create-topic.png" />

### 1.2 Subscribe Clarion to the topic

1. On the topic you just registered in Clarion, click **Create subscription**.
2. Set the protocol to **HTTPS** and paste the webhook URL from Clarion.
3. SNS will send a confirmation request — Clarion auto-confirms it.

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/sns-subscription.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=c81ec8b6dbe65547866c83f45b02bff4" alt="" width="2516" height="768" data-path="images/aws/sns-subscription.png" />

### 1.3 Create an EventBridge rule

1. Open the Amazon EventBridge console and create a new rule.

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/eventbridge-create-rule.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=3c35822f30e22ce2f877dfcea64d4bc9" alt="" width="3080" height="1106" data-path="images/aws/eventbridge-create-rule.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/eventbridge-rule-detail.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=ee7df985eab63e8670d8cfc01c486d15" alt="" width="3080" height="1838" data-path="images/aws/eventbridge-rule-detail.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/eventbridge-rule-target.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=33e2cc61bef93c9705fb598c8e5b0471" alt="" width="3064" height="1898" data-path="images/aws/eventbridge-rule-target.png" />

2. Use the following event pattern to forward all CloudTrail events to Clarion:

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/eventbridge-event-pattern.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=52ae795de2cafb24ebe1deb0441758f9" alt="" width="3032" height="1872" data-path="images/aws/eventbridge-event-pattern.png" />

```json theme={null}
{
  "detail-type": [
    "AWS API Call via CloudTrail",
    "AWS Console Sign In via CloudTrail",
    "AWS Console Signin via CloudTrail",
    "AWS Service Event via CloudTrail"
  ]
}
```

<Tip>
  EventBridge detail-type matching is **case-sensitive**. The pattern above
  includes both known casing variants of the console sign-in detail-type
  (`Sign In` and `Signin`) to ensure events are captured regardless of
  the variant your account emits. Do **not** add a `source` filter — the
  `source` field varies by originating AWS service (e.g. `aws.iam`,
  `aws.ec2`, `aws.signin`) and filtering on it would silently drop events.
</Tip>

These detail-types cover the following CloudTrail event categories:

| Detail type                          | What it captures                         | Examples                                                               |
| ------------------------------------ | ---------------------------------------- | ---------------------------------------------------------------------- |
| `AWS API Call via CloudTrail`        | All management and data API calls        | `DeleteUser`, `PutBucketPolicy`, `RunInstances`                        |
| `AWS Console Sign In via CloudTrail` | Console login and logout events          | `ConsoleLogin` (success, failure, MFA)                                 |
| `AWS Service Event via CloudTrail`   | Non-API events triggered by AWS services | Log file delivery, automated key rotation, service-linked role actions |

Clarion has signal rules that depend on console sign-in events (login failures,
MFA checks, root account logins, multi-IP detection), so including the
console sign-in detail-types is important for full coverage.

A fourth detail-type, `AWS Insight via CloudTrail`, exists for
[CloudTrail Insights](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-insights-events-with-cloudtrail.html)
anomaly detection events. Add it to the pattern if you have Insights enabled
on your trail.

3. Set the target of the rule to the SNS topic you created (`clarion-cloudtrail`).

***

## Step 1B — CloudTrail via Consolidated S3 Logging

An [AWS Organizations trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) writes CloudTrail events from every member account and region into a single S3 bucket — typically a dedicated log-archive account. Clarion subscribes to that bucket's S3 event notifications, fetches each new log file, and creates one signal per CloudTrail record. One SNS topic and one Clarion subscription cover the whole organization.

<Warning>
  For this consolidated S3 path, Clarion must be able to read each CloudTrail log object from S3. See [CloudTrail via existing S3 bucket](/integrations/aws/cloudtrail-s3) for the required IAM setup.
</Warning>

### 1B.1 Place the Clarion IAM role in the log-archive account

Configure the Clarion IAM role from Step 4 **in the account that owns the consolidated CloudTrail bucket** — usually the AWS Organizations log-archive account. The role needs S3 read access to the CloudTrail log objects.

### 1B.2 Create an SNS topic for S3 notifications

1. In the log-archive account, open the SNS console and create a **Standard** topic in the same region as the consolidated log bucket (e.g. `clarion-cloudtrail-s3`).
2. Copy the topic ARN, add it to Clarion's **SNS topic ARN** list on the CloudTrail monitor, and save.

<Warning>
  S3 event notifications deliver only to SNS topics in the same region as the bucket.
</Warning>

### 1B.3 Subscribe Clarion to the topic

1. On the topic, click **Create subscription**.
2. Set the protocol to **HTTPS** and paste the webhook URL from Step 0.
3. Clarion auto-confirms the subscription.

### 1B.4 Configure S3 event notifications on the bucket

1. In the log-archive account, open the consolidated CloudTrail bucket in the S3 console.
2. Go to **Properties → Event notifications → Create event notification**.
3. Restrict the trigger to the CloudTrail prefix (e.g. `AWSLogs/`) and suffix `.json.gz`.
4. Event types: **All object create events** (`s3:ObjectCreated:*`).
5. Destination: **SNS topic**, then select the topic from 1B.2.

### 1B.5 (SSE-KMS only) Allow the Clarion role to use the bucket's KMS key

If the consolidated log bucket uses SSE-KMS, the CMK's key policy must allow the Clarion IAM role from Step 4 to call `kms:Decrypt`. Keys created through the CloudTrail setup wizard delegate to IAM by default, in which case Clarion's role policy is sufficient and no key-policy change is needed. Otherwise, add the following statement to the CMK's key policy, replacing `<your-clarion-role-arn>`:

```json theme={null}
{
  "Sid": "AllowClarionDecrypt",
  "Effect": "Allow",
  "Principal": { "AWS": "<your-clarion-role-arn>" },
  "Action": "kms:Decrypt",
  "Resource": "*"
}
```

***

## Step 2 — CloudWatch Alarms

Send CloudWatch alarm state changes to Clarion by publishing to an SNS topic subscribed to your webhook URL.

1. Create a new SNS **Standard** topic for CloudWatch alarms (e.g. `clarion-cloudwatch`), or reuse a topic you have already registered in Clarion.
2. Copy the topic ARN, paste it into Clarion's SNS topic ARN field for the CloudWatch monitor, and save the monitor.
3. Add an **HTTPS** subscription using the webhook URL from Clarion. Wait for Clarion to auto-confirm.
4. In the CloudWatch console, open the alarm(s) you want Clarion to monitor.
5. Edit the alarm's notification actions and set it to publish to the SNS topic you created.

<Tip>
  You can point multiple alarms at the same SNS topic — no need to create one per alarm.
</Tip>

***

## Step 3 — GuardDuty Findings

Route GuardDuty findings to Clarion through EventBridge and SNS.

### 3.1 Create an event bus

1. Open the Amazon EventBridge console.
2. You can use the **default** event bus, or create a new custom event bus if you want to isolate GuardDuty events (e.g. `clarion-guardduty-bus`).

### 3.2 Create an EventBridge rule for GuardDuty

1. Within the event bus, create a new rule.
2. Set the event source to GuardDuty findings.
3. Make sure you're using the following event pattern:

```json theme={null}
{
  "source": ["aws.guardduty"],
  "detail-type": ["GuardDuty Finding"]
}
```

4. Set the target to the SNS topic you created for Clarion. If you create a dedicated `clarion-guardduty` topic, copy that topic ARN into Clarion's SNS topic ARN field for the GuardDuty monitor and save before creating the HTTPS subscription.
5. Give the rule a descriptive name (e.g. `clarion-guardduty-findings`), review, and save.

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/guardduty-rule-1.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=ef08b9d6dfb20700316a7cc158ad64a0" alt="" width="2492" height="846" data-path="images/aws/guardduty-rule-1.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/guardduty-rule-2.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=5a1c10232990520a4f03cffc377d025f" alt="" width="2500" height="1300" data-path="images/aws/guardduty-rule-2.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/guardduty-rule-3.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=ae0d1b690cb0de1614bfa211ac928919" alt="" width="3070" height="1966" data-path="images/aws/guardduty-rule-3.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/guardduty-rule-4.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=3c6f1ae48da0d629ad6774133a609d74" alt="" width="1632" height="1404" data-path="images/aws/guardduty-rule-4.png" />

<Tip>
  Make sure GuardDuty is enabled in your AWS account. If it's not yet active, enable it in the GuardDuty console first.
</Tip>

***

## Step 4 — IAM Role for Agent Tools

Clarion needs an IAM role to run agent tools (CloudTrail lookup, Route 53, CloudWatch queries). You can set this up via the AWS Console or the AWS CLI.

<Warning>
  The generated policy uses `Resource: "*"` on every statement for convenience. Before production, deselect any permission sets you don't use and replace `"*"` with specific ARNs for your resources, such as SNS topics, S3 log buckets, Route 53 zones, and CloudWatch log groups. Expand each permission set in Clarion's permission picker for per-set scope-down guidance.
</Warning>

***

### Option A — AWS Console

#### 1. Check for an existing role

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/iam-check-role.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=08a48dae022bbc40e2e722753e230d05" alt="" width="3068" height="1908" data-path="images/aws/iam-check-role.png" />

Go to **IAM console** > **Roles** and search for `ClarionIntegrationRole`. If it exists, skip to step 3 to update the trust policy.

#### 2. Create the policy and role

1. Go to **IAM console** > **Policies** and create a new policy with the JSON below.
2. Then go to **IAM console** > **Roles** and create a new role.
3. Select **Custom trust policy** and paste the trust policy JSON below.
4. Attach the policy you just created.

#### 3. Verify or update the trust policy

1. Open the role's **Trust relationships** tab.
2. Verify (or update) the trust policy to match:

Trust Policy

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::762233769489:role/ClarionBridgeRole-20260319110823845000000001"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<your workspace external ID from Clarion>"
        }
      }
    }
  ]
}
```

#### 4. Copy the Role ARN

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/iam-role-arn.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=2b0556e07d05d0dcebd2242d633d74d2" alt="" width="3038" height="666" data-path="images/aws/iam-role-arn.png" />

Verify the permission policy is attached, then copy the **Role ARN** and paste it into Clarion.

***

### Option B — AWS CLI

IAM Permission Policy

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ClarionRoute53",
      "Effect": "Allow",
      "Action": [
        "route53:ListHostedZones",
        "route53:GetHostedZone",
        "route53:ListResourceRecordSets",
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionCloudWatch",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:ListMetrics",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionCloudTrail",
      "Effect": "Allow",
      "Action": [
        "cloudtrail:LookupEvents",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionSNS",
      "Effect": "Allow",
      "Action": [
        "sns:CreateTopic",
        "sns:DeleteTopic",
        "sns:Subscribe",
        "sns:Unsubscribe",
        "sns:SetTopicAttributes",
        "sns:ListTopics",
        "sns:GetTopicAttributes",
        "sns:ListSubscriptionsByTopic"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionEventBridge",
      "Effect": "Allow",
      "Action": [
        "events:PutRule",
        "events:DeleteRule",
        "events:PutTargets",
        "events:RemoveTargets",
        "events:ListRules",
        "events:DescribeRule"
      ],
      "Resource": "*"
    }
  ]
}
```

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/cli-create-policy.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=b993a1dcb702959783250db11dabe2cf" alt="" width="3056" height="1726" data-path="images/aws/cli-create-policy.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/cli-create-role.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=a83a8e207ea182b9a6848edb69896ea8" alt="" width="3072" height="1906" data-path="images/aws/cli-create-role.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/cli-attach-policy.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=dd8ab70e6f4111fadb6eeba3e2498196" alt="" width="3066" height="1050" data-path="images/aws/cli-attach-policy.png" />

<img src="https://mintcdn.com/cantinaclarion/ModSzzOvpzV85eyN/images/aws/cli-verify.png?fit=max&auto=format&n=ModSzzOvpzV85eyN&q=85&s=263cb2de8c221f074e31167abedb52f3" alt="" width="2628" height="958" data-path="images/aws/cli-verify.png" />

Run these commands in your terminal. Replace the Principal ARN and External ID with the values shown in your Clarion integration wizard.

#### 1. Check if the role already exists

```bash theme={null}
aws iam get-role \
  --role-name ClarionIntegrationRole \
  --query 'Role.Arn' --output text 2>/dev/null
```

If this prints an ARN, the role already exists — skip to step 4 to update its trust policy. Otherwise, continue with step 2.

#### 2. Create the IAM policy

```bash theme={null}
aws iam create-policy \
  --policy-name ClarionIntegrationPolicy \
  --policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ClarionRoute53",
      "Effect": "Allow",
      "Action": [
        "route53:ListHostedZones",
        "route53:GetHostedZone",
        "route53:ListResourceRecordSets",
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionCloudWatch",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:ListMetrics",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionCloudTrail",
      "Effect": "Allow",
      "Action": [
        "cloudtrail:LookupEvents",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionSNS",
      "Effect": "Allow",
      "Action": [
        "sns:CreateTopic",
        "sns:DeleteTopic",
        "sns:Subscribe",
        "sns:Unsubscribe",
        "sns:SetTopicAttributes",
        "sns:ListTopics",
        "sns:GetTopicAttributes",
        "sns:ListSubscriptionsByTopic"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ClarionEventBridge",
      "Effect": "Allow",
      "Action": [
        "events:PutRule",
        "events:DeleteRule",
        "events:PutTargets",
        "events:RemoveTargets",
        "events:ListRules",
        "events:DescribeRule"
      ],
      "Resource": "*"
    }
  ]
}'
```

#### 3. Create the IAM role with trust policy

```bash theme={null}
aws iam create-role \
  --role-name ClarionIntegrationRole \
  --assume-role-policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<ClarionBridgeRole ARN from Clarion>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<your workspace external ID from Clarion>"
        }
      }
    }
  ]
}'
```

#### 4. Update the trust policy (existing role only)

Run this instead of step 3 if the role already existed:

```bash theme={null}
aws iam update-assume-role-policy \
  --role-name ClarionIntegrationRole \
  --policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<ClarionBridgeRole ARN from Clarion>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<your workspace external ID from Clarion>"
        }
      }
    }
  ]
}'
```

#### 5. Attach the policy to the role

```bash theme={null}
aws iam attach-role-policy \
  --role-name ClarionIntegrationRole \
  --policy-arn "arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/ClarionIntegrationPolicy"
```

After running these commands, copy the Role ARN from step 1 (existing role) or step 3 (new role) and paste it into Clarion.

***

## Step 4B — Connecting Multiple AWS Accounts

Agent MCP tools (`aws_describe`, `aws_logs_insights`, `aws_athena`, `aws_cloudtrail`, `inspect_alb_auth`) can target any account you connect to the workspace. Repeat Step 4 once per account: create a `ClarionIntegrationRole` in each account, give it the same trust policy and IAM policy, and add the role ARN to Clarion's AWS integration as a new connected account.

When invoking an AWS MCP, the agent passes an `accountId` parameter to select which account the call should hit. Omitting the parameter falls back to the primary account.

### 4B.1 Pick a primary

Exactly one connected account is marked **primary**. The primary's role is used whenever an MCP call omits `accountId`. Pick the account you query most often — typically the AWS Organizations log-archive account if you also use the consolidated-S3 ingest from [Step 1B](#step-1b-cloudtrail-via-consolidated-s3-logging).

### 4B.2 External ID

By default every connected account uses the same workspace external ID, so you paste the same value into every role's trust policy. If you want stricter isolation between accounts (a separate external ID per account so a leak in one does not compromise the others), generate a per-account external ID in the Clarion UI's account-list panel and use that in the corresponding role's trust policy.

### 4B.3 IAM policy

Every connected account's role uses the same IAM policy JSON from Step 4. Permission selection (the `iamPermissionGroupIds` list) is workspace-wide for now — every connected account is expected to honor the same set of granted permissions.

<Tip>
  Agents discover connected accounts through the MCP tool schema: passing an unknown `accountId` returns a structured error listing the known accounts so the agent can self-correct and retry. The agent does not have to enumerate accounts ahead of time — it can start with the account ID from a CloudTrail event's `recipientAccountId` and Clarion will route accordingly.
</Tip>

***

## Step 5 — Activate Monitors in Clarion

1. Go back to Clarion and add the **CloudTrail** monitor.
2. Enable all the rules, then confirm.
3. Review the listed event types and click to enable all relevant ones.
4. If you set up GuardDuty or CloudWatch, add the **GuardDuty** and **CloudWatch** monitors as well. These monitors receive alerts directly, so you don't have to configure additional rules.

<Check>
  You're done! Clarion is now receiving CloudTrail events, CloudWatch alarms, and GuardDuty findings from your AWS account.
</Check>