Anubis è un sistema open source progettato per ridurre il traffico automatizzato e indesiderato diretto verso siti web e applicazioni. Il suo obiettivo è distinguere il traffico generato da utenti reali da quello prodotto da bot, crawler e altri sistemi automatizzati che possono rappresentare un carico inutile e/o dannoso.

anubis

Anubis opera attraverso un sistema di policy che consente di classificare le richieste HTTP e decidere come trattarle. Le principali azioni disponibili sono:

  • ALLOW: autorizza la richiesta senza ulteriori verifiche
  • CHALLENGE: sottopone il client a una challenge anti-bot
  • DENY: rifiuta la richiesta

Anubis non sostituisce un firewall, ma rappresenta un ulteriore livello di sicurezza applicato al traffico HTTP.

Architettura generale

L’idea é quella di utilizzare una sola istanza di Anubis col compito di valutare le richieste e comunicare a Caddy se può procedere, intervenendo prima che il reverse proxy inoltri la richiesta al backend.

Anubis può infatti operare in due modi differenti. Nella modalitá Reverse proxy tradizionale, il flusso è il seguente:

  1. Il browser richiede una pagina
  2. Anubis analizza la richiesta
  3. Se è autorizzata, Anubis inoltra la richiesta al backend
  4. Se è necessario verificare il client, Anubis restituisce una challenge
  5. Se la richiesta viene negata, Anubis restituisce un errore

In questo scenario Anubis è un vero e proprio reverse proxy.

Nella modalità Subrequest Authentication, utilizzata nella nostra infrastruttura, Anubis non gestisce il traffico verso i backend. È Caddy che continua a fare da reverse proxy, mentre Anubis viene interrogato per decidere se autorizzare o meno la richiesta.

Integrazione con Caddy

L’integrazione avviene attraverso la funzionalità forward_auth di Caddy.

