Skip to main content

Sobre a análise de dependência

A análise de dependências permite que você capture dependências não seguras antes que elas sejam introduzidas no ambiente e fornece informações sobre licença, dependências e idade das dependências.

Quem pode usar esse recurso?

A revisão de dependência está habilitada em repositórios públicos. A revisão de dependência também está disponível em repositórios privados pertencentes a organizações que usam o GitHub Enterprise Cloud e que têm uma licença do GitHub Advanced Security. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Sobre a análise de dependência

Revisão de dependências ajuda você a entender as alterações de dependência e o impacto de segurança dessas alterações em cada pull request. Ele fornece uma visualização facilmente compreensível de mudanças de dependência, com um diff avançado na aba "Arquivos alterados" de uma solicitação de pull. A revisão de dependências informa você:

  • Quais dependências foram adicionadas, removidas ou atualizadas, junto com as datas de versão.
  • Quantos projetos usam esses componentes.
  • Dados de vulnerabilidade para essas dependências.

Para solicitações de pull que contêm alterações em manifestos de pacote ou arquivos de bloqueio, você poderá exibir uma revisão de dependência para ver o que foi alterado. A revisão de dependências inclui detalhes de alterações nas dependências indiretas nos arquivos de bloqueio, e informa a você se alguma das dependências adicionadas ou atualizadas contém vulnerabilidades conhecidas.

Às vezes, você pode apenas querer atualizar a versão de uma dependência em um manifesto e gerar um pull request. No entanto, se a versão atualizada desta dependência direta também atualizou as dependências, seu pull request pode ter mais alterações do que o esperado. A revisão de dependência para cada manifesto e arquivo de bloqueio fornece uma maneira fácil de ver o que foi alterado e se alguma das novas versões de dependências contém vulnerabilidades conhecidas.

Ao verificar as revisões de dependências em um pull request e alterar todas as dependências sinalizadas como vulneráveis, você pode evitar que vulnerabilidades sejam adicionadas ao seu projeto. Para obter mais informações sobre como funciona a revisão de dependências, confira "Revendo alterações de dependência em um pull request".

Para obter mais informações sobre como configurar a revisão de dependências, confira "Configuração da revisão de dependência".

Dependabot alerts encontrará vulnerabilidades que já estão nas suas dependências, mas é muito melhor evitar a introdução de possíveis problemas do que corrigir problemas em uma data posterior. Para obter mais informações sobre Dependabot alerts, confira "Sobre alertas do Dependabot".

A revisão de dependências é compatível com as mesmas linguagens e os mesmos ecossistemas de gestão de pacotes do gráfico de dependência. Para obter mais informações, confira "Sobre o gráfico de dependências".

Para obter mais informações sobre os recursos da cadeia de fornecedores disponíveis no GitHub, confira "Sobre a segurança da cadeia de suprimento".

Imposição da revisão de dependência

A ação está disponível para todos os repositórios públicos, bem como para repositórios privados que têm o GitHub Advanced Security habilitado.

É possível usar o ação de revisão de dependência no repositório para impor revisões de dependência em solicitações de pull. A ação examina versões vulneráveis de dependências introduzidas por alterações de versão do pacote em solicitações de pull e avisa você sobre as vulnerabilidades de segurança associadas. Isso oferece uma melhor visibilidade do que está mudando em uma solicitação de pull e ajuda a evitar que vulnerabilidades sejam adicionadas ao repositório. Para obter mais informações, confira dependency-review-action.

Captura de tela de uma execução de fluxo de trabalho que usa a ação de revisão de dependências.

Por padrão, a verificação do ação de revisão de dependência falhará se descobrir pacotes vulneráveis. Uma verificação com falha impede que uma solicitação de pull seja mesclada quando o proprietário do repositório exigir que a verificação de análise de dependência seja aprovada. Para obter mais informações, confira "Sobre branches protegidos".

A ação usa a API REST de revisão de dependência para obter a comparação das alterações de dependência entre o commit base e o commit principal. Use a API de revisão de dependência para obter a comparação das alterações de dependência,entre os dois commits em um repositório, incluindo dados de vulnerabilidade. Para obter mais informações, consulte "Gráfico de Dependência". A ação também considera dependências enviadas por meio do API de envio de dependência. Para obter mais informações sobre o API de envio de dependência, consulte "Usar a API de envio de dependências".

Observação: a API de revisão de dependência e API de envio de dependência funcionam em conjunto. Isso significa que a API de revisão de dependência incluirá dependências enviadas por meio de API de envio de dependência. Atualmente, esse recurso está em versão beta pública e está sujeito a alterações.

É possível configurar o ação de revisão de dependência de acordo com suas necessidades. Por exemplo, você pode especificar o nível de severidade que fará a ação falhar ou definir uma lista de permissões e negações para que as licenças sejam verificadas. Para obter mais informações, confira "Configuração da revisão de dependência".

Práticas recomendadas para usar a API de revisão de dependência e API de envio de dependência juntos

A API de revisão de dependência e o ação de revisão de dependência funcionam comparando as alterações de dependência em uma solicitação de pull com o estado das dependências do commit principal da ramificação de destino.

Se o repositório necessitar apenas de dependências definidas estaticamente em um dos ecossistemas do GitHub com suporte, a API de revisão de dependência e o ação de revisão de dependência funcionarão com consistência.

No entanto, convém que suas dependências sejam verificadas durante uma compilação e, depois, carregadas em API de envio de dependência. Nesse caso, há algumas práticas recomendadas que você deve seguir para garantir que não gere uma condição de corrida ao executar os processos da API de revisão de dependência e API de envio de dependência, já que isso pode resultar em dados ausentes.

As práticas recomendadas que você deve adotar dependerão de você usar o GitHub Actions para acessar API de envio de dependência e a API de revisão de dependência ou se usar diretamente o acesso à API.

Usar o GitHub Actions para acessar API de envio de dependência e a API de revisão de dependência

Se você usa o GitHub Actions para acessar API de envio de dependência ou a API de revisão de dependência:

  • Certifique-se de executar todas as suas ações de envio de dependência no mesmo fluxo de trabalho do GitHub Actions em que seu ação de revisão de dependência é executado. Com isso, poderá controlar a ordem de execução e garantir que a revisão de dependência sempre funcionará.
  • Se optar por executar o ação de revisão de dependência separadamente, você deverá:
    • Definir retry-on-snapshot-warnings para true.
    • Configure retry-on-snapshot-warnings-timeout para exceder levemente o tempo de execução típico (em segundos) da ação de envio de dependência de execução mais longa.

Usar acesso direto da API a API de envio de dependência e à API de revisão de dependência

Se você não usa o GitHub Actions e seu código depende de acesso direto a API de envio de dependência e à API de revisão de dependência:

  • Execute o código que chama API de envio de dependência primeiro e, depois, execute o código que chama a API de revisão de dependência.
  • Se optar por executar o código para API de envio de dependência e a API de revisão de dependência em paralelo, você deverá implementar uma lógica de nova tentativa e observar o seguinte:
    • Quando houver instantâneos ausentes nos dois lados da comparação, o cabeçalho x-github-dependency-graph-snapshot-warnings exibirá uma explicação (como uma cadeia de caracteres codificada em base64). Portanto, caso o cabeçalho não esteja vazio, você deveria considerar tentar realizar a operação novamente.
    • Implemente uma lógica de novas tentativas com repetições de retirada exponencial.
    • Implemente um número razoável de tentativas para levar em consideração o tempo de execução típico do código de envio de dependência.