Validação de entregas de webhooks

Sobre a validação de entregas de webhooks

Quando o servidor estiver configurado para receber cargas úteis, ele escutará qualquer entrega enviada ao endpoint que você configurou. Para garantir que o seu servidor processe somente as entregas de webhooks que foram enviadas pela GitHub e para garantir que a entrega não foi adulterada, você deve validar a assinatura do webhook antes de continuar a processar a entrega. Isso o ajudará a evitar gastar tempo do servidor para processar entregas que não são da GitHub e ajudará a evitar ataques man-in-the-middle.

Para fazer isso, você precisa:

Crie um token secreto para um webhook.
Armazene o token de forma segura no seu servidor.
Valide os payloads do webhook de entrada em relação ao token, a fim de verificar se eles são provenientes do GitHub e se não foram adulterados.

Criando um token secreto

Você pode criar um novo webhook com um token secreto ou pode adicionar um token secreto a um webhook existente. Ao criar um token secreto, você deve escolher uma sequência aleatória de texto com alta entropia.

Para criar um novo webhook com um token secreto, confira AUTOTITLE.
Para adicionar um token secreto a um webhook existente, edite as configurações do webhook. Em "Segredo", digite uma cadeia de caracteres para usar como uma chave . Para saber mais, confira AUTOTITLE.

Armazenamento seguro de tokens secretos

Depois de criar um token secreto, você deve armazená-lo em um local seguro que seu servidor possa acessar. Nunca codifique um token em um aplicativo ou envie um token para qualquer repositório. Para obter mais informações sobre como usar credenciais de autenticação de maneira segura em seu código, confira AUTOTITLE.

Validando entregas de Webhooks

O GitHub usará seu token secreto para criar uma assinatura de hash que será enviada a você com cada carga. A assinatura do hash será exibida em cada entrega como uma valor associado ao cabeçalho. Para saber mais, confira AUTOTITLE.

Em seu código que lida com entregas de webhooks, você deve calcular um hash usando seu token secreto. Em seguida, compare o hash que o GitHub enviou com o hash esperado que você calculou e certifique-se de que eles correspondem. Para ver exemplos que mostram como validar os hashes em várias linguagens de programação, confira Exemplos.

Há alguns aspectos importantes a serem considerados ao validar cargas de webhooks:

O GitHub usa um digest hexadecimal HMAC para calcular o hash.
A assinatura do hash sempre começa com .
A assinatura de hash é gerada usando o token secreto do seu webhook e o conteúdo do payload.
Se o seu idioma e a implementação de servidor especificarem uma codificação de caracteres, certifique-se de que você manipula a carga como UTF-8. As cargas do webhook podem conter caracteres unicode.
Nunca use um operador padrão. Em vez disso, considere usar um método como ou que executa uma comparação da cadeia de caracteres em "tempo constante" a fim de ajudar a atenuar alguns ataques baseado em tempo (timing attack) contra os operadores de igualdade regulares ou loops regulares em linguagens otimizadas por JIT.

Testando a validação da carga útil do webhook

Você pode usar os seguintes valores e para verificar se sua implementação está correta:

Se sua implementação estiver correta, as assinaturas que você gerar deverão corresponder aos seguintes valores de assinatura:

assinatura:
X-Hub-Signature-256:

Exemplos

Você pode usar a linguagem de programação de sua preferência para implementar a verificação HMAC em seu código. A seguir, alguns exemplos que mostram como uma implementação pode ser feita em várias linguagens de programação.

Exemplo de Ruby

Por exemplo, você pode definir a seguinte função :

def verify_signature(payload_body)
  signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body)
  return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['HTTP_X_HUB_SIGNATURE_256'])
end

Em seguida, você pode chamá-lo quando receber um conteúdo de webhook:

post '/payload' do
  request.body.rewind
  payload_body = request.body.read
  verify_signature(payload_body)
  push = JSON.parse(payload_body)
  "I got some JSON: #{push.inspect}"
end

Exemplo de Python

Por exemplo, você pode definir a seguinte função e chamá-la quando receber um conteúdo de webhook:

import hashlib
import hmac
def verify_signature(payload_body, secret_token, signature_header):
    """Verify that the payload was sent from GitHub by validating SHA256.

    Raise and return 403 if not authorized.

    Args:
        payload_body: original request body to verify (request.body())
        secret_token: GitHub app webhook token (WEBHOOK_SECRET)
        signature_header: header received from GitHub (x-hub-signature-256)
    """
    if not signature_header:
        raise HTTPException(status_code=403, detail="x-hub-signature-256 header is missing!")
    hash_object = hmac.new(secret_token.encode('utf-8'), msg=payload_body, digestmod=hashlib.sha256)
    expected_signature = "sha256=" + hash_object.hexdigest()
    if not hmac.compare_digest(expected_signature, signature_header):
        raise HTTPException(status_code=403, detail="Request signatures didn't match!")

Exemplo de JavaScript

Por exemplo, você pode definir a seguinte função e chamá-la em qualquer ambiente JavaScript quando receber um payload de webhook:

let encoder = new TextEncoder();

async function verifySignature(secret, header, payload) {
    let parts = header.split("=");
    let sigHex = parts[1];

    let algorithm = { name: "HMAC", hash: { name: 'SHA-256' } };

    let keyBytes = encoder.encode(secret);
    let extractable = false;
    let key = await crypto.subtle.importKey(
        "raw",
        keyBytes,
        algorithm,
        extractable,
        [ "sign", "verify" ],
    );

    let sigBytes = hexToBytes(sigHex);
    let dataBytes = encoder.encode(payload);
    let equal = await crypto.subtle.verify(
        algorithm.name,
        key,
        sigBytes,
        dataBytes,
    );

    return equal;
}

function hexToBytes(hex) {
    let len = hex.length / 2;
    let bytes = new Uint8Array(len);

    let index = 0;
    for (let i = 0; i < hex.length; i += 2) {
        let c = hex.slice(i, i + 2);
        let b = parseInt(c, 16);
        bytes[index] = b;
        index += 1;
    }

    return bytes;
}

Exemplo de TypeScript

Por exemplo, você pode definir a seguinte função e chamá-la quando receber um conteúdo de webhook:

JavaScript

import { Webhooks } from "@octokit/webhooks";

const webhooks = new Webhooks({
  secret: process.env.WEBHOOK_SECRET,
});

const handleWebhook = async (req, res) => {
  const signature = req.headers["x-hub-signature-256"];
  const body = await req.text();

  if (!(await webhooks.verify(body, signature))) {
    res.status(401).send("Unauthorized");
    return;
  }

  // The rest of your logic here
};

import { Webhooks } from "@octokit/webhooks";

const webhooks = new Webhooks({
  secret: process.env.WEBHOOK_SECRET,
});

const handleWebhook = async (req, res) => {
  const signature = req.headers["x-hub-signature-256"];
  const body = await req.text();

  if (!(await webhooks.verify(body, signature))) {
    res.status(401).send("Unauthorized");
    return;
  }

  // The rest of your logic here
};

Solução de problemas

Se você tiver certeza de que a carga é da GitHub, mas a verificação da assinatura falhar:

Certifique-se de ter configurado um segredo para seu webhook. O cabeçalho X-Hub-Signature-256 não estará presente se você não tiver configurado um segredo para seu webhook. Para obter mais informações sobre como configurar um segredo para seu webhook, confira Editando webhooks.
Certifique-se de que esteja usando o cabeçalho correto. A GitHub recomenda que você use o cabeçalho X-Hub-Signature-256, que usa o algoritmo HMAC-SHA256. O cabeçalho X-Hub-Signature usa o algoritmo HMAC-SHA1 e é incluído apenas para fins herdados.
Certifique-se de que esteja usando o algoritmo correto. Se estiver usando o cabeçalho X-Hub-Signature-256, deverá usar o algoritmo HMAC-SHA256.
Verifique se você está usando o segredo correto do webhook. Se você não souber o valor do segredo do webhook, poderá atualizar o segredo do webhook. Para saber mais, confira Editando webhooks.
Certifique-se de que a carga útil e os cabeçalhos não sejam modificados antes da verificação. Por exemplo, se você usar um proxy ou um balanceador de carga, certifique-se de que o proxy ou o balanceador de carga não modifique a carga útil ou os cabeçalhos.
Se o seu idioma e a implementação de servidor especificarem uma codificação de caracteres, certifique-se de que você manipula a carga como UTF-8. As cargas do webhook podem conter caracteres unicode.

Leitura adicional

AUTOTITLE
AUTOTITLE

Neste artigo