Warden operator guide

Debian package

sha256sum ./witen-warden_*.deb
sudo apt install ./witen-warden_*.deb
warden --version
man 8 warden

RPM package

sha256sum ./witen-warden-*.x86_64.rpm
sudo dnf install ./witen-warden-*.x86_64.rpm
warden --version
man 8 warden

Alpine package

sha256sum ./witen-warden_*.apk
sudo apk add --allow-untrusted ./witen-warden_*.apk
warden --version

The APK is distributed directly, not through an Alpine repository, so install it from the checked local file.

Portable archive

sha256sum ./witen-warden-*-linux-amd64-glibc.tar.gz
tar -xzf ./witen-warden-*-linux-amd64-glibc.tar.gz
cd ./witen-warden-*-linux-amd64-glibc
sudo ./install.sh
sudo warden validate --config /etc/witen/warden.toml

The portable installer doesn't enable or start a service. On OpenRC it installs the service files; on other hosts, install the included init definition that fits.

With Warden installed

Download the statement and its signature next to the file, then let the installed Warden check it before you install. It refuses a file the statement doesn't list, a statement that was changed, and a key that was revoked.

V=0.1.42
B=https://www.witenlabs.com/api/releases/warden
curl -fsSLO "$B/signatures/witen-warden-$V.release.json"
curl -fsSLO "$B/signatures/witen-warden-$V.release.sig"
warden verify-release ./witen-warden_$V-1_amd64.deb
sudo apt install ./witen-warden_$V-1_amd64.deb

The portable install.sh does this check itself before it changes anything: keep the archive, the .release.json, and the .release.sig in one directory and extract the archive there. If a file is missing or doesn't verify, nothing is installed. --skip-signature-check installs anyway and warns loudly; use it only after you've checked the download another way. Package hooks can't see the package file they come from, so check DEB, RPM, and APK files with warden verify-release first.

On a first install

A host without Warden has nothing it already trusts. On a first install, your trust comes from HTTPS to www.witenlabs.com and from the root fingerprint below, which is also printed in man 8 warden. The installer checks the archive with the release's own binary and prints the root fingerprint it used, so compare it. To check without any Warden binary, verify the chain with OpenSSL 3 and jq:

ROOT_PUB=...   # the root public key below
pem() { printf -- '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA%s\n-----END PUBLIC KEY-----\n' "$1"; }
printf %s "$ROOT_PUB" | base64 -d | sha256sum        # must equal the root fingerprint
# The root signed the key set.
jq -r .keys witen-warden-$V.release.sig | base64 -d > keys.json
jq -r .keys_signature witen-warden-$V.release.sig | base64 -d > keys.sig
{ printf 'witen-release-signature/v1\n'; cat keys.json; } > keys.msg
pem "$ROOT_PUB" > root.pem
openssl pkeyutl -verify -pubin -inkey root.pem -rawin -in keys.msg -sigfile keys.sig
# A release key in that set, not revoked, signed the statement.
KEY_ID=$(jq -r .key_id witen-warden-$V.release.json)
pem "$(jq -r --arg id "$KEY_ID" '.keys[] | select(.key_id == $id and .revoked_at == 0) | .public_key' keys.json)" > release.pem
jq -r .signature witen-warden-$V.release.sig | base64 -d > statement.sig
{ printf 'witen-release-signature/v1\n'; cat witen-warden-$V.release.json; } > statement.msg
openssl pkeyutl -verify -pubin -inkey release.pem -rawin -in statement.msg -sigfile statement.sig
# The statement lists your download.
jq -r '.artifacts[] | "\(.sha256)  \(.name)"' witen-warden-$V.release.json
sha256sum ./witen-warden-$V-linux-amd64-glibc.tar.gz

Also check that the key's not_before and not_after in keys.json cover the statement's signed_at.

Transparency log

The build host's signer writes every signature it makes to an append-only log before the statement leaves the host, and we publish that log at /api/releases/warden/log. Each line is a signed entry, chained to the one before it. warden verify-release FILE --log log.txt also requires the statement to appear there. The log only grows. If a release key were ever misused through the signer, every statement it signed would show up here, and revoking the key stops Warden from trusting any of them.

Find supported logs

sudo warden discover
sudo warden discover --toml

Discovery only reads. It lists non-empty supported log files and journal services; it doesn't add them or change the host.

Watch SSH

[ssh]
enabled = true
timezone = "auto"

[journal]
enabled = "true"
cursor_path = "/var/lib/witen/journal-cursors.json"

[jail]
backend = "null"
max_ssh_failures = 3
max_http_probes = 20
window_duration_sec = 300
ban_duration_sec = 3600
firewall_reconcile_interval_sec = 300
# Replace with your actual management address or CIDR before enforcement.
never_block = ["192.0.2.10"]

