Anubis

Anubis is a self‑hosted Web AI Firewall Utility written in Go that sits as an edge proxy between clients and upstream web services. Its core purpose is to weigh the soul of each incoming connection by presenting configurable challenges (CAPTCHAs, JavaScript puzzles, or custom bot‑policy checks) and only forwarding traffic that satisfies those checks. The project targets small to medium deployments where traditional CDN‑based protection (e.g., Cloudflare) is unavailable or undesirable, offering a lightweight yet powerful alternative that can be run on modest hardware.

Technical Stack & Architecture

• Language: Go (current version tracked via go.mod), chosen for its compiled binaries, static linking, and excellent concurrency primitives.
• Web Framework: The standard net/http library is extended with a minimal router (chi) to keep the binary footprint small while still enabling middleware composition.
• Data Store: Anubis ships with an in‑memory LRU cache for rate‑limiting and challenge state, but also supports optional persistence via SQLite or PostgreSQL for long‑term analytics.
• Challenge Engine: Implemented as a pluggable middleware stack. Each challenge is a Go function that writes to the response stream and sets cookies or headers to track progress. The engine can be configured via YAML files, exposing a simple DSL for policy definitions.
• Metrics & Observability: Built‑in Prometheus exporter exposes counters for requests, challenge hits, and blocked traffic. Logs are emitted in JSON format to ease ingestion into ELK or Loki stacks.

The application follows a classic reverse‑proxy pattern: it receives the request, runs through its challenge pipeline, and if approved forwards the request to the configured upstream URL via http.Transport. TLS termination is optional; Anubis can be placed behind a load balancer or run with certmagic for automated Let's Encrypt certificates.

Core Capabilities & APIs

• Policy Definition: YAML files (policies.mdx) allow fine‑grained control over allowed IP ranges, rate limits per origin, and challenge selection. Policies can be reloaded at runtime via a /reload endpoint without restarting the service.
• Challenge API: Exposes REST endpoints (/challenge) that let external services trigger or query challenge status. Webhooks can be configured to notify downstream systems when a client passes all checks.
• Bot Allowlisting: A built‑in list of known good bots (e.g., Bing, Googlebot) can be referenced in policies; the engine inspects User-Agent and X‑Forwarded‑For headers to make decisions.
• Extensibility Hooks: Developers can write custom middleware in Go and compile it into the binary, or expose a plugin interface via HTTP (e.g., a /plugin endpoint that accepts JSON payloads describing challenge logic).

Deployment & Infrastructure

Anubis is intentionally lightweight: a single statically linked binary (~10 MiB) runs on any Linux x86_64 or ARM64 host. It can be deployed in:

• Docker: The official image is available on Docker Hub; the container exposes ports 80 and 443, with volumes for configuration and logs.
• Kubernetes: A Helm chart (under development) defines a Deployment, Service, and Ingress resource. Horizontal Pod Autoscaling can be enabled by exposing CPU/memory metrics to the K8s API.
• Bare Metal / VPS: A systemd service unit is provided in the repository. The binary can be started with environment variables (ANUBIS_UPSTREAM, ANUBIS_PORT) or a config file.

Scalability is achieved by running multiple Anubis instances behind a load balancer. Since the challenge state can be sharded or replicated via Redis, multiple proxies can share a common policy store without race conditions.

Integration & Extensibility

• Webhooks: On successful challenge completion, Anubis can POST a JSON payload to configured URLs (e.g., analytics dashboards or CI/CD pipelines).
• API Key Management: Optional API key support allows third‑party services to programmatically trigger challenge resets or retrieve metrics.
• Plugin System: While the core is written in Go, developers can write HTTP‑based plugins that expose challenge logic as microservices. Anubis will forward challenge requests to these endpoints, aggregating responses.

Developer Experience

• Configuration: YAML files are human‑readable and version‑controlled. The project ships with a comprehensive policies.mdx example that demonstrates rate limits, challenge sequencing, and bot allowlisting.
• Documentation: The README contains a concise overview; deeper docs reside in the docs/docs directory, written in MDX for easy rendering on GitHub Pages.
• Community & Support: The repository has an active issue tracker and a small but responsive sponsor base. Contributors are encouraged to submit PRs for new challenge types or policy enhancements.
• Licensing: The project is released under a permissive MIT license, making it suitable for commercial deployments without licensing headaches.

Use Cases

1. Self‑hosted API Gateways – Protect REST endpoints from automated scraping or data exfiltration when CDN protection is not viable.
2. Open‑Source Projects – Add an extra layer of bot mitigation to public websites or documentation sites that rely on static hosting.
3. Edge Computing – Deploy Anubis on edge nodes (e.g., Cloudflare Workers compatible runtimes) to intercept traffic before it reaches the origin.
4. Compliance‑Heavy Environments – Use Anubis to enforce strict bot policies in regulated industries where third‑party CDNs are prohibited.