Skip to main content
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: "[email protected]"

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us