Gestión de avisos de InnerSource

Para obtener información sobre cómo funcionan los avisos de recursos internos y quién puede crearlos, consulte Avisos de recursos internos.

Prerequisites

Los avisos de Innersource solo se pueden crear en empresas con una licencia GitHub Code Security o GitHub Advanced Security activa.

Creación de avisos de InnerSource

Para crear una asesoría de InnerSource:

1. Cree e instale un GitHub App con el permiso enterprise_innersource_vulnerabilities.
2. Genere un token asociado a la aplicación que tiene write acceso a este permiso.
3. Cree una descripción de la vulnerabilidad mediante el formato OSV y POST en el punto de conexión /enterprises/{enterprise}/innersource-vulnerabilities/syncde la API REST.

Cada uno de estos pasos se describe con más detalle a continuación.

Paso 1: Crear un GitHub App

Registre un GitHub App que pertenezca a su empresa y concédale el permiso enterprise_innersource_vulnerabilities con acceso read and write. Consulte Registro de una aplicación de GitHub.

Después de registrar la aplicación, instálela en su empresa para que pueda actuar en nombre de la empresa.

Paso 2: Generación de un token de acceso

Autentíquese como la instalación GitHub App para generar un token de acceso para la instalación. Este token lleva el enterprise_innersource_vulnerabilities permiso y se usa para autenticar las solicitudes en la API REST. Consulte Generación de un token de acceso de instalación para una aplicación de GitHub.

Paso 3: Cargar una descripción de aviso

Describa la vulnerabilidad utilizando el formato OSV y, a continuación, POST la carga útil a /enterprises/{enterprise}/innersource-vulnerabilities/sync, usando el token de acceso de instalación para autenticarse. La carga útil identifica el paquete afectado y el intervalo de versiones vulnerables. Si hay disponible una versión fija, incluya un fixed campo con el número de versión para que Dependabot pueda abrir solicitudes de incorporación de cambios para actualizar los repositorios afectados.

Para obtener información detallada sobre el esquema de asesoramiento, consulte Puntos de conexión de API de REST para avisos de seguridad.

Uso de avisos de InnerSource

Después de crear un aviso de recursos internos, los repositorios de la empresa que usan el componente afectado recibirán alertas y actualizaciones.

1. Asegúrese de que los repositorios de la empresa tienen Dependabot alerts y las actualizaciones habilitadas. Puede aplicar esto a escala mediante una configuración de seguridad. Consulte Creación de una configuración de seguridad personalizada.
2. Vea la página de repositorios dependientes Dependabot alerts para obtener una nueva alerta sobre el componente afectado. La alerta tendrá una etiqueta distintiva "Innersource" para distinguirla de los avisos de código abierto.
3. Si la carga de asesoramiento incluía un fixed campo con un número de versión que coincide con un paquete disponible, Dependabot también creará una solicitud de incorporación de cambios que actualice el archivo de manifiesto del administrador de paquetes. Consulte Configuración de las actualizaciones de versiones de Dependabot.

Retirada de avisos de InnerSource

Cuando no hay versiones más vulnerables de un componente afectado en uso o si se sustituye un aviso, puede resultar útil retirarlo.

Para retirar un aviso, use el mismo punto de conexión de la API REST que el paso de creación, pero ajuste la carga para incluir una withdrawn clave, cuyo valor es un date-time campo que indica cuándo se retiró la vulnerabilidad.

Compatibilidad y limitaciones de formato de OSV

GitHub acepta vulnerabilidades en el formato de vulnerabilidad de código abierto (OSV) a través de la API de sincronización de vulnerabilidades de origen interno. Aunque GitHub se esfuerza por la compatibilidad con la especificación de OSV, hay diferencias entre el esquema estándar de OSV y lo que GitHub requiere o admite.

Versión del esquema OSV compatible

GitHub admite versiones de esquema de OSV compatibles con ~> 1.0 (es decir, 1.0.0 a través de 1.x.x). La versión de esquema recomendada es 1.4.0.

