Managing Route 53 Resolver DNS Firewall events using Amazon EventBridge

Amazon EventBridge is a serverless service that uses events to connect application components together, making it easier for you to build scalable event-driven applications. Event-driven architecture is a style of building loosely-coupled software systems that work together by emitting and responding to events. Events represent a change in a resource or environment.

As with many AWS services, DNS Firewall generates and sends events to the EventBridge default event bus. (The default event bus is automatically provisioned in every AWS account.) An event bus is a router that receives events and delivers them to zero or more destinations, or targets. Rules you specify for the event bus evaluate events as they arrive. Each rule checks whether an event matches the rule's event pattern. If the event does match, the event bus sends the event to the specified target(s).

Topics

• Route 53 Resolver DNS Firewall events
• Sending Route 53 Resolver DNS Firewall events using EventBridge rules
• Amazon EventBridge permissions
• Additional EventBridge resources
• Route 53 Resolver DNS Firewall events detail reference

Route 53 Resolver DNS Firewall events

Route 53 Resolver sends DNS Firewall events to the default EventBridge event bus automatically. You can create rules on the event bus; each rule includes an event pattern and one or more targets. Events that match a rule's event pattern are delivered to the specified targets on a best-effort basis. Events might be delivered out of order.

The following events are generated by DNS Firewall. For more information, see EventBridge in the Amazon EventBridge User Guide..

Event detail type	Description
DNS Firewall Block	Any block action performed on a domain.
DNS Firewall Alert	Any alert action performed on a domain.

Sending Route 53 Resolver DNS Firewall events using EventBridge rules

To have the EventBridge default event bus send DNS Firewall events to a target, you must create a rule that contains an event pattern that matches the data in the desired DNS Firewall events.

Creating a rule consists of the following general steps:

1. Creating an event pattern for the rule that specifies:

   • Route 53 Resolver is the source of events being evaluated by the rule.

   • (Optional): Any other event data to match against.

   For more information, see Creating event patterns for Route 53 Resolver DNS Firewall events

2. (Optional): Creating an input transformer that customizes the data from the event before EventBridge passes the information to the target of the rule.

   For more information, see Input transformation in the EventBridge User Guide.

3. Specifying the target(s) to which you want EventBridge to deliver events that match the event pattern.

   Targets can be other AWS services, software-as-a-service (SaaS) applications, API destinations, or other custom endpoints. For more information, see Targets in the EventBridge User Guide.

For comprehensive instructions on creating event bus rules, see Creating rules that react to events in the EventBridge User Guide.

Creating event patterns for Route 53 Resolver DNS Firewall events

When DNS Firewall delivers an event to the default event bus, EventBridge uses the event pattern defined for each rule to determine if the event should be delivered to the rule's target(s). An event pattern matches the data in the desired DNS Firewall events. Each event pattern is a JSON object that contains:

• A source attribute that identifies the service sending the event. For DNS Firewall events, the source is aws.route53resolver.

• (Optional): A detail-type attribute that contains an array of the event types to match.

• (Optional): A detail attribute containing any other event data on which to match.

For example, the following event pattern matches against both alert and block events from DNS Firewall:

{
  "source": ["aws.route53resolver"],
  "detail-type": ["DNS Firewall Block", "DNS Firewall Alert"]
}

While the following event pattern matches against a BLOCK action:

{
  "source": ["aws.route53resolver"],
  "detail-type": ["DNS Firewall Block"]
}

DNS Firewall sends the same event for the same domain only once within a 6-hour window. For example:

1. Instance i-123 sent a DNS query exampledomain.com at time T1. DNS Firewall sends an alert or block event as this is the first occurrence.

2. Instance i-123 sent a DNSquery exampledomain.com at time T1+30 minutes. DNS Firewall doesn't send an alert or block event as this is a repeat occurrence within the 6-hour window.

3. Instance i-123 sent a DNS query exampledomain.com at time T1+7 hours. DNS Firewall sends an alert or block event as this is occurred outside the 6-hour window.

For more information on writing event patterns, see Event patterns in the EventBridge User Guide.

Testing event patterns for DNS Firewall events in EventBridge

You can use the EventBridge Sandbox to quickly define and test an event pattern, without having to complete the larger process of creating or editing a rule. Using the Sandbox, you can define an event pattern and use a sample event to confirm the pattern matches the desired events. EventBridge give you the option of creating a new rule using that event pattern, directly from the sandbox.

For more information, see Testing an event pattern using the EventBridge Sandbox in the EventBridge User Guide.

Creating an EventBridge rule and target for DNS Firewall

The following procedure shows you how to create a rule that enables EventBridge to send events for all the DNS Firewall alert and block actions, and add an AWS Lambda function as a target for the rule.

1. Use AWS CLI to create an EventBridge rule:

   aws events put-rule \
   --event-pattern "{\"source\":
   [\"aws.route53resolver\"],\"detail-type\":
   [\"DNS Firewall Block\", \"DNS Firewall Alert\"]}" \
   --name dns-firewall-rule

2. Attach a Lambda function as a target for the rule:

   AWS events put-targets --rule dns-firewall-rule --targets Id=1,Arn=arn:aws:lambda:us-east-1:111122223333:function:<your_function>

3. To add the permissions required to invoke the target, run the following Lambda AWS CLI command:

   AWS lambda add-permission --function-name <your_function> --statement-id 1 --action 'lambda:InvokeFunction' --principal events.amazonaws.com

Amazon EventBridge permissions

DNS Firewall doesn't require any additional permissions to deliver events to Amazon EventBridge.

The targets you specify may need specific permissions or configuration. For more details on using specific services for targets, see Amazon EventBridge targets in the Amazon EventBridge User Guide.

Additional EventBridge resources

Refer to the following topics in the Amazon EventBridge User Guide for more information on how to use EventBridge to process and manage events.

• For detailed information on how event buses work, see Amazon EventBridge event bus.

• For information on event structure, see Events.

• For information on constructing event patterns for EventBridge to use when matching events against rules, see Event patterns.

• For information on creating rules to specify which events EventBridge processes, see Rules.

• For information on to specify what services or other destinations EventBridge sends matched events to, see Targets.