Image hardening#
This page lists what the kit's images harden, where each setting lives, and the switch that turns it down when an app needs that. Every item has a test that reads the file, and the image contract suite checks it again inside the built image. Read Local parity first for the images themselves.
Two kinds of file carry the hardening. The base (.squire/base-fallback.Dockerfile) stands in for the Citadel image; what it sets is what Squire asks the real image to set, and the real image keeps deciding on Citadel. The app image (.squire/Dockerfile) is the local copy of the Dockerfile Citadel generates, and runs on either base.
Apache: a quieter banner, no TRACE#
The base enables .squire/apache-hardening.conf as zz-squire-hardening.conf, so it loads after Debian's security.conf, which ships ServerTokens OS and ServerSignature On:
| Directive | Effect |
|---|---|
ServerTokens Prod |
The Server header says Apache, not Apache/. |
ServerSignature Off |
Error pages Apache writes itself carry no version footer. |
TraceEnable Off |
TRACE answers 405, so a script cannot read cookies back off an echo. |
These live in the base, never in the app image: locally the app image also runs on the real Citadel image, and hardening it there would show a parity the platform does not have.
opcache: set by how your code arrives#
.squire/php.ini turns opcache on for the web (opcache.enable = 1, opcache.enable_cli = 0), and the fallback base loads the extension when its image does not already. Whether opcache looks at your files again depends on how the code gets into the container, so there are two cases and one switch, SQUIRE_OPCACHE_VALIDATE:
| How code arrives | SQUIRE_OPCACHE_VALIDATE |
What opcache does |
|---|---|---|
| Pulled into a running container: a Citadel Quick Update, a bind mount on your machine, or anywhere Squire cannot tell | 1, the default |
Checks a file again at most every 2 seconds (revalidate_), so a release is served within 2 seconds with no restart. |
| Baked into an image that never changes: OpenShift, Coolify or raw Docker with the code copied in at build time | 0, which you choose |
Never checks a file again. The image is replaced, not edited, so there is nothing to notice, and requests skip the check. |
Set the switch where the image is built, docker build --build-arg SQUIRE_OPCACHE_VALIDATE=0 -f .squire/Dockerfile ., or when it runs, -e SQUIRE_OPCACHE_VALIDATE=0 (the run-time value wins). Use 0 or 1, never an empty value: PHP falls back to the default only when the variable is unset, and empty turns the checks off. Locally, put SQUIRE_OPCACHE_VALIDATE=0 in .env.squire to try the baked case on your bind mount, and remember that saved files then wait for an Apache restart.
The other values, each read from the environment (PHP 8.3 and later):
| Setting | Default | Environment variable |
|---|---|---|
opcache.memory_consumption |
128 (megabytes) |
SQUIRE_ |
opcache.max_accelerated_files |
20000 (a Laravel app with its vendor/ is 10000 to 15000 files) |
SQUIRE_ |
opcache.interned_strings_buffer |
16 |
none |
The release warning stays. The release script's "check opcache" step never fails, and says what it sees: a note when opcache checks files, and a warning when a release runs in place (Apache up) against an opcache set to 0, because Apache keeps serving the PHP it compiled before the release until it restarts. In the first-release hook, before Apache starts, 0 is only a note.
disable_functions: the web loses the shell#
A web request should never shell out. .squire/php-web.ini holds the settings only the web server gets, and the app image appends it to php.ini as php-apache2handler.ini, the file mod_php reads instead of php.ini. The CLI reads php.ini alone, so Composer and its scripts, artisan, queue workers, the health check and the release script keep every function.
| Disabled on the web | Why |
|---|---|
exec, passthru, shell_exec, system |
Run a shell command: the first thing an injected payload reaches for. |
pcntl_exec |
Replaces the PHP process with another program. |
phpinfo, show_source, highlight_file |
Print the server's setup or its source to whoever asked. |
proc_open and popen stay: Symfony Mailer's sendmail transport, Laravel's Process and PHPMailer use them on the web. A test runs PHP on the same two files and checks both sides: the web list is gone, and the CLI and the mail functions are still there.
The switch. SQUIRE_PHP_DISABLE_FUNCTIONS replaces the list, and none (a name no function has) disables nothing: the way out for an older app that calls exec from a page while you move that work to a queued job. Leave it unset for the default list: PHP falls back only when the variable is unset, so an empty value disables nothing as well, and the parity compose files pass it by name only for that reason. Locally, put SQUIRE_PHP_DISABLE_FUNCTIONS=none in .env.squire.
disable_classes is not set. It never stopped a caller who could reach another class, and PHP 8.5 removed it.
Session cookie: HttpOnly, Secure, SameSite=Lax#
PHP's own session cookie gets all three flags from .squire/php.ini, so a raw PHP app that never calls helmet_boot() still sends a safe one, and SESAME has nothing to warn about: session.cookie_httponly = 1 (scripts cannot read it), session.cookie_secure = 1 (https only; TLS ends at the proxy in front of the container, so the browser always sees https) and session.cookie_samesite = Lax.
Lax sends the cookie on a top-level GET from another site, which is how a CAS ticket and an OIDC code come back, and never on a cross-site POST, image or frame, which blunts CSRF. A SAML ACS receives a cross-site POST without the cookie; SESAME parks the response and finishes on a GET for that reason. An app whose session must ride some other cross-site POST sets session.cookie_samesite for that app instead. Laravel apps set their own cookie in config/session.php and are not affected. On Citadel, as above, the platform's php.ini decides.
Secrets: files at run time, never in a layer#
An image layer is readable by anyone who can pull the image, and docker history shows every build argument. So no secret is ever a build argument, an ENV line, a copied file, or something build.sh fetches. Tests hold the kit to it: the Dockerfiles carry no ARG or ENV named like a password, key, token or secret, the build context is build.sh and .squire/ only (the .dockerignore starts with * and never lets an env file back in), and build.sh never reads .env.
Secrets arrive when the container runs:
| Where | How a secret arrives | Who reads it |
|---|---|---|
| Citadel | the dashboard's configuration-files step writes ./.env into the source tree at deploy time |
the app (Laravel, or phpdotenv in a raw PHP app); see Citadel setup |
| Docker Compose | a secrets: entry, mounted as / |
the release script and the fallback entrypoint, below |
docker run |
-v "$PWD/ |
the same |
| OpenShift, Kubernetes | a Secret volume mounted at /run/secrets (each key is a file) |
the same |
The secrets folder. scripts/release.sh and the fallback base's entrypoint share one loader: each regular file in SQUIRE_SECRETS_DIR (default /run/secrets) whose name is a variable name becomes that variable, with one trailing line ending trimmed, unless the environment already sets it. Names that would change how the shell runs (PATH, IFS, BASH_ENV, LD_* and a few more) are skipped, and a file the user cannot read is a warning. The log names what it loaded and never prints a value. The entrypoint loads the folder before Apache starts, so the PHP it runs sees the variables through getenv(); the release loads it again, because su -l citadel starts it with a clean environment.
Name the file after the variable the app reads. With Compose, set the file name with target:
services:
app:
secrets:
- source: db_password
target: DB_PASSWORD
secrets:
db_password:
file: ./secrets/db_password.txt
npm: no install scripts, no day-old versions#
A package's install script runs with the release's rights, and a hijacked version is usually caught and pulled within hours. So the release does two things:
- No install scripts.
npm ci --ignore-scripts(orpnpm install --frozen-lockfile --ignore-scripts), on by default withSQUIRE_NPM_IGNORE_SCRIPTS=1. A package that needs its own scripts (a native addon such assharp, a binary download such asesbuild) is named inSQUIRE_NPM_REBUILD, and only it runs them after the install:npm rebuild --ignore-scripts=false sharp, orpnpm rebuild sharp(pnpm 10 also needs it inpnpm.onlyBuiltDependencies). Each name is checked against the shape of a package name first. - A minimum release age. The Vue layer's
.npmrcsetsmin-release-age=1:npm installandnpm updateskip versions published less than a day ago, so they never reach the lock file.npm ciinstalls the lock exactly, so this guards the day the lock is written, not the release. npm reads the setting from 11.10 on; Node 22 ships npm 10, which ignores it, and the release says so in its log.
Policy. Keep one day for every app; raise it, never lower it, in the app's own .npmrc. To take a fix published this morning, install it on purpose and review the lock diff:
npm install --min-release-age=0 some-package@1.2.3
Base images: pinned by digest#
A tag such as php:8.4-apache moves: two builds of the same commit a week apart can get different bytes. Every image the kit's files pull is pinned by the digest of its multi-arch list instead, php:8.4.27-apache@sha256:..., which names the same bytes on an arm64 laptop or CI runner and on an amd64 server: the fallback base's PHP, Node and Composer, the Vue layer's Node service, HA-Proxy and MySQL in the compose files, and the Oracle parity bases. A test fails on any reference without a digest.
The kit's Composer (the fallback base and the Oracle parity image) is 2.11.1, composer:2.11.1@sha256:8de2184c...; 2.10 is no longer maintained. Composer 2.11's policy.cooldown is off by default, and the kit does not turn it on.
The kit's Dockerfiles write each name in full, registry and namespace included: docker.io/library/php:8.4.27-apache@sha256:..., not php:8.4.27-apache@sha256:.... Docker reads both the same way, but Buildah and Podman refuse a short name where their short-name mode is enforcing (a COPY --from=composer:2 fails outright), so a CI job that builds with Buildah needs the full name. A test fails on a short name in any of the kit's Dockerfiles.
Through a proxy or a mirror#
The fallback base takes its three images as build arguments, PHP_IMAGE, NODE_IMAGE and COMPOSER_IMAGE, and Composer comes from a FROM ${COMPOSER_IMAGE} AS composer stage, so nothing has to be edited in the file. To pull through a proxy or a mirror, keep each default's tag and digest and swap the registry part. GitLab's Dependency Proxy takes the Docker Hub name without docker.io/library/ after its group prefix:
base=.squire/base-fallback.Dockerfile
prefix="$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX"
args=""
for arg in PHP_IMAGE NODE_IMAGE COMPOSER_IMAGE; do
ref=$(sed -n "s/^ARG $arg=//p" "$base")
args="$args --build-arg $arg=$prefix/${ref#docker.io/library/}"
done
docker build -f "$base" $args -t squire/php-parity-base:8.5r3 .squire # the app's PHP line; or: buildah bud ...
A registry mirror that keeps Docker Hub's paths takes the same loop with $mirror/library/${ref#docker.io/library/}. The digest still decides the bytes, so a proxy cannot hand back a different image under the same name.
To bump one, read the new list's digest and check it lists both platforms, then replace the whole reference:
docker buildx imagetools inspect php:8.4.28-apache
Look for the Digest: line, and for linux/amd64 and linux/arm64/v8 under Manifests. Then run the tests and the image contract suite on both platforms. Maintainers have the full procedure in MAINTAINING.md. Two references are yours, not the kit's: the real Citadel image (SQUIRE_BASE_IMAGE, pin it once you have its digest) and any SQUIRE_NODE_IMAGE, SQUIRE_PROXY_IMAGE or SQUIRE_MYSQL_IMAGE override.
The image contract suite#
A file can promise anything; the running image is what counts. scripts/contract-image.sh (in Squire's repository) builds the fallback base and the app image for a platform, runs the container with a throwaway raw PHP app mounted at /citadel/src, a throwaway secret mounted at /run/secrets and the compose file's least privilege (every capability dropped but the seven the app service adds back, no-new-privileges, 256 processes, 512 MB), runs the release as citadel, and then pipes scripts/contract-image-checks.php to php inside the container. One PASS or FAIL line per check:
| Item | Checked in the running image |
|---|---|
| Apache | the Server header is exactly Apache; no X-Powered-By; TRACE answers 405 with no version footer |
| opcache | code pulled in place: the web checks files (validate_ 1, revalidate_freq 2) and the release notes it; code baked in (the app image rebuilt with SQUIRE_): the web never checks; 20000 files either way |
| disable_functions | the web has no exec and the rest, and keeps proc_open and popen; the CLI disables nothing; a Composer post-install-cmd that shells out runs in the release |
| Secrets | the web sees the mounted secret (compared as an md5, never printed), the release names it, and its value is in no log, no layer and no image config |
sh scripts/contract-image.sh --platform=linux/amd64
sh scripts/contract-image.sh --platform=linux/arm64 # needs qemu emulation on an amd64 host
sh scripts/contract-image.sh --base-image=citadel/php-apache:8.5r3 # Citadel's own image, already on this machine
GitHub CI runs it on the fallback for both platforms on every push: a green run there is a contract, not a certificate.
On Citadel's own image#
--base-image=REF runs the same contract on an image that is already on your machine instead of the fallback. For Citadel's own, Parity's parity image get loads citadel/php-apache:8.5r3 byte for byte (its image id is checked). The script never pulls the image: Citadel's images are internal, and something else with the same name would prove nothing. It stops if the image is missing or built for another platform.
Three checks test what only the base image decides, which no file in your app can change: the Apache server directives (ServerTokens, TraceEnable, ServerSignature) and whether its entrypoint turns /run/secrets into variables for Apache. On the fallback those are the kit's promises and a miss is a FAIL. On any other image a miss prints a GAP: line, and the run ends with a count of them: true, worth knowing, the image owner's to fix, and not a failure of your app.
On 2026-11-10 citadel/php-apache:8.5r3 (image id 950dcf67937a) passed every check the kit owns, on linux/amd64, in 80 seconds, under the compose file's least privilege, and showed three gaps:
| Gap | What Citadel's image does | What it means for your app |
|---|---|---|
Server header |
Apache/: the version and the OS |
Every answer names the Apache version. Only the platform can set ServerTokens Prod |
| Error page footer | Apache's own error pages carry the version footer | The same, for ServerSignature Off |
| Secrets for the web | the entrypoint does not read /run/secrets |
On Citadel, ./.env is the secret path, as above; the release script still reads /run/secrets |
TRACE already answers 405 there. Everything else held on Citadel's bytes: the first release at container start, a second release with the smoke test, /up.php and health.php, opcache in both cases (pulled in place and baked in), the web's disable_functions, the CLI keeping every function, a Composer script that shells out, and the secret's value in no log, layer or image config.