Challenges

Challenges are the core mechanism Anubis uses to distinguish humans from bots. When a request triggers a CHALLENGE action, Anubis issues a computational puzzle that is trivial for browsers but expensive for scrapers at scale.

Challenge Metadata

Every challenge issued by Anubis contains structured metadata:

// From lib/challenge/challenge.go:6
type Challenge struct {
    IssuedAt       time.Time         `json:"issuedAt"`
    Metadata       map[string]string `json:"metadata"`
    ID             string            `json:"id"`
    Method         string            `json:"method"`
    RandomData     string            `json:"randomData"`
    PolicyRuleHash string            `json:"policyRuleHash,omitempty"`
    Difficulty     int               `json:"difficulty,omitempty"`
    Spent          bool              `json:"spent"`
}

string

required

UUID v7 identifier for the challenge. Used for lookups and validation.

Method

string

required

Challenge algorithm: fast or slow (deprecated).

RandomData

string

required

64 bytes of random data (hex-encoded) that the client must process.

Difficulty

int

default:"0"

Number of leading zero bits required in the proof-of-work hash (0-64).

PolicyRuleHash

string

Hash of the bot rule that issued this challenge. Used to invalidate tokens when policy changes.

Spent

bool

default:"false"

Whether this challenge has been solved. Prevents double-spend attacks.

Challenge Types

Anubis supports multiple challenge algorithms, registered in the challenge registry:

Proof-of-Work (Recommended)

bots:
  - name: suspicious-traffic
    expression:
      - "req.headers['user-agent'].contains('bot')"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 3

The proof-of-work challenge requires clients to find a nonce such that:

SHA256(randomData + nonce) = hash with N leading zero bits

Where N is the configured difficulty.

The slow algorithm is deprecated. Use fast for all new deployments. The algorithms are functionally identical; the naming was legacy.

Meta Refresh

The metarefresh challenge uses HTTP meta refresh tags to redirect browsers. This is a passive challenge that doesn’t require JavaScript or computation.

Registered as metarefresh in the challenge registry. Useful for detecting scrapers that don’t process HTML meta tags.

Preact (Interactive)

The preact challenge renders an interactive UI component using Preact. This challenge type verifies JavaScript execution and DOM manipulation capabilities.

Proof-of-Work Mechanism

Validation Algorithm

When a client submits a solution, Anubis validates it in constant time:

// From lib/challenge/proofofwork/proofofwork.go:35
func (i *Impl) Validate(r *http.Request, lg *slog.Logger, in *chall.ValidateInput) error {
    // Extract parameters
    nonceStr := r.FormValue("nonce")
    elapsedTimeStr := r.FormValue("elapsedTime")
    response := r.FormValue("response")
    
    // Recompute hash
    calcString := fmt.Sprintf("%s%d", challenge, nonce)
    calculated := internal.SHA256sum(calcString)
    
    // Constant-time comparison prevents timing attacks
    if subtle.ConstantTimeCompare([]byte(response), []byte(calculated)) != 1 {
        return chall.ErrFailed
    }
    
    // Verify difficulty requirement
    if !strings.HasPrefix(response, strings.Repeat("0", difficulty)) {
        return chall.ErrFailed
    }
    
    return nil
}

Extract Parameters

The client submits nonce, elapsedTime, and response (the computed hash).

Recompute Hash

Server independently computes SHA256(randomData + nonce).

Constant-Time Comparison

Uses crypto/subtle.ConstantTimeCompare to prevent timing side-channels.

Verify Difficulty

Ensures the hash has the required number of leading zero hex characters.

Client-Side Solving

The challenge page includes JavaScript that brute-forces the nonce:

const randomData = "/* from server */";
const difficulty = 3;

let nonce = 0;
const start = performance.now();

while (true) {
  const input = randomData + nonce;
  const hash = await sha256(input);
  
  if (hash.startsWith('0'.repeat(difficulty))) {
    const elapsed = (performance.now() - start) / 1000;
    submitSolution(nonce, hash, elapsed);
    break;
  }
  
  nonce++;
}

Difficulty Settings

Difficulty determines how many leading zero hex characters (4 bits each) are required:

Difficulty Range

int

default:"0"

Valid range: 0-64

0: No proof-of-work required (instant pass)
1-3: Light verification (milliseconds)
4-6: Moderate difficulty (seconds)
7-10: Heavy computation (tens of seconds)
11+: Extreme difficulty (minutes to hours)

Difficulty Performance Table

Difficulty	Expected Attempts	Average Time (Modern CPU)	Use Case
`0`	1	Instant	Testing only
`1`	16	less than 10ms	Very light verification
`2`	256	~50ms	Light bot deterrent
`3`	4,096	~500ms	Recommended default
`4`	65,536	~5s	Moderate protection
`5`	1,048,576	~1min	Heavy scraper deterrent
`6`	16,777,216	~15min	Extreme protection

These times are approximate and vary based on client hardware and JavaScript engine performance.

Configuring Difficulty

