Rules

A rule sets the conditions for selection of HTTP requests and the action applied to them. If a request satisfies several rules, the resulting action is determined by their priorities.

For setup instructions, see Rule management.

Types of rulesTypes of rules

Yandex Smart Web Security provides the following rule types:

• Basic
• Smart Protection
• Web Application Firewall
• Advanced Rate Limiter

There is also an internal service rule which can trigger during attacks.

Basic rulesBasic rules

A basic rule allows you to manage access based on HTTP request parameters, e.g., client's IP address, request path, or headers. Requests can be allowed, denied, or sent to a CAPTCHA page. For example, you can allow requests from trusted IP addresses or activate a CAPTCHA check for the login page.

Each security profile has a basic default rule with the lowest priority. It allows or denies requests not covered by the conditions of the other rules of the profile.

Smart Protection rulesSmart Protection rules

Smart Protection analyzes traffic based on specified criteria using machine learning algorithms and behavioral analysis. This rule provides Layer 7 DDoS protection and supports full protection and API protection.

WAF + Smart Protection rulesWAF + Smart Protection rules

The Web Application Firewall (WAF) rule connects a WAF profile with basic rule sets for traffic analysis. It also includes Smart Protection and supports the same actions. With WAF connected, no separate Smart Protection rule for the same traffic is required.

Advanced Rate Limiter rulesAdvanced Rate Limiter rules

An Advanced Rate Limiter (ARL) rule limits the number of requests over a specific time period. You can set the limit for all traffic or its specific segments.

Rules are configured in a separate ARL profile, which is linked to the security profile. Available actions apply to requests in excess of the limit.

Rule actionsRule actions

Available actions depend on the rule type. Requests permitted by all rules and allowed to reach the protected resource are called legitimate.

You can create custom response templates to ensure a consistent format of responses triggered by rules.

Basic rulesBasic rules

For basic rules, you can select the following actions:

• Deny: Block requests.
• Allow: Skip requests.
• Show CAPTCHA: Redirect the client to a CAPTCHA.

Smart Protection and WAFSmart Protection and WAF

There are two modes available for Smart Protection and WAF rules:

• Full protection: Suspicious requests are sent for one of the following checks: JS challenge, cookie challenge, or CAPTCHA. Smart Protection automatically selects a check based on its request analysis.
• API protection: Requests are not sent for additional checks, but protection policies block obvious attack attempts. In this mode, a request that would be sent for a check in full protection mode can be allowed to access the resource.

Use the API protection mode for endpoints:

• Of mobile apps.
• With automated calls.
• With dynamic content loading (ajax, xhr, iframe).

Advanced Rate LimiterAdvanced Rate Limiter

For requests exceeding the limit, you can select the following actions:

• Block requests exceeding the limit: Block requests until the end of the limit period.
• Temporarily block all requests: Block requests for a fixed period from 1 second to 24 hours after the limit is exceeded.
• Send to CAPTCHA requests exceeding the limit: Redirect the client to SmartCaptcha.

On blocking, the client gets the 429 error. CAPTCHA allows you to check requests in excess of the limit without immediate blocking.

JS challenge, cookie challenge, and CAPTCHAJS challenge, cookie challenge, and CAPTCHA

In full protection mode, Smart Protection either allows the request to reach the resource or automatically selects a check for suspicious traffic.

• JS Challenge: Automatically checks the execution of JavaScript code on the client side.
• Cookie challenge: Automatically checks whether the client can save a cookie and provide it in the next request.
• CAPTCHA: Redirects the user to SmartCaptcha, where they may be required to complete a challenge.

In normal mode, only unmistakably robotic requests go to CAPTCHA, which Smart Protection can see by their high Bot score. The rest of the requests are either redirected to a JS or cookie challenge or allowed through without any additional check.

A successful JS or cookie challenge does not prove that the request was sent by a human: automated browsers also support JavaScript and cookies. Moreover, if JavaScript or cookies are disabled, even a legitimate client may fail the check.

Configuring CAPTCHAConfiguring CAPTCHA

All rules that forward requests to a CAPTCHA use the CAPTCHA from the security profile. The following options are available:

