Score collection

How to enable bot score calculation for selected traffic.

We recommend configuring score collection for every page that users open in a browser. This gives you control over how strict filtering is without any drawbacks, including no impact on UX.

Available only in Anti-bot mode.

This feature is enabled on request. If the Score collection tab in Custom rules is inactive in the UI, contact support to enable it.

About the rule group

Description

Score collection is a group of rules that lets you specify the traffic for which to perform two operations:

  1. Return a JS challenge—send the request source a special script that collects attributes of its browser environment.

  2. Calculate a JS score for a source that completes the JS challenge—a number from 0 to 1 that shows how similar the source is to a bot.

You may also see the term bot score in the UI. It means the same as JS score. This article uses bot score from this point on.

Why it is useful

You can control how strict traffic filtering is. Here is how it works:

  1. Configure the following:

    • Score collection rules—specify the traffic for which to calculate a bot score.

    • Bot classification rules—specify a bot score threshold. Sources whose bot score equals or exceeds the threshold are recognized as bots. You can set different thresholds for different traffic, making filtering less strict in some cases and stricter in others.

  2. Users send requests to your resource.

  3. When protection receives a request that matches your score collection rules, it checks whether the source, or client, has completed a JS challenge recently:

    • If it has, protection uses the bot score calculated earlier.

    • If it has not, protection returns a JS challenge in response to the request.

      As an exception, allowlisted traffic, such as requests from an IP address on the white list, does not receive a JS challenge and does not have a bot score calculated. This traffic is passed to the resource immediately, without additional checks.
  4. The request source completes the JS challenge:

    • If it succeeds, protection calculates its bot score.

    • If it does not succeed, protection immediately blocks the request.

  5. Protection compares the resulting bot score with the threshold you set. If the bot score:

    • Is below the threshold, the request passes the filter. Protection checks it against other filtering policies and forwards it to your resource if everything is in order.

    • Equals or exceeds the threshold, the source is considered a bot. Protection blocks its request unless an exception applies.

      Exceptions
      • The request matches an enforcement rule that you created. In the rule settings, you specify what to do with this request: pass it, block it, return a cookie challenge, return a JS challenge, or return a CAPTCHA.

      • The request reaches a location where Anti-bot mode is disabled. Such a request may be passed.

FAQ

Why does score collection not affect UX?

A JS challenge takes a fraction of a second, is not displayed in the UI, and is completed by the browser automatically. The user cannot tell the difference between loading a page with a JS challenge and loading one without it.

What is a JS challenge?

A JS challenge is a page with JavaScript code that includes a small mathematical task and collects environment attributes:

  • browser window size;

  • graphics card attributes;

  • whether virtualization is used;

  • support for and operation of different browser APIs;

  • other attributes.

The request source must send the correct answer to the task for the JS challenge to be considered complete. The answer is sent together with the environment attributes. Protection analyzes them and calculates the source’s bot score.

What happens if a request source does not complete a JS challenge?

Protection blocks its request.

What is a bot score?

A bot score is a numerical assessment of how similar a request source is to a bot—that is, how similar its technical and behavioral attributes are to signs of automation.

What values can a bot score have, and what do they mean?

From 0 to 1 in increments of 0.1:

  • 0—there are no signs of automation.

  • From 0.1 to 0.9—there are signs of automation. The higher the value, the more signs there are.

  • 1—obvious automation.

You can consider 0.5 to be a mid-range value.

How does protection calculate a bot score?

The process has five stages:

  1. The user sends a request.

  2. Protection analyzes request telemetry at the L3/L4–L7 levels: it assesses how the request passes through the network, how the connection is established, and what is transmitted over HTTP. It uses this data later.

    Examples of attributes
    • Signs of statistical anomalies.

    • Request source reputation.

    • HTTP request parameters.

    • TLS connection parameters.

    • Other attributes that help identify the nature of traffic.

  3. Protection sends the user a JS challenge—a page with JavaScript code that gives the browser a small mathematical task and collects client environment attributes.

    Examples of environment attributes
    • Browser window size.

    • Graphics card attributes.

    • Whether virtualization is used.

    • Support for and operation of different browser APIs.

    Allowlisted traffic, such as requests from an IP address on the white list, does not receive a JS challenge and does not have a bot score calculated. This traffic is passed to the resource immediately, without additional checks.
  4. The user’s browser runs the JavaScript code: it sends the answer to the task and the collected environment attributes.

  5. Protection checks the answer.

    If the answer does not arrive or is incorrect, no bot score is generated, and protection immediately blocks the request.

    If the answer is correct, protection analyzes the client environment attributes and compares them with the information received in step 2. It calculates the source’s bot score from all collected data.

