Gerenciando avisos de fonte interna

Para obter informações sobre como funcionam os avisos de fonte interna e quem pode criá-los, consulte Innersource advisories.

Pré-requisitos

Os avisos do innersource só podem ser criados em empresas com uma licença GitHub Code Security ou GitHub Advanced Security ativa.

Criando avisos de fonte interna

Para criar um aviso de fonte interna:

1. Crie e instale um GitHub App com permissão enterprise_innersource_vulnerabilities.
2. Gere um token associado ao aplicativo que tem write acesso a essa permissão.
3. Crie uma descrição da vulnerabilidade usando o formato OSV e POST envie-a para o endpoint da API REST /enterprises/{enterprise}/innersource-vulnerabilities/sync.

Cada uma dessas etapas é descrita em mais detalhes abaixo.

Etapa 1: Criar um GitHub App

Registre um GitHub App que pertence à sua empresa e conceda a ele a enterprise_innersource_vulnerabilities permissão com read and write acesso. Consulte Registrando um aplicativo GitHub.

Depois de registrar o aplicativo, instale-o em sua empresa para que ele possa agir em nome da empresa.

Etapa 2: gerar um token de acesso

Autentique-se como a GitHub App instalação para gerar um token de acesso de instalação. Esse token carrega a enterprise_innersource_vulnerabilities permissão e é usado para autenticar suas solicitações na API REST. Consulte Gerando um token de acesso de instalação para um aplicativo GitHub.

Etapa 3: Fazer upload da descrição do aviso

Descreva a vulnerabilidade usando o formato OSV e, em seguida, POST o payload para /enterprises/{enterprise}/innersource-vulnerabilities/sync, usando o token de acesso de instalação para se autenticar. A carga útil identifica o pacote afetado e o intervalo de versões vulneráveis. Se uma versão fixa estiver disponível, inclua um fixed campo com o número de versão para que Dependabot possa abrir solicitações de pull para atualizar os repositórios afetados.

Para obter informações detalhadas sobre o esquema de consultoria, consulte Pontos de extremidade de API REST para avisos de segurança.

Usando orientações do InnerSource

Depois de criar um aviso de fonte interna, os repositórios na empresa que usam o componente afetado receberão alertas e atualizações.

1. Verifique se os repositórios em sua empresa têm Dependabot alerts e as atualizações habilitados. Você pode impor isso em escala usando uma configuração de segurança. Consulte Criando uma configuração de segurança personalizada.
2. Assista à página dos Dependabot alerts repositórios dependentes para obter um novo alerta sobre o componente afetado. O alerta terá um rótulo distinto "Innersource" para distingui-lo dos alertas de aviso de código aberto.
3. Se o payload do aviso incluía um campo fixed com um número de versão que corresponde a um pacote disponível, Dependabot também criará uma pull request que atualiza o arquivo de manifesto do gerenciador de pacotes. Consulte Configuração de atualizações de versão do Dependabot.

Retirando avisos de InnerSource

Quando não há versões mais vulneráveis de um componente afetado em uso ou se um aviso é substituído, pode ser útil retirá-lo.

Para retirar um aviso, use o mesmo endpoint da API REST usado na etapa de criação, mas ajuste o payload para incluir uma chave withdrawn, cujo valor é um campo date-time que indica quando a vulnerabilidade foi retirada.

Suporte e limitações de formato OSV

GitHub aceita vulnerabilidades no formato OSV (Vulnerabilidade de Software Livre) por meio da API de sincronização de vulnerabilidade de fonte interna. Embora GitHub se esforce para compatibilidade com a especificação osV, há diferenças entre o esquema OSV padrão e o que GitHub requer ou dá suporte.

Versão compatível do esquema OSV

GitHub dá suporte a versões de esquema OSV compatíveis com ~> 1.0 (ou seja, 1.0.0 por meio 1.x.x). A versão de esquema recomendada é 1.4.0.

Formatação de entrada afetada

A especificação OSV permite que uma única affected entrada contenha várias ranges e várias versions para o mesmo pacote. GitHub normaliza-os internamente dividindo-os em entradas separadas:

