Sending web ACL traffic logs to an Amazon Simple Storage Service bucket
This topic provides information for sending your web ACL traffic logs to an Amazon S3 bucket.
Note
You are charged for logging in addition to the charges for using Amazon WAF. For information, see Pricing for logging web ACL traffic information.
To send your web ACL traffic logs to Amazon S3, you set up an Amazon S3 bucket
from the same account as you use to manage the web ACL, and you name
the bucket starting with aws-waf-logs-
.
When you enable logging in Amazon WAF, you provide the bucket name.
For information about creating a logging bucket, see Create a Bucket in the
Amazon Simple Storage Service User Guide.
You can access and analyze your Amazon S3 logs using the Amazon Athena interactive query
service. Athena makes it easy to analyze data directly in Amazon S3 using standard SQL.
With a few actions in the Amazon Web Services Management Console, you can point Athena at your data stored in Amazon S3
and quickly begin using standard SQL to run ad-hoc queries and get results. For more
information, see Querying Amazon WAF logs in the Amazon Athena user
guide. For additional sample Amazon Athena queries, see
aws-samples/waf-log-sample-athena-queries
Note
Amazon WAF supports encryption with Amazon S3 buckets for key type Amazon S3 key (SSE-S3) and for Amazon Key Management Service (SSE-KMS) Amazon KMS keys. Amazon WAF doesn't support encryption for Amazon Key Management Service keys that are managed by Amazon.
Your web ACLs publish their log files to the Amazon S3 bucket at 5-minute intervals. Each log file contains log records for the traffic recorded in the previous 5 minutes.
The maximum file size for a log file is 75 MB. If the log file reaches the file size limit within the 5-minute period, the log stops adding records to it, publishes it to the Amazon S3 bucket, and then creates a new log file.
The log files are compressed. If you open the files using the Amazon S3 console, Amazon S3 decompresses the log records and displays them. If you download the log files, you must decompress them to view the records.
A single log file contains interleaved entries with multiple records. To see all the log files for a web ACL, look for entries aggregated by the web ACL name, Region, and your account ID.
Naming requirements and syntax
Your bucket names for Amazon WAF logging must start with aws-waf-logs-
and
can end with any suffix you want. For example,
aws-waf-logs-
. LOGGING-BUCKET-SUFFIX
Bucket location
The bucket locations use the following syntax:
s3://aws-waf-logs-
LOGGING-BUCKET-SUFFIX
/
Bucket ARN
The format of the bucket Amazon Resource Name (ARN) is as follows:
arn:aws:s3:::aws-waf-logs-
LOGGING-BUCKET-SUFFIX
Bucket locations with prefixes
If you use prefixes in your object keys name to organize the data that you store in your buckets, you can provide your prefixes in your logging bucket names.
Note
This option is not available through the console. Use the Amazon WAF APIs, CLI, or Amazon CloudFormation.
For information about using prefixes in Amazon S3, see Organizing objects using prefixes in the Amazon Simple Storage Service User Guide.
The bucket locations with prefixes use the following syntax:
s3://aws-waf-logs-
LOGGING-BUCKET-SUFFIX
/KEY-NAME-PREFIX
/
Bucket folders and file names
Inside your buckets, and following any prefixes that you provide, your Amazon WAF logs are written under a folder structure that's determined by your account ID, the Region, the web ACL name, and the date and time.
AWSLogs/
account-id
/WAFLogs/Region
/web-acl-name
/YYYY
/MM
/dd
/HH
/mm
Inside the folders, the log file names follow a similar format:
account-id
_waflogs_Region
_web-acl-name
_timestamp
_hash
.log.gz
The time specifications used in the folder structure and in the log file name
adhere to the timestamp format specification YYYYMMddTHHmmZ
.
The following shows an example log file in an Amazon S3 bucket for a bucket named
aws-waf-logs-
. The Amazon Web Services account is
LOGGING-BUCKET-SUFFIX
11111111111
. The web ACL is TEST-WEBACL
and the Region
is us-east-1
.
s3://aws-waf-logs-
LOGGING-BUCKET-SUFFIX
/AWSLogs/11111111111/WAFLogs/us-east-1/TEST-WEBACL/2021/10/28/19/50/11111111111_waflogs_us-east-1_TEST-WEBACL_20211028T1950Z_e0ca43b5.log.gz
Note
Your bucket names for Amazon WAF logging must start with aws-waf-logs-
and can end with any suffix you want.
Permissions required to publish logs to Amazon S3
Configuring web ACL traffic logging for an Amazon S3 bucket requires the following
permissions settings. These permissions are set for you when you use one of the
Amazon WAF full access managed policies, AWSWAFConsoleFullAccess
or
AWSWAFFullAccess
. If you want to manage finer-grained access to
your logging and Amazon WAF resources, you can set these permissions yourself. For
information about managing permissions, see Access management for Amazon
resources in the IAM User Guide. For
information about the Amazon WAF managed policies, see Amazon managed policies for Amazon WAF.
The following permissions allow you to change the web ACL logging configuration and to configure log delivery to your Amazon S3 bucket. These permissions must be attached to the user that you use to manage Amazon WAF.
Note
When you set the permissions listed below, you might see errors in your Amazon CloudTrail logs that indicate access denied, but the permissions are correct for Amazon WAF logging.
{ "Version":"2012-10-17", "Statement":[ { "Action":[ "wafv2:PutLoggingConfiguration", "wafv2:DeleteLoggingConfiguration" ], "Resource":[ "*" ], "Effect":"Allow", "Sid":"LoggingConfigurationAPI" }, { "Sid":"WebACLLogDelivery", "Action":[ "logs:CreateLogDelivery", "logs:DeleteLogDelivery" ], "Resource": "*", "Effect":"Allow" }, { "Sid":"WebACLLoggingS3", "Action":[ "s3:PutBucketPolicy", "s3:GetBucketPolicy" ], "Resource": [ "arn:aws:s3:::aws-waf-logs-
LOGGING-BUCKET-SUFFIX
" ], "Effect":"Allow" } ] }
When actions are permitted on all Amazon resources, it's indicated in the
policy with a "Resource"
setting of "*"
. This means
that the actions are permitted on all Amazon resources that each action
supports. For example, the action
wafv2:PutLoggingConfiguration
is supported only for
wafv2
logging configuration resources.
By default, Amazon S3 buckets and the objects that they contain are private. Only the bucket owner can access the bucket and the objects stored in it. The bucket owner, however, can grant access to other resources and users by writing an access policy.
If the user creating the log owns the bucket, the service automatically attaches the following policy to the bucket to give the log permission to publish logs to it:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AWSLogDeliveryWrite", "Effect": "Allow", "Principal": { "Service": "delivery.logs.amazonaws.com" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::aws-waf-logs-
LOGGING-BUCKET-SUFFIX
/AWSLogs/account-id
/*", "Condition": { "StringEquals": { "s3:x-amz-acl": "bucket-owner-full-control", "aws:SourceAccount": ["account-id
"] }, "ArnLike": { "aws:SourceArn": ["arn:aws:logs:region
:account-id
:*"] } } }, { "Sid": "AWSLogDeliveryAclCheck", "Effect": "Allow", "Principal": { "Service": "delivery.logs.amazonaws.com" }, "Action": "s3:GetBucketAcl", "Resource": "arn:aws:s3:::aws-waf-logs-LOGGING-BUCKET-SUFFIX
", "Condition": { "StringEquals": { "aws:SourceAccount": ["account-id
"] }, "ArnLike": { "aws:SourceArn": ["arn:aws:logs:region
:account-id
:*"] } } } ] }
Note
Your bucket names for Amazon WAF logging must start with aws-waf-logs-
and can end with any suffix you want.
If the user creating the log doesn't own the bucket, or doesn't have the
GetBucketPolicy
and PutBucketPolicy
permissions
for the bucket, the log creation fails. In this case, the bucket owner must
manually add the preceding policy to the bucket and specify the log creator's
Amazon Web Services account ID. For more information, see How Do I Add an S3 Bucket
Policy? in the Amazon Simple Storage Service User Guide. If the bucket
receives logs from multiple accounts, add a Resource
element entry
to the AWSLogDeliveryWrite
policy statement for each account.
For example, the following bucket policy allows Amazon Web Services account
111122223333
to publish logs to a bucket named aws-waf-logs-
:LOGGING-BUCKET-SUFFIX
{ "Version": "2012-10-17", "Id": "AWSLogDeliveryWrite20150319", "Statement": [ { "Sid": "AWSLogDeliveryWrite", "Effect": "Allow", "Principal": { "Service": "delivery.logs.amazonaws.com" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::aws-waf-logs-
LOGGING-BUCKET-SUFFIX
/AWSLogs/111122223333/*", "Condition": { "StringEquals": { "s3:x-amz-acl": "bucket-owner-full-control", "aws:SourceAccount": ["111122223333"] }, "ArnLike": { "aws:SourceArn": ["arn:aws:logs:us-east-1:111122223333:*"] } } }, { "Sid": "AWSLogDeliveryAclCheck", "Effect": "Allow", "Principal": { "Service": "delivery.logs.amazonaws.com" }, "Action": "s3:GetBucketAcl", "Resource": "arn:aws:s3:::aws-waf-logs-LOGGING-BUCKET-SUFFIX
", "Condition": { "StringEquals": { "aws:SourceAccount": ["111122223333"] }, "ArnLike": { "aws:SourceArn": ["arn:aws:logs:us-east-1:111122223333:*"] } } } ] }
Permissions for using Amazon Key Management Service with a KMS key
If your logging destination uses server-side encryption with keys that are stored in Amazon Key Management Service (SSE-KMS) and you use a customer managed key (KMS key), you must give Amazon WAF permission to use your KMS key. To do this, you add a key policy to the KMS key for your chosen destination. This permits Amazon WAF logging to write your log files to your destination.
Add the following key policy to your KMS key to allow Amazon WAF to log to your Amazon S3 bucket.
{ "Sid": "Allow Amazon WAF to use the key", "Effect": "Allow", "Principal": { "Service": [ "delivery.logs.amazonaws.com" ] }, "Action": "kms:GenerateDataKey*", "Resource": "*" }
Permissions required to access Amazon S3 log files
Amazon S3 uses access control
lists (ACLs) to manage access to the log files created by an Amazon WAF
log. By default, the bucket owner has FULL_CONTROL
permissions
on each log file. The log delivery owner, if different from the bucket
owner, has no permissions. The log delivery account has READ
and WRITE
permissions. For more information, see Access Control List (ACL)
Overview in the Amazon Simple Storage Service User Guide.