Vérifier les signatures des webhooks GitHub : X-Hub-Signature-256, comparaison à temps constant et identifiants de livraison

Ce que c'est

La documentation des webhooks de GitHub indique que "the hash signature will appear in each delivery as the value of the X-Hub-Signature-256 header" et que "GitHub uses an HMAC hex digest to compute the hash. The hash signature always starts with sha256=." Le condensat est le HMAC-SHA256 du corps brut de la requête, avec pour clé le secret configuré sur le webhook. Chaque livraison porte aussi l'en-tête X-GitHub-Delivery, décrit dans la référence de GitHub sur les événements et charges utiles de webhooks comme "a globally unique identifier (GUID) to identify the event" : c'est ce champ qui doit servir de clé de déduplication, et non un champ du corps JSON. Un en-tête historique X-Hub-Signature est également envoyé lorsqu'un secret est configuré ; la documentation de GitHub précise qu'il "uses the HMAC-SHA1 algorithm and is only included for legacy purposes" et recommande d'utiliser plutôt l'en-tête SHA-256. Aucun des deux en-têtes n'est envoyé si aucun secret n'est configuré.

Pourquoi c'est important

N'importe qui peut envoyer un POST vers une URL de webhook publique. Sans vérification de signature, un point de terminaison ne peut pas distinguer une vraie livraison GitHub d'une livraison forgée ; et se fier uniquement à X-Hub-Signature revient à s'appuyer sur la variante SHA-1 historique, que GitHub lui-même déconseille.

Comment l'appliquer

• Lire les octets du corps brut avant que tout analyseur JSON n'y touche (voir l'article sur le piège du corps brut).
• Calculer hmac_sha256(secret, raw_body) et le comparer au condensat qui suit le préfixe sha256= dans X-Hub-Signature-256.
• Utiliser une comparaison à temps constant — la documentation de GitHub suggère "a method like secure_compare or crypto.timingSafeEqual" — et jamais == ni .equals() sur les chaînes hexadécimales.
• Tester avec le vecteur de test publié par GitHub : le secret It's a Secret to Everybody et la charge utile Hello, World! doivent produire sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17.
• Stocker X-GitHub-Delivery avec les résultats traités et ignorer toute livraison dont l'identifiant a déjà été traité : GitHub ne réessaie pas de lui-même, mais une relivraison manuelle ou via l'API réutilise la valeur d'origine de X-GitHub-Delivery.
• Répondre par un code 2xx en moins de 10 secondes ; GitHub enregistre les réponses plus lentes comme des échecs timed out.
• Rejeter les livraisons dépourvues d'en-tête de signature lorsqu'un secret est configuré : cela indique un émetteur mal configuré ou forgé.

import hashlib, hmac

def verify_github(secret: bytes, raw_body: bytes, header: str) -> bool:
    if not header or not header.startswith("sha256="):
        return False
    expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    # compare bytes: compare_digest raises TypeError on non-ASCII str input
    return hmac.compare_digest(expected.encode(), header.encode())

Pièges

Vérifier la signature avec X-Hub-Signature (SHA-1) parce qu'une bibliothèque l'utilise par défaut : GitHub envoie les deux en-têtes lorsqu'un secret est défini, mais seul l'en-tête SHA-256 doit conditionner l'acceptation. Comparer les signatures avec une égalité de chaînes à court-circuit, qui laisse fuiter des informations de temps. Construire une clé de livraison à partir du contenu de l'événement plutôt qu'à partir de X-GitHub-Delivery, ce qui échoue dès que deux événements distincts partagent légitimement les mêmes valeurs dans leur corps.