Brute force attack preventions

This topic describes how to configure brute force attack prevention in F5 WAF for NGINX.

Brute force attacks try many combinations of usernames and passwords to access a protected application. To detect these attacks, F5 WAF for NGINX tracks failed login attempts for configured login pages.

When a threshold is reached, the policy can log the attack, challenge the client with client-side integrity, or challenge the client with CAPTCHA.

User-defined URLs

To protect a login endpoint, define it as a user-defined URL.

"urls": [
  {
    "method": "*",
    "name": "/html_login",
    "protocol": "http",
    "type": "explicit"
  }
],

Login pages

A login page identifies the endpoint that users submit credentials to. It also defines how F5 WAF for NGINX determines whether a login attempt succeeded or failed.

The accessValidation object is required for brute force protection. You can use fields such as responseContains, responseOmits, or HTTP status checks to classify the login result.

"login-pages": [
  {
    "accessValidation": {
      "responseContains": "Success"
    },
    "authenticationType": "form",
    "url": {
      "method": "*",
      "name": "/html_login",
      "protocol": "http",
      "type": "explicit"
    },
    "usernameParameterName": "username",
    "passwordParameterName": "password"
  }
]

For more information, see the login-pages section of the parameter reference.

Mitigation actions

Use the following action values for loginAttemptsFromTheSameUser, loginAttemptsFromTheSameIp, and loginAttemptsFromTheSameDeviceId:

• alarm logs the brute force event and allows the request.
• alarm-and-client-side-integrity serves a JavaScript challenge to verify that the client behaves like a browser.
• alarm-and-captcha serves a CAPTCHA challenge to verify that the client is operated by a human user. This action requires a generated challenge pool.

Configure brute force challenges

1. Define the login endpoint in urls.
2. Add the same endpoint to login-pages.
3. Configure accessValidation so F5 WAF for NGINX can classify successful and failed logins.
4. With bruteForceProtectionForAllLoginPages, decide whether the brute force settings apply to all login pages or only one page.
5. Set thresholds for loginAttemptsFromTheSameUser, loginAttemptsFromTheSameIp, or loginAttemptsFromTheSameDeviceId, depending on how you want to track failed login activity.
6. Choose a mitigation action: alarm, alarm-and-client-side-integrity, or alarm-and-captcha.
7. Tune the timing fields for detection, mitigation, and re-enable behavior.
8. If needed, configure bypass behavior for the selected challenge type.

Client-side integrity example

The following example applies client-side integrity to all configured login pages.

{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": true,
        "loginAttemptsFromTheSameIp": {
          "action": "alarm-and-client-side-integrity",
          "enabled": true,
          "threshold": 3
        },
        "loginAttemptsFromTheSameUser": {
          "action": "alarm-and-client-side-integrity",
          "enabled": true,
          "threshold": 3
        },
        "clientSideIntegrityBypassCriteria": {
          "action": "alarm-and-captcha",
          "enabled": false,
          "threshold": 1
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}

In this example:

• loginAttemptsFromTheSameUser challenges repeated failures for the same username.
• loginAttemptsFromTheSameIp challenges repeated failures from the same source IP address.

CAPTCHA example

The following example protects a specific login page with CAPTCHA.

{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": false,
        "url": {
          "method": "*",
          "name": "/html_login",
          "protocol": "http"
        },
        "loginAttemptsFromTheSameIp": {
          "action": "alarm-and-captcha",
          "enabled": true,
          "threshold": 3
        },
        "loginAttemptsFromTheSameUser": {
          "action": "alarm-and-captcha",
          "enabled": true,
          "threshold": 3
        },
        "captchaBypassCriteria": {
          "action": "alarm-and-drop",
          "enabled": false,
          "threshold": 5
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}

To protect browser login pages with human verification, use the CAPTCHA example in [section name]. This option replaces a client-side integrity challenge.

Important

CAPTCHA actions have two requirements:

• Make a challenge pool available when you compile your policy. Otherwise, the bundle contains no challenges.
• If your virtual server serves plain HTTP, set secureAttribute to never. If you don’t, the browser discards the enforcer state cookie, and the client can’t pass the challenge.

For more information, see Cookie enforcement.

Device ID examples

Use the following examples to track failed logins by device identifier instead of username or source IP address:

Client-side integrity

{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": false,
        "url": {
          "method": "*",
          "name": "/html_login",
          "protocol": "http"
        },
        "loginAttemptsFromTheSameDeviceId": {
          "action": "alarm-and-client-side-integrity",
          "enabled": true,
          "threshold": 3
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}

CAPTCHA

{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": false,
        "url": {
          "method": "*",
          "name": "/html_login",
          "protocol": "http"
        },
        "loginAttemptsFromTheSameDeviceId": {
          "action": "alarm-and-captcha",
          "enabled": true,
          "threshold": 3
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}

When the brute-force configuration applies to one login page, set url. If bruteForceProtectionForAllLoginPages is set to true, omit url.

More information

For more information, see the brute-force-attack-preventions section of the parameter reference.