Den Sanitizer sicher erweitern

Tutorial · Easy SVG

Easy SVG bereinigt jedes SVG, bevor WordPress es speichert. Die meisten Sites müssen daran nie etwas ändern. Manchmal exportiert ein Design-Tool aber ein Element, das der Bereiniger nicht kennt, oder eine Site will strengere Regeln. Dann kannst du die Regeln mit drei Filtern anpassen. Dieses Tutorial zeigt, wie der Bereiniger aufgebaut ist, welche Änderungen sicher sind, welche nicht, und wie du beweist, dass deine Änderung tut, was du denkst, bevor sie live geht.

So ist der Sanitizer aufgebaut

Easy SVG nutzt die Bibliothek enshrined/svg-sanitize (mitgeliefert ist Version 1.0.0). Sie arbeitet mit zwei Erlaubnislisten: Elementnamen und Attributnamen. Alles, was nicht auf einer Liste steht, fliegt raus. Zusätzlich entfernt sie immer PHP-Verarbeitungsanweisungen, Kommentare und unsichere href-Werte wie javascript:, und sie macht aus CDATA-Abschnitten einfachen Text.

Jedes Mal, wenn Easy SVG etwas bereinigen muss, ruft es easy_svg_sanitizer() auf. Die Funktion baut einen neuen Sanitizer und wendet in diesem Moment deine Filter an:

Daraus folgen drei Dinge:

1. Deine Filter laufen bei jeder Bereinigung, nicht nur einmal. Registriere sie früh (eine Plugin- oder Must-Use-Plugin-Datei reicht), dann gelten sie für jeden Upload in derselben Anfrage und in allen folgenden.
2. Jeder Weg sieht dieselben Regeln. Uploads in die Mediathek, Sideloads (media_sideload_image(), WP-CLI, Importer), die Prüfung in wp_upload_bits() für XML-RPC, die Prüfung jedes neuen Anhangs, die Icon-Bibliothek und Add-ons rufen alle diese eine Funktion auf.
3. Manche Wege haben eigene feste Schritte. Uploads lehnen vorher Dateien über der Größen- und Komplexitätsgrenze ab und entfernen Animationen, die auf href zielen, falls deine Liste Animationselemente erlaubt. Icons verlieren zusätzlich style, script, jedes Animationselement, jedes on*-Attribut und jedes href, das nicht mit # beginnt. Deine Filter können das nicht abschalten.

Wann die Filter im Verhältnis zum Upload laufen:

Die Upload-Filter gibt es nur, solange SVG-Uploads in der Mediathek erlauben unter Icons, Einstellungen eingeschaltet ist. Die Prüfung neuer Anhänge läuft immer, ein SVG, das ein anderes Plugin hereinlässt, wird also auch bereinigt.

Sichere Änderungen an den Erlaubnislisten

Eine sichere Änderung ergänzt einen Namen, der nur beschreibt, wie etwas aussieht, oder streicht einen, den du nie haben willst. Arbeite mit Belegen, nicht mit Vermutungen.

wp eval '
$s = easy_svg_sanitizer();
$s->sanitize( file_get_contents( "/path/to/export.svg" ) );
foreach ( $s->getXmlIssues() as $i ) { WP_CLI::log( $i["message"] . " (line " . $i["line"] . ")" ); }
'

<?php
/**
 * Plugin Name: My SVG allow-list
 */

/**
 * Keep drop shadows from our design tool.
 *
 * @param string[] $tags Allowed element names.
 * @return string[]
 */
function mysite_svg_tags( $tags ) {
	$tags[] = 'feDropShadow';
	return $tags;
}
add_filter( 'esw_svg_allowed_tags', 'mysite_svg_tags' );

/**
 * Keep the mask type our exports rely on.
 *
 * @param string[] $attributes Allowed attribute names.
 * @return string[]
 */
function mysite_svg_attributes( $attributes ) {
	$attributes[] = 'mask-type';
	return $attributes;
}
add_filter( 'esw_svg_allowed_attributes', 'mysite_svg_attributes' );

Wenn du Namen streichst statt ergänzt, vergleiche kleingeschrieben. Die Standardliste mischt Schreibweisen (feBlend, lineargradient), und array_diff() unterscheidet Groß- und Kleinschreibung:

/**
 * Never store embedded bitmaps.
 *
 * @param string[] $tags Allowed element names.
 * @return string[]
 */
