# Managing 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). ![\[AWS services send events to the EventBridge default event bus. If the event matches a rule's event pattern, EventBridge sends the event to the targets specified for that rule.\]](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/images/eventbridge-integration-how-it-works.png) **Topics** + [Resolver DNS Firewall events](#supported-events) + [Sending Resolver DNS Firewall events using EventBridge rules](#eventbridge-using-events-rules) + [Amazon EventBridge permissions](#eventbridge-permissions) + [Additional EventBridge resources](#eventbridge-additonal-resources) + [Resolver DNS Firewall events detail reference](events-detail-reference.md) ## Resolver DNS Firewall events VPC 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](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html#eb-service-event-delivery-level). Events might be delivered out of order. The following events are generated by DNS Firewall. For more information, see [EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide.*. | Event detail type | Description | | --- | --- | | [DNS Firewall Block](events-detail-reference.md#dns-firewall-alert) | Any block action performed on a domain. | | [DNS Firewall Alert](events-detail-reference.md#dns-firewall-block) | Any alert action performed on a domain. | ## Sending 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: + VPC 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 Resolver DNS Firewall events](#eventbridge-using-events-rules-patterns) 1. (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](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-transform-target-input.html) in the *EventBridge User Guide*. 1. 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](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html) in the *EventBridge User Guide*. For comprehensive instructions on creating event bus rules, see [Creating rules that react to events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html) in the *EventBridge User Guide*. ### Creating event patterns for 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. 1. Instance i-123 sent a DNSquery exampledomain.com at time T1\$130 minutes. DNS Firewall doesn't send an alert or block event as this is a repeat occurrence within the 6-hour window. 1. Instance i-123 sent a DNS query exampledomain.com at time T1\$17 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](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) 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](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-pattern-sandbox.html) 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 ``` 1. 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:` 1. To add the permissions required to invoke the target, run the following Lambda AWS CLI command: `AWS lambda add-permission --function-name --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](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html) in the *Amazon EventBridge User Guide*. ## Additional EventBridge resources Refer to the following topics in the [https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) 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](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-bus.html). + For information on event structure, see [Events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html). + For information on constructing event patterns for EventBridge to use when matching events against rules, see [Event patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html). + For information on creating rules to specify which events EventBridge processes, see [Rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html). + For information on to specify what services or other destinations EventBridge sends matched events to, see [Targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html). # Resolver DNS Firewall events detail reference All events from AWS services have a common set of fields containing metadata about the event, such as the AWS service that is the source of the event, the time the event was generated, the account and region in which the event took place, and others. For definitions of these general fields, see [Event structure reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html) in the *Amazon EventBridge User Guide*. In addition, each event has a `detail` field that contains data specific to that particular event. The reference below defines the detail fields for the various DNS Firewall events. When using EventBridge to select and manage DNS Firewall events, it's useful to keep the following in mind: + The `source` field for all events from DNS Firewall is set to `aws.route53resolver`. + The `detail-type` field specifies the event type. For example, `DNS Firewall Block` or `DNS Firewall Alert`. + The `detail` field contains the data that is specific to that particular event. For information on constructing event patterns that enable rules to match DNS Firewall events, see [Event patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) in the *Amazon EventBridge User Guide*. For more information on events and how EventBridge processes them, see [Amazon EventBridge events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*. **Topics** + [DNS Firewall alert event detail](#dns-firewall-alert) + [DNS Firewall block event detail](#dns-firewall-block) ## DNS Firewall alert event detail Below are the detail fields for Alert status event detail . The `source` and `detail-type` fields are included because they contain specific values for Route 53 events. ``` {..., "detail-type": "DNS Firewall Alert", "source": "aws.route53resolver", ..., "detail": { "account-id": "string", "last-observed-at": "string", "query-name": "string", "query-type": "string", "query-class": "string", "transport": "string", "firewall-rule-action": "string", "firewall-rule-group-id": "string", "firewall-domain-list-id": "string", "firewall-protection": "string", "resources": [{ "resource-type": "string", "instance-details": { "id": "string", } }, { "resource-type": "string", "resolver-endpoint-details": { "id": "string" } } ] ``` `detail-type` Identifies the type of event. For this event, this value is `DNS Firewall Alert`. `source` Identifies the service that generated the event. For DNS Firewall events, this value is `aws.route53resolver`. `detail` A JSON object that contains information about the event. The service generating the event determines the content of this field. For this event, this data includes: `account-id` The ID of the AWS account that created the VPC. `last-observed-at` The timestamp of when the Alert/Block query was made in the VPC. `query-name` The domain name (example.com) or subdomain name (www.example.com) that was specified in the query. `query-type` Either the DNS record type that was specified in the request, or ANY. For information about the types that Route 53 supports, see [Supported DNS record types](ResourceRecordTypes.md). `query-class` The class of the query. `transport` The protocol used to submit the DNS query. `firewall-rule-action` The action specified by the rule that matched the domain name in the query. Either `ALERT` or `BLOCK`. `firewall-rule-group-id` The ID of the DNS Firewall rule group that matched the domain name in the query. For more information about the firewall rule groups, see DNS Firewall [DNS Firewall rule groups and rules](resolver-dns-firewall-rule-groups.md). `firewall-domain-list-id` The domain list used by the rule that matched the domain name in the query. `firewall-protection` The DNS Firewall Advanced protection: DGA, DICTIONARY\$1DGA, or DNS\$1TUNNELING. For more information, see DNS Firewall [Resolver DNS Firewall Advanced](firewall-advanced.md). `resourcese` Contains resource types and additional details about them. `resource-type` Specifies the resource type, such as resolver endpoint or a VPC instance. `resource-type-detail` Additional details about the resource. **Example DNS Firewall alert event** The following is an example alert event. ``` { "version": "1.0", "id": "8e5622f9-d81c-4d81-612a-9319e7ee2506", "detail-type": "DNS Firewall Alert", "source": "aws.route53resolver", "account": "123456789012", "time": "2023-05-30T21:52:17Z", "region": "us-west-2", "resources": [], "detail": { "account-id": "123456789012", "last-observed-at": "2023-05-30T20:15:15.900Z", "query-name": "15.3.4.32.in-addr.arpa.", "query-type": "A", "query-class": "IN", "transport": "UDP", "firewall-rule-action": "ALERT", "firewall-rule-group-id": "rslvr-frg-01234567890abcdef", "firewall-domain-list-id": "rslvr-fdl-01234567890abcdef", "firewall-protection": "DGA", "resources": [{ "resource-type": "instance", "instance-details": { "id": "i-05746eb48123455e0", } }, { "resource-type": "resolver-endpoint", "resolver-endpoint-details": { "id": "i-05746eb48123455e0" } } ], "src-addr": "4.5.64.102", "src-port": "56067", "vpc-id": "vpc-7example" } } ``` ## DNS Firewall block event detail Below are the detail fields for *event name*. The `source` and `detail-type` fields are included because they contain specific values for Route 53 events. ``` {..., "detail-type": "DNS Firewall Block", "source": "aws.route53resolver", ..., "detail": { "account-id": "string", "last-observed-at": "string", "query-name": "string", "query-type": "string", "query-class": "string", "transport": "string", "firewall-rule-action": "string", "firewall-rule-group-id": "string", "firewall-domain-list-id": "string", "firewall-protection": "string", "resources": [{ "resource-type": "string", "instance-details": { "id": "string", } }, { "resource-type": "string", "resolver-endpoint-details": { "id": "string" } } ] ``` `detail-type` Identifies the type of event. For this event, this value is `DNS Firewall Alert`. `source` Identifies the service that generated the event. For DNS Firewall events, this value is `aws.route53resolver`. `detail` A JSON object that contains information about the event. The service generating the event determines the content of this field. For this event, this data includes: `account-id` The ID of the AWS account that created the VPC. `last-observed-at` The timestamp of when the Alert/Block query was made in the VPC. `query-name` The domain name (example.com) or subdomain name (www.example.com) that was specified in the query. `query-type` Either the DNS record type that was specified in the request, or ANY. For information about the types that Route 53 supports, see [Supported DNS record types](ResourceRecordTypes.md). `query-class` The class of the query. `transport` The protocol used to submit the DNS query. `firewall-rule-action` The action specified by the rule that matched the domain name in the query. Either `ALERT` or `BLOCK`. `firewall-rule-group-id` The ID of the DNS Firewall rule group that matched the domain name in the query. For more information about the firewall rule groups, see DNS Firewall [DNS Firewall rule groups and rules](resolver-dns-firewall-rule-groups.md). `firewall-domain-list-id` The domain list used by the rule that matched the domain name in the query. `firewall-protection` The DNS Firewall Advanced protection: DGA, DICTIONARY\$1DGA, or DNS\$1TUNNELING. For more information, see DNS Firewall [Resolver DNS Firewall Advanced](firewall-advanced.md). `resourcese` Contains resource types and additional details about them. `resource-type` Specifies the resource type, such as resolver endpoint or a VPC instance. `resource-type-detail` Additional details about the resource. **Example event** The following is an example block event. ``` { "version": "1.0", "id": "8e5622f9-d81c-4d81-612a-9319e7ee2506", "detail-type": "DNS Firewall Block", "source": "aws.route53resolver", "account": "123456789012", "time": "2023-05-30T21:52:17Z", "region": "us-west-2", "resources": [], "detail": { "account-id": "123456789012", "last-observed-at": "2023-05-30T20:15:15.900Z", "query-name": "15.3.4.32.in-addr.arpa.", "query-type": "A", "query-class": "IN", "transport": "UDP", "firewall-rule-action": "BLOCK", "firewall-rule-group-id": "rslvr-frg-01234567890abcdef", "firewall-domain-list-id": "rslvr-fdl-01234567890abcdef", "firewall-protection": "DNS_TUNNELING", "resources": [{ "resource-type": "instance", "instance-details": { "id": "i-05746eb48123455e0" } }, { "resource-type": "resolver-endpoint", "resolver-endpoint-details": { "id": "i-05746eb48123455e0", } } ], "src-addr": "4.5.64.102", "src-port": "56067", "vpc-id": "vpc-7example" } } ```