| Padrão OSV | GitHub Comportamento | |---|---| | Uma única affected entrada pode conter várias ranges | Aceitado. Cada intervalo é processado como um intervalo de versão vulnerável separado. | | Uma única affected entrada pode conter várias versions | Aceitado. Cada versão é tratada como uma correspondência exata (= x.y.z) e processada como um intervalo de versão vulnerável separado. | | Uma única affected entrada pode misturar ranges e versions | Aceitado. Intervalos e versões são divididos em entradas separadas internamente. | | Um SEMVER intervalo pode conter vários introduced/fixed pares | Aceitado. Há suporte a vários intervalos disjuntos (por exemplo, [1.0.0, 1.0.2) e [3.0.0, 3.2.5)) em uma única faixa. |

Tipos de intervalo suportados

Tipo de intervalo	Suporte
ECOSYSTEM
Totalmente suportado. Oferece suporte a eventos introduced, fixed e last_affected.
SEMVER
Totalmente suportado. Compatível com os eventos introduced, fixed e last_affected. O evento last_affected é interpretado como um comparador de limite superior <=.
GIT
Não há suporte. Os intervalos baseados em commit do Git não são processados.

SEMVER os intervalos dão suporte a vários introduced/fixed pares em um único intervalo (por exemplo, [1.0.0, 1.0.2) e [3.0.0, 3.2.5) em uma matriz de eventos).

- fixed e last_affectednão pode aparecer juntos no mesmo intervalo. Use um ou outro, com preferência por fixed.

Campos obrigatórios

A especificação OSV trata vários campos como opcionais, mas GitHub requer eles. As solicitações ausentes desses campos são rejeitadas com um erro 422.

| Campo | Especificação de OSV | GitHub Exigência | |---|---|---| | id | Obrigatório | Required. Usado como o identificador externo para a vulnerabilidade. | | severity matriz | Optional | Obrigatório. Deve conter pelo menos uma CVSS_V3 ou CVSS_V4 entrada com uma cadeia de caracteres não vazia score (por exemplo, CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H). As solicitações sem uma entrada CVSS válida são rejeitadas. | | affected[].package.ecosystem | Obrigatório | Deve ser um ecossistema com suporte | | affected[].ranges ou affected[].versions | Pelo menos um é obrigatório | Pelo menos um intervalo ou versão deve ser especificado para a correspondência de alertas |

Campos opcionais com derivação automática

Campo	Behavior
database_specific.severity	Se fornecido, usado como o rótulo de severidade qualitativa (critical, , high``moderateou low). Se ausente, a severidade é derivada automaticamente da pontuação de vetor CVSS.
summary	Se estiver ausente, recorre ao campo id.
details	Se estiver ausente, recorre a summary ou id.

Tipos de severidade suportados

Tipo de severidade	Suporte
CVSS_V3
Compatível. Deve ser uma cadeia de caracteres de vetor CVSS 3.1 válida.
CVSS_V4
Compatível. Deve ser uma cadeia de caracteres de vetor CVSS 4.0 válida.
Outros tipos
Não há suporte. Causará um erro de análise.

Tipos de referência com suporte

Tipo de referência	Suporte
ADVISORY	Supported
WEB	Supported
FIX	Supported
ARTICLE	Supported
REPORT	Supported
PACKAGE	Compatível (mapeado para a localização do código-fonte)
EVIDENCE	Suporte (ignorado durante o processamento)
DETECTION
Não há suporte. Despojado durante o processamento.

Suporte de alias

Formato de alias	Suporte
CVE-YYYY-NNNNN
Compatível. Extraído como o identificador CVE. Somente o primeiro alias CVE é usado.
Outros formatos (GHSA, PYSEC etc.)
Não há suporte. Despojado durante o processamento.

Restrições de tamanho de campo

A especificação OSV não define comprimentos máximos de string para nenhum campo — todas as strings não têm limite de comprimento. No entanto, GitHub impõe limites de tamanho de campo com base em seu esquema de banco de dados interno. Esses limites não podem ser relaxados sem interromper a sincronização com GitHub Enterprise Server, que mantém seu próprio esquema compatível.

Os envios que excedem esses limites são rejeitados com um erro descritivo 422 indicando qual campo excedeu o limite e o comprimento real fornecido (por exemplo, affected[0].first_patched_version is 63 characters (max 50)).