bots:
  - name: aggressive-crawler
    user_agent_regex: "(curl|wget|python-requests)"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 4  # Harder for known scrapers

  - name: suspicious-behavior
    expression:
      - "req.path.matches('/api/.*')"
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 2  # Lighter for API endpoints

Challenge Lifecycle

Double-Spend Protection: Each challenge can only be solved once. The Spent flag prevents replay attacks where an attacker tries to reuse a valid solution.

Storage Requirements

Challenges are stored with a 30-minute TTL:

// From lib/anubis.go:133
if err := j.Set(ctx, "challenge:"+id.String(), chall, 30*time.Minute); err != nil {
    return nil, err
}

Storage backends must support:

JSON serialization: Challenges are stored as store.JSON[challenge.Challenge]
TTL/Expiration: Automatic cleanup after 30 minutes
Atomic updates: For marking challenges as spent

For high-traffic deployments, use Valkey/Redis or another distributed store to share challenge state across multiple Anubis instances.

Challenge Metrics

Anubis exposes Prometheus metrics for monitoring:

# Challenges issued by method
anubis_challenges_issued{method="embedded"} 1523
anubis_challenges_issued{method="api"} 42

# Challenges successfully validated
anubis_challenges_validated{method="fast"} 1401

# Failed validation attempts
anubis_failed_validations{method="fast"} 164

# Time taken to solve challenges (histogram)
anubis_challenge_time_taken_seconds{algorithm="fast"}

Error Handling

Challenge validation can fail with specific errors:

// From lib/challenge/error.go:9
var (
    ErrFailed        = errors.New("challenge: user failed challenge")
    ErrMissingField  = errors.New("challenge: missing field")
    ErrInvalidFormat = errors.New("challenge: field has invalid format")
)

ErrMissingField

The client didn’t submit required parameters (nonce, elapsedTime, or response).HTTP Status: 400 Bad Request

ErrInvalidFormat

Parameters have wrong type (e.g., non-numeric nonce).HTTP Status: 400 Bad Request

ErrFailed

The solution is incorrect or doesn’t meet difficulty requirements.HTTP Status: 403 Forbidden

Best Practices

Start Low

Begin with difficulty 2-3 and increase only if you observe scraper persistence.

Monitor Solve Times

Use anubis_challenge_time_taken_seconds to ensure challenges aren’t frustrating legitimate users.

Different Difficulty by Context

Use lower difficulty for public pages, higher for sensitive endpoints.

Test Cookie Support

Anubis automatically checks cookie support. Failed cookie tests appear in logs.

Custom Challenge Implementation

You can implement custom challenges by satisfying the challenge.Impl interface:

// From lib/challenge/interface.go:59
type Impl interface {
    // Setup registers any additional routes with the Impl for assets or API routes.
    Setup(mux *http.ServeMux)

    // Issue a new challenge to the user, called by the Anubis.
    Issue(w http.ResponseWriter, r *http.Request, lg *slog.Logger, in *IssueInput) (templ.Component, error)

    // Validate a challenge, making sure that it passes muster.
    Validate(r *http.Request, lg *slog.Logger, in *ValidateInput) error
}

func init() {
    challenge.Register("my-custom-challenge", &MyImpl{)
}

Get Started

Core Concepts

Installation

Administration

Deployment

Integrations

Challenge Metadata

Challenge Types

Proof-of-Work (Recommended)

Meta Refresh

Preact (Interactive)

Proof-of-Work Mechanism

Validation Algorithm

Client-Side Solving

Difficulty Settings

Difficulty Performance Table

Configuring Difficulty

Challenge Lifecycle

Storage Requirements

Challenge Metrics

Error Handling

Best Practices

Start Low

Monitor Solve Times

Different Difficulty by Context

Test Cookie Support

Custom Challenge Implementation

Next Steps

Policies

How It Works

Build docs developers (and LLMs) love

Get Started

Core Concepts

Installation

Administration

Deployment

Integrations

​Challenge Metadata

​Challenge Types

​Proof-of-Work (Recommended)

​Meta Refresh

​Preact (Interactive)

​Proof-of-Work Mechanism

​Validation Algorithm

​Client-Side Solving

​Difficulty Settings

​Difficulty Performance Table

​Configuring Difficulty

​Challenge Lifecycle

​Storage Requirements

​Challenge Metrics

​Error Handling

​Best Practices

Start Low

Monitor Solve Times

Different Difficulty by Context

Test Cookie Support

​Custom Challenge Implementation

​Next Steps

Policies

How It Works

Build docs developers (and LLMs) love

Challenge Metadata

Challenge Types

Proof-of-Work (Recommended)

Meta Refresh

Preact (Interactive)

Proof-of-Work Mechanism

Validation Algorithm

Client-Side Solving

Difficulty Settings

Difficulty Performance Table

Configuring Difficulty

Challenge Lifecycle

Storage Requirements

Challenge Metrics

Error Handling

Best Practices

Custom Challenge Implementation

Next Steps