Get started
On Free plans, the leaked credentials detection is enabled by default, and no action is required. On paid plans, you can turn on the detection in the Cloudflare dashboard or via API.
- Log in to the Cloudflare dashboard ↗, and select your account and domain.
- Go to Security > Settings.
- Under Incoming traffic detections, turn on Leaked credentials.
Enable the feature using a POST request similar to the following:
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/leaked-credential-checks" \--header "X-Auth-Email: <EMAIL>" \--header "X-Auth-Key: <API_KEY>" \--header "Content-Type: application/json" \--data '{ "enabled": true }'Use Security Analytics and HTTP logs to validate that the WAF is correctly detecting leaked credentials in incoming requests.
Refer to Test your configuration for more information on the test credentials you can use to validate your configuration.
Alternatively, create a WAF custom rule like the one described in the next step using a Log action (only available to Enterprise customers). This rule will generate firewall events (available in Security > Events) that will allow you to validate your configuration.
If you are on a Free plan, deploy the suggested rate limiting rule template available in WAF > Rate limiting rules. When you deploy a rule using this template, you get instant protection against IPs attempting to access your application with a leaked password more than five times per 10 seconds. This rule can delay attacks by blocking them for a period of time. Alternatively, you can create a custom rule.
Paid plans have access to more granular controls when creating a WAF rule. If you are on a paid plan, create a custom rule that challenges requests containing leaked credentials:
| Field | Operator | Value |
|---|---|---|
| User and Password Leaked | equals | True |
If you use the Expression Editor, enter the following expression:
(cf.waf.credential_check.username_and_password_leaked)Rule action: Managed Challenge
This rule will match requests where the WAF detects a previously leaked set of credentials (username and password). For a list of fields provided by leaked credentials detection, refer to Leaked credentials fields.
Combine with other Rules language fields
You can combine the previous expression with other fields and functions of the Rules language. This allows you to customize the rule scope or combine leaked credential checking with other security features. For example:
-
The following expression will match requests containing leaked credentials addressed at an authentication endpoint:
Field Operator Value Logic User and Password Leaked equals True And URI Path contains /admin/login.phpExpression when using the editor:
(cf.waf.credential_check.username_and_password_leaked and http.request.uri.path contains "/admin/login.php") -
The following expression will match requests coming from bots that include authentication credentials:
Field Operator Value Logic Authentication detected equals True And Bot Score less than 10Expression when using the editor:
(cf.waf.auth_detected and cf.bot_management.score lt 10)
For additional examples, refer to Mitigation examples.
Additionally, you may want to handle leaked credentials detected by Cloudflare at your origin server.
-
Turn on the Add Leaked Credentials Checks Header managed transform.
-
For requests received at your origin server containing the
Exposed-Credential-Checkheader, you could redirect your end users to your reset password page when detecting previously leaked credentials.
To check for leaked credentials in a way that is not covered by the default configuration, add a custom detection location.
-
Log in to the Cloudflare dashboard ↗, and select your account and domain.
-
Go to Security > Settings.
-
Under Incoming traffic detections, select Leaked credentials and then select Add custom username and password location.
-
In Username location and Password location (optional), enter expressions for obtaining the username and the password from the HTTP request. Refer to the following example expressions:
Request type Username location / Password location JSON body lookup_json_string(http.request.body.raw, "user")lookup_json_string(http.request.body.raw, "secret")URL-encoded form url_decode(http.request.body.form["user"][0])url_decode(http.request.body.form["secret"][0])Multipart form url_decode(http.request.body.multipart["user"][0])url_decode(http.request.body.multipart["secret"][0])Refer to the
lookup_json_string()andurl_decode()documentation for more information on these functions. -
Select Save.
Use a POST request similar to the following:
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/leaked-credential-checks/detections" \--header "X-Auth-Email: <EMAIL>" \--header "X-Auth-Key: <API_KEY>" \--header "Content-Type: application/json" \--data '{ "username": "lookup_json_string(http.request.body.raw, \"user\")", "password": "lookup_json_string(http.request.body.raw, \"secret\")"}'This pair of lookup expressions (for username and password) will scan incoming HTTP requests containing a JSON body with a structure similar to the following:
{"user": "<username>", "secret": "<password>"}Refer to the lookup_json_string() documentation for more information on this function.
You only need to provide an expression for the username in custom detection locations.
Cloudflare provides a special set of case-sensitive credentials for testing the configuration of the leaked credentials detection.
After enabling and configuring the detection, you can use the credentials mentioned in this section in your test HTTP requests.
Test credentials for users on a Free plan (will also work in paid plans):
- Username:
CF_LEAKED_USERNAME_FREE - Password:
CF_LEAKED_PASSWORD
Test credentials for users on paid plans (will not work on Free plans):
- Username:
CF_EXPOSED_USERNAMEorCF_EXPOSED_USERNAME@example.com - Password:
CF_EXPOSED_PASSWORD
The Cloudflare WAF considers these specific credentials as having been previously leaked. Use them in your tests to check the behavior of your current configuration.