> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TecharoHq/Anubis/llms.txt
> Use this file to discover all available pages before exploring further.

# ChallengeRules

> Challenge configuration for proof-of-work bot detection

## Overview

The `ChallengeRules` struct configures proof-of-work challenges presented to clients when a bot rule with the `CHALLENGE` action is triggered. Challenges require clients to solve computational puzzles, which legitimate browsers can complete but automated bots typically cannot.

## Type Definition

```go theme={null}
type ChallengeRules struct {
    Algorithm  string `json:"algorithm,omitempty" yaml:"algorithm,omitempty"`
    Difficulty int    `json:"difficulty,omitempty" yaml:"difficulty,omitempty"`
    ReportAs   int    `json:"report_as,omitempty" yaml:"report_as,omitempty"`
}
```

## Fields

<ParamField path="Algorithm" type="string" required>
  Challenge algorithm to use. Anubis supports multiple challenge implementations.

  Available algorithms:

  * `"fast"` - Fast proof-of-work algorithm (default)
  * `"preact"` - Preact-based interactive challenge
  * `"metarefresh"` - Meta-refresh based challenge

  The algorithm must be registered with the challenge system. Unknown algorithms will fail validation.
</ParamField>

<ParamField path="Difficulty" type="int" required>
  Computational difficulty level for the challenge. Valid range: 0-64.

  * Lower values (5-15): Easy challenges, suitable for high-traffic sites
  * Medium values (16-25): Moderate challenges, balanced protection
  * Higher values (26-40): Hard challenges, strong bot protection
  * Very high values (41-64): Very hard challenges, may impact user experience

  Default difficulty is defined by `anubis.DefaultDifficulty` (typically 20).
</ParamField>

<ParamField path="ReportAs" type="int">
  Optional HTTP status code to report in metrics when this challenge is served. Useful for tracking different challenge types separately. Does not affect the actual HTTP response code sent to clients.

  When not set, challenges use the configured challenge status code from `StatusCodes.Challenge`.
</ParamField>

## Validation Rules

The `Valid()` method enforces these constraints:

* `Algorithm` must be set (non-empty)
* `Difficulty` must be greater than or equal to 0
* `Difficulty` must be less than or equal to 64

### Errors

```go theme={null}
var (
    ErrChallengeDifficultyTooLow  = errors.New("config.ChallengeRules: difficulty is too low (must be >= 0)")
    ErrChallengeDifficultyTooHigh = errors.New("config.ChallengeRules: difficulty is too high (must be <= 64)")
    ErrChallengeMustHaveAlgorithm = errors.New("config.ChallengeRules: must have algorithm name set")
)
```

## Usage Examples

### Basic Challenge Configuration

```yaml theme={null}
bots:
  - name: Challenge suspicious traffic
    expression: "weight > 10"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 20
```

### High-Security Challenge

```yaml theme={null}
bots:
  - name: Strong bot protection
    path_regex: "/api/.*"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 35
      report_as: 429  # Track as rate-limiting in metrics
```

### Easy Challenge for Known Bots

```yaml theme={null}
bots:
  - name: Verify legitimate crawlers
    user_agent_regex: "(Googlebot|Bingbot)"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 10  # Low difficulty for known good bots
```

### Multiple Algorithms

```yaml theme={null}
bots:
  - name: Interactive challenge for humans
    expression: "weight > 50"
    action: CHALLENGE
    challenge:
      algorithm: preact
      difficulty: 15

  - name: Fast challenge for bots
    expression: "weight > 20 && weight <= 50"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 25
```

## Integration with Thresholds

Challenges are often used with threshold rules that trigger based on accumulated weight:

```yaml theme={null}
bots:
  - name: Add weight for suspicious patterns
    user_agent_regex: "(bot|crawler|spider)"
    action: WEIGH
    weight:
      adjust: 10

thresholds:
  - name: Challenge on high weight
    expression: "weight > 15"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 22
```

## Algorithm Selection

### fast

The default and most commonly used algorithm. Provides good bot protection with minimal user impact. Recommended for most use cases.

### preact

Interactive challenge using the Preact framework. Better user experience for complex challenges but requires JavaScript.

### metarefresh

Simple meta-refresh based challenge. Works without JavaScript but easier for sophisticated bots to bypass.

## Difficulty Tuning

Difficulty affects how long challenges take to solve:

```yaml theme={null}
# Production recommendations
challenge:
  algorithm: fast
  difficulty: 20  # ~1-2 seconds on modern devices

# High-security environments
challenge:
  algorithm: fast
  difficulty: 28  # ~5-10 seconds on modern devices

# Low-friction experiences
challenge:
  algorithm: fast
  difficulty: 12  # <1 second on modern devices
```

## Related Types

* [BotConfig](/api/config/bot-policy#botconfig) - Bot rule configuration using challenges
* [Threshold](/api/config/bot-policy) - Threshold rules that trigger challenges
* [StatusCodes](/api/config/store-config#statuscodes) - HTTP status code configuration

## See Also