| Campo OSV | Mapeia para | Limite padrão do OSV | GitHub Limite | Unidade | |---|---|---|---|---| | summary | vulnerabilities.summary | Sem limite (≤ 120 caracteres recomendados) | 1,024 | bytes | | id | vulnerabilities.external_id | Sem limite | 2,048 | Caracteres | | aliases[] (Entrada CVE) | vulnerabilities.cve_id | Sem limite | 20 | Caracteres | | severity[].score (CVSS v3) | vulnerabilities.cvss_v3 | Sem limite | 255 | bytes | | severity[].score (CVSS v4) | vulnerabilities.cvss_v4 | Sem limite | 255 | Caracteres | | affected[].package.ecosystem | vulnerable_version_ranges.ecosystem | Sem limite | 20 | Caracteres | | affected[].package.name | vulnerable_version_ranges.affects | Sem limite | 255 | Caracteres | | affected[].ranges[].events[].fixed | vulnerable_version_ranges.fixed_in | Sem limite | 50 | Caracteres | | Intervalo de versão vulnerável computado | vulnerable_version_ranges.requirements | Sem limite | 65,535 | bytes |

varchar as colunas são validadas por contagem de caracteres; varbinary e text as colunas são validadas pelo tamanho do byte (relevante para caracteres UTF-8 de vários bytes).

• Esses limites são restringidos pela GitHub Enterprise Server compatibilidade de esquema. Ampliar as colunas em GitHub sem as alterações correspondentes no GHES causaria falhas na sincronização de avisos entre ambientes.

Mapeamento de ecossistema

GitHub mapeia os nomes de ecossistema do OSV para seus identificadores internos. Há suporte para os seguintes ecossistemas:

| Ecossistema de OSV | GitHub ecossistema | |---|---| | npm | npm | | PyPI | pip | | RubyGems | RubyGems | | Maven | Maven | | NuGet | NuGet | | Packagist | Composer | | Go | Go | | crates.io | Rust | | Hex | Erlang | | Pub | Pub | | SwiftURL | Swift | | GitHub Actions | GitHub Actions |

Exemplo: carga mínima de OSV para geração de alertas

A seguir, está um payload OSV mínimo que contém todos os campos necessários para que GitHub crie um alerta Dependabot:

{
  "schema_version": "1.4.0",
  "id": "EXAMPLE-2024-001",
  "modified": "2024-01-15T10:00:00Z",
  "summary": "Example vulnerability in example-package",
  "details": "A detailed description of the vulnerability.",
  "aliases": ["CVE-2024-12345"],
  "severity": [
    {
      "type": "CVSS_V3",
      "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
    }
  ],
  "affected": [
    {
      "package": {
        "ecosystem": "npm",
        "name": "example-package"
      },
      "ranges": [
        {
          "type": "ECOSYSTEM",
          "events": [
            { "introduced": "0" },
            { "fixed": "1.2.3" }
          ]
        }
      ]
    }
  ],
  "database_specific": {
    "severity": "Critical"
  },
  "references": [
    { "type": "ADVISORY", "url": "https://example.com/advisory" }
  ],
  "published": "2024-01-15T10:00:00Z"
}

Limitações conhecidas

• Máximo de 100 vulnerabilidades por solicitação. A API de sincronização aceita no máximo 100 vulnerabilidades em uma única solicitação.
• Sem GIT tipo de intervalo. Não há suporte para intervalos de versão baseados em commit do Git.
• Tipos de evento únicos por faixa do ECOSYSTEM. Cada intervalo ECOSYSTEM suporta um introduced e um evento de limite superior (fixed ou last_affected). Não há suporte a vários pares de introduced/fixed em um único intervalo ECOSYSTEM — use intervalos separados ou entradas affected separadas. (Essa limitação não se aplica a SEMVER intervalos, que suportam múltiplos pares de eventos.)
• fixed e last_affected são mutuamente exclusivos. Um único intervalo não pode conter eventos fixed e last_affected. Use um ou outro.
• Compatibilidade de sincronização de GHES. Os limites de tamanho do campo (como fixed_in com 50 caracteres) são limitados pelos requisitos de compatibilidade do esquema de GitHub Enterprise Server.