Once the bot score is generated, protection compares it with the threshold you set on the Bot classification tab. If the value equals or exceeds the threshold, the source is marked as a bot.

Is a bot score calculated for every source?

No. It is calculated only for sources that receive a JS challenge from protection and complete it successfully.

If I do not configure score collection, will protection still calculate bot scores for some request sources?

Yes, but only for a small share of all traffic.

A bot score is calculated for every source that completes a JS challenge. By default, protection returns this challenge in response to some requests according to the current filtering policy and the enforcement rules you configure.

If a source has already completed a JS challenge and received a bot score, does it need to do it again?

No, if the bot score result is still recent.

In this case, protection uses the score that has already been calculated. For example, if a user visits several pages with score collection configured within a short time, the user receives a JS challenge only on the first page.

Recommendations

  • Enable score collection on every page that users open in a browser. This gives you control over how strict filtering is without any drawbacks.

  • Do not enable score collection for AJAX locations. With AJAX, the request is initiated by JavaScript code that expects a specific response format. If it receives a JS challenge instead, the code cannot process it correctly or perform the required action.

  • Do not enable score collection for URLs accessed outside a browser, such as an API that external systems must call. A request source must be able to process the JS script, but many automated systems do not expect JavaScript in a response. As a result, they may not complete the JS challenge and can be blocked. This disrupts your resource.

  • After you enable a score collection rule, check its operation in Request logs. Make sure the JS challenge does not interfere with your integrations or other useful automation.

  • Use Bot classification to set the bot score threshold at which protection starts considering a source to be a bot.

  • If you want to specify what protection must do with traffic from bots—block it, pass it, or return one of the challenges—configure Enforcement.

Configuration

Open Score collection

Go to Application protection → Resources. For the required resource, click the ellipsis (…) and select Custom rules. The page that opens contains the Score collection tab.