On OpenRC or with file-based logging, set ssh.log_file to the authentication log and grant the service account the narrowest group or ACL that can read it.

Web access logs

[[logs]]
path = "/var/log/caddy/access.log"
type = "caddy"

[[logs]]
path = "/var/log/nginx/access.log"
type = "nginx"

Supported access logs: nginx, Apache, Caddy, lighttpd, Traefik, Envoy, HAProxy, Varnish, and Pound. Have Caddy write its native JSON with client IP fields that respect trusted proxies.

Portable installs restart the service

From 0.1.37, the portable install.sh checks the release signature, then stops a running Warden service, replaces the binary, starts the service again, and checks that exactly one Warden runs the new binary. Don't restart it again afterwards. A stopped service stays stopped. On OpenRC it installs its own init script first, which waits up to 50 seconds for the old daemon to finish its last upload. If anything fails after the stop, it starts the service again. --no-restart replaces only the files, and the running daemon keeps the old binary until you restart it.

# Keep the .tar.gz, .release.json and .release.sig together
tar xzf witen-warden-0.1.37-linux-amd64-glibc.tar.gz
cd witen-warden-0.1.37-linux-amd64-glibc
sudo ./install.sh

Update notices

Warden 0.1.37 and later tell you when a newer release is out. You'll see update available: 0.1.38 in the TUI header, an update check: line in warden stats with the installed version, the latest version, and the last check time, and a warning in warden validate. Each new version is logged once. Warden never downloads or installs anything on its own. Upgrade with the steps above.

Shortly after it starts, and then about once a day, Warden sends one plain HTTPS request to /api/releases/warden/latest, the signed statement of the latest release. It reports a new version only after the signatures check out against the root built into Warden, the statement hasn't expired, and it isn't older than one it has already seen. The request carries only a User-Agent with the installed version, an Accept header, and a random request ID. It sends no sensor credential, hostname, or configuration. Like any web request, it shows us the connecting address. An answer that doesn't verify shows as update check failed: signature in warden stats and warden validate. A failed check never affects blocking or reporting. Behind a proxy, set HTTPS_PROXY in the service environment.

# /etc/witen/warden.toml: turn the check off, for example on offline hosts
[update_check]
enabled = false

The service won't start

• Run warden validate --json and fix the first failing check.
• Check the configured logs exist and the service account can read them.
• Check the selected firewall binary and kernel support are present.
• Don't start a foreground daemon while the service holds the runtime lock or admin socket.

Why was this address blocked?

• Run warden decisions to list recorded local blocking decisions.
• Run warden explain RECEIPT_ID for the subject, reason, evidence count, actuator, timing, and lifecycle state.
• Add --json for output you can attach to automation or a support request.
• Undo a block with warden unban IP; the receipt then records rolled_back.

Outbound protection

Outbound blocking is off unless you set outbound_protection_enabled, and needs a firewall backend with direction-specific rules. The feed is active only when Warden status shows both outbound_configured=true and outbound_enforced=true.

Events are missing

• Run warden sources to check the selected backend, offset, last event, and collection error.
• Apache and nginx error logs listed under [[logs]] are read from their files even when journald collection is on (Warden 0.1.31 and later). Earlier versions skipped them on journald hosts.
• Error, mail, FTP, and database logs carry no timezone. With timezone = "auto", Warden 0.1.32 and later read them in the host's zone; earlier versions read them as UTC, which can make events look hours old.
• Check the log format and client IP fields, especially behind trusted proxies.
• From 0.1.37, warden stats lists a source Warden can't read as log sources: N of M UNHEALTHY, with the reason (permission_denied, not_found, or read_error), when it started, and how to fix it. Warden also reports each source's health to Witen with its uploads.
• On systemd hosts, 0.1.37 repairs the service account's access to Apache logs by itself: witen-warden-log-access.path runs when the log directory's permissions change and witen-warden-log-access.timer every 15 minutes. OpenRC hosts repair it when the service starts.
• From 0.1.38, a log that file permissions allow but Warden's AppArmor profile or SELinux policy refuses is listed as confinement_denied, with the rule or file context that fixes it; the ACL repair can't help there. warden stats also shows a confinement: line, and warns when Warden runs outside its packaged profile or SELinux domain. On systemd hosts witen-warden-confinement.path and .timer load the profile, reinstall the SELinux module, and restore labels by themselves, and leave a profile you disabled with aa-disable or a module you disabled with semodule -d alone.
• Run warden backfill --since 1h to import history without blocking. Add --enforce only after you've reviewed what it would block.

Witen is unreachable

Local detection and blocking carry on. Events wait in the on-disk outbox, which has a size limit, and send in order once the connection returns. Check the upload counters in warden stats, DNS and TLS reachability, and the sensor credential file. Don't replace the credential just because the collector is briefly unreachable.

