diff --git a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json index fc52244fb..4f4bb3037 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json +++ b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json @@ -59498,6 +59498,848 @@ } } }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": { + "post": { + "summary": "Sync innersource vulnerabilities for an enterprise", + "description": "Synchronize innersource vulnerability data with the Advisory Database for an enterprise.\nThis endpoint receives vulnerability data in OSV format and creates, updates, or withdraws\ninnersource vulnerabilities accordingly. Dependabot alerting is triggered for created and\nupdated vulnerabilities.\n\nThe request body accepts up to 100 vulnerabilities per call. The request is validated and\nthen queued for asynchronous processing: a successful request returns `202 Accepted` with a\n`Location` header pointing to a status URL that you poll for the final result.\n\nSyncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see \"[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)\" and \"[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api).\"\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/sync-enterprise-innersource-vulnerabilities", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of vulnerabilities in OSV format to synchronize", + "items": { + "title": "OSV Vulnerability", + "description": "A vulnerability in OSV (Open Source Vulnerability) format", + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the vulnerability from the external system", + "examples": [ + "MVS-2026-001" + ] + }, + "schema_version": { + "type": "string", + "description": "The OSV schema version", + "examples": [ + "1.4.0" + ] + }, + "summary": { + "type": "string", + "description": "A short summary of the vulnerability", + "examples": [ + "Example vulnerability summary" + ] + }, + "details": { + "type": "string", + "description": "Detailed description of the vulnerability" + }, + "aliases": { + "type": "array", + "description": "IDs for the same vulnerability in other databases. Only CVE IDs are used (to populate the vulnerability's CVE identifier); other aliases are ignored.", + "items": { + "type": "string" + }, + "examples": [ + "CVE-2026-12345" + ] + }, + "severity": { + "type": "array", + "description": "Severity information for the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of severity scoring (e.g., CVSS_V3)" + }, + "score": { + "type": "string", + "description": "The severity score or vector string" + } + } + } + }, + "affected": { + "type": "array", + "description": "Packages and versions affected by the vulnerability", + "items": { + "type": "object", + "properties": { + "package": { + "type": "object", + "properties": { + "ecosystem": { + "type": "string", + "description": "The package ecosystem (e.g., npm, pip, maven)" + }, + "name": { + "type": "string", + "description": "The package name" + } + } + }, + "ranges": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "introduced": { + "type": "string", + "description": "The version that introduced the vulnerability" + }, + "fixed": { + "type": "string", + "description": "The version that fixed the vulnerability" + }, + "last_affected": { + "type": "string", + "description": "The last affected version" + }, + "limit": { + "type": "string", + "description": "The upper limit of the affected range" + } + } + } + } + } + } + } + } + } + }, + "references": { + "type": "array", + "description": "URLs for more information about the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reference. Supported values: PACKAGE, ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types are ignored." + }, + "url": { + "type": "string", + "format": "uri", + "description": "The reference URL" + } + } + } + }, + "published": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was first published" + }, + "modified": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was last modified" + }, + "withdrawn": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was withdrawn. If present, the vulnerability will be marked as withdrawn." + } + } + }, + "minItems": 1, + "maxItems": 100 + }, + "examples": { + "default": { + "value": [ + { + "id": "MVS-2026-001", + "schema_version": "1.4.0", + "summary": "Example vulnerability summary", + "aliases": [ + "GHSA-xxxx-xxxx-xxxx" + ], + "affected": [ + { + "package": { + "ecosystem": "npm", + "name": "example-package" + }, + "ranges": [ + { + "type": "SEMVER", + "events": [ + { + "introduced": "1.0.0" + }, + { + "fixed": "1.0.1" + } + ] + } + ] + } + ] + } + ] + } + } + } + } + }, + "responses": { + "202": { + "description": "Sync operation accepted for asynchronous processing. Poll the returned URL for results.", + "headers": { + "Location": { + "description": "URL to poll for sync results", + "schema": { + "type": "string", + "format": "uri" + } + }, + "Retry-After": { + "description": "Number of seconds to wait before polling", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "title": "External Vulnerability Sync Accepted", + "description": "Response when an external vulnerability sync request is accepted for asynchronous processing", + "type": "object", + "required": [ + "id", + "url", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID for polling", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "url": { + "type": "string", + "description": "URL to poll for sync results", + "format": "uri", + "examples": [ + "https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Initial job status", + "enum": [ + "queued" + ], + "examples": [ + "queued" + ] + } + } + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "queued" + } + } + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": [ + "string", + "null" + ] + }, + "documentation_url": { + "type": [ + "string", + "null" + ] + }, + "detail": { + "type": [ + "string", + "null" + ] + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": [ + "string", + "null" + ] + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Requires authentication", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": { + "get": { + "summary": "Get innersource vulnerability sync status for an enterprise", + "description": "Get the status of an asynchronous innersource vulnerability sync operation for an enterprise.\nReturns 202 with a `Retry-After` header while the sync is still processing, or 200 with\nthe full sync results once complete.\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/get-enterprise-innersource-vulnerability-sync-status", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "The unique identifier of the sync job.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Sync operation completed", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "title": "External Vulnerability Sync Result", + "description": "Result of an external vulnerability synchronization operation", + "type": "object", + "required": [ + "processed", + "created", + "updated", + "withdrawn", + "errors", + "results" + ], + "properties": { + "processed": { + "type": "integer", + "description": "Total number of vulnerabilities processed", + "examples": [ + 3 + ] + }, + "created": { + "type": "integer", + "description": "Number of new vulnerabilities created", + "examples": [ + 2 + ] + }, + "updated": { + "type": "integer", + "description": "Number of existing vulnerabilities updated", + "examples": [ + 1 + ] + }, + "withdrawn": { + "type": "integer", + "description": "Number of vulnerabilities marked as withdrawn", + "examples": [ + 0 + ] + }, + "errors": { + "type": "integer", + "description": "Number of vulnerabilities that failed to process", + "examples": [ + 0 + ] + }, + "results": { + "type": "array", + "description": "Detailed result for each processed vulnerability", + "items": { + "type": "object", + "required": [ + "external_id", + "status" + ], + "properties": { + "external_id": { + "type": "string", + "description": "The external ID of the vulnerability (corresponds to the `id` field in the request payload)", + "examples": [ + "MVS-2026-001" + ] + }, + "status": { + "type": "string", + "description": "The processing status", + "enum": [ + "created", + "updated", + "withdrawn", + "error" + ], + "examples": [ + "created" + ] + }, + "ghsa_id": { + "type": "string", + "description": "The advisory ID assigned to the vulnerability. For innersource vulnerabilities this is a GHIS ID. Present for successful operations.", + "examples": [ + "GHIS-xxxx-xxxx-xxxx" + ] + }, + "error": { + "type": "string", + "description": "Error message (present only when status is 'error')" + } + } + } + } + } + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string" + } + } + } + ] + }, + "examples": { + "success": { + "value": { + "processed": 1, + "created": 1, + "updated": 0, + "withdrawn": 0, + "errors": 0, + "results": [ + { + "external_id": "MVS-2026-001", + "status": "created", + "ghsa_id": "GHIS-xxxx-xxxx-xxxx" + } + ] + } + }, + "error": { + "value": { + "status": "error", + "error": "Internal error processing vulnerabilities" + } + } + } + } + } + }, + "202": { + "description": "Sync operation is still processing", + "headers": { + "Retry-After": { + "description": "Number of seconds to wait before polling again", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "title": "External Vulnerability Sync Status", + "description": "Status of an in-progress external vulnerability sync operation", + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Current processing status", + "enum": [ + "processing" + ], + "examples": [ + "processing" + ] + } + } + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "processing" + } + } + } + } + } + }, + "401": { + "description": "Requires authentication", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, "/enterprises/{enterprise}/installation": { "get": { "summary": "Get an enterprise installation for the authenticated app", diff --git a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml index 928fb96a9..3f358d5b7 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml +++ b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml @@ -22814,6 +22814,407 @@ paths: enabledForGitHubApps: true category: enterprise-admin subcategory: enterprise-roles + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": + post: + summary: Sync innersource vulnerabilities for an enterprise + description: |- + Synchronize innersource vulnerability data with the Advisory Database for an enterprise. + This endpoint receives vulnerability data in OSV format and creates, updates, or withdraws + innersource vulnerabilities accordingly. Dependabot alerting is triggered for created and + updated vulnerabilities. + + The request body accepts up to 100 vulnerabilities per call. The request is validated and + then queued for asynchronous processing: a successful request returns `202 Accepted` with a + `Location` header pointing to a status URL that you poll for the final result. + + Syncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api)." + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/sync-enterprise-innersource-vulnerabilities + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise + parameters: + - *39 + requestBody: + required: true + content: + application/json: + schema: + type: array + description: Array of vulnerabilities in OSV format to synchronize + items: + title: OSV Vulnerability + description: A vulnerability in OSV (Open Source Vulnerability) format + type: object + required: + - id + properties: + id: + type: string + description: Unique identifier for the vulnerability from the + external system + examples: + - MVS-2026-001 + schema_version: + type: string + description: The OSV schema version + examples: + - 1.4.0 + summary: + type: string + description: A short summary of the vulnerability + examples: + - Example vulnerability summary + details: + type: string + description: Detailed description of the vulnerability + aliases: + type: array + description: IDs for the same vulnerability in other databases. + Only CVE IDs are used (to populate the vulnerability's CVE identifier); + other aliases are ignored. + items: + type: string + examples: + - CVE-2026-12345 + severity: + type: array + description: Severity information for the vulnerability + items: + type: object + properties: + type: + type: string + description: The type of severity scoring (e.g., CVSS_V3) + score: + type: string + description: The severity score or vector string + affected: + type: array + description: Packages and versions affected by the vulnerability + items: + type: object + properties: + package: + type: object + properties: + ecosystem: + type: string + description: The package ecosystem (e.g., npm, pip, + maven) + name: + type: string + description: The package name + ranges: + type: array + items: + type: object + properties: + type: + type: string + events: + type: array + items: + type: object + properties: + introduced: + type: string + description: The version that introduced the + vulnerability + fixed: + type: string + description: The version that fixed the vulnerability + last_affected: + type: string + description: The last affected version + limit: + type: string + description: The upper limit of the affected + range + references: + type: array + description: URLs for more information about the vulnerability + items: + type: object + properties: + type: + type: string + description: 'The type of reference. Supported values: PACKAGE, + ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References + with other types are ignored.' + url: + type: string + format: uri + description: The reference URL + published: + type: string + format: date-time + description: When the vulnerability was first published + modified: + type: string + format: date-time + description: When the vulnerability was last modified + withdrawn: + type: string + format: date-time + description: When the vulnerability was withdrawn. If present, + the vulnerability will be marked as withdrawn. + minItems: 1 + maxItems: 100 + examples: + default: + value: + - id: MVS-2026-001 + schema_version: 1.4.0 + summary: Example vulnerability summary + aliases: + - GHSA-xxxx-xxxx-xxxx + affected: + - package: + ecosystem: npm + name: example-package + ranges: + - type: SEMVER + events: + - introduced: 1.0.0 + - fixed: 1.0.1 + responses: + '202': + description: Sync operation accepted for asynchronous processing. Poll the + returned URL for results. + headers: + Location: + description: URL to poll for sync results + schema: + type: string + format: uri + Retry-After: + description: Number of seconds to wait before polling + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + title: External Vulnerability Sync Accepted + description: Response when an external vulnerability sync request + is accepted for asynchronous processing + type: object + required: + - id + - url + - status + properties: + id: + type: string + description: Job status ID for polling + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: + type: string + description: URL to poll for sync results + format: uri + examples: + - https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Initial job status + enum: + - queued + examples: + - queued + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: queued + '400': *14 + '401': *23 + '403': *27 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": + get: + summary: Get innersource vulnerability sync status for an enterprise + description: |- + Get the status of an asynchronous innersource vulnerability sync operation for an enterprise. + Returns 202 with a `Retry-After` header while the sync is still processing, or 200 with + the full sync results once complete. + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/get-enterprise-innersource-vulnerability-sync-status + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise + parameters: + - *39 + - name: job_id + in: path + required: true + description: The unique identifier of the sync job. + schema: + type: string + responses: + '200': + description: Sync operation completed + content: + application/json: + schema: + oneOf: + - title: External Vulnerability Sync Result + description: Result of an external vulnerability synchronization + operation + type: object + required: + - processed + - created + - updated + - withdrawn + - errors + - results + properties: + processed: + type: integer + description: Total number of vulnerabilities processed + examples: + - 3 + created: + type: integer + description: Number of new vulnerabilities created + examples: + - 2 + updated: + type: integer + description: Number of existing vulnerabilities updated + examples: + - 1 + withdrawn: + type: integer + description: Number of vulnerabilities marked as withdrawn + examples: + - 0 + errors: + type: integer + description: Number of vulnerabilities that failed to process + examples: + - 0 + results: + type: array + description: Detailed result for each processed vulnerability + items: + type: object + required: + - external_id + - status + properties: + external_id: + type: string + description: The external ID of the vulnerability (corresponds + to the `id` field in the request payload) + examples: + - MVS-2026-001 + status: + type: string + description: The processing status + enum: + - created + - updated + - withdrawn + - error + examples: + - created + ghsa_id: + type: string + description: The advisory ID assigned to the vulnerability. + For innersource vulnerabilities this is a GHIS ID. Present + for successful operations. + examples: + - GHIS-xxxx-xxxx-xxxx + error: + type: string + description: Error message (present only when status is + 'error') + - type: object + properties: + status: + type: string + enum: + - error + error: + type: string + examples: + success: + value: + processed: 1 + created: 1 + updated: 0 + withdrawn: 0 + errors: 0 + results: + - external_id: MVS-2026-001 + status: created + ghsa_id: GHIS-xxxx-xxxx-xxxx + error: + value: + status: error + error: Internal error processing vulnerabilities + '202': + description: Sync operation is still processing + headers: + Retry-After: + description: Number of seconds to wait before polling again + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + title: External Vulnerability Sync Status + description: Status of an in-progress external vulnerability sync + operation + type: object + required: + - id + - status + properties: + id: + type: string + description: Job status ID + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Current processing status + enum: + - processing + examples: + - processing + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: processing + '401': *23 + '403': *27 + '404': *6 + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories "/enterprises/{enterprise}/installation": get: summary: Get an enterprise installation for the authenticated app diff --git a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json index 066fe7480..98e6ac9f1 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json +++ b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json @@ -59337,6 +59337,848 @@ } } }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": { + "post": { + "summary": "Sync innersource vulnerabilities for an enterprise", + "description": "Synchronize innersource vulnerability data with the Advisory Database for an enterprise.\nThis endpoint receives vulnerability data in OSV format and creates, updates, or withdraws\ninnersource vulnerabilities accordingly. Dependabot alerting is triggered for created and\nupdated vulnerabilities.\n\nThe request body accepts up to 100 vulnerabilities per call. The request is validated and\nthen queued for asynchronous processing: a successful request returns `202 Accepted` with a\n`Location` header pointing to a status URL that you poll for the final result.\n\nSyncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see \"[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)\" and \"[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api).\"\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/sync-enterprise-innersource-vulnerabilities", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of vulnerabilities in OSV format to synchronize", + "items": { + "title": "OSV Vulnerability", + "description": "A vulnerability in OSV (Open Source Vulnerability) format", + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the vulnerability from the external system", + "examples": [ + "MVS-2026-001" + ] + }, + "schema_version": { + "type": "string", + "description": "The OSV schema version", + "examples": [ + "1.4.0" + ] + }, + "summary": { + "type": "string", + "description": "A short summary of the vulnerability", + "examples": [ + "Example vulnerability summary" + ] + }, + "details": { + "type": "string", + "description": "Detailed description of the vulnerability" + }, + "aliases": { + "type": "array", + "description": "IDs for the same vulnerability in other databases. Only CVE IDs are used (to populate the vulnerability's CVE identifier); other aliases are ignored.", + "items": { + "type": "string" + }, + "examples": [ + "CVE-2026-12345" + ] + }, + "severity": { + "type": "array", + "description": "Severity information for the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of severity scoring (e.g., CVSS_V3)" + }, + "score": { + "type": "string", + "description": "The severity score or vector string" + } + } + } + }, + "affected": { + "type": "array", + "description": "Packages and versions affected by the vulnerability", + "items": { + "type": "object", + "properties": { + "package": { + "type": "object", + "properties": { + "ecosystem": { + "type": "string", + "description": "The package ecosystem (e.g., npm, pip, maven)" + }, + "name": { + "type": "string", + "description": "The package name" + } + } + }, + "ranges": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "introduced": { + "type": "string", + "description": "The version that introduced the vulnerability" + }, + "fixed": { + "type": "string", + "description": "The version that fixed the vulnerability" + }, + "last_affected": { + "type": "string", + "description": "The last affected version" + }, + "limit": { + "type": "string", + "description": "The upper limit of the affected range" + } + } + } + } + } + } + } + } + } + }, + "references": { + "type": "array", + "description": "URLs for more information about the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reference. Supported values: PACKAGE, ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types are ignored." + }, + "url": { + "type": "string", + "format": "uri", + "description": "The reference URL" + } + } + } + }, + "published": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was first published" + }, + "modified": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was last modified" + }, + "withdrawn": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was withdrawn. If present, the vulnerability will be marked as withdrawn." + } + } + }, + "minItems": 1, + "maxItems": 100 + }, + "examples": { + "default": { + "value": [ + { + "id": "MVS-2026-001", + "schema_version": "1.4.0", + "summary": "Example vulnerability summary", + "aliases": [ + "GHSA-xxxx-xxxx-xxxx" + ], + "affected": [ + { + "package": { + "ecosystem": "npm", + "name": "example-package" + }, + "ranges": [ + { + "type": "SEMVER", + "events": [ + { + "introduced": "1.0.0" + }, + { + "fixed": "1.0.1" + } + ] + } + ] + } + ] + } + ] + } + } + } + } + }, + "responses": { + "202": { + "description": "Sync operation accepted for asynchronous processing. Poll the returned URL for results.", + "headers": { + "Location": { + "description": "URL to poll for sync results", + "schema": { + "type": "string", + "format": "uri" + } + }, + "Retry-After": { + "description": "Number of seconds to wait before polling", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "title": "External Vulnerability Sync Accepted", + "description": "Response when an external vulnerability sync request is accepted for asynchronous processing", + "type": "object", + "required": [ + "id", + "url", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID for polling", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "url": { + "type": "string", + "description": "URL to poll for sync results", + "format": "uri", + "examples": [ + "https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Initial job status", + "enum": [ + "queued" + ], + "examples": [ + "queued" + ] + } + } + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "queued" + } + } + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": [ + "string", + "null" + ] + }, + "documentation_url": { + "type": [ + "string", + "null" + ] + }, + "detail": { + "type": [ + "string", + "null" + ] + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": [ + "string", + "null" + ] + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Requires authentication", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": { + "get": { + "summary": "Get innersource vulnerability sync status for an enterprise", + "description": "Get the status of an asynchronous innersource vulnerability sync operation for an enterprise.\nReturns 202 with a `Retry-After` header while the sync is still processing, or 200 with\nthe full sync results once complete.\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/get-enterprise-innersource-vulnerability-sync-status", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "The unique identifier of the sync job.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Sync operation completed", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "title": "External Vulnerability Sync Result", + "description": "Result of an external vulnerability synchronization operation", + "type": "object", + "required": [ + "processed", + "created", + "updated", + "withdrawn", + "errors", + "results" + ], + "properties": { + "processed": { + "type": "integer", + "description": "Total number of vulnerabilities processed", + "examples": [ + 3 + ] + }, + "created": { + "type": "integer", + "description": "Number of new vulnerabilities created", + "examples": [ + 2 + ] + }, + "updated": { + "type": "integer", + "description": "Number of existing vulnerabilities updated", + "examples": [ + 1 + ] + }, + "withdrawn": { + "type": "integer", + "description": "Number of vulnerabilities marked as withdrawn", + "examples": [ + 0 + ] + }, + "errors": { + "type": "integer", + "description": "Number of vulnerabilities that failed to process", + "examples": [ + 0 + ] + }, + "results": { + "type": "array", + "description": "Detailed result for each processed vulnerability", + "items": { + "type": "object", + "required": [ + "external_id", + "status" + ], + "properties": { + "external_id": { + "type": "string", + "description": "The external ID of the vulnerability (corresponds to the `id` field in the request payload)", + "examples": [ + "MVS-2026-001" + ] + }, + "status": { + "type": "string", + "description": "The processing status", + "enum": [ + "created", + "updated", + "withdrawn", + "error" + ], + "examples": [ + "created" + ] + }, + "ghsa_id": { + "type": "string", + "description": "The advisory ID assigned to the vulnerability. For innersource vulnerabilities this is a GHIS ID. Present for successful operations.", + "examples": [ + "GHIS-xxxx-xxxx-xxxx" + ] + }, + "error": { + "type": "string", + "description": "Error message (present only when status is 'error')" + } + } + } + } + } + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string" + } + } + } + ] + }, + "examples": { + "success": { + "value": { + "processed": 1, + "created": 1, + "updated": 0, + "withdrawn": 0, + "errors": 0, + "results": [ + { + "external_id": "MVS-2026-001", + "status": "created", + "ghsa_id": "GHIS-xxxx-xxxx-xxxx" + } + ] + } + }, + "error": { + "value": { + "status": "error", + "error": "Internal error processing vulnerabilities" + } + } + } + } + } + }, + "202": { + "description": "Sync operation is still processing", + "headers": { + "Retry-After": { + "description": "Number of seconds to wait before polling again", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "title": "External Vulnerability Sync Status", + "description": "Status of an in-progress external vulnerability sync operation", + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Current processing status", + "enum": [ + "processing" + ], + "examples": [ + "processing" + ] + } + } + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "processing" + } + } + } + } + } + }, + "401": { + "description": "Requires authentication", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, "/enterprises/{enterprise}/installation": { "get": { "summary": "Get an enterprise installation for the authenticated app", diff --git a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml index 74bcc5d4a..25dc313f9 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml +++ b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml @@ -22739,6 +22739,407 @@ paths: enabledForGitHubApps: true category: enterprise-admin subcategory: enterprise-roles + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": + post: + summary: Sync innersource vulnerabilities for an enterprise + description: |- + Synchronize innersource vulnerability data with the Advisory Database for an enterprise. + This endpoint receives vulnerability data in OSV format and creates, updates, or withdraws + innersource vulnerabilities accordingly. Dependabot alerting is triggered for created and + updated vulnerabilities. + + The request body accepts up to 100 vulnerabilities per call. The request is validated and + then queued for asynchronous processing: a successful request returns `202 Accepted` with a + `Location` header pointing to a status URL that you poll for the final result. + + Syncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api)." + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/sync-enterprise-innersource-vulnerabilities + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise + parameters: + - *39 + requestBody: + required: true + content: + application/json: + schema: + type: array + description: Array of vulnerabilities in OSV format to synchronize + items: + title: OSV Vulnerability + description: A vulnerability in OSV (Open Source Vulnerability) format + type: object + required: + - id + properties: + id: + type: string + description: Unique identifier for the vulnerability from the + external system + examples: + - MVS-2026-001 + schema_version: + type: string + description: The OSV schema version + examples: + - 1.4.0 + summary: + type: string + description: A short summary of the vulnerability + examples: + - Example vulnerability summary + details: + type: string + description: Detailed description of the vulnerability + aliases: + type: array + description: IDs for the same vulnerability in other databases. + Only CVE IDs are used (to populate the vulnerability's CVE identifier); + other aliases are ignored. + items: + type: string + examples: + - CVE-2026-12345 + severity: + type: array + description: Severity information for the vulnerability + items: + type: object + properties: + type: + type: string + description: The type of severity scoring (e.g., CVSS_V3) + score: + type: string + description: The severity score or vector string + affected: + type: array + description: Packages and versions affected by the vulnerability + items: + type: object + properties: + package: + type: object + properties: + ecosystem: + type: string + description: The package ecosystem (e.g., npm, pip, + maven) + name: + type: string + description: The package name + ranges: + type: array + items: + type: object + properties: + type: + type: string + events: + type: array + items: + type: object + properties: + introduced: + type: string + description: The version that introduced the + vulnerability + fixed: + type: string + description: The version that fixed the vulnerability + last_affected: + type: string + description: The last affected version + limit: + type: string + description: The upper limit of the affected + range + references: + type: array + description: URLs for more information about the vulnerability + items: + type: object + properties: + type: + type: string + description: 'The type of reference. Supported values: PACKAGE, + ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References + with other types are ignored.' + url: + type: string + format: uri + description: The reference URL + published: + type: string + format: date-time + description: When the vulnerability was first published + modified: + type: string + format: date-time + description: When the vulnerability was last modified + withdrawn: + type: string + format: date-time + description: When the vulnerability was withdrawn. If present, + the vulnerability will be marked as withdrawn. + minItems: 1 + maxItems: 100 + examples: + default: + value: + - id: MVS-2026-001 + schema_version: 1.4.0 + summary: Example vulnerability summary + aliases: + - GHSA-xxxx-xxxx-xxxx + affected: + - package: + ecosystem: npm + name: example-package + ranges: + - type: SEMVER + events: + - introduced: 1.0.0 + - fixed: 1.0.1 + responses: + '202': + description: Sync operation accepted for asynchronous processing. Poll the + returned URL for results. + headers: + Location: + description: URL to poll for sync results + schema: + type: string + format: uri + Retry-After: + description: Number of seconds to wait before polling + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + title: External Vulnerability Sync Accepted + description: Response when an external vulnerability sync request + is accepted for asynchronous processing + type: object + required: + - id + - url + - status + properties: + id: + type: string + description: Job status ID for polling + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: + type: string + description: URL to poll for sync results + format: uri + examples: + - https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Initial job status + enum: + - queued + examples: + - queued + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: queued + '400': *14 + '401': *23 + '403': *27 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": + get: + summary: Get innersource vulnerability sync status for an enterprise + description: |- + Get the status of an asynchronous innersource vulnerability sync operation for an enterprise. + Returns 202 with a `Retry-After` header while the sync is still processing, or 200 with + the full sync results once complete. + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/get-enterprise-innersource-vulnerability-sync-status + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise + parameters: + - *39 + - name: job_id + in: path + required: true + description: The unique identifier of the sync job. + schema: + type: string + responses: + '200': + description: Sync operation completed + content: + application/json: + schema: + oneOf: + - title: External Vulnerability Sync Result + description: Result of an external vulnerability synchronization + operation + type: object + required: + - processed + - created + - updated + - withdrawn + - errors + - results + properties: + processed: + type: integer + description: Total number of vulnerabilities processed + examples: + - 3 + created: + type: integer + description: Number of new vulnerabilities created + examples: + - 2 + updated: + type: integer + description: Number of existing vulnerabilities updated + examples: + - 1 + withdrawn: + type: integer + description: Number of vulnerabilities marked as withdrawn + examples: + - 0 + errors: + type: integer + description: Number of vulnerabilities that failed to process + examples: + - 0 + results: + type: array + description: Detailed result for each processed vulnerability + items: + type: object + required: + - external_id + - status + properties: + external_id: + type: string + description: The external ID of the vulnerability (corresponds + to the `id` field in the request payload) + examples: + - MVS-2026-001 + status: + type: string + description: The processing status + enum: + - created + - updated + - withdrawn + - error + examples: + - created + ghsa_id: + type: string + description: The advisory ID assigned to the vulnerability. + For innersource vulnerabilities this is a GHIS ID. Present + for successful operations. + examples: + - GHIS-xxxx-xxxx-xxxx + error: + type: string + description: Error message (present only when status is + 'error') + - type: object + properties: + status: + type: string + enum: + - error + error: + type: string + examples: + success: + value: + processed: 1 + created: 1 + updated: 0 + withdrawn: 0 + errors: 0 + results: + - external_id: MVS-2026-001 + status: created + ghsa_id: GHIS-xxxx-xxxx-xxxx + error: + value: + status: error + error: Internal error processing vulnerabilities + '202': + description: Sync operation is still processing + headers: + Retry-After: + description: Number of seconds to wait before polling again + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + title: External Vulnerability Sync Status + description: Status of an in-progress external vulnerability sync + operation + type: object + required: + - id + - status + properties: + id: + type: string + description: Job status ID + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Current processing status + enum: + - processing + examples: + - processing + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: processing + '401': *23 + '403': *27 + '404': *6 + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories "/enterprises/{enterprise}/installation": get: summary: Get an enterprise installation for the authenticated app diff --git a/descriptions-next/ghec/dereferenced/ghec.deref.json b/descriptions-next/ghec/dereferenced/ghec.deref.json index d83addfea..25d259ce8 100644 --- a/descriptions-next/ghec/dereferenced/ghec.deref.json +++ b/descriptions-next/ghec/dereferenced/ghec.deref.json @@ -59970,6 +59970,848 @@ } } }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": { + "post": { + "summary": "Sync innersource vulnerabilities for an enterprise", + "description": "Synchronize innersource vulnerability data with the Advisory Database for an enterprise.\nThis endpoint receives vulnerability data in OSV format and creates, updates, or withdraws\ninnersource vulnerabilities accordingly. Dependabot alerting is triggered for created and\nupdated vulnerabilities.\n\nThe request body accepts up to 100 vulnerabilities per call. The request is validated and\nthen queued for asynchronous processing: a successful request returns `202 Accepted` with a\n`Location` header pointing to a status URL that you poll for the final result.\n\nSyncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see \"[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)\" and \"[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api).\"\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/sync-enterprise-innersource-vulnerabilities", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of vulnerabilities in OSV format to synchronize", + "items": { + "title": "OSV Vulnerability", + "description": "A vulnerability in OSV (Open Source Vulnerability) format", + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the vulnerability from the external system", + "examples": [ + "MVS-2026-001" + ] + }, + "schema_version": { + "type": "string", + "description": "The OSV schema version", + "examples": [ + "1.4.0" + ] + }, + "summary": { + "type": "string", + "description": "A short summary of the vulnerability", + "examples": [ + "Example vulnerability summary" + ] + }, + "details": { + "type": "string", + "description": "Detailed description of the vulnerability" + }, + "aliases": { + "type": "array", + "description": "IDs for the same vulnerability in other databases. Only CVE IDs are used (to populate the vulnerability's CVE identifier); other aliases are ignored.", + "items": { + "type": "string" + }, + "examples": [ + "CVE-2026-12345" + ] + }, + "severity": { + "type": "array", + "description": "Severity information for the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of severity scoring (e.g., CVSS_V3)" + }, + "score": { + "type": "string", + "description": "The severity score or vector string" + } + } + } + }, + "affected": { + "type": "array", + "description": "Packages and versions affected by the vulnerability", + "items": { + "type": "object", + "properties": { + "package": { + "type": "object", + "properties": { + "ecosystem": { + "type": "string", + "description": "The package ecosystem (e.g., npm, pip, maven)" + }, + "name": { + "type": "string", + "description": "The package name" + } + } + }, + "ranges": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "introduced": { + "type": "string", + "description": "The version that introduced the vulnerability" + }, + "fixed": { + "type": "string", + "description": "The version that fixed the vulnerability" + }, + "last_affected": { + "type": "string", + "description": "The last affected version" + }, + "limit": { + "type": "string", + "description": "The upper limit of the affected range" + } + } + } + } + } + } + } + } + } + }, + "references": { + "type": "array", + "description": "URLs for more information about the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reference. Supported values: PACKAGE, ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types are ignored." + }, + "url": { + "type": "string", + "format": "uri", + "description": "The reference URL" + } + } + } + }, + "published": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was first published" + }, + "modified": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was last modified" + }, + "withdrawn": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was withdrawn. If present, the vulnerability will be marked as withdrawn." + } + } + }, + "minItems": 1, + "maxItems": 100 + }, + "examples": { + "default": { + "value": [ + { + "id": "MVS-2026-001", + "schema_version": "1.4.0", + "summary": "Example vulnerability summary", + "aliases": [ + "GHSA-xxxx-xxxx-xxxx" + ], + "affected": [ + { + "package": { + "ecosystem": "npm", + "name": "example-package" + }, + "ranges": [ + { + "type": "SEMVER", + "events": [ + { + "introduced": "1.0.0" + }, + { + "fixed": "1.0.1" + } + ] + } + ] + } + ] + } + ] + } + } + } + } + }, + "responses": { + "202": { + "description": "Sync operation accepted for asynchronous processing. Poll the returned URL for results.", + "headers": { + "Location": { + "description": "URL to poll for sync results", + "schema": { + "type": "string", + "format": "uri" + } + }, + "Retry-After": { + "description": "Number of seconds to wait before polling", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "title": "External Vulnerability Sync Accepted", + "description": "Response when an external vulnerability sync request is accepted for asynchronous processing", + "type": "object", + "required": [ + "id", + "url", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID for polling", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "url": { + "type": "string", + "description": "URL to poll for sync results", + "format": "uri", + "examples": [ + "https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Initial job status", + "enum": [ + "queued" + ], + "examples": [ + "queued" + ] + } + } + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "queued" + } + } + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": [ + "string", + "null" + ] + }, + "documentation_url": { + "type": [ + "string", + "null" + ] + }, + "detail": { + "type": [ + "string", + "null" + ] + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": [ + "string", + "null" + ] + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Requires authentication", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": { + "get": { + "summary": "Get innersource vulnerability sync status for an enterprise", + "description": "Get the status of an asynchronous innersource vulnerability sync operation for an enterprise.\nReturns 202 with a `Retry-After` header while the sync is still processing, or 200 with\nthe full sync results once complete.\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/get-enterprise-innersource-vulnerability-sync-status", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "The unique identifier of the sync job.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Sync operation completed", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "title": "External Vulnerability Sync Result", + "description": "Result of an external vulnerability synchronization operation", + "type": "object", + "required": [ + "processed", + "created", + "updated", + "withdrawn", + "errors", + "results" + ], + "properties": { + "processed": { + "type": "integer", + "description": "Total number of vulnerabilities processed", + "examples": [ + 3 + ] + }, + "created": { + "type": "integer", + "description": "Number of new vulnerabilities created", + "examples": [ + 2 + ] + }, + "updated": { + "type": "integer", + "description": "Number of existing vulnerabilities updated", + "examples": [ + 1 + ] + }, + "withdrawn": { + "type": "integer", + "description": "Number of vulnerabilities marked as withdrawn", + "examples": [ + 0 + ] + }, + "errors": { + "type": "integer", + "description": "Number of vulnerabilities that failed to process", + "examples": [ + 0 + ] + }, + "results": { + "type": "array", + "description": "Detailed result for each processed vulnerability", + "items": { + "type": "object", + "required": [ + "external_id", + "status" + ], + "properties": { + "external_id": { + "type": "string", + "description": "The external ID of the vulnerability (corresponds to the `id` field in the request payload)", + "examples": [ + "MVS-2026-001" + ] + }, + "status": { + "type": "string", + "description": "The processing status", + "enum": [ + "created", + "updated", + "withdrawn", + "error" + ], + "examples": [ + "created" + ] + }, + "ghsa_id": { + "type": "string", + "description": "The advisory ID assigned to the vulnerability. For innersource vulnerabilities this is a GHIS ID. Present for successful operations.", + "examples": [ + "GHIS-xxxx-xxxx-xxxx" + ] + }, + "error": { + "type": "string", + "description": "Error message (present only when status is 'error')" + } + } + } + } + } + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string" + } + } + } + ] + }, + "examples": { + "success": { + "value": { + "processed": 1, + "created": 1, + "updated": 0, + "withdrawn": 0, + "errors": 0, + "results": [ + { + "external_id": "MVS-2026-001", + "status": "created", + "ghsa_id": "GHIS-xxxx-xxxx-xxxx" + } + ] + } + }, + "error": { + "value": { + "status": "error", + "error": "Internal error processing vulnerabilities" + } + } + } + } + } + }, + "202": { + "description": "Sync operation is still processing", + "headers": { + "Retry-After": { + "description": "Number of seconds to wait before polling again", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "title": "External Vulnerability Sync Status", + "description": "Status of an in-progress external vulnerability sync operation", + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Current processing status", + "enum": [ + "processing" + ], + "examples": [ + "processing" + ] + } + } + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "processing" + } + } + } + } + } + }, + "401": { + "description": "Requires authentication", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, "/enterprises/{enterprise}/installation": { "get": { "summary": "Get an enterprise installation for the authenticated app", diff --git a/descriptions-next/ghec/dereferenced/ghec.deref.yaml b/descriptions-next/ghec/dereferenced/ghec.deref.yaml index f5e2deb26..1edd6d07e 100644 --- a/descriptions-next/ghec/dereferenced/ghec.deref.yaml +++ b/descriptions-next/ghec/dereferenced/ghec.deref.yaml @@ -22987,6 +22987,407 @@ paths: enabledForGitHubApps: true category: enterprise-admin subcategory: enterprise-roles + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": + post: + summary: Sync innersource vulnerabilities for an enterprise + description: |- + Synchronize innersource vulnerability data with the Advisory Database for an enterprise. + This endpoint receives vulnerability data in OSV format and creates, updates, or withdraws + innersource vulnerabilities accordingly. Dependabot alerting is triggered for created and + updated vulnerabilities. + + The request body accepts up to 100 vulnerabilities per call. The request is validated and + then queued for asynchronous processing: a successful request returns `202 Accepted` with a + `Location` header pointing to a status URL that you poll for the final result. + + Syncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api)." + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/sync-enterprise-innersource-vulnerabilities + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise + parameters: + - *39 + requestBody: + required: true + content: + application/json: + schema: + type: array + description: Array of vulnerabilities in OSV format to synchronize + items: + title: OSV Vulnerability + description: A vulnerability in OSV (Open Source Vulnerability) format + type: object + required: + - id + properties: + id: + type: string + description: Unique identifier for the vulnerability from the + external system + examples: + - MVS-2026-001 + schema_version: + type: string + description: The OSV schema version + examples: + - 1.4.0 + summary: + type: string + description: A short summary of the vulnerability + examples: + - Example vulnerability summary + details: + type: string + description: Detailed description of the vulnerability + aliases: + type: array + description: IDs for the same vulnerability in other databases. + Only CVE IDs are used (to populate the vulnerability's CVE identifier); + other aliases are ignored. + items: + type: string + examples: + - CVE-2026-12345 + severity: + type: array + description: Severity information for the vulnerability + items: + type: object + properties: + type: + type: string + description: The type of severity scoring (e.g., CVSS_V3) + score: + type: string + description: The severity score or vector string + affected: + type: array + description: Packages and versions affected by the vulnerability + items: + type: object + properties: + package: + type: object + properties: + ecosystem: + type: string + description: The package ecosystem (e.g., npm, pip, + maven) + name: + type: string + description: The package name + ranges: + type: array + items: + type: object + properties: + type: + type: string + events: + type: array + items: + type: object + properties: + introduced: + type: string + description: The version that introduced the + vulnerability + fixed: + type: string + description: The version that fixed the vulnerability + last_affected: + type: string + description: The last affected version + limit: + type: string + description: The upper limit of the affected + range + references: + type: array + description: URLs for more information about the vulnerability + items: + type: object + properties: + type: + type: string + description: 'The type of reference. Supported values: PACKAGE, + ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References + with other types are ignored.' + url: + type: string + format: uri + description: The reference URL + published: + type: string + format: date-time + description: When the vulnerability was first published + modified: + type: string + format: date-time + description: When the vulnerability was last modified + withdrawn: + type: string + format: date-time + description: When the vulnerability was withdrawn. If present, + the vulnerability will be marked as withdrawn. + minItems: 1 + maxItems: 100 + examples: + default: + value: + - id: MVS-2026-001 + schema_version: 1.4.0 + summary: Example vulnerability summary + aliases: + - GHSA-xxxx-xxxx-xxxx + affected: + - package: + ecosystem: npm + name: example-package + ranges: + - type: SEMVER + events: + - introduced: 1.0.0 + - fixed: 1.0.1 + responses: + '202': + description: Sync operation accepted for asynchronous processing. Poll the + returned URL for results. + headers: + Location: + description: URL to poll for sync results + schema: + type: string + format: uri + Retry-After: + description: Number of seconds to wait before polling + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + title: External Vulnerability Sync Accepted + description: Response when an external vulnerability sync request + is accepted for asynchronous processing + type: object + required: + - id + - url + - status + properties: + id: + type: string + description: Job status ID for polling + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: + type: string + description: URL to poll for sync results + format: uri + examples: + - https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Initial job status + enum: + - queued + examples: + - queued + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: queued + '400': *14 + '401': *23 + '403': *27 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": + get: + summary: Get innersource vulnerability sync status for an enterprise + description: |- + Get the status of an asynchronous innersource vulnerability sync operation for an enterprise. + Returns 202 with a `Retry-After` header while the sync is still processing, or 200 with + the full sync results once complete. + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/get-enterprise-innersource-vulnerability-sync-status + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise + parameters: + - *39 + - name: job_id + in: path + required: true + description: The unique identifier of the sync job. + schema: + type: string + responses: + '200': + description: Sync operation completed + content: + application/json: + schema: + oneOf: + - title: External Vulnerability Sync Result + description: Result of an external vulnerability synchronization + operation + type: object + required: + - processed + - created + - updated + - withdrawn + - errors + - results + properties: + processed: + type: integer + description: Total number of vulnerabilities processed + examples: + - 3 + created: + type: integer + description: Number of new vulnerabilities created + examples: + - 2 + updated: + type: integer + description: Number of existing vulnerabilities updated + examples: + - 1 + withdrawn: + type: integer + description: Number of vulnerabilities marked as withdrawn + examples: + - 0 + errors: + type: integer + description: Number of vulnerabilities that failed to process + examples: + - 0 + results: + type: array + description: Detailed result for each processed vulnerability + items: + type: object + required: + - external_id + - status + properties: + external_id: + type: string + description: The external ID of the vulnerability (corresponds + to the `id` field in the request payload) + examples: + - MVS-2026-001 + status: + type: string + description: The processing status + enum: + - created + - updated + - withdrawn + - error + examples: + - created + ghsa_id: + type: string + description: The advisory ID assigned to the vulnerability. + For innersource vulnerabilities this is a GHIS ID. Present + for successful operations. + examples: + - GHIS-xxxx-xxxx-xxxx + error: + type: string + description: Error message (present only when status is + 'error') + - type: object + properties: + status: + type: string + enum: + - error + error: + type: string + examples: + success: + value: + processed: 1 + created: 1 + updated: 0 + withdrawn: 0 + errors: 0 + results: + - external_id: MVS-2026-001 + status: created + ghsa_id: GHIS-xxxx-xxxx-xxxx + error: + value: + status: error + error: Internal error processing vulnerabilities + '202': + description: Sync operation is still processing + headers: + Retry-After: + description: Number of seconds to wait before polling again + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + title: External Vulnerability Sync Status + description: Status of an in-progress external vulnerability sync + operation + type: object + required: + - id + - status + properties: + id: + type: string + description: Job status ID + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Current processing status + enum: + - processing + examples: + - processing + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: processing + '401': *23 + '403': *27 + '404': *6 + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories "/enterprises/{enterprise}/installation": get: summary: Get an enterprise installation for the authenticated app diff --git a/descriptions-next/ghec/ghec.2022-11-28.json b/descriptions-next/ghec/ghec.2022-11-28.json index 870bce8a4..fab7908c6 100644 --- a/descriptions-next/ghec/ghec.2022-11-28.json +++ b/descriptions-next/ghec/ghec.2022-11-28.json @@ -14994,6 +14994,262 @@ } } }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": { + "post": { + "summary": "Sync innersource vulnerabilities for an enterprise", + "description": "Synchronize innersource vulnerability data with the Advisory Database for an enterprise.\nThis endpoint receives vulnerability data in OSV format and creates, updates, or withdraws\ninnersource vulnerabilities accordingly. Dependabot alerting is triggered for created and\nupdated vulnerabilities.\n\nThe request body accepts up to 100 vulnerabilities per call. The request is validated and\nthen queued for asynchronous processing: a successful request returns `202 Accepted` with a\n`Location` header pointing to a status URL that you poll for the final result.\n\nSyncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see \"[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)\" and \"[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api).\"\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/sync-enterprise-innersource-vulnerabilities", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise" + }, + "parameters": [ + { + "$ref": "#/components/parameters/enterprise" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of vulnerabilities in OSV format to synchronize", + "items": { + "$ref": "#/components/schemas/osv-vulnerability" + }, + "minItems": 1, + "maxItems": 100 + }, + "examples": { + "default": { + "value": [ + { + "id": "MVS-2026-001", + "schema_version": "1.4.0", + "summary": "Example vulnerability summary", + "aliases": [ + "GHSA-xxxx-xxxx-xxxx" + ], + "affected": [ + { + "package": { + "ecosystem": "npm", + "name": "example-package" + }, + "ranges": [ + { + "type": "SEMVER", + "events": [ + { + "introduced": "1.0.0" + }, + { + "fixed": "1.0.1" + } + ] + } + ] + } + ] + } + ] + } + } + } + } + }, + "responses": { + "202": { + "description": "Sync operation accepted for asynchronous processing. Poll the returned URL for results.", + "headers": { + "Location": { + "description": "URL to poll for sync results", + "schema": { + "type": "string", + "format": "uri" + } + }, + "Retry-After": { + "description": "Number of seconds to wait before polling", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/external-vulnerability-sync-accepted" + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "queued" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/requires_authentication" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": { + "get": { + "summary": "Get innersource vulnerability sync status for an enterprise", + "description": "Get the status of an asynchronous innersource vulnerability sync operation for an enterprise.\nReturns 202 with a `Retry-After` header while the sync is still processing, or 200 with\nthe full sync results once complete.\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/get-enterprise-innersource-vulnerability-sync-status", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise" + }, + "parameters": [ + { + "$ref": "#/components/parameters/enterprise" + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "The unique identifier of the sync job.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Sync operation completed", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/external-vulnerability-sync-result" + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string" + } + } + } + ] + }, + "examples": { + "success": { + "value": { + "processed": 1, + "created": 1, + "updated": 0, + "withdrawn": 0, + "errors": 0, + "results": [ + { + "external_id": "MVS-2026-001", + "status": "created", + "ghsa_id": "GHIS-xxxx-xxxx-xxxx" + } + ] + } + }, + "error": { + "value": { + "status": "error", + "error": "Internal error processing vulnerabilities" + } + } + } + } + } + }, + "202": { + "description": "Sync operation is still processing", + "headers": { + "Retry-After": { + "description": "Number of seconds to wait before polling again", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/external-vulnerability-sync-status" + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "processing" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/requires_authentication" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, "/enterprises/{enterprise}/installation": { "get": { "summary": "Get an enterprise installation for the authenticated app", @@ -140520,6 +140776,317 @@ } ] }, + "osv-vulnerability": { + "title": "OSV Vulnerability", + "description": "A vulnerability in OSV (Open Source Vulnerability) format", + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the vulnerability from the external system", + "examples": [ + "MVS-2026-001" + ] + }, + "schema_version": { + "type": "string", + "description": "The OSV schema version", + "examples": [ + "1.4.0" + ] + }, + "summary": { + "type": "string", + "description": "A short summary of the vulnerability", + "examples": [ + "Example vulnerability summary" + ] + }, + "details": { + "type": "string", + "description": "Detailed description of the vulnerability" + }, + "aliases": { + "type": "array", + "description": "IDs for the same vulnerability in other databases. Only CVE IDs are used (to populate the vulnerability's CVE identifier); other aliases are ignored.", + "items": { + "type": "string" + }, + "examples": [ + "CVE-2026-12345" + ] + }, + "severity": { + "type": "array", + "description": "Severity information for the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of severity scoring (e.g., CVSS_V3)" + }, + "score": { + "type": "string", + "description": "The severity score or vector string" + } + } + } + }, + "affected": { + "type": "array", + "description": "Packages and versions affected by the vulnerability", + "items": { + "type": "object", + "properties": { + "package": { + "type": "object", + "properties": { + "ecosystem": { + "type": "string", + "description": "The package ecosystem (e.g., npm, pip, maven)" + }, + "name": { + "type": "string", + "description": "The package name" + } + } + }, + "ranges": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "introduced": { + "type": "string", + "description": "The version that introduced the vulnerability" + }, + "fixed": { + "type": "string", + "description": "The version that fixed the vulnerability" + }, + "last_affected": { + "type": "string", + "description": "The last affected version" + }, + "limit": { + "type": "string", + "description": "The upper limit of the affected range" + } + } + } + } + } + } + } + } + } + }, + "references": { + "type": "array", + "description": "URLs for more information about the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reference. Supported values: PACKAGE, ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types are ignored." + }, + "url": { + "type": "string", + "format": "uri", + "description": "The reference URL" + } + } + } + }, + "published": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was first published" + }, + "modified": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was last modified" + }, + "withdrawn": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was withdrawn. If present, the vulnerability will be marked as withdrawn." + } + } + }, + "external-vulnerability-sync-accepted": { + "title": "External Vulnerability Sync Accepted", + "description": "Response when an external vulnerability sync request is accepted for asynchronous processing", + "type": "object", + "required": [ + "id", + "url", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID for polling", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "url": { + "type": "string", + "description": "URL to poll for sync results", + "format": "uri", + "examples": [ + "https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Initial job status", + "enum": [ + "queued" + ], + "examples": [ + "queued" + ] + } + } + }, + "external-vulnerability-sync-result": { + "title": "External Vulnerability Sync Result", + "description": "Result of an external vulnerability synchronization operation", + "type": "object", + "required": [ + "processed", + "created", + "updated", + "withdrawn", + "errors", + "results" + ], + "properties": { + "processed": { + "type": "integer", + "description": "Total number of vulnerabilities processed", + "examples": [ + 3 + ] + }, + "created": { + "type": "integer", + "description": "Number of new vulnerabilities created", + "examples": [ + 2 + ] + }, + "updated": { + "type": "integer", + "description": "Number of existing vulnerabilities updated", + "examples": [ + 1 + ] + }, + "withdrawn": { + "type": "integer", + "description": "Number of vulnerabilities marked as withdrawn", + "examples": [ + 0 + ] + }, + "errors": { + "type": "integer", + "description": "Number of vulnerabilities that failed to process", + "examples": [ + 0 + ] + }, + "results": { + "type": "array", + "description": "Detailed result for each processed vulnerability", + "items": { + "type": "object", + "required": [ + "external_id", + "status" + ], + "properties": { + "external_id": { + "type": "string", + "description": "The external ID of the vulnerability (corresponds to the `id` field in the request payload)", + "examples": [ + "MVS-2026-001" + ] + }, + "status": { + "type": "string", + "description": "The processing status", + "enum": [ + "created", + "updated", + "withdrawn", + "error" + ], + "examples": [ + "created" + ] + }, + "ghsa_id": { + "type": "string", + "description": "The advisory ID assigned to the vulnerability. For innersource vulnerabilities this is a GHIS ID. Present for successful operations.", + "examples": [ + "GHIS-xxxx-xxxx-xxxx" + ] + }, + "error": { + "type": "string", + "description": "Error message (present only when status is 'error')" + } + } + } + } + } + }, + "external-vulnerability-sync-status": { + "title": "External Vulnerability Sync Status", + "description": "Status of an in-progress external vulnerability sync operation", + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Current processing status", + "enum": [ + "processing" + ], + "examples": [ + "processing" + ] + } + } + }, "get-license-sync-status": { "title": "License Sync Status", "description": "Information about the status of a license sync job for an enterprise.", diff --git a/descriptions-next/ghec/ghec.2022-11-28.yaml b/descriptions-next/ghec/ghec.2022-11-28.yaml index a9672398c..00a45f625 100644 --- a/descriptions-next/ghec/ghec.2022-11-28.yaml +++ b/descriptions-next/ghec/ghec.2022-11-28.yaml @@ -11130,6 +11130,183 @@ paths: enabledForGitHubApps: true category: enterprise-admin subcategory: enterprise-roles + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": + post: + summary: Sync innersource vulnerabilities for an enterprise + description: |- + Synchronize innersource vulnerability data with the Advisory Database for an enterprise. + This endpoint receives vulnerability data in OSV format and creates, updates, or withdraws + innersource vulnerabilities accordingly. Dependabot alerting is triggered for created and + updated vulnerabilities. + + The request body accepts up to 100 vulnerabilities per call. The request is validated and + then queued for asynchronous processing: a successful request returns `202 Accepted` with a + `Location` header pointing to a status URL that you poll for the final result. + + Syncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api)." + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/sync-enterprise-innersource-vulnerabilities + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise + parameters: + - "$ref": "#/components/parameters/enterprise" + requestBody: + required: true + content: + application/json: + schema: + type: array + description: Array of vulnerabilities in OSV format to synchronize + items: + "$ref": "#/components/schemas/osv-vulnerability" + minItems: 1 + maxItems: 100 + examples: + default: + value: + - id: MVS-2026-001 + schema_version: 1.4.0 + summary: Example vulnerability summary + aliases: + - GHSA-xxxx-xxxx-xxxx + affected: + - package: + ecosystem: npm + name: example-package + ranges: + - type: SEMVER + events: + - introduced: 1.0.0 + - fixed: 1.0.1 + responses: + '202': + description: Sync operation accepted for asynchronous processing. Poll the + returned URL for results. + headers: + Location: + description: URL to poll for sync results + schema: + type: string + format: uri + Retry-After: + description: Number of seconds to wait before polling + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + "$ref": "#/components/schemas/external-vulnerability-sync-accepted" + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: queued + '400': + "$ref": "#/components/responses/bad_request" + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": + get: + summary: Get innersource vulnerability sync status for an enterprise + description: |- + Get the status of an asynchronous innersource vulnerability sync operation for an enterprise. + Returns 202 with a `Retry-After` header while the sync is still processing, or 200 with + the full sync results once complete. + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/get-enterprise-innersource-vulnerability-sync-status + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise + parameters: + - "$ref": "#/components/parameters/enterprise" + - name: job_id + in: path + required: true + description: The unique identifier of the sync job. + schema: + type: string + responses: + '200': + description: Sync operation completed + content: + application/json: + schema: + oneOf: + - "$ref": "#/components/schemas/external-vulnerability-sync-result" + - type: object + properties: + status: + type: string + enum: + - error + error: + type: string + examples: + success: + value: + processed: 1 + created: 1 + updated: 0 + withdrawn: 0 + errors: 0 + results: + - external_id: MVS-2026-001 + status: created + ghsa_id: GHIS-xxxx-xxxx-xxxx + error: + value: + status: error + error: Internal error processing vulnerabilities + '202': + description: Sync operation is still processing + headers: + Retry-After: + description: Number of seconds to wait before polling again + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + "$ref": "#/components/schemas/external-vulnerability-sync-status" + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: processing + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories "/enterprises/{enterprise}/installation": get: summary: Get an enterprise installation for the authenticated app @@ -102204,6 +102381,238 @@ components: type: array items: "$ref": "#/components/schemas/enterprise-team" + osv-vulnerability: + title: OSV Vulnerability + description: A vulnerability in OSV (Open Source Vulnerability) format + type: object + required: + - id + properties: + id: + type: string + description: Unique identifier for the vulnerability from the external system + examples: + - MVS-2026-001 + schema_version: + type: string + description: The OSV schema version + examples: + - 1.4.0 + summary: + type: string + description: A short summary of the vulnerability + examples: + - Example vulnerability summary + details: + type: string + description: Detailed description of the vulnerability + aliases: + type: array + description: IDs for the same vulnerability in other databases. Only CVE + IDs are used (to populate the vulnerability's CVE identifier); other aliases + are ignored. + items: + type: string + examples: + - CVE-2026-12345 + severity: + type: array + description: Severity information for the vulnerability + items: + type: object + properties: + type: + type: string + description: The type of severity scoring (e.g., CVSS_V3) + score: + type: string + description: The severity score or vector string + affected: + type: array + description: Packages and versions affected by the vulnerability + items: + type: object + properties: + package: + type: object + properties: + ecosystem: + type: string + description: The package ecosystem (e.g., npm, pip, maven) + name: + type: string + description: The package name + ranges: + type: array + items: + type: object + properties: + type: + type: string + events: + type: array + items: + type: object + properties: + introduced: + type: string + description: The version that introduced the vulnerability + fixed: + type: string + description: The version that fixed the vulnerability + last_affected: + type: string + description: The last affected version + limit: + type: string + description: The upper limit of the affected range + references: + type: array + description: URLs for more information about the vulnerability + items: + type: object + properties: + type: + type: string + description: 'The type of reference. Supported values: PACKAGE, ADVISORY, + WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types + are ignored.' + url: + type: string + format: uri + description: The reference URL + published: + type: string + format: date-time + description: When the vulnerability was first published + modified: + type: string + format: date-time + description: When the vulnerability was last modified + withdrawn: + type: string + format: date-time + description: When the vulnerability was withdrawn. If present, the vulnerability + will be marked as withdrawn. + external-vulnerability-sync-accepted: + title: External Vulnerability Sync Accepted + description: Response when an external vulnerability sync request is accepted + for asynchronous processing + type: object + required: + - id + - url + - status + properties: + id: + type: string + description: Job status ID for polling + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: + type: string + description: URL to poll for sync results + format: uri + examples: + - https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Initial job status + enum: + - queued + examples: + - queued + external-vulnerability-sync-result: + title: External Vulnerability Sync Result + description: Result of an external vulnerability synchronization operation + type: object + required: + - processed + - created + - updated + - withdrawn + - errors + - results + properties: + processed: + type: integer + description: Total number of vulnerabilities processed + examples: + - 3 + created: + type: integer + description: Number of new vulnerabilities created + examples: + - 2 + updated: + type: integer + description: Number of existing vulnerabilities updated + examples: + - 1 + withdrawn: + type: integer + description: Number of vulnerabilities marked as withdrawn + examples: + - 0 + errors: + type: integer + description: Number of vulnerabilities that failed to process + examples: + - 0 + results: + type: array + description: Detailed result for each processed vulnerability + items: + type: object + required: + - external_id + - status + properties: + external_id: + type: string + description: The external ID of the vulnerability (corresponds to + the `id` field in the request payload) + examples: + - MVS-2026-001 + status: + type: string + description: The processing status + enum: + - created + - updated + - withdrawn + - error + examples: + - created + ghsa_id: + type: string + description: The advisory ID assigned to the vulnerability. For innersource + vulnerabilities this is a GHIS ID. Present for successful operations. + examples: + - GHIS-xxxx-xxxx-xxxx + error: + type: string + description: Error message (present only when status is 'error') + external-vulnerability-sync-status: + title: External Vulnerability Sync Status + description: Status of an in-progress external vulnerability sync operation + type: object + required: + - id + - status + properties: + id: + type: string + description: Job status ID + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Current processing status + enum: + - processing + examples: + - processing get-license-sync-status: title: License Sync Status description: Information about the status of a license sync job for an enterprise. diff --git a/descriptions-next/ghec/ghec.2026-03-10.json b/descriptions-next/ghec/ghec.2026-03-10.json index 17ab35888..956010b19 100644 --- a/descriptions-next/ghec/ghec.2026-03-10.json +++ b/descriptions-next/ghec/ghec.2026-03-10.json @@ -14994,6 +14994,262 @@ } } }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": { + "post": { + "summary": "Sync innersource vulnerabilities for an enterprise", + "description": "Synchronize innersource vulnerability data with the Advisory Database for an enterprise.\nThis endpoint receives vulnerability data in OSV format and creates, updates, or withdraws\ninnersource vulnerabilities accordingly. Dependabot alerting is triggered for created and\nupdated vulnerabilities.\n\nThe request body accepts up to 100 vulnerabilities per call. The request is validated and\nthen queued for asynchronous processing: a successful request returns `202 Accepted` with a\n`Location` header pointing to a status URL that you poll for the final result.\n\nSyncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see \"[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)\" and \"[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api).\"\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/sync-enterprise-innersource-vulnerabilities", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise" + }, + "parameters": [ + { + "$ref": "#/components/parameters/enterprise" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of vulnerabilities in OSV format to synchronize", + "items": { + "$ref": "#/components/schemas/osv-vulnerability" + }, + "minItems": 1, + "maxItems": 100 + }, + "examples": { + "default": { + "value": [ + { + "id": "MVS-2026-001", + "schema_version": "1.4.0", + "summary": "Example vulnerability summary", + "aliases": [ + "GHSA-xxxx-xxxx-xxxx" + ], + "affected": [ + { + "package": { + "ecosystem": "npm", + "name": "example-package" + }, + "ranges": [ + { + "type": "SEMVER", + "events": [ + { + "introduced": "1.0.0" + }, + { + "fixed": "1.0.1" + } + ] + } + ] + } + ] + } + ] + } + } + } + } + }, + "responses": { + "202": { + "description": "Sync operation accepted for asynchronous processing. Poll the returned URL for results.", + "headers": { + "Location": { + "description": "URL to poll for sync results", + "schema": { + "type": "string", + "format": "uri" + } + }, + "Retry-After": { + "description": "Number of seconds to wait before polling", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/external-vulnerability-sync-accepted" + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "queued" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/requires_authentication" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": { + "get": { + "summary": "Get innersource vulnerability sync status for an enterprise", + "description": "Get the status of an asynchronous innersource vulnerability sync operation for an enterprise.\nReturns 202 with a `Retry-After` header while the sync is still processing, or 200 with\nthe full sync results once complete.\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/get-enterprise-innersource-vulnerability-sync-status", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise" + }, + "parameters": [ + { + "$ref": "#/components/parameters/enterprise" + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "The unique identifier of the sync job.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Sync operation completed", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/external-vulnerability-sync-result" + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string" + } + } + } + ] + }, + "examples": { + "success": { + "value": { + "processed": 1, + "created": 1, + "updated": 0, + "withdrawn": 0, + "errors": 0, + "results": [ + { + "external_id": "MVS-2026-001", + "status": "created", + "ghsa_id": "GHIS-xxxx-xxxx-xxxx" + } + ] + } + }, + "error": { + "value": { + "status": "error", + "error": "Internal error processing vulnerabilities" + } + } + } + } + } + }, + "202": { + "description": "Sync operation is still processing", + "headers": { + "Retry-After": { + "description": "Number of seconds to wait before polling again", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/external-vulnerability-sync-status" + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "processing" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/requires_authentication" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, "/enterprises/{enterprise}/installation": { "get": { "summary": "Get an enterprise installation for the authenticated app", @@ -140292,6 +140548,317 @@ } ] }, + "osv-vulnerability": { + "title": "OSV Vulnerability", + "description": "A vulnerability in OSV (Open Source Vulnerability) format", + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the vulnerability from the external system", + "examples": [ + "MVS-2026-001" + ] + }, + "schema_version": { + "type": "string", + "description": "The OSV schema version", + "examples": [ + "1.4.0" + ] + }, + "summary": { + "type": "string", + "description": "A short summary of the vulnerability", + "examples": [ + "Example vulnerability summary" + ] + }, + "details": { + "type": "string", + "description": "Detailed description of the vulnerability" + }, + "aliases": { + "type": "array", + "description": "IDs for the same vulnerability in other databases. Only CVE IDs are used (to populate the vulnerability's CVE identifier); other aliases are ignored.", + "items": { + "type": "string" + }, + "examples": [ + "CVE-2026-12345" + ] + }, + "severity": { + "type": "array", + "description": "Severity information for the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of severity scoring (e.g., CVSS_V3)" + }, + "score": { + "type": "string", + "description": "The severity score or vector string" + } + } + } + }, + "affected": { + "type": "array", + "description": "Packages and versions affected by the vulnerability", + "items": { + "type": "object", + "properties": { + "package": { + "type": "object", + "properties": { + "ecosystem": { + "type": "string", + "description": "The package ecosystem (e.g., npm, pip, maven)" + }, + "name": { + "type": "string", + "description": "The package name" + } + } + }, + "ranges": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "introduced": { + "type": "string", + "description": "The version that introduced the vulnerability" + }, + "fixed": { + "type": "string", + "description": "The version that fixed the vulnerability" + }, + "last_affected": { + "type": "string", + "description": "The last affected version" + }, + "limit": { + "type": "string", + "description": "The upper limit of the affected range" + } + } + } + } + } + } + } + } + } + }, + "references": { + "type": "array", + "description": "URLs for more information about the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reference. Supported values: PACKAGE, ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types are ignored." + }, + "url": { + "type": "string", + "format": "uri", + "description": "The reference URL" + } + } + } + }, + "published": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was first published" + }, + "modified": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was last modified" + }, + "withdrawn": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was withdrawn. If present, the vulnerability will be marked as withdrawn." + } + } + }, + "external-vulnerability-sync-accepted": { + "title": "External Vulnerability Sync Accepted", + "description": "Response when an external vulnerability sync request is accepted for asynchronous processing", + "type": "object", + "required": [ + "id", + "url", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID for polling", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "url": { + "type": "string", + "description": "URL to poll for sync results", + "format": "uri", + "examples": [ + "https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Initial job status", + "enum": [ + "queued" + ], + "examples": [ + "queued" + ] + } + } + }, + "external-vulnerability-sync-result": { + "title": "External Vulnerability Sync Result", + "description": "Result of an external vulnerability synchronization operation", + "type": "object", + "required": [ + "processed", + "created", + "updated", + "withdrawn", + "errors", + "results" + ], + "properties": { + "processed": { + "type": "integer", + "description": "Total number of vulnerabilities processed", + "examples": [ + 3 + ] + }, + "created": { + "type": "integer", + "description": "Number of new vulnerabilities created", + "examples": [ + 2 + ] + }, + "updated": { + "type": "integer", + "description": "Number of existing vulnerabilities updated", + "examples": [ + 1 + ] + }, + "withdrawn": { + "type": "integer", + "description": "Number of vulnerabilities marked as withdrawn", + "examples": [ + 0 + ] + }, + "errors": { + "type": "integer", + "description": "Number of vulnerabilities that failed to process", + "examples": [ + 0 + ] + }, + "results": { + "type": "array", + "description": "Detailed result for each processed vulnerability", + "items": { + "type": "object", + "required": [ + "external_id", + "status" + ], + "properties": { + "external_id": { + "type": "string", + "description": "The external ID of the vulnerability (corresponds to the `id` field in the request payload)", + "examples": [ + "MVS-2026-001" + ] + }, + "status": { + "type": "string", + "description": "The processing status", + "enum": [ + "created", + "updated", + "withdrawn", + "error" + ], + "examples": [ + "created" + ] + }, + "ghsa_id": { + "type": "string", + "description": "The advisory ID assigned to the vulnerability. For innersource vulnerabilities this is a GHIS ID. Present for successful operations.", + "examples": [ + "GHIS-xxxx-xxxx-xxxx" + ] + }, + "error": { + "type": "string", + "description": "Error message (present only when status is 'error')" + } + } + } + } + } + }, + "external-vulnerability-sync-status": { + "title": "External Vulnerability Sync Status", + "description": "Status of an in-progress external vulnerability sync operation", + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Current processing status", + "enum": [ + "processing" + ], + "examples": [ + "processing" + ] + } + } + }, "get-license-sync-status": { "title": "License Sync Status", "description": "Information about the status of a license sync job for an enterprise.", diff --git a/descriptions-next/ghec/ghec.2026-03-10.yaml b/descriptions-next/ghec/ghec.2026-03-10.yaml index 02f755897..ef801f8d9 100644 --- a/descriptions-next/ghec/ghec.2026-03-10.yaml +++ b/descriptions-next/ghec/ghec.2026-03-10.yaml @@ -11130,6 +11130,183 @@ paths: enabledForGitHubApps: true category: enterprise-admin subcategory: enterprise-roles + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": + post: + summary: Sync innersource vulnerabilities for an enterprise + description: |- + Synchronize innersource vulnerability data with the Advisory Database for an enterprise. + This endpoint receives vulnerability data in OSV format and creates, updates, or withdraws + innersource vulnerabilities accordingly. Dependabot alerting is triggered for created and + updated vulnerabilities. + + The request body accepts up to 100 vulnerabilities per call. The request is validated and + then queued for asynchronous processing: a successful request returns `202 Accepted` with a + `Location` header pointing to a status URL that you poll for the final result. + + Syncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api)." + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/sync-enterprise-innersource-vulnerabilities + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise + parameters: + - "$ref": "#/components/parameters/enterprise" + requestBody: + required: true + content: + application/json: + schema: + type: array + description: Array of vulnerabilities in OSV format to synchronize + items: + "$ref": "#/components/schemas/osv-vulnerability" + minItems: 1 + maxItems: 100 + examples: + default: + value: + - id: MVS-2026-001 + schema_version: 1.4.0 + summary: Example vulnerability summary + aliases: + - GHSA-xxxx-xxxx-xxxx + affected: + - package: + ecosystem: npm + name: example-package + ranges: + - type: SEMVER + events: + - introduced: 1.0.0 + - fixed: 1.0.1 + responses: + '202': + description: Sync operation accepted for asynchronous processing. Poll the + returned URL for results. + headers: + Location: + description: URL to poll for sync results + schema: + type: string + format: uri + Retry-After: + description: Number of seconds to wait before polling + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + "$ref": "#/components/schemas/external-vulnerability-sync-accepted" + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: queued + '400': + "$ref": "#/components/responses/bad_request" + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": + get: + summary: Get innersource vulnerability sync status for an enterprise + description: |- + Get the status of an asynchronous innersource vulnerability sync operation for an enterprise. + Returns 202 with a `Retry-After` header while the sync is still processing, or 200 with + the full sync results once complete. + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/get-enterprise-innersource-vulnerability-sync-status + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise + parameters: + - "$ref": "#/components/parameters/enterprise" + - name: job_id + in: path + required: true + description: The unique identifier of the sync job. + schema: + type: string + responses: + '200': + description: Sync operation completed + content: + application/json: + schema: + oneOf: + - "$ref": "#/components/schemas/external-vulnerability-sync-result" + - type: object + properties: + status: + type: string + enum: + - error + error: + type: string + examples: + success: + value: + processed: 1 + created: 1 + updated: 0 + withdrawn: 0 + errors: 0 + results: + - external_id: MVS-2026-001 + status: created + ghsa_id: GHIS-xxxx-xxxx-xxxx + error: + value: + status: error + error: Internal error processing vulnerabilities + '202': + description: Sync operation is still processing + headers: + Retry-After: + description: Number of seconds to wait before polling again + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + "$ref": "#/components/schemas/external-vulnerability-sync-status" + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: processing + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories "/enterprises/{enterprise}/installation": get: summary: Get an enterprise installation for the authenticated app @@ -102020,6 +102197,238 @@ components: type: array items: "$ref": "#/components/schemas/enterprise-team" + osv-vulnerability: + title: OSV Vulnerability + description: A vulnerability in OSV (Open Source Vulnerability) format + type: object + required: + - id + properties: + id: + type: string + description: Unique identifier for the vulnerability from the external system + examples: + - MVS-2026-001 + schema_version: + type: string + description: The OSV schema version + examples: + - 1.4.0 + summary: + type: string + description: A short summary of the vulnerability + examples: + - Example vulnerability summary + details: + type: string + description: Detailed description of the vulnerability + aliases: + type: array + description: IDs for the same vulnerability in other databases. Only CVE + IDs are used (to populate the vulnerability's CVE identifier); other aliases + are ignored. + items: + type: string + examples: + - CVE-2026-12345 + severity: + type: array + description: Severity information for the vulnerability + items: + type: object + properties: + type: + type: string + description: The type of severity scoring (e.g., CVSS_V3) + score: + type: string + description: The severity score or vector string + affected: + type: array + description: Packages and versions affected by the vulnerability + items: + type: object + properties: + package: + type: object + properties: + ecosystem: + type: string + description: The package ecosystem (e.g., npm, pip, maven) + name: + type: string + description: The package name + ranges: + type: array + items: + type: object + properties: + type: + type: string + events: + type: array + items: + type: object + properties: + introduced: + type: string + description: The version that introduced the vulnerability + fixed: + type: string + description: The version that fixed the vulnerability + last_affected: + type: string + description: The last affected version + limit: + type: string + description: The upper limit of the affected range + references: + type: array + description: URLs for more information about the vulnerability + items: + type: object + properties: + type: + type: string + description: 'The type of reference. Supported values: PACKAGE, ADVISORY, + WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types + are ignored.' + url: + type: string + format: uri + description: The reference URL + published: + type: string + format: date-time + description: When the vulnerability was first published + modified: + type: string + format: date-time + description: When the vulnerability was last modified + withdrawn: + type: string + format: date-time + description: When the vulnerability was withdrawn. If present, the vulnerability + will be marked as withdrawn. + external-vulnerability-sync-accepted: + title: External Vulnerability Sync Accepted + description: Response when an external vulnerability sync request is accepted + for asynchronous processing + type: object + required: + - id + - url + - status + properties: + id: + type: string + description: Job status ID for polling + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: + type: string + description: URL to poll for sync results + format: uri + examples: + - https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Initial job status + enum: + - queued + examples: + - queued + external-vulnerability-sync-result: + title: External Vulnerability Sync Result + description: Result of an external vulnerability synchronization operation + type: object + required: + - processed + - created + - updated + - withdrawn + - errors + - results + properties: + processed: + type: integer + description: Total number of vulnerabilities processed + examples: + - 3 + created: + type: integer + description: Number of new vulnerabilities created + examples: + - 2 + updated: + type: integer + description: Number of existing vulnerabilities updated + examples: + - 1 + withdrawn: + type: integer + description: Number of vulnerabilities marked as withdrawn + examples: + - 0 + errors: + type: integer + description: Number of vulnerabilities that failed to process + examples: + - 0 + results: + type: array + description: Detailed result for each processed vulnerability + items: + type: object + required: + - external_id + - status + properties: + external_id: + type: string + description: The external ID of the vulnerability (corresponds to + the `id` field in the request payload) + examples: + - MVS-2026-001 + status: + type: string + description: The processing status + enum: + - created + - updated + - withdrawn + - error + examples: + - created + ghsa_id: + type: string + description: The advisory ID assigned to the vulnerability. For innersource + vulnerabilities this is a GHIS ID. Present for successful operations. + examples: + - GHIS-xxxx-xxxx-xxxx + error: + type: string + description: Error message (present only when status is 'error') + external-vulnerability-sync-status: + title: External Vulnerability Sync Status + description: Status of an in-progress external vulnerability sync operation + type: object + required: + - id + - status + properties: + id: + type: string + description: Job status ID + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Current processing status + enum: + - processing + examples: + - processing get-license-sync-status: title: License Sync Status description: Information about the status of a license sync job for an enterprise. diff --git a/descriptions-next/ghec/ghec.json b/descriptions-next/ghec/ghec.json index ac0a41630..5972a763c 100644 --- a/descriptions-next/ghec/ghec.json +++ b/descriptions-next/ghec/ghec.json @@ -15008,6 +15008,262 @@ } } }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": { + "post": { + "summary": "Sync innersource vulnerabilities for an enterprise", + "description": "Synchronize innersource vulnerability data with the Advisory Database for an enterprise.\nThis endpoint receives vulnerability data in OSV format and creates, updates, or withdraws\ninnersource vulnerabilities accordingly. Dependabot alerting is triggered for created and\nupdated vulnerabilities.\n\nThe request body accepts up to 100 vulnerabilities per call. The request is validated and\nthen queued for asynchronous processing: a successful request returns `202 Accepted` with a\n`Location` header pointing to a status URL that you poll for the final result.\n\nSyncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see \"[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)\" and \"[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api).\"\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/sync-enterprise-innersource-vulnerabilities", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise" + }, + "parameters": [ + { + "$ref": "#/components/parameters/enterprise" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of vulnerabilities in OSV format to synchronize", + "items": { + "$ref": "#/components/schemas/osv-vulnerability" + }, + "minItems": 1, + "maxItems": 100 + }, + "examples": { + "default": { + "value": [ + { + "id": "MVS-2026-001", + "schema_version": "1.4.0", + "summary": "Example vulnerability summary", + "aliases": [ + "GHSA-xxxx-xxxx-xxxx" + ], + "affected": [ + { + "package": { + "ecosystem": "npm", + "name": "example-package" + }, + "ranges": [ + { + "type": "SEMVER", + "events": [ + { + "introduced": "1.0.0" + }, + { + "fixed": "1.0.1" + } + ] + } + ] + } + ] + } + ] + } + } + } + } + }, + "responses": { + "202": { + "description": "Sync operation accepted for asynchronous processing. Poll the returned URL for results.", + "headers": { + "Location": { + "description": "URL to poll for sync results", + "schema": { + "type": "string", + "format": "uri" + } + }, + "Retry-After": { + "description": "Number of seconds to wait before polling", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/external-vulnerability-sync-accepted" + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "url": "https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "queued" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/bad_request" + }, + "401": { + "$ref": "#/components/responses/requires_authentication" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": { + "get": { + "summary": "Get innersource vulnerability sync status for an enterprise", + "description": "Get the status of an asynchronous innersource vulnerability sync operation for an enterprise.\nReturns 202 with a `Retry-After` header while the sync is still processing, or 200 with\nthe full sync results once complete.\n\nThis endpoint does not support OAuth apps or personal access tokens.", + "operationId": "enterprise-admin/get-enterprise-innersource-vulnerability-sync-status", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise" + }, + "parameters": [ + { + "$ref": "#/components/parameters/enterprise" + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "The unique identifier of the sync job.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Sync operation completed", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/external-vulnerability-sync-result" + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string" + } + } + } + ] + }, + "examples": { + "success": { + "value": { + "processed": 1, + "created": 1, + "updated": 0, + "withdrawn": 0, + "errors": 0, + "results": [ + { + "external_id": "MVS-2026-001", + "status": "created", + "ghsa_id": "GHIS-xxxx-xxxx-xxxx" + } + ] + } + }, + "error": { + "value": { + "status": "error", + "error": "Internal error processing vulnerabilities" + } + } + } + } + } + }, + "202": { + "description": "Sync operation is still processing", + "headers": { + "Retry-After": { + "description": "Number of seconds to wait before polling again", + "schema": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/external-vulnerability-sync-status" + }, + "examples": { + "default": { + "value": { + "id": "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "status": "processing" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/requires_authentication" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, + "404": { + "$ref": "#/components/responses/not_found" + } + }, + "x-github": { + "githubCloudOnly": true, + "enabledForGitHubApps": true, + "category": "enterprise-admin", + "subcategory": "security-advisories" + } + } + }, "/enterprises/{enterprise}/installation": { "get": { "summary": "Get an enterprise installation for the authenticated app", @@ -141157,6 +141413,317 @@ } ] }, + "osv-vulnerability": { + "title": "OSV Vulnerability", + "description": "A vulnerability in OSV (Open Source Vulnerability) format", + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the vulnerability from the external system", + "examples": [ + "MVS-2026-001" + ] + }, + "schema_version": { + "type": "string", + "description": "The OSV schema version", + "examples": [ + "1.4.0" + ] + }, + "summary": { + "type": "string", + "description": "A short summary of the vulnerability", + "examples": [ + "Example vulnerability summary" + ] + }, + "details": { + "type": "string", + "description": "Detailed description of the vulnerability" + }, + "aliases": { + "type": "array", + "description": "IDs for the same vulnerability in other databases. Only CVE IDs are used (to populate the vulnerability's CVE identifier); other aliases are ignored.", + "items": { + "type": "string" + }, + "examples": [ + "CVE-2026-12345" + ] + }, + "severity": { + "type": "array", + "description": "Severity information for the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of severity scoring (e.g., CVSS_V3)" + }, + "score": { + "type": "string", + "description": "The severity score or vector string" + } + } + } + }, + "affected": { + "type": "array", + "description": "Packages and versions affected by the vulnerability", + "items": { + "type": "object", + "properties": { + "package": { + "type": "object", + "properties": { + "ecosystem": { + "type": "string", + "description": "The package ecosystem (e.g., npm, pip, maven)" + }, + "name": { + "type": "string", + "description": "The package name" + } + } + }, + "ranges": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "introduced": { + "type": "string", + "description": "The version that introduced the vulnerability" + }, + "fixed": { + "type": "string", + "description": "The version that fixed the vulnerability" + }, + "last_affected": { + "type": "string", + "description": "The last affected version" + }, + "limit": { + "type": "string", + "description": "The upper limit of the affected range" + } + } + } + } + } + } + } + } + } + }, + "references": { + "type": "array", + "description": "URLs for more information about the vulnerability", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of reference. Supported values: PACKAGE, ADVISORY, WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types are ignored." + }, + "url": { + "type": "string", + "format": "uri", + "description": "The reference URL" + } + } + } + }, + "published": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was first published" + }, + "modified": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was last modified" + }, + "withdrawn": { + "type": "string", + "format": "date-time", + "description": "When the vulnerability was withdrawn. If present, the vulnerability will be marked as withdrawn." + } + } + }, + "external-vulnerability-sync-accepted": { + "title": "External Vulnerability Sync Accepted", + "description": "Response when an external vulnerability sync request is accepted for asynchronous processing", + "type": "object", + "required": [ + "id", + "url", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID for polling", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "url": { + "type": "string", + "description": "URL to poll for sync results", + "format": "uri", + "examples": [ + "https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Initial job status", + "enum": [ + "queued" + ], + "examples": [ + "queued" + ] + } + } + }, + "external-vulnerability-sync-result": { + "title": "External Vulnerability Sync Result", + "description": "Result of an external vulnerability synchronization operation", + "type": "object", + "required": [ + "processed", + "created", + "updated", + "withdrawn", + "errors", + "results" + ], + "properties": { + "processed": { + "type": "integer", + "description": "Total number of vulnerabilities processed", + "examples": [ + 3 + ] + }, + "created": { + "type": "integer", + "description": "Number of new vulnerabilities created", + "examples": [ + 2 + ] + }, + "updated": { + "type": "integer", + "description": "Number of existing vulnerabilities updated", + "examples": [ + 1 + ] + }, + "withdrawn": { + "type": "integer", + "description": "Number of vulnerabilities marked as withdrawn", + "examples": [ + 0 + ] + }, + "errors": { + "type": "integer", + "description": "Number of vulnerabilities that failed to process", + "examples": [ + 0 + ] + }, + "results": { + "type": "array", + "description": "Detailed result for each processed vulnerability", + "items": { + "type": "object", + "required": [ + "external_id", + "status" + ], + "properties": { + "external_id": { + "type": "string", + "description": "The external ID of the vulnerability (corresponds to the `id` field in the request payload)", + "examples": [ + "MVS-2026-001" + ] + }, + "status": { + "type": "string", + "description": "The processing status", + "enum": [ + "created", + "updated", + "withdrawn", + "error" + ], + "examples": [ + "created" + ] + }, + "ghsa_id": { + "type": "string", + "description": "The advisory ID assigned to the vulnerability. For innersource vulnerabilities this is a GHIS ID. Present for successful operations.", + "examples": [ + "GHIS-xxxx-xxxx-xxxx" + ] + }, + "error": { + "type": "string", + "description": "Error message (present only when status is 'error')" + } + } + } + } + } + }, + "external-vulnerability-sync-status": { + "title": "External Vulnerability Sync Status", + "description": "Status of an in-progress external vulnerability sync operation", + "type": "object", + "required": [ + "id", + "status" + ], + "properties": { + "id": { + "type": "string", + "description": "Job status ID", + "examples": [ + "external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + }, + "status": { + "type": "string", + "description": "Current processing status", + "enum": [ + "processing" + ], + "examples": [ + "processing" + ] + } + } + }, "get-license-sync-status": { "title": "License Sync Status", "description": "Information about the status of a license sync job for an enterprise.", diff --git a/descriptions-next/ghec/ghec.yaml b/descriptions-next/ghec/ghec.yaml index 0e59cc37b..ef1010bb8 100644 --- a/descriptions-next/ghec/ghec.yaml +++ b/descriptions-next/ghec/ghec.yaml @@ -11138,6 +11138,183 @@ paths: enabledForGitHubApps: true category: enterprise-admin subcategory: enterprise-roles + "/enterprises/{enterprise}/innersource-vulnerabilities/sync": + post: + summary: Sync innersource vulnerabilities for an enterprise + description: |- + Synchronize innersource vulnerability data with the Advisory Database for an enterprise. + This endpoint receives vulnerability data in OSV format and creates, updates, or withdraws + innersource vulnerabilities accordingly. Dependabot alerting is triggered for created and + updated vulnerabilities. + + The request body accepts up to 100 vulnerabilities per call. The request is validated and + then queued for asynchronous processing: a successful request returns `202 Accepted` with a + `Location` header pointing to a status URL that you poll for the final result. + + Syncing vulnerabilities too quickly using this endpoint may result in secondary rate limiting. For more information, see "[Rate limits for the API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits)" and "[Best practices for using the REST API](https://docs.github.com/enterprise-cloud@latest/rest/guides/best-practices-for-using-the-rest-api)." + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/sync-enterprise-innersource-vulnerabilities + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#sync-innersource-vulnerabilities-for-an-enterprise + parameters: + - "$ref": "#/components/parameters/enterprise" + requestBody: + required: true + content: + application/json: + schema: + type: array + description: Array of vulnerabilities in OSV format to synchronize + items: + "$ref": "#/components/schemas/osv-vulnerability" + minItems: 1 + maxItems: 100 + examples: + default: + value: + - id: MVS-2026-001 + schema_version: 1.4.0 + summary: Example vulnerability summary + aliases: + - GHSA-xxxx-xxxx-xxxx + affected: + - package: + ecosystem: npm + name: example-package + ranges: + - type: SEMVER + events: + - introduced: 1.0.0 + - fixed: 1.0.1 + responses: + '202': + description: Sync operation accepted for asynchronous processing. Poll the + returned URL for results. + headers: + Location: + description: URL to poll for sync results + schema: + type: string + format: uri + Retry-After: + description: Number of seconds to wait before polling + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + "$ref": "#/components/schemas/external-vulnerability-sync-accepted" + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: https://api.github.com/enterprises/my-enterprise/innersource-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: queued + '400': + "$ref": "#/components/responses/bad_request" + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories + "/enterprises/{enterprise}/innersource-vulnerabilities/sync/status/{job_id}": + get: + summary: Get innersource vulnerability sync status for an enterprise + description: |- + Get the status of an asynchronous innersource vulnerability sync operation for an enterprise. + Returns 202 with a `Retry-After` header while the sync is still processing, or 200 with + the full sync results once complete. + + This endpoint does not support OAuth apps or personal access tokens. + operationId: enterprise-admin/get-enterprise-innersource-vulnerability-sync-status + tags: + - enterprise-admin + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/security-advisories#get-innersource-vulnerability-sync-status-for-an-enterprise + parameters: + - "$ref": "#/components/parameters/enterprise" + - name: job_id + in: path + required: true + description: The unique identifier of the sync job. + schema: + type: string + responses: + '200': + description: Sync operation completed + content: + application/json: + schema: + oneOf: + - "$ref": "#/components/schemas/external-vulnerability-sync-result" + - type: object + properties: + status: + type: string + enum: + - error + error: + type: string + examples: + success: + value: + processed: 1 + created: 1 + updated: 0 + withdrawn: 0 + errors: 0 + results: + - external_id: MVS-2026-001 + status: created + ghsa_id: GHIS-xxxx-xxxx-xxxx + error: + value: + status: error + error: Internal error processing vulnerabilities + '202': + description: Sync operation is still processing + headers: + Retry-After: + description: Number of seconds to wait before polling again + schema: + type: integer + examples: + - 1 + content: + application/json: + schema: + "$ref": "#/components/schemas/external-vulnerability-sync-status" + examples: + default: + value: + id: external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: processing + '401': + "$ref": "#/components/responses/requires_authentication" + '403': + "$ref": "#/components/responses/forbidden" + '404': + "$ref": "#/components/responses/not_found" + x-github: + githubCloudOnly: true + enabledForGitHubApps: true + category: enterprise-admin + subcategory: security-advisories "/enterprises/{enterprise}/installation": get: summary: Get an enterprise installation for the authenticated app @@ -102616,6 +102793,238 @@ components: type: array items: "$ref": "#/components/schemas/enterprise-team" + osv-vulnerability: + title: OSV Vulnerability + description: A vulnerability in OSV (Open Source Vulnerability) format + type: object + required: + - id + properties: + id: + type: string + description: Unique identifier for the vulnerability from the external system + examples: + - MVS-2026-001 + schema_version: + type: string + description: The OSV schema version + examples: + - 1.4.0 + summary: + type: string + description: A short summary of the vulnerability + examples: + - Example vulnerability summary + details: + type: string + description: Detailed description of the vulnerability + aliases: + type: array + description: IDs for the same vulnerability in other databases. Only CVE + IDs are used (to populate the vulnerability's CVE identifier); other aliases + are ignored. + items: + type: string + examples: + - CVE-2026-12345 + severity: + type: array + description: Severity information for the vulnerability + items: + type: object + properties: + type: + type: string + description: The type of severity scoring (e.g., CVSS_V3) + score: + type: string + description: The severity score or vector string + affected: + type: array + description: Packages and versions affected by the vulnerability + items: + type: object + properties: + package: + type: object + properties: + ecosystem: + type: string + description: The package ecosystem (e.g., npm, pip, maven) + name: + type: string + description: The package name + ranges: + type: array + items: + type: object + properties: + type: + type: string + events: + type: array + items: + type: object + properties: + introduced: + type: string + description: The version that introduced the vulnerability + fixed: + type: string + description: The version that fixed the vulnerability + last_affected: + type: string + description: The last affected version + limit: + type: string + description: The upper limit of the affected range + references: + type: array + description: URLs for more information about the vulnerability + items: + type: object + properties: + type: + type: string + description: 'The type of reference. Supported values: PACKAGE, ADVISORY, + WEB, FIX, ARTICLE, REPORT, EVIDENCE. References with other types + are ignored.' + url: + type: string + format: uri + description: The reference URL + published: + type: string + format: date-time + description: When the vulnerability was first published + modified: + type: string + format: date-time + description: When the vulnerability was last modified + withdrawn: + type: string + format: date-time + description: When the vulnerability was withdrawn. If present, the vulnerability + will be marked as withdrawn. + external-vulnerability-sync-accepted: + title: External Vulnerability Sync Accepted + description: Response when an external vulnerability sync request is accepted + for asynchronous processing + type: object + required: + - id + - url + - status + properties: + id: + type: string + description: Job status ID for polling + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + url: + type: string + description: URL to poll for sync results + format: uri + examples: + - https://api.github.com/enterprises/my-enterprise/external-vulnerabilities/sync/status/external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Initial job status + enum: + - queued + examples: + - queued + external-vulnerability-sync-result: + title: External Vulnerability Sync Result + description: Result of an external vulnerability synchronization operation + type: object + required: + - processed + - created + - updated + - withdrawn + - errors + - results + properties: + processed: + type: integer + description: Total number of vulnerabilities processed + examples: + - 3 + created: + type: integer + description: Number of new vulnerabilities created + examples: + - 2 + updated: + type: integer + description: Number of existing vulnerabilities updated + examples: + - 1 + withdrawn: + type: integer + description: Number of vulnerabilities marked as withdrawn + examples: + - 0 + errors: + type: integer + description: Number of vulnerabilities that failed to process + examples: + - 0 + results: + type: array + description: Detailed result for each processed vulnerability + items: + type: object + required: + - external_id + - status + properties: + external_id: + type: string + description: The external ID of the vulnerability (corresponds to + the `id` field in the request payload) + examples: + - MVS-2026-001 + status: + type: string + description: The processing status + enum: + - created + - updated + - withdrawn + - error + examples: + - created + ghsa_id: + type: string + description: The advisory ID assigned to the vulnerability. For innersource + vulnerabilities this is a GHIS ID. Present for successful operations. + examples: + - GHIS-xxxx-xxxx-xxxx + error: + type: string + description: Error message (present only when status is 'error') + external-vulnerability-sync-status: + title: External Vulnerability Sync Status + description: Status of an in-progress external vulnerability sync operation + type: object + required: + - id + - status + properties: + id: + type: string + description: Job status ID + examples: + - external-vulnerability-sync-a1b2c3d4-e5f6-7890-abcd-ef1234567890 + status: + type: string + description: Current processing status + enum: + - processing + examples: + - processing get-license-sync-status: title: License Sync Status description: Information about the status of a license sync job for an enterprise.