Create a score collection rule

  1. Click + Create score collection rule. The rule creation window opens. Complete the remaining steps there.

  2. Specify the Position and Description.

    Configure the position and description

    Position is the rule’s place in the list. It helps organize rules in the UI but does not affect how they work. You can use any number.

    Description is the name you give the rule. We recommend stating the traffic for which you configure the rule. Example: Login page.

  3. Configure the Conditions.

    Enable score collection only for pages that users open in a browser.

    You can configure two types of conditions:

    • Traffic—the request attributes for which protection must return a JS challenge and calculate the source’s bot score.

    • DDoS status—whether score collection must depend on whether your resource is currently under a DDoS attack.

    Score collection applies to requests that meet all conditions at the same time. For example, you set the traffic conditions Country—Germany and URL path starts with /login, and the DDoS status to During DDoS attack. Protection checks:

    • Does the request come from an IP address in Germany?

    • Is the request directed to /login?

    • Is a DDoS attack currently in progress?

    If the answer to all three questions is yes, protection returns a JS challenge and calculates the source’s bot score. If at least one condition is not met, it does neither.

    • Traffic

    • DDoS status

    Example traffic settings

    To add a condition, click + Add condition, select a parameter such as URL path, select a comparison operator such as starts with, and specify a value such as /login.

    The tables below provide entry rules, limits, and examples for parameters, as well as a description of operators. Click a heading to expand its text.

    Description of each parameter
    Parameter name Parameter description Value requirements Condition example

    Country

    The geographical location of the source IP address.

    Select a value from the drop-down list.

    Country in Germany

    Query string

    Parameters specified in the URL after the ? character.

    • You can add up to 100 values to one condition (use the + Or button).

    • You can specify only a key or a key-value pair.

    • The string length must be from 1 to 200 characters.

    • Do not start the string with a space, /, or ?.

    • Use only characters allowed in URLs.

    • Specify special characters in percent-encoding format. For example, use %2F instead of /.

    Query string contains debug=true

    URL path

    The request URL path, the part of the URL after the domain and before the ? character.

    • Always start the string with /.

    • Do not specify a domain name, for example site.com.

    • Do not specify a protocol, for example https://.

    • Do not add parameters after the ? character.

    • Use only characters allowed in URLs.

    URL path starts with /admin

    URL path segment

    Any part of a URL path between / characters.

    • You can add up to 100 values to one condition (use the + Or button).

    • The value length is from 1 to 200 characters.

    • You can specify a section name, such as api, or a file extension, such as .php.

    • Do not use the / character.

    URL path segment contains backup

    Content-Type

    The format of the data sent in the request, such as JSON, plain text, images, or web form data.

    • You can add up to 100 values to one condition (use the + Or button).

    • The value length must be from 1 to 200 characters.

    • Do not start the string with a space.

    • Specify the full type or part of it.

    Content-Type equals application/json

    Cookie_any (or)

    Cookie names and values. The rule applies when the request contains at least one specified name-value pair.

    • You can add up to 100 name-value pairs to one condition (use the + Or button).

    • The name length must not exceed 200 characters.

    • The value length must not exceed 4,096 characters.

    Name equals user_type

    Value starts with premium

    OR

    Name equals partner_id

    Value equals any

    Cookie_all (and)

    Cookie names and values. The rule applies when the request contains the entire set of specified name-value pairs at the same time.

    • You can add up to 100 name-value pairs to one condition (use the + And button).

    • The name length must not exceed 200 characters.

    • The value length must not exceed 4,096 characters.

    Name equals promo_code

    Value equals active

    AND

    Name equals is_subscriber

    Value equals yes

    Header

    Names and values of HTTP headers.

    Parameter details
    • Different headers use AND logic: the request must contain all specified name-value pairs.

    • Multiple values for the same header use OR logic: it is enough for one of them to match.

    • These conditions work together: different headers use AND logic, while multiple values of one header use OR logic.

    Example. You specify the headers X-Env: prod, X-Region: eu, and X-Region: us. If the request contains:

    • X-Env: prod and X-Region: eu, the rule applies;

    • X-Env: prod and X-Region: us, the rule applies;

    • only X-Env: prod, the rule does not apply;

    • only X-Region: eu, the rule does not apply.

    • You can add up to 100 name-value pairs to one condition (use the + Or button).

    • The name length must not exceed 200 characters.

    • The value length must not exceed 200 characters.

    Name equals X-App-Version

    Value starts with 2.0

    Host

    The value of the Host header: the domain name of the server that the client requests.

    • You can add up to 100 values to one condition (use the + Or button).

    • The value length must not exceed 200 characters.

    • Do not start the string with a space.

    • Specify the full domain or part of it.

    • Do not specify a protocol, for example https://.

    • Do not specify a path, for example /main.

    Host equals api.site.com

    Hosting subnet

    Traffic from IP addresses that belong to hosting providers or data centers.

    Not set.

    —

    Request method

    The type of HTTP method used.

    Select one or more methods from the drop-down list.

    Request method in POST

    Referer

    The value of the Referer header: the address of the page from which the user came to your resource.

    • You can add up to 100 values to one condition (use the + Or button).

    • The value length must not exceed 200 characters.

    • Specify the full URL, a domain, or part of it.

    • Do not start the string with a space.

    • Use only characters allowed in URLs.

    Referer starts with google.com

    ASN

    The autonomous system number (ASN) to which the source IP address belongs.

    • Use a number with the AS prefix, for example AS13335 or as13335.

    • The number must contain from 1 to 10 digits.

    • You can specify up to 100 unique numbers in one field.

    • The same number cannot be specified in both the in and not in lists.

    ASN in AS15169

    Hashes

    A unique device fingerprint (hash), with one of three available accuracy levels: Strictera hash (loose), Strictera hash (medium), or Strictera hash (strict).

    • You can add up to 100 values to one condition (use the + Or button).

    • The value must be a positive number from 1 to 200 characters long.

    Strictera hash (strict) in 1234567890

    Request from a new user

    Traffic from users who visit the resource for the first time and whose device fingerprint (hash) has not yet been recorded in our database.

    Not set.

    —

    Source subnets

    The sender’s IP address or subnet.

    • You can add up to 200 values to one condition (use the + Or button).

    • Specify individual IP addresses or their ranges (subnets).

    • You can specify IPv4 addresses, for example 192.168.1.1, and IPv6 addresses, for example 2001:db8::1.

    • To specify ranges, use CIDR notation with a slash, for example /24 for a whole network or /32 for one address.

    Source subnets in 192.168.1.0/24 or 2001:db8::1

    User-Agent

    The value of the User-Agent header: an identifier of the browser, device, or software client that sends the request.

    • You can add up to 100 values to one condition (use the + Or button).

    • The value length must not exceed 200 characters.

    • Do not start the string with a space.

    • Use the required letter case, for example Chrome and chrome are different values.

    User-Agent equals BadBot/1.0

    X-Forwarded-For

    The value of the X-Forwarded-For header: the chain of proxy server IP addresses through which the request passed before reaching your resource.

    • You can add up to 100 values to one condition (use the + Or button).

    • The value length must not exceed 200 characters.

    • Do not start the string with a space.

    • Specify individual IP addresses or their ranges.

    X-Forwarded-For contains 203.0.113.10

    Tor (The Onion Router)

    Traffic from the Tor network, which hides the source’s real IP address.

    Not set.

    —

    Description of operators
    The available operators depend on the selected parameter.
    Operator When the rule applies

    equals

    When the value matches exactly.

    Example: you specify URL path equals /login. The rule applies to a request for /login but not to a request for any other path, including a nested path such as /login/reset.

    does not equal

    When the value does not match the specified value.

    Example: you specify Host does not equal api.example.com. The rule applies to requests for other hosts, such as example.com, www.example.com, or admin.example.com. It does not apply to requests for api.example.com.

    contains

    When the value contains the specified character sequence.

    Example: you specify Query string contains debug=true. The rule applies only to requests whose parameters include debug=true, for example ?id=10&debug=true. The sequence must match exactly. If the parameters contain something similar but not identical, such as degub=true or debug=treu, the rule does not apply.

    does not contain

    When the value does not contain the specified character sequence.

    Example: you specify Content-Type does not contain json. The rule applies to a request with any header value that does not include json, such as text/plain, application/xml, multipart/form-data, and others. It does not apply to application/json, application/ld+json, or similar values.

    starts with

    When the value starts with the specified character sequence.

    Example: you specify URL path starts with /admin. The rule applies to requests for /admin and all nested paths: /admin/users, /admin/access, and others.

    does not start with

    When the value does not start with the specified character sequence.

    Example: you specify Host does not start with api. The rule applies to requests for hosts such as example.com, www.example.com, and admin.example.com, whose names do not start with api. It does not apply to api.example.com or api-test.example.com.

    ends with

    When the value ends with the specified character sequence.

    Example: you specify URL path segment ends with .php. The rule applies to values login.php, index.php, and profile.php. It does not apply to login.html, index.js, or php-login: the specified sequence must be at the end of the value.

    does not end with

    When the value does not end with the specified character sequence.

    Example: you specify X-Forwarded-For does not end with 10. The rule applies to requests where the header value ends with other characters, such as 192.0.2.15 or 198.51.100.25. It does not apply to values 192.0.2.10, 203.0.113.10, or other values ending in 10.

    in

    When the value belongs to the specified list.

    Example: you specify Request method in GET, POST. The rule applies to requests with one of these methods. It does not apply to requests using PUT, DELETE, PATCH, or other methods that are not in the list.

    not in

    When the value does not belong to the specified list.

    Example: you specify Country not in Germany, France. The rule applies to requests from all countries except Germany and France.

    empty

    When the parameter has no value.

    Example: you specify Content-Type empty. The rule applies to requests where the Content-Type header is not passed. If the header is present and contains any value, such as application/json or text/plain, the rule does not apply.

    not empty

    When the parameter has a value.

    Example: you specify Content-Type not empty. The rule applies to requests where the Content-Type header contains any value, such as application/json or text/plain. If the header is not passed, the rule does not apply.

    any

    With any parameter value.

    Example: you specify Cookie_all (and): Name—session, Value—any. The rule applies when the request contains a session cookie with any value. If the request has no cookie with this name, the rule does not apply.

    DDoS status settings

    Choose when the rule must apply: Always, While no attack, or During DDoS attack.

  4. Click Create.

    The rule appears in the list on the Score collection tab. To activate it, turn on the switch in the Enabled column. It must turn white.

    Enable and disable a rule

Configuration example

Task: collect bot scores for sources that open catalog pages.

Configuration:

  1. Rule description: Catalog.

  2. Traffic conditions:

    • Parameter: URL path.

    • Operator: starts with.

    • Value: /catalogue/.

  3. DDoS status: Always.

Protection returns a JS challenge for requests to the catalog. After the challenge is completed, it calculates the source’s bot score.

Management

On the Score collection tab, you can manage rules directly in the list:

  • Move: use the six-dot icon (⠿) to change the rule’s position in the list. This changes only the display order in the UI and does not affect how the rule works.

  • View details: use the > icon to view all rule conditions without entering edit mode.

  • Enable or disable: use the switch in the Enabled column. White means the rule is active and collects bot scores; gray means it is inactive.

  • Edit: click the ellipsis (…) at the end of the row and select Edit. You can change any rule parameter there.

  • Delete: click the ellipsis (…), select Delete, and confirm the action. A deleted rule cannot be restored.

Actions for rules