Managing innersource advisories

For background on how innersource advisories work and who can create them, see Innersource advisories.

Prerequisites

Innersource advisories can only be created in enterprises with an active GitHub Code Security or GitHub Advanced Security license.

Creating innersource advisories

To create an innersource advisory:

1. Create and install a GitHub App with the enterprise_innersource_vulnerabilities permission.
2. Generate a token associated with the app that has write access to this permission.
3. Create a description of the vulnerability using the OSV format, and POST it to the REST API endpoint /enterprises/{enterprise}/innersource-vulnerabilities/sync.

Each of these steps is described in more detail below.

Step 1: Create a GitHub App

Register a GitHub App that is owned by your enterprise, and grant it the enterprise_innersource_vulnerabilities permission with read and write access. See Registro de una aplicación de GitHub.

After registering the app, install it on your enterprise so that it can act on the enterprise's behalf.

Step 2: Generate an access token

Authenticate as the GitHub App installation to generate an installation access token. This token carries the enterprise_innersource_vulnerabilities permission and is used to authenticate your requests to the REST API. See Generación de un token de acceso de instalación para una aplicación de GitHub.

Step 3: Upload an advisory description

Describe the vulnerability using the OSV format, then POST the payload to /enterprises/{enterprise}/innersource-vulnerabilities/sync, using the installation access token to authenticate. The payload identifies the affected package and the range of vulnerable versions. If a fixed version is available, include a fixed field with the version number so that Dependabot can open pull requests to update affected repositories.

For detailed information on the advisory schema, see REST API endpoints for security advisories.

Using innersource advisories

After you create an innersource advisory, repositories in the enterprise that use the affected component will receive alerts and updates.

1. Ensure that the repositories in your enterprise have Dependabot alerts and updates enabled. You can enforce this at scale using a security configuration. See Creación de una configuración de seguridad personalizada.
2. Watch the dependent repositories' Dependabot alerts page for a new alert about the affected component. The alert will have a distinct "Innersource" label on it to distinguish it from open source advisory alerts.
3. If your advisory payload included a fixed field with a version number that matches an available package, Dependabot will also create a pull request that updates the package manager's manifest file. See Configuración de las actualizaciones de versiones de Dependabot.

Withdrawing innersource advisories

When there are no more vulnerable versions of an affected component in use, or if an advisory is superseded, it can be helpful to withdraw it.

To withdraw an advisory, use the same REST API endpoint as the creation step, but adjust the payload to include a withdrawn key, whose value is a date-time field indicating when the vulnerability was withdrawn.

OSV format support and limitations

GitHub accepts vulnerabilities in the Open Source Vulnerability (OSV) format through the innersource vulnerability sync API. While GitHub strives for compatibility with the OSV specification, there are differences between the standard OSV schema and what GitHub requires or supports.

Supported OSV schema version

GitHub supports OSV schema versions compatible with ~> 1.0 (i.e., 1.0.0 through 1.x.x). The recommended schema version is 1.4.0.

Affected entry formatting

The OSV specification allows a single affected entry to contain multiple ranges and multiple versions for the same package. GitHub normalizes these internally by splitting them into separate entries:

OSV standard	GitHub behavior
A single affected entry can contain multiple ranges	Accepted. Each range is processed as a separate vulnerable version range.
A single affected entry can contain multiple versions	Accepted. Each version is treated as an exact match (= x.y.z) and processed as a separate vulnerable version range.
A single affected entry can mix ranges and versions	Accepted. Ranges and versions are split into separate entries internally.
A SEMVER range can contain multiple introduced/fixed pairs	Accepted. Multiple disjoint intervals (e.g., [1.0.0, 1.0.2) and [3.0.0, 3.2.5)) within a single range are supported.

Supported range types

Range type	Support
ECOSYSTEM	Fully supported. Supports introduced, fixed, and last_affected events.
SEMVER	Fully supported. Supports introduced, fixed, and last_affected events. The last_affected event is parsed as a <= upper-bound comparator.
GIT	Not supported. Git commit-based ranges are not processed.

Required fields

