Guides on xodbox

OIDC / SSO

Mon, 01 Jan 0001 00:00:00 +0000

The admin console supports single sign-on via any OpenID Connect provider (Google, Okta, Keycloak, Azure AD, Authentik, Dex, etc.). SSO runs alongside built-in username/password login — a local admin can always sign in even when the IdP is down or misconfigured.

Prerequisites

A working xodbox instance with the admin console enabled (admin_listener or ui_path configured).
An OIDC provider with a client application registered for xodbox.

Register xodbox with your identity provider

Create an application / client in your IdP with these settings:

Admin Console Setup

Mon, 01 Jan 0001 00:00:00 +0000

The admin console is an embedded React web UI and JSON API for managing payloads, browsing captured interactions, creating sinks, and managing users and API keys. It ships inside the xodbox binary — no separate install needed.

Bootstrap the first user

There is no default account. Create an admin user before starting the server:

xodbox user add alice --admin

This prints a generated 24-character password once — store it immediately. To choose your own password:

TLS / ACME Setup

Mon, 01 Jan 0001 00:00:00 +0000

The HTTPX handler can automatically provision and renew TLS certificates via Let’s Encrypt using certmagic. Two challenge methods are supported: DNS-01 (recommended — works behind firewalls and supports wildcards) and HTTP-01 / TLS-ALPN-01 (requires ports 80 and 443 to be reachable from the internet).

Prerequisites

A domain (or subdomain) whose DNS you control.
For DNS-01: API credentials for a supported DNS provider (Namecheap or Route53).
For HTTP-01: ports 80 and 443 open and reachable from the public internet.

Quick start (DNS-01 with Namecheap)

handlers:
 - handler: HTTPX
 listener: :80
 tls_names: "*.oob.example.com,oob.example.com"
 acme_email: you@example.com
 acme_accept: "true"
 acme_url: https://acme-staging-v02.api.letsencrypt.org/directory
 dns_provider: namecheap
 dns_provider_api_user: your-namecheap-user
 dns_provider_api_key: your-namecheap-api-key

Start with the staging ACME URL to avoid rate limits while testing. Once certificates provision correctly, switch to production (see below).

HTTP Payloads

Mon, 01 Jan 0001 00:00:00 +0000

The HTTPX handler serves user-defined payloads — configurable HTTP responses keyed by URL pattern. Payloads use Go templates for dynamic headers, bodies, and status codes, letting you craft responses that test how an application consumes remote data.

How payloads work

Payloads form a processing chain, not a simple route table. On each request:

All payloads are evaluated in order of weight (ascending), then by pattern.
Every payload whose pattern regex matches r.URL.Path runs — it can set headers, write a body, or set the status code.
If a payload has is_final: true, processing stops. Otherwise, the next matching payload runs.

This means multiple non-final payloads can contribute to a single response. For example, the built-in Default Header payload (weight -1000) adds a Server header to every response, then processing continues to the content payload.

Notifier Integration

Mon, 01 Jan 0001 00:00:00 +0000

Notifiers deliver alerts when xodbox captures an interaction. Every handler (HTTP, DNS, SMB, SSH, FTP, SMTP, TCP) emits events; notifiers filter them and forward matches to external services.

Four notifiers ship built-in: app_log (structured log, enabled by default), slack, discord, and webhook (generic HTTP POST).

How filtering works

Each notifier has an optional filter key — a Go regular expression matched against the event’s canonical filter string. The filter string has the form:

DNS Delegation

Mon, 01 Jan 0001 00:00:00 +0000

The DNS handler listens for UDP queries and responds to every request with a configurable A record. Every query is logged as an interaction event and delivered to notifiers. This makes it ideal for detecting out-of-band DNS lookups triggered by SSRF, XXE, log4shell, and similar vulnerabilities.

How it works

The handler responds to all queries for all domains — there is no zone configuration. Every query (regardless of type — A, AAAA, MX, etc.) receives the same A record response with a TTL of 0 (not cacheable).

Docker Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Pre-built Docker images are published to the GitHub Container Registry (GHCR) and signed with cosign (keyless OIDC via GitHub Actions). The images are Alpine-based, run as a non-root xodbox user, and contain a single statically-linked binary.

Quick start

# Generate a starter config
docker run --rm ghcr.io/defektive/xodbox:latest config -e > xodbox.yaml

# Edit xodbox.yaml to taste, then run
docker run -d \
 --name xodbox \
 -v "$PWD:/workspace" \
 --user "$(id -u):$(id -g)" \
 -p 80:80 \
 ghcr.io/defektive/xodbox:latest serve

Image details

Property	Value
Image	`ghcr.io/defektive/xodbox`
Tags	`:latest`, `:v1.2.3` (per release)
Architecture	`linux/amd64`
Base	`alpine:3.21`
Entrypoint	`/bin/xodbox`
Working directory	`/workspace`
Runs as	`xodbox` (non-root)

Volumes and persistence

The container’s working directory is /workspace. Mount a host directory there to persist: