Análise de dependência

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 lançamento
• 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 Revisão de alterações de dependências em um pull request.

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

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, consulte Ecossistemas de pacotes com suporte a gráficos de dependência.

Para obter mais informações sobre os recursos da cadeia de suprimentos disponíveis em GitHub, consulte Segurança da cadeia de fornecedores.

Habilitar revisão de dependências

O recurso de revisão de dependências é disponibilizado quando você habilitar o gráfico de dependências. Para obter mais informações, consulte Habilitando o grafo de dependência para sua empresa.

Sobre o ação de revisão de dependência

O "ação de revisão de dependência" se refere à ação específica que pode relatar diferenças em um pull request dentro do contexto do GitHub Actions. Consulte dependency-review-action. É 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.

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 saber mais, confira Sobre branches protegidos.

A ação está disponível para todos os que têm GitHub Code Security or GitHub Advanced Security habilitado.

Os proprietários da organização podem implantar a revisão de dependência em escala impondo o uso do ação de revisão de dependência em repositórios da organização. Isso envolve o uso de conjuntos de regras de repositório para os quais você definirá o ação de revisão de dependência como um fluxo de trabalho obrigatório, o que significa que as pull requests só podem ser mescladas depois que o fluxo de trabalho passar por todas as verificações necessárias. Para saber mais, confira Como aplicar a revisão de dependências em uma organização.

Proprietários de empresas e pessoas com acesso de administrador a um repositório podem adicionar o ação de revisão de dependência à empresa e ao repositório, respectivamente.

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 Pontos de extremidade da API REST para revisão de dependências. A ação também considera as dependências enviadas por meio do API de envio de dependência. Para obter mais informações sobre API de envio de dependência, confira Usar a API de envio de dependências.

Você pode configurar ação de revisão de dependência para atender melhor às suas necessidades. Por exemplo, você pode especificar o nível de gravidade que fará a ação falhar. Para obter mais informações, consulte Configurando a ação de revisão de dependências.

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

A API de revisão de dependências e o ação de revisão de dependência funcionam comparando as alterações nas dependências em um pull request com o estado das suas dependências no commit HEAD do branch de destino.

Se o seu repositório depender apenas de dependências definidas estaticamente em um dos ecossistemas com suporte do GitHub, a API de revisão de dependências e o ação de revisão de dependência funcionam de forma consistente.

No entanto, talvez você queira que suas dependências sejam analisadas durante a compilação e, em seguida, enviadas para o API de envio de dependência. Nesse caso, há algumas boas práticas que você deve seguir para garantir que não introduza uma condição de corrida ao executar os processos da API de revisão de dependências e do API de envio de dependência, pois isso pode resultar em falta de dados.

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

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

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

• Verifique se você executa todas as ações de envio de dependências no mesmo fluxo de trabalho GitHub Actions que o seu ação de revisão de dependência. Com isso, poderá controlar a ordem de execução e garantir que a revisão de dependência sempre funcionará.
• Se você optar por executar o ação de revisão de dependência separadamente, deverá:
  • Defina retry-on-snapshot-warnings como 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.

Usando acesso direto via API ao API de envio de dependência e à API de revisão de dependências

Se você não usar GitHub Actions, e seu código depender de acesso direto à API de envio de dependência e à API de revisão de dependência:

• Execute o código que chama o API de envio de dependência primeiro e execute o código que chama a API de revisão de dependência posteriormente.
• Se você optar por executar em paralelo o código do API de envio de dependência e a API de revisão de dependências, 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.

Leitura adicional

• Personalizando sua configuração de ação de revisão de dependência