Skip to content

WAF Commands

List Web ACLs and pull the statistics you need when WAF is blocking something it should not.

troubleshoot is the one to reach for during an incident: it combines the Web ACL configuration, per-rule match counts, and sampled requests into a single report, so you can see which rule fired rather than guessing.

Commands

waf list

List all Web ACLs in the account.

aws-cloud-utilities waf list [OPTIONS]
Option Value Description
--scope REGIONAL | CLOUDFRONT WAF scope (default: REGIONAL)
--output-file TEXT Save output to file

waf stats

Get comprehensive WAF statistics for troubleshooting.

aws-cloud-utilities waf stats [OPTIONS]
Option Value Description
--web-acl TEXT Required. Web ACL name to analyze
--hours INTEGER Hours of data to analyze (default: 24)
--scope REGIONAL | CLOUDFRONT WAF scope (default: REGIONAL)
--output-file TEXT Save output to file

waf troubleshoot

Generate comprehensive WAF troubleshooting report.

aws-cloud-utilities waf troubleshoot [OPTIONS]
Option Value Description
--web-acl TEXT Required. Web ACL name to troubleshoot
--hours INTEGER Hours of data to analyze (default: 24)
--output-file TEXT Save troubleshooting report to file

Examples

# Regional Web ACLs (ALB, API Gateway, AppSync)
aws-cloud-utilities waf list

# CloudFront Web ACLs
aws-cloud-utilities waf list --scope CLOUDFRONT

# Save the list
aws-cloud-utilities waf list --output-file web-acls.json

# Statistics for one Web ACL
aws-cloud-utilities waf stats --web-acl my-web-acl
aws-cloud-utilities waf stats --web-acl my-web-acl --hours 168 --scope CLOUDFRONT

# Full troubleshooting report
aws-cloud-utilities waf troubleshoot --web-acl my-web-acl --hours 48 --output-file waf-report.json

Scope matters

--scope REGIONAL (the default) covers ALB, API Gateway, AppSync, and Cognito. --scope CLOUDFRONT covers CloudFront distributions and only resolves from us-east-1:

aws-cloud-utilities --region us-east-1 waf list --scope CLOUDFRONT

A Web ACL that does not appear in list is almost always a scope or region mismatch, not a missing ACL.

Notes

--web-acl is required on both stats and troubleshoot, and takes the Web ACL name as shown by list.

Sampled requests cover a rolling three-hour window, so --hours beyond that reports aggregate metrics without per-request samples.