Enhance security policy and documentation updates

- Expanded the SECURITY.md file to clarify the reporting process for vulnerabilities, including what is in and out of scope for reporting.
- Added detailed guidelines on how to handle end-of-life (EOL) software and the implications of using EOL operating systems.
- Updated the documentation on choosing an image to include notes on floating vs. version-pinned tags, emphasizing the importance of selecting supported OS releases.
- Revised the Upgrade Guide to explain the release process and update strategies, ensuring users understand the implications of their choices regarding image tags.

Author: jaydrogers

SECURITY.md

@@ -1,29 +1,58 @@
 # Security Policy
 
-## PHP upstream support (php.net)
+`serversideup/php` is a **downstream distributor**. We package PHP, NGINX, Apache, Composer, the base operating system, and related tooling into production-ready Docker images. We do not maintain those upstream projects ourselves — this policy explains what belongs here and what belongs upstream.
 
-The table below is the **official PHP project** support phase for each branch—not a guarantee that every branch appears in our image matrix. Use it to decide when to upgrade.
+## Reporting a vulnerability
+
+For anything in scope below, please use **[GitHub's private vulnerability reporting](https://github.com/serversideup/docker-php/security/advisories/new)** to open a confidential report. Please include:
+
+- The affected image tag and digest (e.g. `serversideup/php:8.4-fpm-nginx@sha256:…`)
+- Steps to reproduce and the impact
+- Any suggested mitigation, if you have one
+
+Do not disclose details publicly (issues, discussions, social media) before a fix is released.
+
+## What is in scope
+
+Vulnerabilities in what *we* author and ship:
+
+- Entrypoint scripts, healthchecks, helper scripts, and S6 service definitions in `src/`
+- Default configs we ship for PHP-FPM, NGINX, Apache, and FrankenPHP
+- Insecure defaults: ports, file permissions, the `www-data` user model, SSL defaults
+- Build pipeline integrity (GitHub Actions workflows, tag assembly, image publishing)
+- Documentation that materially misleads users about a security-relevant setting
 
-| Branch | Phase on php.net |
+## What is out of scope — report to the upstream project
+
+Vulnerabilities in software we package but do not maintain belong with the upstream project, not here:
+
+| Component | Where to report |
 | --- | --- |
-| 8.5 | Active support (bug + security fixes) |
-| 8.4 | Active support (bug + security fixes) |
-| 8.3 | Security fixes only |
-| 8.2 | Security fixes only |
-| 8.1 | End of life — upgrade as soon as practical |
-| 8.0 | End of life — upgrade as soon as practical |
-| 7.4 | End of life — upgrade as soon as practical |
-| ≤ 7.3 | End of life — not built in this project’s current matrix |
+| PHP itself | [The PHP project](https://www.php.net/) (security mailing list: `security@php.net`) |
+| NGINX | [NGINX security advisories](https://nginx.org/en/security_advisories.html) |
+| Apache HTTP Server | [Apache HTTPD security](https://httpd.apache.org/security_report.html) |
+| Composer | [composer/composer on GitHub](https://github.com/composer/composer/security) |
+| Debian / Alpine base packages | The respective distribution security teams |
+
+If an upstream CVE is already publicly disclosed, you don't need to file with us — we pick up upstream patches on our **weekly rebuilds (Tuesday 08:00 UTC)** for floating tags. See [How our releases work](https://serversideup.net/open-source/docker-php/docs/getting-started/upgrade-guide#how-our-releases-work) for the full cadence and which tags receive rebuilds.
 
-**References**
+## Component lifecycle references
 
-- [Supported Versions](https://www.php.net/supported-versions.php) — active and security support dates for current branches  
-- [End-of-life branches](https://www.php.net/eol.php) — historical EOL dates  
+Our images bundle third-party software, each with its own support window. Before reporting an issue (or pinning to a particular version), confirm the component is still receiving security fixes from its maintainers:
 
-We may still ship images for **EOL** PHP versions to help migrate legacy apps; prefer a [currently supported branch](https://www.php.net/supported-versions.php) for production.
+| Component | Lifecycle reference |
+| --- | --- |
+| PHP | [endoflife.date/php](https://endoflife.date/php) |
+| Debian | [endoflife.date/debian](https://endoflife.date/debian) |
+| Alpine Linux | [endoflife.date/alpine-linux](https://endoflife.date/alpine-linux) |
+| NGINX | [endoflife.date/nginx](https://endoflife.date/nginx) |
+| Apache HTTP Server | [endoflife.date/apache](https://endoflife.date/apache) |
+| Composer | [endoflife.date/composer](https://endoflife.date/composer) |
 
----
+We continue to publish images for end-of-life PHP versions and operating system bases so legacy applications have a path into containers — but those bases will not receive new upstream security fixes. Use them as a stepping stone, not a destination. See [Choosing an image — Operating Systems](https://serversideup.net/open-source/docker-php/docs/getting-started/choosing-an-image#operating-systems) for the trade-off.
 
-## Reporting a vulnerability
+## How updates flow
+
+For the full release model, how floating vs. version-pinned tags behave, and how to apply your own patches to a pinned image, see the [Upgrade Guide](https://serversideup.net/open-source/docker-php/docs/getting-started/upgrade-guide).
 
-Follow [our responsible disclosure policy](https://www.notion.so/Responsible-Disclosure-Policy-421a6a3be1714d388ebbadba7eebbdc8).
+For the EOL trade-off when picking an operating system base, see [Choosing an image — Operating Systems](https://serversideup.net/open-source/docker-php/docs/getting-started/choosing-an-image#operating-systems).

docs/content/docs/1.getting-started/5.choosing-an-image.md

@@ -61,6 +61,10 @@ Here's what each part means:
 | `{{operating-system}}` <br />The operating system to use. | `debian` | `alpine` <br /> `bullseye` <br /> `bookworm` <br /> `trixie` |
 | `{{github-release-version}}` <br />The version of the GitHub release to use. | (latest stable release) | See our [GitHub Releases](https://github.com/serversideup/docker-php/releases){target="_blank"} for specific versions. |
 
+::note{title="Floating vs. version-pinned tags"}
+Including `{{github-release-version}}` (e.g. `8.4-fpm-nginx-v4.3.5`) creates a **version-pinned tag** that is written once and never updated. Omitting it (e.g. `8.4-fpm-nginx`) gives you a **floating tag** that we rebuild weekly with the latest security patches. The right choice depends on how you balance reproducibility against staying current — see [How our releases work](/docs/getting-started/upgrade-guide#how-our-releases-work) and [Choosing your update strategy](/docs/getting-started/upgrade-guide#choosing-your-update-strategy) in the upgrade guide.
+::
+
 ## PHP version
 There are many factors to consider when choosing the right PHP version. Best practices include:
 
@@ -127,6 +131,17 @@ Choosing an operating system comes down to a few preferences, but ultimately you
 | `debian` (default) | Debian is a popular Linux distribution that is known for its stability and reliability. It is the default operating system for our images. |
 | `alpine` | Alpine is a lightweight Linux distribution that is known for its small size and low resource usage. |
 
+::warning{title="Choose an OS release that's still supported"}
+We continue to publish images on end-of-life operating system releases (like Debian Bullseye and Alpine 3.16) so legacy applications can be containerized as a first step. Be aware that EOL bases also ship EOL versions of other software like NGINX and OpenSSL — and no amount of `apt upgrade` will get you newer ones, because the distribution itself has stopped releasing fixes.
+
+Before picking a base, confirm it's currently supported:
+
+- [Debian release lifecycle](https://endoflife.date/debian){target="_blank"}
+- [Alpine Linux release lifecycle](https://endoflife.date/alpine-linux){target="_blank"}
+
+If you must start on an EOL base, treat it as a stepping stone. See [EOL versions and the legacy-modernization path](https://github.com/serversideup/docker-php/blob/main/SECURITY.md#eol-versions-and-the-legacy-modernization-path) for the recommended migration approach.
+::
+
 ### Specific versions
 ::note
 Not all operating systems are available for all image variations and PHP versions. Double check [Docker Hub](https://hub.docker.com/r/serversideup/php/tags){target="_blank"} and [GitHub Packages](https://github.com/serversideup/docker-php/pkgs/container/php){target="_blank"} for the most accurate list of available tags.