codesyntax/anubis repository overview

⁠Anubis Guide

Anubis is a lightweight Web AI Firewall designed to protect upstream services from AI crawlers and bots by "weighing the soul" of incoming connections using Proof-of-Work (PoW) challenges. Anubis acts as a protective reverse proxy. It intercepts incoming HTTP traffic, performs security checks (Soul Weighing), and forwards legitimate requests to your backend service.

For more information, visit the official Anubis documentation⁠.

⁠Why this image?

This custom Anubis image has been created to override the default challenge templates provided by Anubis. The primary goal is to provide a more serious and professional look for the security verification pages, ensuring they align with corporate branding and standards.

⁠1. Docker Compose Setup

Add Anubis to your docker-compose.yaml as the entry point for your web traffic:

services:
  anubis:
    image: codesyntax/anubis:latest # Or your custom tag
    ports:
      - "9090:9090" # (Optional) Metrics and Health checks
    environment:
      - TARGET=http://backend-app:8080 # Internal URL of your backend
      - BIND=:3000
      - POLICY_FNAME=/anubis-policy.yaml
    volumes:
      - ./base-anubis-policy.yaml:/anubis-policy.yaml:ro
    depends_on:
      - backend-app

  backend-app:
    image: your-application-image:latest
    # Do not expose ports to the public if you want all traffic to go through Anubis
    expose:
      - "8080"

⁠Key Environment Variables

• TARGET: The URL of your backend service (e.g., http://backend:8080).
• BIND: The address and port Anubis listens on (default is :3000).
• POLICY_FNAME: Path to the YAML policy file inside the container.

⁠Custom policies

Add a volume with a custom configuration file if you want to override the default configuration for this image.

volumes:
      - ./custom-anubis-policy.yaml:/anubis-policy.yaml:ro

⁠2. Anubis Configuration Options

Anubis policies are defined in a YAML file (typically base-anubis-policy.yaml).

⁠Logging (logging)

Controls how Anubis emits its structured JSON logs.

• level: Logging threshold (DEBUG, INFO, WARN, ERROR).
• sink: Where logs are sent (stdio for container logs, file for persistent files).

⁠Bot Policies (bots)

Rules evaluated in order to match incoming requests.

• name: Identifier for metrics and logs.
• import: Includes built-in policy snippets (e.g., (data)/meta/ai-block-aggressive.yaml).
• Matchers: user_agent_regex, path_regex, headers_regex, remote_addresses.
• Actions:
  • ALLOW: Bypasses further checks.
  • DENY: Blocks the request (often with a 200 status to fool scrapers).
  • CHALLENGE: Forces a Proof-of-Work challenge.
  • WEIGH: Adjusts the "suspicion weight" for threshold evaluation.

⁠Weight Thresholds (thresholds)

Maps the cumulative weight of a request to specific actions.

• expression: CEL expression (e.g., weight >= 10).
• action: ALLOW, DENY, or CHALLENGE.

⁠Storage (store)

Where challenge states are stored to prevent replay attacks.

• memory: In-memory (non-persistent).
• bbolt: On-disk (persistent, single instance).
• valkey / redis: Network-backed (cluster-aware).
• s3api: S3-compatible object storage.

⁠Metrics (metrics)

Exposes Prometheus metrics, health checks, and debug routes.

• bind: The address to listen on (e.g., :9090).
• basicAuth: Optional credentials to protect metrics data.

⁠Impressum & UI (impressum)

Customizes the appearance of the challenge and denial pages, including titles, bodies, and custom HTML/JS footers.

⁠3. Recommended Configuration

Below is a production-ready configuration that balances security with user experience.

# Recommended Anubis Policy
logging:
  level: INFO
  sink: stdio

# Persistent storage for challenge validation
store:
  backend: bbolt
  parameters:
    path: /data/anubis.bdb

metrics:
  bind: ":9090"

status_codes:
  CHALLENGE: 200
  DENY: 200

bots:
  # 1. Allow system critical paths
  - name: allow-well-known
    path_regex: ^/.well-known/.*$
    action: ALLOW
    
  - name: allow-static-assets
    path_regex: ^/(favicon\.ico|robots\.txt)$
    action: ALLOW

  # 2. Aggressive AI Blocking
  - import: (data)/meta/ai-block-aggressive.yaml
  - import: (data)/crawlers/_allow-good.yaml
  - import: (data)/common/keep-internet-working.yaml

  # 3. Assign initial weight to browser-like agents
  - name: generic-browser
    user_agent_regex: Mozilla|Opera
    action: WEIGH
    weight:
      adjust: 10

# 4. Thresholds: Graduated response based on weight
thresholds:
  - name: human-behavior
    expression: weight < 5
    action: ALLOW

  - name: suspicious-meta-refresh
    expression: weight >= 5 && weight < 10
    action: CHALLENGE
    challenge:
      algorithm: metarefresh
      difficulty: 1

  - name: bot-pow-challenge
    expression: weight >= 10
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 3

# 5. UI Branding
impressum:
  page:
    title: "Security Verification"
    body: "Please wait while we verify your connection."

⁠4. Running this image locally

This repository includes a test directory with a pre-configured environment to quickly test the image.

1. Build the image:

   docker build -t cs-anubis:local .
   

   Copy

2. Run the test environment:

   cd test
   docker compose up --build
   

   Copy

This will spin up:

• An Anubis instance.
• A simple Nginx backend, for backend simulation
• An Nginx entry point to simulate a real-world proxy setup.

You can then access the environment at http://localhost. Check anubis challenge template in http://localhost:3000 See anubis metrics in http://localhost:9090/metrics