Skip to main content

AWS WAF

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.

CrowdSec ConsoleCrowdSec Console