• Default: Managed by Yandex Cloud. This CAPTCHA has the following settings:

  • Main challenge: Checkbox.
  • Additional challenge: Silhouettes.
  • Additional challenge difficulty: Easy.
  • Appearance: Standard.

  The Default CAPTCHA usage fee is included in the cost of Smart Web Security.

• Custom CAPTCHA: You can customize CAPTCHA's difficulty, types of main and additional challenges, and appearance.

  Note

  To use a custom CAPTCHA, select Disable domain verification in its settings.

  The custom CAPTCHA usage fee is charged according to the SmartCaptcha pricing policy.

Rule application modesRule application modes

For each security profile rule, you select a set of protection modes it operates in:

• All modes (default).
• Enhanced protection and Under attack.
• Under attack.

When you switch the profile mode, the selected rule set becomes active.

Application modes are set when adding or modifying a rule and displayed in the profile rule table.

General principles of rulesGeneral principles of rules

First, requests are processed by the security profile rules. Then, the allowed requests are checked by the ARL profile rules, if there is an ARL. The priorities in these profiles are independent of each other.

Security profileSecurity profile

Set the rule priority using a number from 1 to 1000000. Rules active in the current protection mode will trigger simultaneously. One request may be subject to several rules. The final action is determined by the highest priority rule.

Assign higher priority to:

• Rules that allow requests.
• Rules with filtering conditions based on specific parameters.

Otherwise, general rules with broader conditions may apply.

Security profile rules apply to traffic based on priority: the lower the number, the higher the priority.

Recommended order of priority

1. Allowing rule for captcha service routes.
2. Allowing rules with traffic conditions.
3. Blocking rules with traffic conditions.
4. Smart Protection and WAF + Smart Protection rules in API protection mode with traffic conditions for endpoints where you cannot show captcha.
5. Smart Protection and WAF + Smart Protection rules in Full protection mode with traffic conditions.
6. Smart Protection and WAF + Smart Protection rules in Full protection mode for the whole traffic.

Rule configuration example

Priority	Rule name	Action	Rule description
8000	allow-captcha	Allow	Rule to allow captcha service routes
9000	allow-by-list	Allow	Basic for white IP addresses
9100	block-by-list	Deny	Basic for black IP addresses
9200	block-by-geo	Deny	Basic by regions
900000	api-protection	API protection	Smart Protection for the public API
999900	sp-rule-1	Full protection	Smart Protection from a ready-made template
1000000		Allow	Basic default

The Allow action is set for the basic default rule, while other rules are in the Only logging mode. When switching rules to regular operation mode, set the Deny action for the basic default rule.

ARL profileARL profile

ARL rules can block requests permitted by the security profile. If this traffic needs not be limited, exclude it from the ARL rule conditions.

The lower the number, the higher the ARL rule priority. You can choose any priority values​ at will. Rule order example:

Priority	Rule name	Action	Rule description
1,000	arl-rule-1	Block requests in excess of the limit	Limits general load on resource
2,000	arl-rule-2	Temporarily block all requests	Protects against bots, parsers, brute-force attacks, spam
3,000	arl-rule-3	Send requests in excess of limit to captcha	Checks browser clients if the limit is exceeded

Logging only modeLogging onlymode

The Logging only mode allows you to check rule conditions and priorities prior to enabling protection. This rule logs information about matching requests but does not apply an action to them. For ARL rules, limit violations are logged.

Such rules do not affect traffic processing: the next suitable highest priority rule applies for which protection is enabled. Thus, a Smart Protection rule in the Logging only mode does not protect against DDoS attacks.

For security profile rules, the dry_run_matched_rule_verdict field contains the expected rule action in the Logging only mode. The actual action performed with the request is in the action field. Learn more about log fields and rule filters in logging mode.

Service ruleService rule

For enhanced protection from attacks, Smart Web Security can block malicious requests even if the security profile allows them. The rest of the requests are processed according to the profile settings.

Service rule trigger events get logged with the sws_service_rule label. Log examples:

• In Smart Web Security:

  matched_rule_name: "sws_service_rule",
  matched_rule_type: "SMART_PROTECTION",
  matched_rule_verdict: "DENY",
  

• In Yandex Application Load Balancer:

  "matched_rule": {
    "dry_run": "false",
    "rule_name": "sws_service_rule",
    "rule_type": "SMART_PROTECTION",
    "verdict": "DENY"
  }