Skip to main content
Version: v1.5.0

AWS WAF Bouncer

CrowdSec

📚 Documentation💠 Hub💬 Discourse

Overview

The crowdsec-awf-waf-bouncer automatically adds rules to an AWS WAF ACL and manages IPSets content to apply decisions taken by crowdsec.

This allows to protect the following AWS resources with crowdsec:

  • AWS REST API Gateway
  • Cloudfront distribution
  • AWS Application LoadBalancer
  • AWS AppSync GraphQL API

As the bouncer does not manage your WAF ACLs, you will need to have existing ACLs already associated with your AWS resources for the bouncer to work properly. The bouncer supports the ban and captcha decisions type and can be configured to fall back to one of those for decisions of unknown type.

It can block at the IP (using ip scope in CrowdSec), range (using range scope in CrowdSec) or country level (using country scope in CrowdSec).

The bouncer will create all required resources and associate them with your existing ACLs based on your provided configuration.

As the resources will incur an AWS cost, the bouncer will remove everything it created when stopping.

If you do not have an existing AWS WAF configuration, you can refer to the official documentation to get started.

Installation

Using packages

Packages for crowdsec-aws-waf-bouncer are available on our repositories. You need to pick the package accord to your firewall system :

sudo apt install crowdsec-aws-waf-bouncer

Docker

docker run -v $(PWD)/config.yaml:/cs-aws-waf-bouncer.yaml crowdsecurity/aws-waf-bouncer

Configuration

You will need to edit /etc/crowdsec/bouncers/crowdsec-aws-waf-bouncer.yaml to configure the ACLs you want the bouncer to use.

api_key: XXXX
api_url: "http://127.0.0.1:8080/"
update_frequency: 10s
waf_config:
- web_acl_name: mywebacl
fallback_action: ban
rule_group_name: crowdsec-rule-group-eu-west-1
scope: REGIONAL
region: eu-west-1
ipset_prefix: crowdsec-ipset-a
ip_header: X-Forwarded-For
ip_header_position: LAST
aws_profile: myprofile
- web_acl_name: test-cloudfront
fallback_action: captcha
rule_group_name: crowdsec-rule-group-cloudfront
scope: CLOUDFRONT
ipset_prefix: crowdsec-ipset-cf

Optionally, the bouncer can also be configured using only environment variables.

Environment variables will take priority over values defined in the configuration file, in which case the suggested approach is via systemctl edit crowdsec-aws-waf-bouncer:

[Service]
Environment="BOUNCER_API_KEY=XXXXX"

AWS authentication is handled with the standard environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE) or instance role.

You can also use the aws_profile directive to specify a profile to use for a specific waf configuration.


api_key

Environment variable: BOUNCER_API_KEY

API key to use for communication with LAPI.

api_url

Environment variable: BOUNCER_API_URL

URL of LAPI.

update_frequency

Environment variable: BOUNCER_UPDATE_FREQUENCY

How often the bouncer will contact LAPI to update its content.

The format must be supported by golang ParseDuration.

supported_actions

Environment variable: BOUNCER_SUPPORTED_ACTIONS

Which actions (ie, remediation type) the bouncer supports.

List with any of the following: ban, captcha, count.

Default to ban, captcha and count.

If set from the environment, provide a comma-separated list: ban,captcha,count.


waf_config

Environment variable: BOUNCER_WAF_CONFIG_

List of object with the following properties:

waf_config:
- web_acl_name: mywebacl
fallback_action: ban
rule_group_name: crowdsec-rule-group-XXX
scope: REGIONAL
region: eu-west-1
ipset_prefix: crowdsec-ipset-

When configuring via environment variables, you can pass multiple BOUNCER_WAF_CONFIG_X_ variables, with X being a unique identifier (eg, 0, 1, 2, ...).

web_acl_name

Environment variable: BOUNCER_WAF_CONFIG_X_WEB_ACL_NAME

Name of the WAF ACL in which the rule group will be added

fallback_action

Environment variable: BOUNCER_WAF_CONFIG_X_FALLBACK_ACTION

Action to use if the type of a decision is not in the list defined by supported_actions.

Must be one of captcha, ban or count.

rule_group_name

Environment variable: BOUNCER_WAF_CONFIG_X_RULE_GROUP_NAME

Name of the rule group the bouncer will create and add to the WAF ACL.

Must be unique across all the configuration.

2 rules can be created:

  • crowdsec-rule-ban
  • crowdsec-rule-captcha

Those rules are automatically deleted if no decisions of the associated type exist.

If a decision for a country is received, the following rules will be created:

  • crowdsec-rule-ban-country: Contains a geomatch statement for banned countries
  • crowdsec-rule-captcha-country: Contains a geomatch statement for captcha'ed countries

Those rules will be deleted on shutdown and recreated on startup if they already exist.

scope

Environment variable: BOUNCER_WAF_CONFIG_X_SCOPE

Scope of the rule group and ipset. Can be REGIONAL or CLOUDFRONT.

Must match the scope of the WAF ACL.

region

Environment variable: BOUNCER_WAF_CONFIG_X_REGION

Region where all resources will be created.

No required when scope is CLOUDFRONT

ipset_prefix

Environment variable: BOUNCER_WAF_CONFIG_X_IPSET_PREFIX

Prefix for all the ipsets the bouncer will create.

One ipset will be created per 10k IPs, and will be automatically deleted if it becomes empty.

Differents ipsets are used for ban and captcha.

All ipsets are deleted on shutdown.

aws_profile

Environment variable: BOUNCER_WAF_CONFIG_X_AWS_PROFILE

Name of the AWS profile (defined in ~/.aws/config) to use.

ip_header

Environment variable: BOUNCER_WAF_CONFIG_X_IP_HEADER

Name of the header to use to get the source IP. If not defined, the actual source IP will be used.

The request will be allowed if the header is not present or contains no valid IP.

ip_header_position

Environment variable: BOUNCER_WAF_CONFIG_X_IP_HEADER_POSITION

If the header used to get the source IP is a comma-separated list, this parameter can be used to specify which part of the list should be used.

Must be one of FIRST, LAST, ANY.

Required when ip_header is defined.

capacity

Environment variable: BOUNCER_WAF_CONFIG_X_CAPACITY

Capacity of the rule group created by the bouncer.

If not set, default to 300 (this value is way higher than it needs to be, but this prevents any kind of issue regarding capacity of the rule group).

For reference, a simple match on a IP with no custom header will cost 1 WCU per IPSet created by the bouncer, or 5 WCU if you are getting the source IP from a header.

See AWS WAF documentation for more information.

cloudwatch_enabled

Environment variable: BOUNCER_WAF_CONFIG_X_CLOUDWATCH_ENABLED

Whether or not AWS WAF will send metrics to CloudWatch for the rule group.

cloudwatch_metric_name

Environment variable: BOUNCER_WAF_CONFIG_X_CLOUDWATCH_METRIC_NAME

Name of the cloudwatch metric. Default to the rule group name.

sample_requests

Environment variable: BOUNCER_WAF_CONFIG_X_SAMPLE_REQUESTS

Whether or not to sample requests from the rule groups created by the bouncer.