Saltar para o conteúdo principal

​
Visão geral

O ZeroPath se conecta a instâncias auto-hospedadas do GitHub Enterprise Server (GHES) por meio de um GitHub App que você cria na sua própria instância. Uma vez conectado, você pode importar repositórios, executar scans completos, escanear pull requests, publicar verificações de status e comentários inline, abrir pull requests de correção para achados validados e visualizar achados de dependências no painel Supply Chain. Essas são as mesmas funcionalidades que o ZeroPath oferece para o GitHub.com. A conexão é configurada com o fluxo de App Manifest do GitHub: você insere a URL da sua instância no ZeroPath, revisa o app na sua instância e confirma a sua criação. O ZeroPath recebe as credenciais do app da sua instância, armazena-as criptografadas e instala o app nas organizações que você escolher. Você nunca copia um client secret ou uma chave privada manualmente.
Apps do GHES são isolados por instância. Cada instância que você conecta recebe seu próprio registro de app e suas próprias credenciais criptografadas, então conectar uma instância nunca afeta outra, e nunca interfere na sua conexão com o GitHub.com.

​
Pré-requisitos

  • Uma organização no ZeroPath onde você possa criar instalações de VCS e repositórios.
  • Uma instância do GitHub Enterprise Server que seja:
    • acessível pelo ZeroPath via HTTPS (HTTP simples é rejeitado), e
    • resolvível por DNS público.
  • Permissão na instância para criar um GitHub App (via fluxo de App Manifest) e para instalar o app na organização de destino. Se você não puder instalar apps diretamente, sua solicitação de instalação é enviada a um proprietário da organização para aprovação.
  • A capacidade de atualizar sua lista de permissões de rede / firewall para que os IPs de saída do ZeroPath alcancem sua instância, e para que sua instância consiga entregar webhooks de volta ao ZeroPath. Consulte Rede e firewall.

​
Conecte o GitHub Enterprise Server

1

Abra a configuração do GitHub Enterprise Server

No ZeroPath, acesse Add Repositories, selecione a aba GitHub Enterprise Server e abra o diálogo de configuração.
2

Libere o ZeroPath no seu firewall

O diálogo de configuração lista os IPs de origem de saída do ZeroPath. Adicione-os à sua lista de permissões de rede para que o ZeroPath possa alcançar a API REST/GraphQL da sua instância, clonar repositórios, e para que sua instância possa entregar webhooks ao ZeroPath.
Se a lista de IPs de saída não for exibida no seu ambiente, entre em contato com o suporte do ZeroPath para obter os IPs de origem atuais antes de continuar.
3

Insira a URL da sua instância

Insira a URL do seu GitHub Enterprise Server, por exemplo https://github.your-company.com. A URL deve ser uma origem HTTPS que resolva por DNS público. O ZeroPath rejeita github.com e seus aliases, bem como hosts que resolvem para endereços privados, de loopback ou link-local.
4

Escolha como o ZeroPath confia no seu certificado TLS

  • Publicly-trusted certificate - o padrão. Você não precisa fornecer mais nada.
  • Internal / self-signed - cole ou envie seu bundle de CA em formato PEM. O ZeroPath o armazena criptografado e o usa apenas para verificar o TLS da sua instância. O ZeroPath sempre verifica certificados; ele nunca desabilita a validação.
5

Crie o app na sua instância

Clique em Create app on your GitHub Enterprise. O ZeroPath envia você para a sua instância para criar o GitHub App zeropath-scanner. Revise as permissões e eventos solicitados (consulte O que o app pode acessar) e então confirme em Create GitHub App.
O handshake de manifest do GitHub é válido por uma hora e pode ser usado uma única vez. Se você demorar demais ou sair da página, reinicie o fluxo a partir do diálogo de configuração.
6

Instale o app na sua organização

Depois que o app é criado, o ZeroPath envia você para a página de instalação de apps da sua instância. Selecione a organização cujos repositórios você quer escanear e aprove a instalação.
Se você não tiver permissão para instalar o app, sua solicitação é enviada a um proprietário da organização para aprovação. Os repositórios aparecem assim que o proprietário a aprovar.
7

Aguarde a sincronização

Você é redirecionado de volta ao ZeroPath, e seus repositórios do GHES começam a sincronizar. Eles aparecem em Accessible repositories quando estiverem prontos.
8

Adicione repositórios

Selecione quais repositórios adicionar ao ZeroPath ou clique em Add All.

​
O que o app pode acessar

O ZeroPath cria o app com o mesmo conjunto de permissões e eventos do seu GitHub App oficial, para que o scanning se comporte de forma idêntica no GitHub.com e no GitHub Enterprise Server. O app solicita estas permissões: O app se inscreve nestes eventos de webhook: push, pull_request, pull_request_review, pull_request_review_comment, pull_request_review_thread, issues, issue_comment, merge_group, member, membership, organization, repository, team, team_add e custom_property_values.

​
Rede e firewall