The OSV specification treats several fields as optional, but GitHub requires them. Requests missing these fields are rejected with a 422 error.

Field	OSV spec	GitHub requirement
id	Required	Required. Used as the external identifier for the vulnerability.
severity array	Optional	Required. Must contain at least one CVSS_V3 or CVSS_V4 entry with a non-empty score string (e.g., CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H). Requests without a valid CVSS entry are rejected.
affected[].package.ecosystem	Required	Must be a supported ecosystem
affected[].ranges or affected[].versions	At least one required	At least one range or version must be present for alert matching

Optional fields with automatic derivation

Field	Behavior
database_specific.severity	If provided, used as the qualitative severity label (critical, high, moderate, or low). If absent, the severity is automatically derived from the CVSS vector score.
summary	If absent, falls back to the id field.
details	If absent, falls back to summary or id.

Supported severity types

Severity type	Support
CVSS_V3	Supported. Must be a valid CVSS 3.1 vector string.
CVSS_V4	Supported. Must be a valid CVSS 4.0 vector string.
Other types	Not supported. Will cause a parsing error.

Supported reference types

Reference type	Support
ADVISORY	Supported
WEB	Supported
FIX	Supported
ARTICLE	Supported
REPORT	Supported
PACKAGE	Supported (mapped to source code location)
EVIDENCE	Supported (ignored during processing)
DETECTION	Not supported. Stripped during processing.

Alias support

Alias format	Support
CVE-YYYY-NNNNN	Supported. Extracted as the CVE identifier. Only the first CVE alias is used.
Other formats (GHSA, PYSEC, etc.)	Not supported. Stripped during processing.

Field size constraints

The OSV specification does not define maximum string lengths for any field — all strings are unbounded. However, GitHub enforces field size limits based on its internal database schema. These limits cannot be relaxed without breaking synchronization with GitHub Enterprise Server, which maintains its own compatible schema.

Submissions exceeding these limits are rejected with a descriptive 422 error indicating which field exceeded the limit and the actual length provided (e.g., affected[0].first_patched_version is 63 characters (max 50)).

OSV field	Maps to	OSV standard limit	GitHub limit	Unit
summary	vulnerabilities.summary	No limit (recommended ≤120 chars)	1,024	bytes
id	vulnerabilities.external_id	No limit	2,048	characters
aliases[] (CVE entry)	vulnerabilities.cve_id	No limit	20	characters
severity[].score (CVSS v3)	vulnerabilities.cvss_v3	No limit	255	bytes
severity[].score (CVSS v4)	vulnerabilities.cvss_v4	No limit	255	characters
affected[].package.ecosystem	vulnerable_version_ranges.ecosystem	No limit	20	characters
affected[].package.name	vulnerable_version_ranges.affects	No limit	255	characters
affected[].ranges[].events[].fixed	vulnerable_version_ranges.fixed_in	No limit	50	characters
Computed vulnerable version range	vulnerable_version_ranges.requirements	No limit	65,535	bytes

Ecosystem mapping

GitHub maps OSV ecosystem names to its internal ecosystem identifiers. The following ecosystems are supported:

OSV ecosystem	GitHub ecosystem
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

Example: minimal OSV payload for alert generation

The following is a minimal OSV payload that contains all required fields for GitHub to create a Dependabot alert:

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

Known limitations

• Maximum 100 vulnerabilities per request. The sync API accepts at most 100 vulnerabilities in a single request.
• No GIT range type. Git commit-based version ranges are not supported.
• Single event types per ECOSYSTEM range. Each ECOSYSTEM range supports one introduced and one upper-bound event (fixed or last_affected). Multiple introduced/fixed pairs in a single ECOSYSTEM range are not supported — use separate ranges or separate affected entries instead. (This limitation does not apply to SEMVER ranges, which support multiple event pairs.)
• fixed and last_affected are mutually exclusive. A single range cannot contain both fixed and last_affected events. Use one or the other.
• GHES sync compatibility. Field size limits (such as fixed_in at 50 characters) are constrained by GitHub Enterprise Server schema compatibility requirements.