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

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

Algorithm · 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.

Difficulty · 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).

ReportAs · 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.

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

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

bots:
  - name: Challenge suspicious traffic
    expression: "weight > 10"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 20

High-Security Challenge

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

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

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:

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:

# 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 - Bot rule configuration using challenges
• Threshold - Threshold rules that trigger challenges
• StatusCodes - HTTP status code configuration

See Also