EventBridge Alerting Pipelines

What it is

Amazon EventBridge is a serverless event bus that receives events from AWS services and your own applications, matches them against rules, and sends them to targets. For security teams it is the glue between detection services and response or notification: a GuardDuty finding, a Security Hub finding, an AWS Config compliance change or a CloudTrail API call becomes an event, and a rule routes it onward.

The big design question is where the alert should land. A single account can alert itself, but an organization usually forwards events to one central security account.

How it works

Buses, rules and patterns

Every account has a default event bus that AWS services write to. A rule holds an event pattern (a JSON filter) or a schedule, plus up to several targets. Matching is exact on the field values you list, and it is case sensitive.

This pattern matches GuardDuty findings with a severity of 7 or higher.

{
  "source": ["aws.guardduty"],
  "detail-type": ["GuardDuty Finding"],
  "detail": {
    "severity": [{ "numeric": [">=", 7] }]
  }
}

API activity that is not published as its own event type arrives with the detail type AWS API Call via CloudTrail. Rules on that detail type depend on CloudTrail management events being recorded, and events from global services such as IAM are recorded in us-east-1, so the rule must live in that Region.

# AWS CLI: create the rule, then attach an SNS topic as the target
aws events put-rule --name high-severity-guardduty \
  --event-pattern file://pattern.json
aws events put-targets --rule high-severity-guardduty \
  --targets "Id"="1","Arn"="arn:aws:sns:us-east-1:111122223333:security-alerts"

Targets and permissions

How EventBridge is allowed to call a target depends on the target type. This is a favourite troubleshooting point.

For failed deliveries, configure a retry policy and a dead letter queue (DLQ) on the target. An archive and replay feature stores events so that you can re-run a rule after fixing it.

Cross account and organization alerting

To centralise alerts, create a custom event bus in the security account and give it a resource policy that allows events:PutEvents from the other accounts. A policy that trusts a whole organization uses the aws:PrincipalOrgID condition key, so you do not list every account.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "AllowOrgToPutEvents",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "events:PutEvents",
    "Resource": "arn:aws:events:us-east-1:222233334444:event-bus/central-security",
    "Condition": { "StringEquals": { "aws:PrincipalOrgID": "o-exampleorgid" } }
  }]
}

In each source account, a rule forwards matching events to that central bus. Events are Regional, so each Region needs its own forwarding rule or its own central bus.

Notification choices

Prefer the delegated administrator feature of detection services over per account wiring where it exists. GuardDuty and Security Hub can aggregate findings across the organization, so one rule in the administrator account sees member findings.

Input transformers

Raw findings are long. An input transformer picks fields from the event, such as severity, resource and account, and builds a short message for the target. Use it to make a page readable at three in the morning.