Administración de avisos de recursos internos

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

Prerequisites

Los avisos internos solo se pueden crear en empresas con una licencia o GitHub Code Security activaGitHub Advanced Security.

Creación de avisos de recursos internos

Para crear un aviso de recursos internos:

1. Cree e instale un GitHub App con el enterprise_innersource_vulnerabilities permiso .
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 sea propiedad de su empresa y conceda el enterprise_innersource_vulnerabilities permiso con read and write acceso. 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 GitHub App instalación para generar un token de acceso de 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 mediante el formato OSV y, a continuación POST , la carga útil en /enterprises/{enterprise}/innersource-vulnerabilities/sync, mediante el token de acceso de instalación para autenticarse. La carga 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 recursos internos

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 "Innersource" distinta en ella para distinguirla de código abierto alertas de aviso.
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.

Retirar avisos de recursos internos

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 de esquema de 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 de versiones vulnerable independiente. | | 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 intervalo de versiones vulnerable independiente. | | 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 introducedeventos , fixedy last_affected .
SEMVER
Totalmente compatible. Admite introducedeventos , fixedy last_affected . El last_affected evento se analiza como un <= comparador enlazado superior.
GIT
No se admite. Los intervalos basados en confirmaciones 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 (asignado a la ubicación del código fuente)
EVIDENCE	Compatible (omitido durante el procesamiento)
DETECTION
No se admite. Quitado durante el procesamiento.

Compatibilidad con alias

Formato de 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 restringidos por GitHub Enterprise Server la compatibilidad de esquemas. La ampliación de columnas en GitHub sin hacer coincidir los cambios de GHES provocaría errores de sincronización de avisos entre entornos.

Asignación del ecosistema

GitHub asigna nombres de ecosistema de OSV a sus identificadores internos del 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 mínima de OSV para la generación de 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.
• Sin GIT tipo de intervalo. No se admiten intervalos de versiones basados en confirmación de Git.
• Tipos de eventos únicos por intervalo ECOSYSTEM. Cada ECOSYSTEM intervalo admite un introduced evento de límite superior (fixed o last_affected). No se admiten varios introduced/fixed pares en un solo ECOSYSTEM intervalo: use intervalos independientes o entradas independientes affected en su lugar. (Esta limitación no se aplica a SEMVER los intervalos, que admiten 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.