# Access Rules

Access Rules are your first line of defense against unwanted traffic. They're the security layer of smoxy, evaluated before all other rules and before the Web Application Firewall (WAF), giving you precise control over who can access your site and how.

### What are Access Rules?

Access Rules let you control access to your site based on request characteristics like IP addresses, geographic location, user agents, headers, and more. They're specifically designed for security decisions and execute before any other processing happens.

**Key characteristics:**

* Execute **first** in the rule sequence (before Rewrite, Page, and Conditional Rules)
* Run **before WAF** processing
* Focus on **security actions**: allow, block, challenge, or skip specific protections
* Evaluated in **position order** (1, 2, 3...)
* **All matching rules apply** - multiple rules can affect the same request
* **Optional Stop Mode** - halt further evaluation when needed

### How Access Rules Work

Access Rules are evaluated in ascending position order (1 → 2 → 3...) for every incoming request. When a rule's conditions match, its action is applied, and evaluation **continues** to the next rule (unless Stop Mode is enabled).

#### Position-Based Evaluation

```
Request arrives
    ↓
Access Rule (Position 1) → Match? → Apply Action → CONTINUE
    ↓
Access Rule (Position 2) → Match? → Apply Action → CONTINUE
    ↓
Access Rule (Position 3) → Match + Stop Mode? → Apply Action → STOP
    ↓ (no match or no stop)
Access Rule (Position 4) → Match? → Apply Action → CONTINUE
    ↓
Continue to Rewrite Rules...
```

**Important:** All Access Rules are evaluated unless a matching rule has Stop Mode enabled. This allows you to build layered security policies where multiple rules can apply to the same request.

### Stop Mode

The **Stop Mode** option controls whether evaluation continues after a rule matches.

#### How Stop Mode Works

**When Stop Mode is disabled (default):**

* Rule's action is applied
* Evaluation continues to the next Access Rule
* Multiple rules can affect the same request

**When Stop Mode is enabled:**

* Rule's action is applied
* **All subsequent Access Rules are skipped**
* Processing continues to Rewrite Rules

#### When to Use Stop Mode

Use Stop Mode when:

* A rule should be **final** and no further Access Rules should apply
* You want to **prevent conflicting actions** from other rules
* Trusted traffic should skip all remaining security checks

**Example:**

```
Position 1: IF (IP in office_range) THEN Allow + Stop Mode
Position 2: IF (Country = "XX") THEN Block [not evaluated for office IPs]
Position 3: IF (URI = /admin) THEN Challenge [not evaluated for office IPs]

→ Office IPs get Allow and skip all other Access Rules
```

### Actions

Access Rules support four security actions:

#### 1. Allow

**Allows the request through while bypassing all security protections**, including Under Attack mode and any future security measures that may be added.

**When to use:**

* Trusted traffic that should never be blocked by any security feature
* Requests that must bypass all current and future security measures
* Internal tools or monitoring services that need guaranteed access
* Office IPs that need full, unrestricted access

**Example:**

```
Condition: IP in [203.0.113.0/24] (trusted internal network)
Action: Allow
Stop Mode: Enabled
→ Internal traffic bypasses all security and skips remaining Access Rules
```

**Note:** Allow automatically bypasses all security measures, including any new ones added in the future. This is the most permissive action.

#### 2. Block

**Immediately blocks the request** and returns an error response.

**When to use:**

* Block known malicious IPs
* Block requests from specific countries
* Block suspicious user agents or bots
* Prevent access to sensitive areas

**Example:**

```
Condition: Country = "XX"
Action: Block
→ All requests from that country are blocked
```

#### 3. Challenge

**Presents a proof-of-work challenge** that the client must solve before proceeding. This is handled automatically by the client's browser - the user doesn't need to solve a CAPTCHA or any visual puzzle.

**When to use:**

* Protect against automated bots
* Add computational cost to suspicious traffic without completely blocking
* Protect login pages or forms from brute force attacks
* Challenge unusual traffic patterns

**Example:**

```
Condition: User Agent contains "bot" OR "crawler"
Action: Challenge
→ Suspected bots must complete a computational challenge
```

#### 4. Skip

**Bypasses specific security features** for trusted traffic, while keeping other security measures active. This action has two optional flags that can be combined.

**Skip Flags**

**`waf` flag:**

* When `true`: Bypass the Web Application Firewall for this request
* When `false`: WAF still applies

**`challenge` flag:**

* When `true`: Bypass Challenge for this request, including Under Attack Mode
* When `false`: Challenge and Under Attack Mode still apply

**When to use:**

* Bypass WAF for tools that trigger false positives
* Bypass Under Attack Mode for trusted traffic while keeping WAF active
* Fine-grained control over which security features to disable
* API clients or webhooks that need to bypass specific protections

**Examples:**

```
Condition: User Agent = "Monitoring-Tool/1.0"
Action: Skip
Flags: waf=true
→ Monitoring tool bypasses WAF only, Challenge/Under Attack still applies
```

```
Condition: IP in payment_webhook_ips
Action: Skip
Flags: challenge=true
→ Payment webhooks bypass Under Attack Mode, WAF still applies
```

```
Condition: IP in trusted_api_clients
Action: Skip
Flags: waf=true, challenge=true
→ API clients bypass both WAF and Under Attack Mode
```

**Difference from Allow:** Skip lets you choose which specific security features to bypass. Allow bypasses everything automatically, including any future security features. Use Skip when you need granular control, use Allow when you need full bypass.

### Conditions & Expressions

Access Rules use a rich condition builder that lets you match requests based on various characteristics including:

* IP addresses and IP ranges
* Geographic location (country, city, EU status)
* HTTP headers (User Agent, Referer, custom headers)
* Request properties (URI, method, host)
* Cookies and query parameters

You can combine multiple conditions using **AND/OR logic** to create sophisticated matching rules:

```
(IP in office_range OR IP in partner_ips) AND URI starts with /admin
```

The condition builder is the same system used by Conditional Rules, giving you powerful and flexible matching capabilities for your security policies.

### Best Practice Workflow

The recommended approach for Access Rules is:

#### 1. Define ALLOW Rules First (Positions 1-3)

Start by whitelisting fully trusted traffic that should bypass all security, including future features. Use **Stop Mode** to prevent further evaluation.

```
Position 1: IF (IP in office_range) THEN Allow + Stop Mode
Position 2: IF (IP in trusted_partners) THEN Allow + Stop Mode
Position 3: IF (User Agent = "internal-api-client") THEN Allow + Stop Mode
```

#### 2. Define SKIP Rules for Partial Bypass (Positions 4-6)

Next, add rules for traffic that should bypass specific security features but remain subject to others.

```
Position 4: IF (IP in monitoring_tools) THEN Skip (waf=true)
Position 5: IF (User Agent = "payment-webhook") THEN Skip (challenge=true)
Position 6: IF (IP in api_clients) THEN Skip (waf=true, challenge=true)
```

#### 3. Define BLOCK/CHALLENGE Rules Last (Positions 7+)

After whitelisting trusted traffic, add your restrictive rules. These have **higher position numbers**.

```
Position 7: IF (Country in ["XX", "YY"]) THEN Block
Position 8: IF (User Agent contains "malicious-bot") THEN Block
Position 9: IF (URI starts with "/admin") THEN Challenge
```

#### Why Stop Mode Matters

Without Stop Mode, all rules are evaluated. With Stop Mode on your Allow rules, trusted traffic skips remaining security checks:

❌ **Without Stop Mode:**

```
Position 1: Allow IP = office (no stop)
Position 2: Challenge URI = /admin
→ Office accessing /admin still gets challenged!
```

✅ **With Stop Mode:**

```
Position 1: Allow IP = office + Stop Mode
Position 2: Challenge URI = /admin
→ Office skips the challenge rule entirely
```

### Use Cases & Examples

#### Example 1: Full Access for Office IPs

**Scenario:** Your team needs full access without any security checks, including during Under Attack mode.

```
Position: 1
Condition: IP in [203.0.113.0/24, 198.51.100.50]
Action: Allow
Stop Mode: Enabled

Result: Office traffic bypasses ALL security and skips remaining Access Rules
```

#### Example 2: Block Malicious Countries with Exceptions

**Scenario:** Block traffic from countries with high bot activity, except your legitimate users.

```
Position: 1
Condition: IP = "203.0.113.45" (your VPN exit)
Action: Allow
Stop Mode: Enabled

Position: 2
Condition: Country in ["XX", "YY", "ZZ"]
Action: Block

Result: Your VPN is allowed and stops evaluation, others from those countries are blocked
```

#### Example 3: Bypass Under Attack Mode for Webhooks

**Scenario:** Your payment provider's webhooks need to reach your site even during Under Attack mode, but should still be checked by WAF.

```
Position: 1
Condition: IP in payment_provider_ips
Action: Skip
Flags: challenge=true
Stop Mode: Enabled

Result: Payment webhooks bypass Under Attack Mode but WAF still applies
```

### Using IP Lists

Instead of hardcoding IPs in each rule, create reusable IP Lists in your account settings:

1. Create an IP List named "office\_ips" with your office IP ranges
2. Reference it in your Access Rule conditions

**Benefit:** Update the IP list once, and all rules using it are automatically updated across all your sites.

### Uniqueness

Each site can only have **one Access Rule per unique expression**. If you try to create a duplicate, you'll see: "The rule for this expression already exists."

This prevents conflicting rules and keeps your configuration clean.

### Common Mistakes

❌ **Forgetting Stop Mode on Allow rules**

```
Position 1: Allow IP = office (no stop)
Position 2: Block Country = "US"
→ Office in US is allowed but then also blocked!
```

✅ **Enable Stop Mode for trusted traffic**

```
Position 1: Allow IP = office + Stop Mode
Position 2: Block Country = "US"
→ Office is allowed and skips all other rules
```

***

❌ **Using Allow when Skip is sufficient**

```
Action: Allow
→ Bypasses ALL security, including future features
```

✅ **Use Skip for granular control**

```
Action: Skip (waf=true)
→ Only bypasses WAF, other protections remain active
```

***

❌ **Forgetting challenge flag during Under Attack Mode**

```
Action: Skip (waf=true)
→ Under Attack Mode still challenges the request!
```

✅ **Add challenge flag when needed**

```
Action: Skip (waf=true, challenge=true)
→ Bypasses both WAF and Under Attack Mode
```

***

❌ **Too broad conditions**

```
Condition: URI contains "admin"
→ Affects /administrator, /admin, /admin-panel, /user-admin-settings
```

✅ **Specific conditions**

```
Condition: URI starts with "/admin/"
→ Only affects actual admin section
```

***

❌ **Conflicting actions without Stop Mode**

```
Position 1: Allow IP = partner (no stop)
Position 2: Block URI = /internal
→ Partner accessing /internal is allowed then blocked!
```

✅ **Use Stop Mode to prevent conflicts**

```
Position 1: Allow IP = partner + Stop Mode
Position 2: Block URI = /internal
→ Partner skips the block rule
```