Magento patches beheren: Composer en de Quality Patches Tool

Een Magento-patch is niet altijd een nieuwe versie. Wie het verschil tussen een security-release en een losse patch niet kent, laat gaten open of breekt zijn shop.

Adobe levert fixes op drie manieren: nieuwe versies, security-only patch-releases en losse patches. Elk heeft eigen regels. Dit artikel zet ze op een rij en laat zien hoe je patches onder versiebeheer houdt, zodat je ze reproduceerbaar, testbaar en terugdraaibaar uitrolt.

Drie soorten fixes

1. Een nieuwe 2.4.x-release

De reguliere versies bevatten functionaliteit, bugfixes en beveiligingsfixes. Upgraden naar een nieuwe lijn is een project: je moet PHP-versies, extensies en eigen code controleren. Meer daarover in Magento 2.4 versies en end-of-support.

2. Security-only patch-releases (-pX)

Naast de grote releases publiceert Adobe patch-releases met de toevoeging -p1, -p2 en zo verder. Een voorbeeld van de notatie is 2.4.x-p3, waar x je minor-versie is. Deze releases bevatten vooral beveiligingsfixes en geen nieuwe functionaliteit. Daardoor zijn ze minder risicovol om uit te rollen dan een volledige upgrade.

Een patch-release volg je via Composer: je past de versie van de Magento-metapackages aan en draait composer update. Test altijd op staging.

3. Isolated patches

Soms is een volledige release te groot of nog niet beschikbaar voor jouw versie. Dan publiceert Adobe een losse patch voor één specifiek probleem. Dat kan een beveiligingsfix zijn, zoals bij kritieke lekken, of een functionele fix. Zo'n patch pas je toe op je bestaande installatie, zonder je versie te veranderen.

Voor losse patches zijn twee gangbare routes: de Quality Patches Tool en Composer-patches.

De Quality Patches Tool

Adobe biedt de Quality Patches Tool aan als Composer-package: magento/quality-patches. Je gebruikt hem om officiele patches voor je versie te bekijken, toe te passen en terug te draaien.

Installeren:

composer require magento/quality-patches

Daarna gebruik je het commando vendor/bin/magento-patches. Veelgebruikte acties:

# Welke patches zijn beschikbaar voor deze installatie en wat is de status?
vendor/bin/magento-patches status

# Een patch toepassen (gebruik de patch-ID uit de status-uitvoer)
vendor/bin/magento-patches apply <patch-id>

# Een patch terugdraaien
vendor/bin/magento-patches revert <patch-id>

Wat het goed doet:

• Het kent welke patches bij jouw versie passen en laat zien welke al zijn toegepast.
• Het houdt bij wat is toegepast, zodat je terug kunt draaien.
• Het is de aanbevolen route voor officiele patches van Adobe.

Waar je op moet letten:

• De tool past bestanden aan in je codebase. Zonder aandacht verdwijnt die wijziging bij de volgende composer install op een schone omgeving of bij een deploy vanaf git. Maak patches daarom onderdeel van je deployproces, of leg de uitkomst vast in versiebeheer.
• Zie de status-uitvoer als bron: de lijst met beschikbare patches verandert per versie en tijd. Gebruik de actuele uitvoer, niet een lijst uit een artikel.
• Een patch kan botsen met eigen code of een extensie die dezelfde bestanden overschrijft of beinvloedt. Test.

cweagans/composer-patches: patches in je repository

De tweede route is de Composer-plugin cweagans/composer-patches. Daarmee definieer je in composer.json welke patchbestanden worden toegepast op welke packages, tijdens composer install. Het grote voordeel: de patches staan in je repository en worden bij elke installatie op elke omgeving gelijk toegepast.

De opzet is grofweg zo, in de extra-sectie van composer.json:

{
  "extra": {
    "patches": {
      "magento/module-catalog": {
        "Korte omschrijving van de fix": "patches/magento/module-catalog-fix.patch"
      }
    }
  }
}

De exacte syntax verschilt per hoofdversie van de plugin. Lees de documentatie van de versie die je installeert voor de actuele opties, zoals een apart patchbestand in plaats van inline definities. Gebruik dus niet blind een voorbeeld uit een blog, ook niet dit.

Wat we praktisch doen:

• Elk patchbestand staat in patches/ in de repository, met een duidelijke naam en een korte beschrijving.
• Een patch bevat een verwijzing naar de bron: de Adobe-publicatie of het issue waar de fix vandaan komt.
• We stellen in dat een falende patch de installatie laat mislukken. Een patch die stil niet wordt toegepast is het gevaarlijkste scenario.
• Een patch verdwijnt uit de lijst zodra de fix in de release zit waar je naar upgradet.

Welke route kies je?

Veel teams combineren ze. De Quality Patches Tool helpt je de juiste officiele patch te vinden en uit te proberen. Voor de blijvende, versiebeheerde variant leg je de patch vast in je repository. Welke aanpak past hangt af van je deployproces. Wat telt: de patch moet op elke omgeving hetzelfde worden toegepast, en je moet kunnen zien welke patches er zitten.

Patches onder versiebeheer