A conexão precisa de tráfego em ambas as direções:
  • Do ZeroPath para a sua instância (saída do ZeroPath). O ZeroPath chama as APIs REST e GraphQL da sua instância (em https://<your-host>/api/v3 e https://<your-host>/api), clona repositórios e conclui os handshakes de manifest e OAuth. Tudo isso se origina dos IPs de saída do ZeroPath exibidos no diálogo de configuração. Adicione-os à lista de permissões no firewall da sua instância.
  • Da sua instância para o ZeroPath (entrada no ZeroPath). Sua instância entrega eventos de webhook ao endpoint público do ZeroPath. Sua instância deve conseguir alcançar o ZeroPath pela internet pública para que scans de PR e atualizações de repositórios sejam acionados.
O ZeroPath deve alcançar sua instância via HTTPS em um nome DNS resolvível publicamente. Instâncias que são acessíveis apenas em uma rede privada, ou cujo hostname resolve para um endereço privado ou de loopback, não podem ser conectadas. Isso é aplicado como uma salvaguarda anti-SSRF.

​
Certificados TLS

Se a sua instância apresenta um certificado com confiança pública, nenhuma configuração extra é necessária. Se ela usa um certificado interno ou autoassinado, forneça o bundle de CA (PEM) durante a configuração. O ZeroPath armazena o bundle criptografado e confia nele apenas para conexões com a sua instância. Ele não altera nenhum repositório de confiança global, e a verificação de certificados permanece habilitada o tempo todo.

​
Importação de repositórios

O ZeroPath descobre repositórios a partir das organizações onde o app está instalado. Importe-os da mesma forma que nos outros provedores:
  • Repositório único - selecione um repositório e adicione-o.
  • Lote selecionado - selecione vários repositórios e importe-os juntos.
  • Adicionar todos - importe todos os repositórios acessíveis de uma vez.
Repositórios importados recebem as mesmas configurações padrão de scanner, tags, limites de repositórios, eventos de auditoria e notificações de repositório adicionado que os demais provedores de VCS suportados.

​
Scan de PRs

Quando um pull request é aberto ou atualizado em um repositório conectado, sua instância entrega um webhook ao ZeroPath, que agenda um scan de PR sobre os arquivos alterados. Os resultados podem incluir:
  • Uma verificação de status do ZeroPath no pull request.
  • Comentários de revisão inline nas linhas de diff afetadas.
  • Um comentário de resumo no PR com o resultado do scan.
  • Resolução automática de threads de comentários obsoletas quando os achados são corrigidos ou triados.
Os comandos do bot funcionam em comentários de pull requests do GHES da mesma forma que no GitHub.com.

​
Pull requests de correção

Quando um achado é elegível para uma correção automática, o ZeroPath pode abrir um pull request na sua instância usando o mesmo fluxo de correção dos outros provedores:
  • Gerar um branch de correção.
  • Fazer o commit da correção com a convenção padrão de mensagens de commit do ZeroPath.
  • Abrir um pull request direcionado ao branch original.
  • Adicionar contexto de resumo e vincular o PR de correção de volta ao achado no ZeroPath.

​
Múltiplas organizações e reconexão

  • Múltiplas organizações em uma instância - o app zeropath-scanner pode ser instalado em várias organizações da sua instância. Instale-o em cada organização cujos repositórios você quer escanear.
  • Reconexão - se você iniciar a configuração novamente para uma instância que o ZeroPath já registrou, ele pula a criação do app e envia você direto para a página de instalação. Se o app anterior foi excluído na sua instância, o ZeroPath registra um novo.

​
Solução de problemas

A URL deve ser HTTPS e resolver por DNS público. github.com e seus aliases são rejeitados, assim como hosts que resolvem para endereços privados, de loopback, link-local ou de NAT de nível de operadora. Confirme que sua instância tem um nome DNS público e um endpoint HTTPS acessível.
Se a sua instância usa um certificado interno ou autoassinado, escolha Internal / self-signed e forneça a cadeia de CA completa em formato PEM. Uma cadeia parcial (sem os intermediários) é a causa mais comum de falhas de verificação.
O app deve ser instalado em uma organização, não apenas criado. Conclua a etapa de instalação e selecione a organização de destino. Se você não tem permissão de instalação, um proprietário da organização deve aprovar a solicitação pendente antes que os repositórios sincronizem.
O handshake de manifest do GitHub expira uma hora após o início e é de uso único. Reinicie a configuração a partir da aba GitHub Enterprise Server para obter um novo handshake.
Os eventos de webhook são entregues da sua instância para o endpoint público do ZeroPath. Confirme que sua instância consegue alcançar a internet pública e que nenhum firewall de saída está bloqueando a entrega de webhooks. Confirme também que o scan de PR está habilitado nas configurações do repositório no ZeroPath.
Isso requer que as permissões de escrita do app (checks, pull requests, contents) permaneçam concedidas na organização de destino. Confirme que a instalação ainda possui essas permissões e que as regras de proteção de branch na sua instância não estão bloqueando atualizações automatizadas de branches.

​
Notas operacionais

  • Desconectar uma instalação do GHES impede que novos scans sejam agendados para aquela conexão e remove os repositórios vinculados por meio dela. Repositórios protegidos pelo modo pesquisador são retidos até que o modo pesquisador seja desabilitado.
  • Se você adicionar novas organizações após a configuração, instale o app nelas para que o ZeroPath possa descobrir seus repositórios.
  • Apps e credenciais do GHES têm escopo por instância e são armazenados criptografados; conectar ou desconectar uma instância não afeta nenhuma outra instância nem a sua conexão com o GitHub.com.