Acesso programático e integrações com o GitHub Enterprise Cloud

O GitHub Enterprise Cloud (GHEC) oferece vários métodos de acesso à API e à linha de comando, e é uma prática recomendada conhecer as vantagens, desvantagens e limitações de cada um. Se você pretende integrar outras ferramentas ao GitHub ou construir automação, você também precisará estender e proteger essas opções de acesso programático usando as plataformas de aplicativos e webhooks do GitHub.

Saberemos como a Philips e a Figma usaram webhooks para ajudar com a integração da automação e prevenir o abuso de políticas, e ouviremos a SoftwareTesting.ai sobre as vantagens de criar GitHub Apps.

Neste guia, você aprenderá:

Como acessar a API e a linha de comando do GitHub por meio de tokens pessoais de acesso (PATs) e chaves SSH
As vantagens de usar GitHub Apps para automações e integrações que exigem acesso repetido à API
Como proteger as integrações, mesmo com uma mistura de ferramentas SaaS e auto-hospedadas
A melhor prática para o uso de webhooks no lugar de sondagens para as integrações

API e acesso à linha de comando

O GitHub oferece três métodos primários para autorizar o acesso à API e à linha de comando em nome de seus usuários: tokens pessoais de acesso (PATs), chaves SSH e listas de permissões para IPs. Cada método tem qualidades únicas que o torna mais ou menos apropriado para certas situações. Vamos aprender mais sobre cada um deles.

Tokens pessoais de acesso (PATs)

Os PATs acessam os recursos do GitHub em nome de um usuário individual, por meio da API ou da interface da linha de comando (CLI) do GitHub. Para acessar recursos em nome de uma organização ou para integrações de longa duração, um GitHub Apps é mais adequado porque fornece escalabilidade e controles de nível corporativo. Exploraremos essa abordagem abaixo.

Os PATs são sempre criados, gerenciados e de propriedade do usuário individual. Eles podem receber acesso com escopo para recursos específicos e tipos de permissões que o usuário tenha.

Em empresas e organizações nas quais o SAML estiver habilitado e adotado, o usuário deverá autorizar o PAT fazendo uma autenticação single sign-on (SSO) do SAML no navegador, antes que possa acessar os recursos. Os PATs autorizados pelo SAML podem então ser auditados pelos administradores da empresa ou da organização, e sua autorização pode ser revogada pelos administradores na interface do usuário ou por meio da API a qualquer momento. Sem a intervenção do administrador, os tokens autorizados permanecerão autorizados até que o usuário seja removido da organização, os escopos dos PATs sejam editados ou o token seja regenerado ou expire.

O GitHub atualmente é compatível com dois tipos de PATs: clássicos e fine-grained. PATs fine-grained fornecem segurança aprimorada com outras funcionalidades, como datas de expiração obrigatória e escopos de acesso granular. Os PATs clássicos ainda existem para apoiar recursos e pontos de extremidade legados que ainda não estiverem prontos para os PATs fine-grained. Recomendamos usar os PATs fine-grained sempre que possível para aproveitar as vantagens dos seus aprimoramentos. Os proprietários de empresas e organizações podem definir políticas para restringir o acesso de PATs clássicos às empresas e organizações de propriedade da empresa.

Chaves SSH e autoridades de certificação

As chaves SSH tem como função proteger o acesso individual à CLI do GitHub. Como são usados somente para a linha de comando, os controles adicionais para fazer o escopo dos tipos de acesso a outros recursos exigidos pelos PATs não são uma consideração para as chaves SSH.

Porém, como os PATs, as chaves SSH precisam ser autorizadas pelo SAML nas empresas e organizações nas quais o SAML estiver ativado ou adotado, concluindo a autenticação SSO do SAML no navegador. Os administradores da empresa ou da organização podem auditar as chaves autorizadas pelo SAML e revogar a autorização na interface do usuário ou por meio da API a qualquer momento. Sem a intervenção do administrador, as chaves autorizadas permanecerão autorizadas até que o usuário seja removido da organização, ou a chave seja removida ou invalidada.

