Policy Configuration

Anubis uses YAML-based policy files to define bot protection rules, storage backends, logging, and other security settings. This page covers the structure and loading of policy files.

Policy File Structure

A complete policy file includes:

# Bot detection and response rules
bots:
  - name: example-rule
    user_agent_regex: ".*bot.*"
    action: DENY

# Storage backend configuration
store:
  backend: bbolt
  parameters:
    path: /data/anubis.bdb

# Weight-based thresholds
thresholds:
  - name: moderate-suspicion
    expression:
      all:
        - weight >= 10
        - weight < 20
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 2

# Logging configuration
logging:
  sink: stdio
  level: INFO

# HTTP status codes for responses
status_codes:
  CHALLENGE: 200
  DENY: 200

# DNS settings
dnsbl: false
dns_ttl:
  forward: 300
  reverse: 300

# Optional: Open Graph tag passthrough
openGraph:
  enabled: false

# Optional: Impressum/imprint information
impressum:
  name: "Your Organization"
  email: "[e-mail]"

Loading Policy Files

Anubis loads policy files using the --policy-fname flag or POLICY_FNAME environment variable:

anubis --policy-fname /etc/anubis/policy.yaml

If no policy file is specified, Anubis uses a built-in default policy from data/botPolicies.yaml.

Import Statements

Policy files support importing other YAML files:

bots:
  - import: "/path/to/shared-rules.yaml"
  - import: "(data)/crawlers.yaml"  # Built-in policies

The (data)/ prefix references embedded policy files shipped with Anubis.

Configuration Validation

Anubis validates all configuration at startup using the Valid() method pattern. Common validation errors:

Required Fields

• At least one bot rule must be defined (ErrNoBotRulesDefined)
• Each bot rule must have a name field (ErrBotMustHaveName)
• Bots must match on at least one field: user_agent_regex, path_regex, headers_regex, remote_addresses, or expression (ErrBotMustHaveUserAgentOrPath)

Rule Actions

Valid actions are:

• ALLOW - Bypass all checks and forward to backend
• DENY - Block the request with a fake success page
• CHALLENGE - Present a proof-of-work challenge
• WEIGH - Adjust request suspicion weight
• DEBUG_BENCHMARK - Development only

Regular Expression Validation

Regular expressions are compiled at config load time. Common issues:

• Regex ending with newline (ErrRegexEndsWithNewline) - use >- instead of > in YAML:

# Wrong - includes trailing newline
user_agent_regex: >
  Mozilla.*

# Correct - strips trailing newline  
user_agent_regex: >-
  Mozilla.*

CIDR Validation

IP address ranges in remote_addresses must be valid CIDR notation:

# Valid
remote_addresses:
  - 192.168.0.0/16
  - 10.0.0.0/8
  - 2001:db8::/32

# Invalid - missing /mask
remote_addresses:
  - 192.168.0.1  # Error: invalid CIDR

Configuration Defaults

If not specified in the policy file, Anubis uses these defaults:

status_codes:
  CHALLENGE: 200
  DENY: 200

dns_ttl:
  forward: 300
  reverse: 300

store:
  backend: memory
  parameters: {}

logging:
  sink: stdio
  level: INFO

Environment-Specific Configuration

Policy files can reference environment variables through standard Go flag environment variable support:

# Set via environment
export POLICY_FNAME=/etc/anubis/prod-policy.yaml
export DIFFICULTY=4

# Or via flags
anubis --policy-fname /etc/anubis/prod-policy.yaml --difficulty 4

Configuration Reloading

Anubis does not currently support hot-reloading of policy files. Configuration changes require a service restart:

sudo systemctl restart anubis

Next Steps

• Bot Rules - Define detection rules
• Challenge Configuration - Configure proof-of-work settings
• Storage Backends - Choose a storage backend
• Security - Key generation and JWT signing