More detail

The package includes the full offline manual, man 8 warden and info warden, covering XDP, JA4, backfill, policy rules, sockets, and the TUI.

Local rules

A local rule matches the method, path, query, status, User-Agent, or, with request metadata turned on, the media type and declared length of a request. Paths are checked as sent and after decoding, so encoded variants still match. List rule files under [signatures], test them offline, then run warden reload; no restart is needed.

[signatures]
files = ["/etc/witen/signatures/site.toml"]

schema_version = 1

[[rule]]
id = "local.old-admin-probe"
revision = 1
description = "Requests for a removed admin tool"
mode = "observe"   # or "score" to count toward a local ban

[[rule.all]]
field = "path"
op = "prefix"      # equals, prefix, contains, or regex
value = "/old-admin/"

warden signatures validate --rules /etc/witen/signatures/site.toml
warden signatures test --rules /etc/witen/signatures/site.toml --input fixtures.jsonl
sudo warden signatures replay --rules /etc/witen/signatures/site.toml   --format apache --input /var/log/httpd/access_log
sudo warden reload --config /etc/witen/warden.toml

Replay reads a log you already have and reports what would have matched, without touching the daemon, the database, or the firewall.

PHP2Shell examples

Warden 0.1.29 and later ship two opt-in examples for the PHP2Shell flaws (CVE-2026-109618 and CVE-2026-109619) in /usr/share/doc/witen-warden/examples/php2shell/, or examples/php2shell/ in the portable archive. Updating PHP is the fix; see the PHP2Shell guide. These only report.

• php2shell-tooling.toml is a local rule for User-Agents that advertise php2shell tooling. It needs no WAF but misses tools that send a browser User-Agent.
• php2shell-modsecurity.conf holds ModSecurity rules 9420000 to 9420003, derived from the PHP fix. They inspect request bodies, pass and log only, and call a match a probe or check, since public checkers send the same requests. Rule 9420000 also matches ordinary upload-progress forms.

ModSecurity findings

If the host already runs ModSecurity, Warden can report which rules fired, as http_waf_observation events with the rule ID. It never copies request bodies, headers, matched data, or the raw log line. Three inputs are supported, and enabling any of them needs a restart.

• libModSecurity v3 (nginx connector) or ModSecurity 2.9 (Apache mod_security2) writing a JSON audit log with SecAuditLogFormat JSON. Parts AHZ are enough and keep headers out of the log.
• ModSecurity 2.9 builds without JSON support, including EPEL's for RHEL and AlmaLinux 10: set apache_error_log = true and Warden reads findings from your apache-error logs.

With a JSON audit log:

[modsecurity]
enabled = true
log_files = ["/var/log/modsecurity/audit.json"]

With ModSecurity 2.9 and no JSON, reading the Apache error logs instead:

[modsecurity]
enabled = true
apache_error_log = true

[[logs]]
type = "apache-error"
path = "/var/log/httpd/error_log"

Findings from a DetectionOnly engine still reach warden events and Witen, but they don't mark a CVE Seen on your sensors in Vulnerability Intel. That takes a ModSecurity rule written for that specific CVE, such as 9420000 for CVE-2026-109619, firing while the engine enforces. Coraza findings never mark a CVE observed. What counts as observed exploitation has the full rule.

Search and AI crawlers

Behavior detection flags an address that keeps changing which bot it claims to be. From 0.1.36, Google's own crawler tokens, such as Googlebot, Googlebot-Image, and AdsBot-Google, count as one identity when they come from Google's published ranges, so genuine Google crawling is no longer identity churn. The same tokens from any other address still count separately.

When a connected sensor reports a request from Google, Bing, Apple, DuckDuckGo, GPTBot, or OAI-SearchBot, Witen checks the claim against the operator's published ranges or reverse and forward DNS. A verified crawler request with no specific hostile signal is filed as verified crawler traffic and carries no reputation weight. A sensitive path, an exploit or web-shell shape, or a campaign match is still judged on its own. A claim the operator's sources contradict stays suspicious, and so does one that can't be verified.

When the first report arrives

The first report goes out after a random delay of 0 to 10 minutes from the moment Warden starts, then every interval_sec seconds. The default is 86400, warden validate accepts 3600 to 604800, and each interval is jittered by up to 10%. A failed upload is retried after 15 minutes, doubling up to the interval.

Gentoo slots

From 0.1.36, Warden reports every installed slot of a package as its own item, with a slot field read from Portage's SLOT file without the sub-slot. With Python 3.13 and 3.14 installed, dev-lang/python arrives twice, with slot set to 3.13 and 3.14, and each is judged against its own GLSA ranges. Earlier versions reported only the first slot they found. Entries with an unreadable or invalid SLOT are skipped and counted.