Managing innersource advisories

Create, distribute, and withdraw enterprise-scoped advisories to alert your internal repositories to vulnerabilities and ship fixes automatically.

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 Registering a GitHub App.

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 Generating an installation access token for a GitHub App.

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 Creating a custom security configuration.
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 Configuring Dependabot version updates.

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:

Supported range types

Required fields

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

Optional fields with automatic derivation

Supported severity types

Supported reference types

Alias support

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)).

Ecosystem mapping

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

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.