Os usuários podem configurar chaves SSH gerando um novo par de chaves SSH e adicionando a chave pública à sua conta do GitHub. Porém, é possível para uma empresa ou organização provisionar e gerenciar as chaves SSH de forma centralizada, configurando uma autoridade de certificação (CA) SSH. Quando uma CA SSH for configurada, a empresa ou organização poderá opcionalmente exigir que somente as chaves SSH sejam usadas para o acesso programático, o que pode ser interessante se a organização preferir evitar o gerenciamento dos PATs para o acesso total da linha de comando. Os certificados assinados pela CA não precisam ser autorizados pelo SAML como as chaves de SSH gerenciadas individualmente.

Observação sobre APIs e as listas de permissão de IPs

As integrações com o GitHub poderão precisar chamar as APIs do GitHub para que funcionem adequadamente. Se você configurou uma lista de permissões de IPs para sua empresa ou organização, as faixas de IP das integrações instaladas devem ser incluídas. Ao configurar a lista de permissões de IP, você poderá opcionalmente permitir que as integrações instaladas a atualize. Se a pessoa que criou a integração fornecer uma lista de permissões para a aplicação, ela será automaticamente adicionada à sua lista de permissões. Caso contrário, a lista de permissões deverá ser gerenciada manualmente.

Listas de permissões de IP e políticas de acesso condicional para Enterprise Managed Users (EMUs)

Se você estiver usando EMUs com OIDC, o GitHub poderá ser configurado para usar as condições de IP da sua política de acesso condicional do IdP (CAP) para validar as interações do usuário. Será necessário também adicionar as faixas de IP de todas as aplicações e integrações do CAP do seu IdP.

Acesso às listas de permissões de IPs, ao CAP e ao executor do Actions

O GitHub oferece executores do Actions que podem ser usados para criar builds, implementações, verificações de análise estáticas e qualquer outra automação desejada. Se você estiver usando os executores hospedados no GitHub com quatro ou mais vCPUs, poderá receber um endereço IP estático para os executores. Esse endereço IP é exclusivo para a empresa e pode ser adicionado à sua lista de permissões de IP ou IdP CAP para conceder aos executores acesso ao código.

Aplicativos

Se você planeja usar a API do GitHub de forma repetida, a melhor prática é usar um aplicativo para interagir com a API ao invés de acessar a API diretamente. Recomendamos principalmente a estrutura do GitHub App ao invés da estrutura do OAuth para a integração de aplicativos. Os GitHub Apps oferecem várias vantagens sobre os aplicativos OAuth e o acesso da API baseado no PAT, incluindo:

Recursos de segurança aprimorados, como permissões fine-grained, escolha do acesso ao repositório e tokens de curta duração
Habilidade de atuar de forma independente do usuário ou em seu nome
Limites de taxa escaláveis
Webhooks incorporados

O GitHub apoia também uma comunidade robusta de integrações pré-existentes usando as interfaces do GitHub App e do OAuth. Se você estiver procurando integrar com outras ferramentas na sua cadeia de ferramentas, possivelmente já existe uma integração de GitHub baseada em aplicativos disponível para você instalar e começar a usar!

Os administradores controlam quais aplicativos estão instalados para suas organizações e quais os repositórios e permissões eles podem conceder. Você pode também definir políticas para restringir totalmente as instalações ou exigir a aprovação do administrador para a instalação de aplicativos. Os administradores podem também delegar permissões administrativas específicas para aplicativos, ajudando a gerenciar os GitHub Apps.

Os aplicativos só podem ser instalados no nível da organização (ou de usuários individuais).

Tem muita coisa que nós, desenvolvedores, podemos fazer para melhorar nossos fluxos de trabalho e abordar as ineficiências ao escrever e entregar código. O GitHub oferece um conjunto robusto de APIs e SDKs no Octokit que simplifica o processo de desenvolver ferramentas para facilitar nossa vida. Daqui, é fácil publicar no GitHub Marketplace para que outros desenvolvedores possam usar o código também, beneficiando a comunidade de desenvolvedores em geral.

Justin Trugman // Founder // SoftwareTesting.ai

Webhooks