(anubis) {
    route {
        reverse_proxy /.within.website/* 127.0.0.1:8923

        forward_auth 127.0.0.1:8923 {
            uri /.within.website/x/cmd/anubis/api/check
            trusted_proxies private_ranges

            @unauthorized status 401

            handle_response @unauthorized {
                redir * /.within.website/?redir={uri} 307
            }
        }
    }
}

Ogni dominio da proteggere deve importare lo snippet anubis nel relativo blocco di configurazione. Per esempio:

https://linkding.novemila.org {
	import anubis
	encode gzip zstd
	reverse_proxy localhost:3021
}

https://hal.novemila.org {
	import common
    import anubis
	encode gzip zstd
	root * /path/to/hal/
	file_server
}

Il funzionamento è il seguente:

  • Caddy riceve la richiesta HTTPS
  • Prima di procedere, esegue una verifica tramite forward_auth, inviando la richiesta ad Anubis, in ascolto sulla porta 8923
  • Anubis riceve la richiesta di verifica e valuta le policy
  • Se il client è autorizzato, Caddy prosegue con la gestione della richiesta originale
  • Se è necessaria una challenge, il client viene indirizzato all’interfaccia di verifica di Anubis
  • Se la richiesta viene negata, viene restituito il relativo errore

anubis-subrequest-authentication

Supponiamo, ad esempio, che un visitatore richieda il sito git.novemila.org. Caddy effettua una richiesta di verifica verso Anubis. La richiesta originale del browser non viene sostituita: rimane semplicemente sospesa in attesa della decisione.

Anubis deve comunicare al reverse proxy il risultato della valutazione attraverso una risposta HTTP:

  • HTTP 2xx: autorizzazione concessa
  • HTTP 401: richiesta di autenticazione/challenge
  • HTTP 403: accesso negato

Docker compose

L’infrastruttura utilizza un solo container Anubis per tutti i servizi protetti.

x-anubis-common: &anubis-common
  image: ghcr.io/techarohq/anubis:latest
  restart: unless-stopped
  mem_limit: 128m
  cap_drop:
    - ALL
  security_opt:
    - no-new-privileges:true

services:

  anubis:
    container_name: anubis
    <<: *anubis-common
    ports:
      - "127.0.0.1:8923:8923"
    environment:
      WEBMASTER_EMAIL: "support@novemila.org"
      ED25519_PRIVATE_KEY_HEX: "${ANUBIS_ED25519_PRIVATE_KEY_HEX}"
      REDIRECT_DOMAINS: "${REDIRECT_DOMAINS}"
      USE_SIMPLIFIED_EXPLANATION: "${USE_SIMPLIFIED_EXPLANATION}"
      SERVE_ROBOTS_TXT: "true"
      OG_PASSTHROUGH: "true"
      OG_EXPIRY_TIME: "24h"
      BIND: ":8923"
      TARGET: " "
      POLICY_FNAME: /etc/anubis/policies/botPolicies.yaml
    volumes:
      - ./policies:/etc/anubis/policies:ro
      - ./geoip:/var/lib/GeoIP:ro

  geoipupdate:
    container_name: geoipupdate
    image: ghcr.io/maxmind/geoipupdate:latest
    restart: unless-stopped
    mem_limit: 32m
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    environment:
      GEOIPUPDATE_ACCOUNT_ID: "${MAXMIND_ACCOUNT_ID}"
      GEOIPUPDATE_LICENSE_KEY: "${MAXMIND_LICENSE_KEY}"
      GEOIPUPDATE_EDITION_IDS: "GeoLite2-ASN GeoLite2-Country"
      GEOIPUPDATE_FREQUENCY: "24"
      GEOIPUPDATE_DB_DIR: "/usr/share/GeoIP"
    volumes:
      - ./geoip:/usr/share/GeoIP

La configurazione TARGET: " " è intenzionale: abilita la modalità di integrazione tramite subrequest authentication, nella quale Anubis non deve inoltrare autonomamente le richieste ai backend. Il collegamento verso i servizi applicativi rimane interamente responsabilità di Caddy.

SERVE_ROBOTS_TXT: "true" fa sì che Anubis serva direttamente un file robots.txt predefinito. Questo file contiene direttive per impedire ai vari scraper di effettuare la scansione dei contenuti. Bisogna sottolineare che i crawler malevoli possono ignorarle completamente. La protezione effettiva resta quella delle policy Anubis.

La direttiva OG_PASSTHROUGH: "true" abilita il cosiddetto Open Graph passthrough, il sistema utilizzato dai siti per generare l’anteprima quando un link viene condiviso.

Ulteriori Variabili d’ambiente.

Le credenziali sono conservate nel file .env.

ANUBIS_ED25519_PRIVATE_KEY_HEX=
REDIRECT_DOMAINS="novemila.org,*.novemila.org"
USE_SIMPLIFIED_EXPLANATION=false
MAXMIND_ACCOUNT_ID=""
MAXMIND_LICENSE_KEY=""

Per generare la chiave persistente bisogna eseguire il comando openssl rand -hex 32 e aggiungerla al parametro ED25519_PRIVATE_KEY_HEX. Anubis utilizza questa chiave per firmare i token di accesso e verificarne la validità nelle richieste successive, evitando di ripetere la challenge a ogni richiesta.

Il container geoipupdate si occupa dell’aggiornamento automatico dei database per il blocco geografico.

Organizzazione delle policy

Le policy sono organizzate in un file principale e in file separati per le regole comuni e per le eccezioni dei singoli servizi.

.
├── docker-compose.yaml
├── geopip
│   ├── GeoLite2-ASN.mmdb
│   └── GeoLite2-Country.mmdb
└── policies
    ├── botPolicies.yaml
    ├── common
    │   ├── 00-common-rules.yaml
    │   └── 99-default-rules.yaml
    └── services
        ├── beszel.yaml
        ├── gitea.yaml
        ├── immich.yaml
        ├── kuma.yaml
        ├── linkding.yaml
        ├── mailcow.yaml
        ├── miniflux.yaml
        └── vaultwarden.yaml

Il file botPolicies.yaml è il punto di ingresso della configurazione. Contiene:

  • percorsi dei database GeoIP
  • codici HTTP associati alle azioni
  • import delle regole comuni
  • import delle regole specifiche
  • import delle regole predefinite finali
geoip:
  asn:
    path: /var/lib/GeoIP/GeoLite2-ASN.mmdb
  country:
    path: /var/lib/GeoIP/GeoLite2-Country.mmdb

metrics:
  bind: "127.0.0.1:9100"
  network: "tcp"

status_codes:
  CHALLENGE: 200
  DENY: 403

bots:
  # Common rules
  - import: /etc/anubis/policies/common/00-common-rules.yaml

  # Service-specific rules
  - import: /etc/anubis/policies/services/beszel.yaml
  - import: /etc/anubis/policies/services/gitea.yaml
  - import: /etc/anubis/policies/services/immich.yaml
  - import: /etc/anubis/policies/services/kuma.yaml
  - import: /etc/anubis/policies/services/linkding.yaml
  - import: /etc/anubis/policies/services/mailcow.yaml
  - import: /etc/anubis/policies/services/miniflux.yaml
  - import: /etc/anubis/policies/services/vaultwarden.yaml

  # Default rules
  - import: /etc/anubis/policies/common/99-default-rules.yaml

La struttura delle regole segue un ordine preciso: le eccezioni devono essere valutate prima delle regole generali che potrebbero bloccare o sottoporre a challenge la richiesta.

Il file common/00-common-rules.yaml contiene le regole condivise da tutti i domini.

# -----------------------------------------------
# Pathological bots
# -----------------------------------------------

- import: (data)/bots/_deny-pathological.yaml

- import: (data)/bots/aggressive-brazilian-scrapers.yaml

- import: (data)/common/domain-fronting.yaml

# -----------------------------------------------
# AI bots
# -----------------------------------------------

- import: (data)/meta/ai-block-aggressive.yaml

# -----------------------------------------------
# Legitimate crawlers
# -----------------------------------------------

- import: (data)/crawlers/_allow-good.yaml

# -----------------------------------------------
# Browser AI clients
# -----------------------------------------------

- import: (data)/clients/x-firefox-ai.yaml

- import: (data)/crawlers/xai.yaml

# -----------------------------------------------
# Common resources
# -----------------------------------------------

- import: (data)/common/keep-internet-working.yaml

# -----------------------------------------------
# GeoIP country filtering
# -----------------------------------------------

- name: blocked-countries
  action: DENY
  geoip:
    countries:
      - BR
      - BY
      - CN
      - KP
      - IR
      - SY
      - VN
      - RU

Il blocco geografico utilizza il database GeoLite2 di Maxmind. per configurarlo, bisogna seguire la procedura guidata, iscrivendosi al sito e scaricando il file.

Nel file 99-default-rules.yaml i browser riconosciuti vengono sottoposti a challenge; tutti i client sconosciuti vengono bloccati.

# -----------------------------------------------
# Challenge legitimate browsers
# -----------------------------------------------

- name: allowed-browsers
  user_agent_regex: '(?i)(Firefox|Brave|Chrome|Chromium|Safari)'
  action: CHALLENGE
  challenge:
    algorithm: fast
    difficulty: 4

# -----------------------------------------------
# Deny everything else
# -----------------------------------------------

- name: deny-unknown-clients
  expression: "true"
  action: DENY

Eccezioni specifiche per i servizi

Alcune applicazioni utilizzano API o percorsi che non possono essere sottoposti indiscriminatamente alla challenge. Per questo motivo sono presenti policy con eccezioni dedicate.

Le eccezioni sono vincolate all’hostname del servizio e al percorso HTTP, in modo da evitare che una regola destinata a un’applicazione diventi un’esenzione globale.

Ad esempio, per l’istanza di Linkding disponibile su linkding.novemila.org, è configurata un’eccezione per il percorso:

/api/

Questa eccezione consente le richieste API necessarie al funzionamento delle applicazioni mobile.

# -----------------------------------------------
# Linkding API exceptions
# -----------------------------------------------

# Allow REST API requests from browser extensions and integrations
- name: linkding-api
  expression: 'host == "linkding.novemila.org" && path.startsWith("/api/")'
  action: ALLOW

Configurazione di Caddy

Formattare i file di configurazione di Caddy e, quindi, verificarne la correttezza:

caddy fmt /etc/caddy/Caddyfile --overwrite

caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

Nel caso non vi siano errori, ricaricare la configurazione: systemctl reload caddy && systemctl status caddy.

Visitando una pagina protetta da Anubis, dovrebbe apparire la challenge anti-bot:

challenge-anti-bot

Riferimenti