Skip to content
Menu

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/2.4.x (Debian).
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_freq = 2), 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_MEMORY
opcache.max_accelerated_files 20000 (a Laravel app with its vendor/ is 10000 to 15000 files) SQUIRE_OPCACHE_MAX_FILES
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.

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 /run/secrets/NAME the release script and the fallback entrypoint, below
docker run -v "$PWD/secrets/DB_PASSWORD:/run/secrets/DB_PASSWORD:ro" 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 (or pnpm install --frozen-lockfile --ignore-scripts), on by default with SQUIRE_NPM_IGNORE_SCRIPTS=1. A package that needs its own scripts (a native addon such as sharp, a binary download such as esbuild) is named in SQUIRE_NPM_REBUILD, and only it runs them after the install: npm rebuild --ignore-scripts=false sharp, or pnpm rebuild sharp (pnpm 10 also needs it in pnpm.onlyBuiltDependencies). Each name is checked against the shape of a package name first.
  • A minimum release age. The Vue layer's .npmrc sets min-release-age=1: npm install and npm update skip versions published less than a day ago, so they never reach the lock file. npm ci installs 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_timestamps 1, revalidate_freq 2) and the release notes it; code baked in (the app image rebuilt with SQUIRE_OPCACHE_VALIDATE=0): 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/2.4.69 (Debian): 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.