RunReveal
Notifications

AWS SNS

RunReveal publishes a JSON message to an Amazon SNS topic when a detection fires, a test runs, or another notification event triggers. Standard and FIFO (.fifo) topics work across all AWS partitions (aws, aws-us-gov, aws-cn).

Setup Instructions

Step 1: Create or Select an SNS Topic

Create or pick the SNS topic that will receive alerts and copy its Topic ARN (for example, arn:aws:sns:us-east-1:123456789012:runreveal-alerts).

On FIFO (.fifo) topics, RunReveal sets MessageGroupId to runreveal-<workspaceID> and MessageDeduplicationId to <historyID>-<pageIndex> so content-based deduplication does not drop multi-page alerts.

Step 2: Configure AWS Authentication

Authenticate with an IAM role that RunReveal assumes (recommended) or an AWS access key pair.

Create an IAM role in your AWS account with sns:Publish permission on the target topic:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowRunRevealSNSPublish",
      "Effect": "Allow",
      "Action": [
        "sns:Publish"
      ],
      "Resource": "arn:aws:sns:<REGION>:<ACCOUNT_ID>:<TOPIC_NAME>"
    }
  ]
}

If your SNS topic uses server-side encryption (SSE) with a customer-managed KMS key, also grant kms:GenerateDataKey and kms:Decrypt on that KMS key ARN.

Add a trust policy on the role so RunReveal can assume it with your External ID:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::253602268883:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<EXTERNAL_ID>"
        }
      }
    }
  ]
}

Note: BYOC, On-Prem, and BYODB customers must use their deployment's AWS account ID in the Principal ARN instead of 253602268883.

Step 3: Configure in RunReveal

  1. Open Notification Channels, click Connect a notification channel, and select AWS SNS.
  2. Enter a display name and paste your SNS Topic ARN (arn:aws:sns:us-east-1:123456789012:my-alerts-topic). RunReveal fills in the AWS region from the ARN.
  3. Pick Customer provided role (Role ARN and optional External ID) or AWS access key (Access Key ID and Secret Access Key).
  4. Click Test notification to publish a test message, then click Create Notification to save.

Payload Schema & Page Splitting

Each SNS message body is a JSON object matching the Webhook notification payload, with two differences for AWS.

Scheduled SQL detections include detection.results (an array of row objects) and omit the columnar columns and values arrays so rows are not duplicated in the payload.

AWS SNS caps messages at 256 KB (262,144 bytes). When a detection result exceeds 256 KB, RunReveal splits detection.results across multiple SNS messages and sets pageIndex (0, 1, 2, ...) and totalPages on each message.

Top-level fields

FieldTypeDescription
titlestringRendered notification title (from template).
bodystringRendered notification body (from template).
channelstringAlways "sns" for this channel.
pageIndexnumber0-based index of this message page (0 when unsplit).
totalPagesnumberTotal number of pages sent for this notification (1 when unsplit).
detectionobjectPresent for detection alerts.
testobjectPresent for test notifications ({"status": true}).
dataobjectPresent for other event types.

Example payloads

{
  "title": "RunReveal Detection Alert: Impossible Travel Detected",
  "body": "User [email protected] logged in from two countries within 5 minutes.\n\nSeverity: high\nRows Returned: 1\nResult Link: https://app.runreveal.com/dash/history?alertID=abc123",
  "channel": "sns",
  "pageIndex": 0,
  "totalPages": 1,
  "detection": {
    "id": "abc123",
    "detectionID": "det_456",
    "workspaceID": "ws_789",
    "name": "impossible-travel",
    "displayName": "Impossible Travel Detected",
    "detectionType": "query",
    "severity": "high",
    "riskScore": 80,
    "categories": ["identity"],
    "mitreAttacks": ["TA0001"],
    "mitreTechniques": ["T1078"],
    "description": "Detects logins from geographically distant locations.",
    "system": false,
    "executedAt": "2025-02-19T12:00:00Z",
    "triggered": true,
    "resultLink": "https://app.runreveal.com/dash/history?alertID=abc123",
    "query": "SELECT actor, srcIP, srcCity FROM events WHERE ...",
    "params": { "from": "2025-02-19T11:00:00Z", "to": "2025-02-19T12:00:00Z" },
    "runTime": 230,
    "resultCount": 1,
    "nextRunTime": "2025-02-19T12:15:00Z",
    "prevRunTime": "2025-02-19T11:45:00Z",
    "results": [
      {
        "__alertID__": "abc123",
        "actor": "[email protected]",
        "srcIP": "203.0.113.42",
        "srcCity": "London"
      }
    ]
  }
}

Previous

VictorOps

Next

AWS SQS

On this page