Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais atualizadas, acesse a documentação em inglês.

Melhores práticas para escrever avisos de segurança do repositório

Quando você cria ou edita avisos de segurança, os outros usuários conseguem entender melhor as informações fornecidas quando são especificados o ecossistema, o nome do pacote e as versões afetadas usando os formatos padrão.

Qualquer pessoa com permissões de administrador em um repositório pode criar e editar um aviso de segurança.

Observação: se você é um pesquisador de segurança, você deve entrar em contato diretamente com os mantenedores para pedir que criem consultorias de segurança ou emitam CVEs em seu nome em repositórios que você não administra. No entanto, se os relatórios de vulnerabilidade privados estiverem habilitados para o repositório, será possível relatar uma vulnerabilidade de maneira privada por conta própria. Para saber mais, confira "Como relatar de maneira privada uma vulnerabilidade de segurança".

Sobre os avisos de segurança para repositórios

Os avisos de segurança do repositório permitem que os responsáveis pelo repositório discutam e corrijam de modo privado as vulnerabilidades de segurança em um projeto. Depois de colaborar em uma correção, os responsáveis pelo repositório podem publicar o aviso de segurança para divulgar publicamente a vulnerabilidade de segurança na comunidade do projeto. Ao publicar avisos de segurança, os responsáveis pelo repositório facilitam para a comunidade a atualização das dependências do pacote e a pesquisa sobre o impacto das vulnerabilidades de segurança. Para obter mais informações, confira "Sobre os avisos de segurança do repositório".

Práticas recomendadas

Recomendamos que você use a sintaxe usada no GitHub Advisory Database, principalmente a formatação de versão, ao criar um aviso de segurança de repositório, ou faça uma contribuição da comunidade para um aviso de segurança global.

Se você seguir a sintaxe do GitHub Advisory Database, principalmente ao definir as versões afetadas:

  • Ao publicar o aviso de repositório, podemos adicioná-lo ao GitHub Advisory Database como uma consultoria "revisada pelo GitHub", sem precisar solicitar mais informações.
  • O Dependabot terá as informações para identificar com precisão os repositórios afetados e enviar Dependabot alerts para notificá-los.
  • Os membros da comunidade são menos propensos a sugerir edições ao aviso para corrigir informações ausentes ou incorretas.

Adicione ou edite um aviso de repositório usando o formulário Rascunho de aviso de segurança. Para obter mais informações, confira "Como criar um aviso de segurança do repositório".

Sugira um aprimoramento para um aviso global existente usando o formulário Aprimorar o aviso de segurança. Para obter mais informações, confira "Como editar avisos de segurança no GitHub Advisory Database".

Ecossistema

Você precisa atribuir o aviso a um dos ecossistemas com suporte usando o campo Ecossistema. Para obter mais informações sobre os ecossistemas com suporte, confira "Procurar avisos de segurança no GitHub Advisory Database".

Captura de tela realçando o campo Ecossistema no formulário

Nome do pacote

Recomendamos que você use o campo Nome do pacote para especificar quais pacotes são afetados porque as informações do pacote são necessárias para avisos revisados pelo "GitHub" no GitHub Advisory Database. As informações do pacote são opcionais para avisos de segurança no nível do repositório, mas a inclusão dessas informações já simplifica o processo de revisão quando você publica o aviso de segurança.

Captura de tela realçando o Nome do pacote no formulário

Versões afetadas

Recomendamos que você use o campo Versões afetadas para especificar quais versões são afetadas porque essas informações são necessárias para avisos "revisados pelo GitHub" no GitHub Advisory Database. As informações de versão são opcionais para avisos de segurança no nível do repositório, mas a inclusão dessas informações já simplifica o processo de revisão quando você publica o aviso de segurança.

Captura de tela realçando o campo Versões afetadas

  • Uma cadeia de caracteres de versão afetada válida consiste em uma das seguintes opções:

    • Uma sequência de operadores com limite inferior.
    • Uma sequência de operadores com limite superior.
    • Uma sequência de operadores com limites superior e inferior.
    • Uma sequência de versão específica usando o operador de igualdade (=).
  • Cada sequência de operador deve ser especificada como o operador, um espaço único e depois a versão.

    • Os operadores válidos são =, <, <=, > ou >=.

    • A versão precisa começar com um número seguido por qualquer quantidade de números, letras, pontos, traços ou sublinhados (tudo menos espaço ou vírgula)

    • Ao especificar uma sequência com limites superior e inferior, o limite inferior precisa vir primeiro, seguido por uma vírgula, um espaço e depois o limite superior.

      Observação: as cadeias de caracteres de versão afetadas não podem conter espaços à esquerda ou à direita.

  • Os operadores com limite superior podem ser inclusivos ou exclusivos, ou seja, <= ou <, respectivamente.

  • Os operadores com limite inferior podem ser inclusivos ou exclusivos, ou seja, >= ou >, respectivamente. No entanto, se você publicar um aviso de repositório e se tornar um aviso global, uma regra diferente se aplicará: as cadeias de caracteres com limite inferior só poderão ser inclusivas, ou seja, >=. O operador exclusivo de limite inferior (>) só é permitido quando a versão é 0, por exemplo > 0.

    Observações: a limitação de limite inferior:

    • é devido a incompatibilidades com o esquema OSV (vulnerabilidade de software livre).
    • só se aplica quando você faz uma sugestão em um aviso existente no GitHub Advisory Database.
  • Não é possível especificar vários intervalos de versão afetados no mesmo campo, como > 2.0, < 2.3, > 3.0, < 3.2. Para especificar mais de um intervalo, você precisa criar uma nova seção Produtos afetados para cada intervalo clicando no botão + Adicionar outro produto afetado.

    Captura de tela realçando o botão a ser usado para adicionar vários intervalos de versão afetada

  • Se o intervalo de versão afetada incluir apenas um limite superior ou inferior:

    • O valor implícito será sempre > 0 se o limite inferior não for especificado explicitamente.
    • O valor implícito será sempre infinito se o limite superior não for especificado explicitamente.

Para obter mais informações sobre o GitHub Advisory Database, confira https://github.com/github/advisory-database.