Files

T

check / check (push) Waiting to run

Details

README rewritten from scratch so a newcomer can follow it (closes #154 , closes #155 )

The old README opened with project history and one list of a hundred
settings. The new one leads with what smallwebwaf is, what it protects
against, how to build and deploy it, how it sits in front of the app,
what happens to a request, the settings most deployments touch, how to
check it works and how to develop it. The reference material, every
setting, bans, rule files, the Core Rule Set, the admin endpoints, the
request log, alerts, metrics, state files, lookups, reputation sources,
the image and gitea, moves to files under docs/, each linked from the
README. Every statement was checked against the code on next.

Model: fable-5-1

2026-10-22 21:02:38 +00:00

3.2 KiB

Raw Blame History

What the image holds

The smallwebwaf image is the base of each app's own image. The requirements are under "Deployment" in SPEC.md; this file lists what the image holds, how each part is pinned, and why.

Ubuntu 26.04 LTS, the newest long-term support release of Ubuntu, pinned by digest. The image moves to the next LTS release when that ships.
ca-certificates, nix-bin and runit from Ubuntu, installed from a dated snapshot of its archive and checked by hash. The Ubuntu image has no CA certificates; without them Nix cannot download packages and smallwebwaf cannot reach GeoJS.
Nix and nixpkgs, fixed at one release. Root uses Nix directly; no Nix daemon runs. nix-bin creates no build users, so build-users-group = in /etc/nix/nix.conf lets root build without them.
runit, and runsvinit as the entrypoint, as the owner's code style guide asks for service containers. No package carries runsvinit, so the image builds it from its archived source (github.com/peterbourgon/runsvinit, unchanged since 2015) at a fixed commit hash, with a go.mod the build writes. runsvinit starts runit's runsvdir, which runs the run script of each directory under /etc/service and runs it again whenever it exits. Ubuntu's sv looks for services there too.
The smallwebwaf binary, and a user of its own, smallwebwaf (uid and gid 65532).
The service directory /etc/service/smallwebwaf. Its run script waits one second (sleep 1), makes SWWAF_STATE_DIR and every file in it belong to the smallwebwaf user, and starts smallwebwaf as that user with runit's chpst.
The directory /var/lib/smallwebwaf for the state files, and /etc/smallwebwaf/rules.d with the default rule file.
Port 8080 declared (EXPOSE 8080), and the health check (HEALTHCHECK) that "The health check" in SPEC.md describes.

Pinning

Ubuntu's packages come from Ubuntu's snapshot service, the archive as it was at the moment the Dockerfile names (--snapshot 20261001T000000Z), never earlier than the pinned Ubuntu image's date. The Dockerfile names the SHA-256 hash of each of the snapshot's InRelease files, which cover every package list and so every package, and the build checks them before installing. The hashes are the amd64 archive's, so the image is built for amd64 only. The snapshot is fetched over HTTPS with the CA certificates of the Go image that builds smallwebwaf, itself pinned by digest, since the Ubuntu image has none.
nixpkgs comes from a release file on releases.nixos.org (nixexprs.tar.xz of nixos-26.05.11045.774debe7a0d1), named with its SHA-256 hash, not from a GitHub archive, whose bytes can change. It is set up for root as nixpkgs. Root's Nix profile, /nix/var/nix/profiles/default/bin, is last on the PATH, so that no package hides the image's own commands; busybox's sv, for one, looks for services elsewhere. Unpacked, nixpkgs takes about 500 MiB.
An app built on the image gets the same packages each time it is built. Security fixes from Ubuntu and nixpkgs come with a newer smallwebwaf image, which an app takes by changing the digest in its FROM line. The image moves to each new nixpkgs release, every six months.

3.2 KiB Raw Blame History

What the image holds

Contents

Pinning

3.2 KiB

Raw Blame History