function mysite_no_bitmaps_in_svg( $tags ) {
	return array_values(
		array_filter(
			$tags,
			static function ( $tag ) {
				return 'image' !== strtolower( $tag );
			}
		)
	);
}
add_filter( 'esw_svg_allowed_tags', 'mysite_no_bitmaps_in_svg' );

Ein entferntes Element nimmt alles mit, was darin liegt. Streichst du g oder a, kann die ganze Zeichnung leer werden.

Was nie erlaubt sein darf, und warum

Schon auf der Standardliste und dort unbedenklich: style (CSS, fremde Verweise werden entfernt), use, image, a (ihre href-Werte werden geprüft), animateTransform, animateMotion, animateColor.

Fremde Verweise

esw_svg_remove_remote_references steht standardmäßig auf true: Jede absolute URL (https://..., //host/...) wird aus Attributen entfernt, und fremde url()-Angaben sowie jedes @import werden aus style-Elementen herausgeschnitten. Deine eigene Domain zählt dabei als fremd, weil die Prüfung die Form der URL ansieht, nicht den Host. Lass das eingeschaltet, solange du nicht jedem vertraust, der hochladen darf. Brauchst du fremde Verweise nur für einen Import, hänge vorher __return_false ein und nimm es danach wieder heraus. Der Wert wird bei jedem Aufbau eines Sanitizers neu gelesen.

Der alte globale $sanitizer

Easy SVG 4.1 hat Uploads mit einem einzigen Sanitizer in der globalen Variable $sanitizer bereinigt, und manche Sites haben ihn per Snippet eingestellt:

global $sanitizer;
$sanitizer->removeXMLTag( true );

Easy SVG legt diese globale Variable beim Laden weiterhin an, solange die Bibliothek da ist und der Name nicht anderweitig belegt ist. Sie ist jetzt eine Vorlage: easy_svg_sanitizer() klont sie, Einstellungen daran gehen also auf jede Kopie über. In der Praxis heißt das:

• Funktioniert weiterhin: Ausgabe-Einstellungen wie removeXMLTag( true ) und minify( true ). Die Testsuite beweist, dass ein removeXMLTag() am globalen Objekt den gespeicherten Upload erreicht.
• Wirkt nicht: setAllowedTags(), setAllowedAttrs() und removeRemoteReferences(). Die Kopie bekommt nach dem Klonen die gefilterten Listen und die gefilterte Einstellung für fremde Verweise, die gewinnen also immer. Verschieb diese Einstellungen in die drei Filter.
• Wird nie durch Benutzung verändert: Easy SVG ändert das globale Objekt selbst nie und gibt es auch nie heraus.
• Fremdes wird nicht aufgerufen: Hat ein anderes Plugin ein ganz anderes Objekt in $sanitizer gelegt, ignoriert Easy SVG es und baut einen frischen Sanitizer.

Neuer Code sollte das globale Objekt gar nicht anfassen. Nimm die Filter für die Regeln und easy_svg_sanitizer() für einen eigenen Sanitizer.

Deine Änderungen testen

printf '%s
' '<?php' 'add_filter( "esw_svg_allowed_attributes", function ( $a ) { $a[] = "onload"; return $a; } );' > wp-content/mu-plugins/zz-svg-mutation.php
wp eval-file svg-sanitizer-check.php
rm wp-content/mu-plugins/zz-svg-mutation.php

printf '%s' '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script><rect width="9" height="9"/></svg>' > /tmp/evil.svg
printf '%s' '<svg><rect></svg' > /tmp/broken.svg

ID=$(wp media import /tmp/evil.svg --porcelain)
grep -c '<script' "$(wp eval "echo get_attached_file( $ID );")"

wp media import /tmp/broken.svg

Checkliste

• Jeder Name, den du ergänzt hast, ändert nur, wie die Zeichnung aussieht.
• Beim Streichen vergleichst du kleingeschrieben, und deine Callbacks geben immer ein Array zurück.
• Das Prüfskript läuft grün und schlägt fehl, wenn du absichtlich onload ergänzt.
• wp media import speichert eine bereinigte Datei und lehnt eine kaputte ab.
• Dateien, die schon in der Mediathek liegen, wurden mit den alten Regeln bereinigt. Lade die wichtigen neu hoch, wenn deine Änderung sie betrifft.

Siehe auch

• esw_svg_allowed_tags
• esw_svg_allowed_attributes
• esw_svg_remove_remote_references
• easy_svg_sanitizer()
• esw_svg_file_checker()
• Ein Add-on bauen