Formato de entrada afectado

La especificación de OSV permite que una sola affected entrada contenga varias ranges y varias versions para el mismo paquete. GitHub normaliza estos elementos internamente dividiéndolas en entradas independientes:

| Estándar de OSV | GitHub comportamiento | |---|---| | Una sola affected entrada puede contener varios ranges | Accepted. Cada intervalo se procesa como un intervalo independiente de versiones vulnerables. | | Una sola affected entrada puede contener varios versions | Accepted. Cada versión se trata como una coincidencia exacta (= x.y.z) y se procesa como un rango independiente de versiones vulnerables. | | Una sola affected entrada puede mezclar ranges y versions | Accepted. Los intervalos y las versiones se dividen en entradas independientes internamente. | | Un SEMVER intervalo puede contener varios introduced/fixed pares | Accepted. Se admiten varios intervalos separados (por ejemplo, [1.0.0, 1.0.2) y [3.0.0, 3.2.5)) dentro de un solo intervalo. |

Tipos de intervalo admitidos

Tipo de intervalo	Apoyo
ECOSYSTEM
Totalmente compatible. Admite eventos introduced, fixed y last_affected.
SEMVER
Totalmente compatible. Admite eventos introduced, fixed y last_affected. El evento last_affected se analiza como un comparador de límite superior <=.
GIT
No se admite. Los rangos basados en commits de Git no se procesan.

SEMVER los intervalos admiten varios introduced/fixed pares dentro de un único intervalo (por ejemplo, [1.0.0, 1.0.2) y [3.0.0, 3.2.5) en una matriz de eventos).

- fixed y last_affectedno pueden aparecer juntos en el mismo intervalo. Use uno u otro, con preferencia para fixed.

Campos obligatorios

La especificación de OSV trata varios campos como opcionales, pero GitHub los requiere. Las solicitudes que faltan estos campos se rechazan con un error 422.

| Campo | Especificación de OSV | GitHub requisito | |---|---|---| | id | Obligatorio | Required. Se usa como identificador externo para la vulnerabilidad. | | severity arreglo | Optional | Obligatorio. Debe contener al menos una CVSS_V3 entrada o CVSS_V4 con una cadena no vacía score (por ejemplo, CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H). Se rechazan las solicitudes sin una entrada CVSS válida. | | affected[].package.ecosystem | Obligatorio | Debe ser un ecosistema compatible. | | affected[].ranges o affected[].versions | Al menos uno requerido | Al menos un intervalo o versión debe estar presente para la coincidencia de alertas. |

Campos opcionales con derivación automática

Campo	Comportamiento
database_specific.severity	Si se proporciona, se usa como etiqueta de gravedad cualitativa (critical, high, moderateo low). Si no está presente, la gravedad se deriva automáticamente de la puntuación del vector CVSS.
summary	Si está ausente, vuelve al id campo.
details	Si está ausente, retroceda a summary o id.

Tipos de gravedad admitidos

Tipo de gravedad	Apoyo
CVSS_V3
Admitido. Debe ser una cadena de vector CVSS 3.1 válida.
CVSS_V4
Admitido. Debe ser una cadena de vector CVSS 4.0 válida.
Otros tipos
No se admite. Provocará un error de análisis.

Tipos de referencia admitidos

Tipo de referencia	Apoyo
ADVISORY	Soportado
WEB	Soportado
FIX	Soportado
ARTICLE	Soportado
REPORT	Soportado
PACKAGE	Compatible (asociado a la ubicación del código fuente)
EVIDENCE	Admitido (ignorado durante el procesamiento)
DETECTION
No se admite. Quitado durante el procesamiento.

Compatibilidad con alias

Formato del alias	Apoyo
CVE-YYYY-NNNNN
Admitido. Extraído como identificador CVE. Solo se usa el primer alias CVE.
Otros formatos (GHSA, PYSEC, etc.)
No se admite. Quitado durante el procesamiento.

