sneak
dfb44c5546
check / check (push) Waiting to run
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
57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
# What the image holds
|
|
|
|
The `smallwebwaf` image is the base of each app's own image. The requirements
|
|
are under "Deployment" in [`SPEC.md`](../SPEC.md); this file lists what the
|
|
image holds, how each part is pinned, and why.
|
|
|
|
## Contents
|
|
|
|
- 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.
|