Sécurité et exploitation du générateur de rétroportage

Outil de génération — PAS une dépendance d’exécution. Cette page traite de l’exploitation du pipeline de génération et de la confiance qu’on peut lui accorder. La posture de sécurité du moteur PDF lui-même est documentée avec le moteur, pas ici.

En un coup d’œil

Le générateur transforme du code source dont il n’est pas l’auteur et produit une distribution sur laquelle il n’assure pas le développement. Son modèle de sécurité en découle. La frontière de confiance se situe au niveau de l’extraction du code source et de la chaîne d’outils. L’artefact produit est en lecture seule et généré par la machine. La répartition des licences entre le paquet public et le paquet Pro est figée dans le code.

La frontière de confiance

Les entrées du générateur sont les dépôts source et la chaîne d’outils épinglée. Sa sortie est un artefact dérivé. Trois propriétés sont garanties :

La distribution générée est en lecture seule et produite par la machine. Elle est publiée sous forme d’étiquettes de version, pas sous forme de branches de ce dépôt. Le développement, les rapports de bogue et les demandes de fonctionnalités doivent être adressés aux dépôts source nextpdf/* d’origine, jamais à l’arborescence générée. Vérifié par rapport au bloc d’avertissement du README.md du projet et à .github/workflows/build.yml (la publication valide et étiquette l’arborescence générée à partir de zéro).
La portée du jeton de publication est étroite. secrets.BACKPORT_TRIGGER_TOKEN autorise le clonage des dépôts source à l’étiquette de publication. Il n’est référencé que dans les étapes d’extraction du code source. Vérifié par rapport à build.yml (utilisation de GH_TOKEN).
La répartition des exécuteurs CI est délibérée. Les événements de confiance s’exécutent sur des exécuteurs PHP auto-hébergés ; les pull requests issues de forks et les exécutions Dependabot sont orientées vers des exécuteurs hébergés par GitHub. Le code non fiable ne s’exécute jamais sur le pool d’exécuteurs de confiance. Vérifié par rapport à .github/workflows/0-ci.yml (la condition runs-on).

Posture vis-à-vis de la chaîne d’approvisionnement

La chaîne d’outils est contrainte dans composer.json. Rector ^2.0, PHPStan ^2.1, PHPUnit ^13.0 et l’ensemble symfony/polyfill-*. Le générateur n’a aucune dépendance d’exécution NextPDF, de sorte que la compromission d’un paquet d’exécution NextPDF ne peut pas atteindre le générateur. Vérifié par rapport à composer.json.
Les mises à jour de dépendances sont pilotées par un bot et soumises à un contrôle. Il existe une configuration Dependabot et un workflow de fusion automatique ; les exécutions Dependabot sont épinglées à des exécuteurs hébergés par GitHub et passent tout de même par l’ensemble des contrôles CI (PHPStan, tests, exécution à blanc) avant la fusion. Vérifié par rapport à .github/dependabot.yml et .github/workflows/0-ci.yml, 9-dependabot-auto-merge.yml.
La sortie exclut l’état de génération. L’archive de publication est créée en excluant vendor/ et .git/, si bien que l’artefact publié contient le code source et le manifeste généré, et non l’arbre de dépendances propre au générateur. Vérifié par rapport à build.yml (zip ... -x '*/vendor/*' '*/.git/*').
L’analyse statique contrôle le code de génération. composer analyse exécute PHPStan au niveau 10 sur rector/rules et scripts à chaque push et à chaque pull request vers l’une ou l’autre des branches permanentes. Cela s’exécute avant toute exécution à blanc. Vérifié par rapport à composer.json et 0-ci.yml.

Le contrôle de validation syntaxique

Le script de génération ne vérifie pas la syntaxe de la sortie en local. La raison en est que l’hôte de génération exécute une version de PHP plus récente que la cible. Le contrôle qui fait autorité se trouve dans le workflow de publication. Après la génération, l’exécuteur bascule sur le PHP cible et lance php -l sur l’ensemble de output/src, ce qui fait échouer la publication à la moindre erreur d’analyse ou erreur fatale. L’artefact est ensuite installé et éprouvé sur l’ensemble de la matrice de validation — PHP 8.1 à 8.4 pour la voie PHP 8.1, PHP 7.4 et 8.0 pour la voie PHP 7.4. Une distribution qu’un environnement d’exécution cible rejetterait n’est jamais publiée. Vérifié par rapport à scripts/build.php (validateOutput()) et .github/workflows/build.yml (la vérification syntaxique et les jobs validate-*).

Il s’agit d’une garantie de comportement observé, limitée aux environnements d’exécution que le pipeline éprouve. Ce n’est pas une certification de conformité. Elle n’atteste pas la correction du programme transformé au-delà de l’acceptation syntaxique et de la suite de tests propre au projet.

Répartition des licences

Les deux paquets produits portent des licences différentes, figées dans scripts/adjust-composer.php :

Paquet	Champ de licence	Défini par
`nextpdf/backport`	`Apache-2.0`	`generatePublicComposer()`
`nextpdf/backport-pro`	`proprietary`	`generateProComposer()`

Le dépôt du générateur lui-même est sous licence Apache-2.0 (composer.jsonlicense). Son CHANGELOG.md consigne un changement de licence antérieur, de LGPL-3.0-or-later vers Apache-2.0. Les versions publiées avant ce changement restent sous l’ancienne licence et demeurent récupérables, tandis que chaque nouvelle version est sous Apache-2.0. La distribution Pro est propriétaire, n’est produite que pour la cible PHP 8.1 et requiert phpseclib/phpseclib ^3.0. Vérifié par rapport à CHANGELOG.md, composer.json et scripts/adjust-composer.php.

Garanties d’exploitation et leurs limites

Ce que le pipeline garantit, dans la limite de ce que le code impose :

Arrêt à la première défaillance. La génération s’interrompt à la première étape qui échoue, avec une erreur nommée. Une distribution partielle n’est jamais publiée, car les jobs de publication dépendent d’une génération et d’une validation réussies. Vérifié par rapport à scripts/build.php (step()) et au needs du job build.yml.
Générations sérialisées. Le groupe de concurrence backport-build avec cancel-in-progress: false empêche deux publications source d’entrer en concurrence pour la même étiquette de publication. Vérifié par rapport à build.yml.
Entrées reproductibles. Le pipeline clone chaque dépôt source à l’étiquette de publication exacte avant de générer. Vérifié par rapport à build.yml (--branch "${TAG}").

Ce qu’il ne prétend pas garantir :

Il ne certifie ni la conformité aux normes, ni la compatibilité complète avec les versions de PHP, ni la correction du programme transformé au-delà de l’acceptation syntaxique et de la suite de tests.
Le rétroportage supprime l’immuabilité imposée à l’exécution (suppression de readonly). Le code qui comptait sur l’environnement d’exécution pour rejeter une écriture sur une propriété en lecture seule perd cette défense dans la sortie rétroportée. Il s’agit d’un compromis documenté et intentionnel au profit de la sûreté de clone-with — voir /integrations/backport/troubleshooting/.

Signaler un problème

Les problèmes de sécurité dans le générateur suivent le SECURITY.md du dépôt : signale-les via un GitHub Security Advisory ou auprès du contact sécurité, pas dans une issue publique. Les problèmes dans le code généré doivent être signalés sur les dépôts source d’origine, car l’arborescence générée est produite par la machine et ne fait l’objet d’aucun développement. Vérifié par rapport à SECURITY.md et au README.md du projet.

Et ensuite

/integrations/backport/overview/ — ce qu’est le générateur et ce qu’il produit.
/integrations/backport/production-usage/ — exploiter le pipeline de publication.