Restricciones de tamaño de campo

La especificación de OSV no define las longitudes máximas de cadena para ningún campo; todas las cadenas están sin enlazar. Sin embargo, GitHub aplica límites de tamaño de campo en función de su esquema interno de la base de datos. Estos límites no se pueden relajar sin interrumpir la sincronización con GitHub Enterprise Server, que mantiene su propio esquema compatible.

Los envíos que superan estos límites se rechazan con un error descriptivo 422 que indica qué campo superó el límite y la longitud real proporcionada (por ejemplo, affected[0].first_patched_version is 63 characters (max 50)).

| Campo OSV | Se asigna a | Límite estándar de OSV | GitHub límite | Unidad | |---|---|---|---|---| | summary | vulnerabilities.summary | Sin límite (se recomienda ≤120 caracteres) | 1,024 | bytes | | id | vulnerabilities.external_id | Sin límite | 2,048 | caracteres | | aliases[] (Entrada CVE) | vulnerabilities.cve_id | Sin límite | 20 | caracteres | | severity[].score (CVSS v3) | vulnerabilities.cvss_v3 | Sin límite | 255 | bytes | | severity[].score (CVSS v4) | vulnerabilities.cvss_v4 | Sin límite | 255 | caracteres | | affected[].package.ecosystem | vulnerable_version_ranges.ecosystem | Sin límite | 20 | caracteres | | affected[].package.name | vulnerable_version_ranges.affects | Sin límite | 255 | caracteres | | affected[].ranges[].events[].fixed | vulnerable_version_ranges.fixed_in | Sin límite | 50 | caracteres | | Intervalo de versiones vulnerables calculado | vulnerable_version_ranges.requirements | Sin límite | 65,535 | bytes |

varchar las columnas se validan mediante el recuento de caracteres; varbinary y text las columnas se validan por tamaño de byte (relevante para caracteres UTF-8 de varios bytes).

• Estos límites están condicionados por GitHub Enterprise Server la compatibilidad del esquema. La ampliación de columnas en GitHub sin hacer coincidir los cambios de GHES provocaría errores de sincronización de avisos entre entornos.

Mapeo del ecosistema

GitHub asocia los nombres de ecosistema de OSV con sus identificadores internos de ecosistema. Se admiten los siguientes ecosistemas:

| Ecosistema de OSV | GitHub ecosistema | |---|---| | npm | npm | | PyPI | pip | | RubyGems | RubyGems | | Maven | Maven | | NuGet | NuGet | | Packagist | Compositor | | Go | Go | | crates.io | Óxido | | Hex | Erlang | | Pub | Bar | | SwiftURL | Swift | | GitHub Actions | Acciones de GitHub |

Ejemplo: carga útil mínima de OSV para generar alertas

A continuación se muestra una carga mínima de OSV que contiene todos los campos necesarios para GitHub crear una Dependabot alerta:

{
  "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"
}

Limitaciones conocidas

• Máximo de 100 vulnerabilidades por solicitud. La API de sincronización acepta como máximo 100 vulnerabilidades en una sola solicitud.
• No hay ningún GIT tipo de intervalo. No se admiten rangos de versiones basados en commit de Git.
• Tipos de eventos individuales por rango de ECOSYSTEM. Cada intervalo ECOSYSTEM admite un introduced y un evento de límite superior (fixed o last_affected). No se admiten varios pares de introduced/fixed dentro de un único intervalo ECOSYSTEM — use intervalos independientes o entradas affected independientes en su lugar. (Esta limitación no se aplica a los intervalos SEMVER, que permiten varios pares de eventos.)
• fixed y last_affected son mutuamente excluyentes. Un único intervalo no puede contener eventos fixed y last_affected . Use uno u otro.
• Compatibilidad de sincronización de GHES. Los límites de tamaño de campo (como fixed_in en 50 caracteres) están restringidos por GitHub Enterprise Server los requisitos de compatibilidad del esquema.