Een patch die alleen op de productieserver is toegepast, is een tikkende bom. Bij de volgende deploy of server-herinstallatie is hij weg, en niemand weet het.

Houd deze regels aan:

• Patches in git. Patchbestanden, composer.json en composer.lock staan in je repository.
• Productie bouwt vanuit de repository. Handmatig bestanden aanpassen op de server gebeurt niet. Elke afwijking is een alarmsignaal, ook voor malware-controles.
• Eén overzicht. Een korte lijst (bijvoorbeeld een PATCHES.md in de repo) met per patch: wat, waarom, wanneer, en wanneer hij weg kan.
• Opruimen bij upgrades. Na een versie-upgrade controleer je welke patches zijn opgenomen. Een patch die niet meer nodig is, moet er uit, anders kan hij falen of dubbel werken.

Een patch uitrollen: stappen

Dit is het stappenplan dat wij aanhouden.

1. Beoordeel de melding. Gaat het om een kritiek lek, wordt het actief misbruikt, en raakt het jouw versie en configuratie? Dat bepaalt de haast.
2. Controleer welke route past. Is er een security-release voor jouw lijn of een isolated patch?
3. Pas toe op een branch en op staging. Nooit rechtstreeks op productie.
4. Draai de basistests. Zorg in elk geval dat checkout, betaling, login en de belangrijkste pagina's werken. Test ook je eigen extensies die in de buurt van de gepatchte code komen.
5. Build en deploy. Draai composer install op de buildomgeving, daarna het gebruikelijke deployproces.
6. Controleer na livegang. Kijk naar foutlogs, een testbestelling en de status van de patch.
7. Leg vast wat is uitgerold, wanneer en door wie.

De technieken om dit zonder downtime te doen, staan in security patches zonder downtime.

Een noodsituatie, zoals de uren na publicatie van een kritiek lek dat actief wordt misbruikt, vraagt snelheid. Een korte, vaste testlijst en een geoefend deployproces zorgen dat je dan snel kunt zijn zonder te gokken. Voorbeelden van lekken waar snelheid doorslaggevend was, vind je in TrojanOrders, CosmicSting en SessionReaper.

Veelvoorkomende fouten

• Een patch toepassen op productie en vergeten vast te leggen. Bij de volgende deploy is de fix weg, en dat merk je niet.
• Patches die niet bij je versie horen. Een patch voor een andere versie kan mislukken of, erger, half werken.
• Patch-conflicten met extensies. Een extensie die dezelfde klasse overschrijft kan de fix omzeilen. Test na het patchen of het gedrag echt is gewijzigd.
• De cache vergeten. Na een patch moet de relevante cache worden geleegd en moet je static content opnieuw deployen waar nodig.
• Alleen Magento patchen. Ook je extensies en PHP zelf hebben updates nodig. Zie PHP2Shell voor een voorbeeld van een lek dat buiten Magento zit.
• Geen terugweg. Zorg dat je een patch kunt terugdraaien of een eerdere release kunt herstellen als de test op productie tegenvalt.

Wanneer is dit overkill?

Draai je een standaard installatie zonder custom code en met weinig extensies, dan volstaat vaak het bijhouden van de security-only patch-releases via een gewone composer update. Je hebt dan geen aparte patch-infrastructuur nodig. Een eigen patches/-map en een composer-patches-configuratie wordt pas de moeite waard als je regelmatig losse fixes toepast of third-party code moet repareren. Wat altijd nodig is: een vaste procedure, een stagingomgeving en wie het doet. Meer over wat dat in een contract is, staat in Magento security-onderhoud.

Veelgestelde vragen

Wat is het verschil tussen een security-only patch-release en een isolated patch?

Een patch-release (de -pX-versie) is een volledige, geteste versie met vooral beveiligingsfixes. Een isolated patch is een los bestand voor één specifiek probleem dat je op je bestaande installatie toepast. Gebruik de release als die er is voor jouw versie, een isolated patch als je geen release kunt of wilt installeren.

Hoe installeer ik de Quality Patches Tool?

Via Composer: composer require magento/quality-patches. Daarna gebruik je vendor/bin/magento-patches status om beschikbare patches te zien en apply of revert om ze toe te passen of terug te draaien.

Waarom zou ik cweagans/composer-patches gebruiken?

Omdat de patches dan in je repository staan en bij elke composer install op elke omgeving worden toegepast. Daardoor kun je ze reproduceren en reviewen. Dat is lastiger als je ze handmatig toepast.

Moet ik elke patch installeren?

Beoordeel ze. Kritieke beveiligingspatches wil je snel installeren. Functionele fixes voor problemen die jij niet hebt kunnen wachten tot de volgende release. Laat die afweging niet bij toeval over aan iemand.

Hoe test ik een patch veilig?

Op staging met een kopie van productiedata, met aandacht voor checkout, betaling, login en de extensies die in de buurt van de gepatchte code werken. Doe dat vooraf, ook als je haast hebt.

Wil je dat patchen bij ons vaste team ligt, met een geoefend proces voor de uren na een kritiek lek? Kijk bij /magento-support of neem contact op.