Os webhooks fornecem uma maneira pela qual as notificações podem ser entregues a um servidor da Web externo, sempre que certos eventos ocorrerem, ao invés de sondar a API em uma programação para verificar se certos eventos ocorreram. Eles entregam uma carga JASON de forma segura por meio do HTTPS POST. As integrações criam webhooks, selecionam os eventos para a notificação, oferecem um ponto de extremidade direcionável publicamente no qual o GitHub pode entregar a carga e, opcionalmente, fornecem um valor secreto que o GitHub pode usar para assinar criptograficamente a carga. Fornecendo webhooks para recursos locais como parte da nossa implantação GHEC, os webhooks precisarão enviar notificações às aplicações hospedadas atrás do firewall que você deseja integrar ao GitHub.

Com a configuração adequada da rede, o GHEC pode notificar esses sistemas implementando uma forma de proxy reverso, que inclui:

Um nome de domínio totalmente qualificado e publicamente direcionável (FQDN) para o qual o GitHub pode enviar a publicação HTTPS Recriação do URL e encaminhamento da porta para a aplicação apropriada

Esse padrão pode ser implementado usando componentes prontos de fornecedores como ngrok, configurando servidores da Web existentes como NGINX ou um produto comercial como um gateway da API ou WAF.

Usamos webhooks para monitorar eventos do GitHub. Assim, quando um novo usuário entra na organização, podemos criar e atribuir automaticamente a ele um problema para ajudar na sua integração.

Niek Palm // Principal Software Engineer // Philips

Protegendo entregas do webhook aos recursos locais

Ao implementar um proxy reverso para administrar a entrega do webhook, o GitHub recomenda as seguintes práticas:

Permita somente o tráfego do HTTPS de entrada na porta 443 para seu FQDN
Permita somente o tráfego das faixas de IP publicadas nas seção de hooks do https://api.github.com/meta
Encerre o SSL no FQDN e inspecione a carga JSON procurando por JSON bem-formatados
Verifique se a solução a qual você está integrando é compatível e usa as assinaturas do webhook

Nossa política de controle de alterações foi projetada para melhorar a eficiência. Exigimos mais de uma aprovação em pull requests para fazer o merge, mas não descartamos aprovações obsoletas. Nossa abordagem se baseia no motivo da aprovação do revisor, não os bytes, da pull request. Então, quando uma aprovação tem alguns comentários simples sobre estilo, por exemplo, geralmente permitimos que o remetente aborde os comentários e faça o merge da pull request sem precisar de uma segunda aprovação.

Ao mesmo tempo, queríamos ter certeza de que essa política não estava sendo usada de forma indiscriminada. Por isso, criamos uma automação usando um webhook de nível organizacional que alimenta uma automação personalizada que criamos no AWS Lambda que, por sua vez, alimenta nossa plataforma de gerenciamento de eventos e informações de segurança (SIEM). Isso nos permite sinalizar casos em que achamos que essa política está sendo usada de forma indiscriminada, como pull requests que foram mescladas com alterações significativas pós-aprovação, e nos alertar para que possamos resolvê-los.

Tommy MacWilliam // Engineering Manager for Infrastructure // Figma

Sondagem

Se você estiver criando uma integração ou automação baseada na API do GitHub, evite a sondagem de APIs. Para garantir o desempenho e a confiabilidade do sistema para todos, o GitHub adota um limite de taxa rígido na atividade da IP para indivíduos e um limite mais alto para as aplicações. A sondagem regular de APIs, principalmente em organizações maiores, atingirá o limite de taxas.

Ao invés de sondar as APIs de forma programada, use os webhooks para receber as notificações de eventos no GitHub. A integração receberá todos os eventos do webhook para os quais estiver assinada e poderá então fazer uma solicitação autenticada para o GitHub, caso alguma medida precise ser tomada.

Próximo: Acessar, capturar e consumir os logs de auditoria

Estamos quase no final deste módulo, mas temos ainda mais um tópico: Logs de auditoria. Seja para a conformidade regulamentar ou para a solução de problemas, os logs de auditoria fornecem um registro em papel de várias ações ocorridas na empresa, e sua integração inicial não será concluída até que você entenda o que ela oferece e como acessá-la.