diff --git a/openapi.json b/openapi.json index 44db1a1f..10d8786c 100644 --- a/openapi.json +++ b/openapi.json @@ -7468,6 +7468,49 @@ } } }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "enum": [ + "pendingScan" + ] + }, + "value": { + "allOf": [ + { + "$ref": "#/components/schemas/SocketIssueBasics" + }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "description": { + "type": "string", + "description": "", + "default": "" + }, + "props": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": {} + }, + "usage": { + "$ref": "#/components/schemas/SocketUsageRef" + } + }, + "required": [ + "description", + "props" + ] + } + ] + } + } + }, { "type": "object", "additionalProperties": false, @@ -8140,6 +8183,49 @@ } } }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "enum": [ + "notFound" + ] + }, + "value": { + "allOf": [ + { + "$ref": "#/components/schemas/SocketIssueBasics" + }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "description": { + "type": "string", + "description": "", + "default": "" + }, + "props": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": {} + }, + "usage": { + "$ref": "#/components/schemas/SocketUsageRef" + } + }, + "required": [ + "description", + "props" + ] + } + ] + } + } + }, { "type": "object", "additionalProperties": false, @@ -12119,11 +12205,21 @@ "default": false } }, + { + "name": "poll", + "in": "query", + "required": false, + "description": "When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors.", + "schema": { + "type": "boolean", + "default": false + } + }, { "name": "cachedResultsOnly", "in": "query", "required": false, - "description": "Return only cached results, do not attempt to scan new artifacts or rescan stale results.", + "description": "Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior.", "schema": { "type": "boolean", "default": false @@ -12143,7 +12239,7 @@ "name": "timeoutSec", "in": "query", "required": false, - "description": "Maximum time in seconds to wait for scan results. PURLs that have not completed processing when the timeout is reached will be returned as errors (when purlErrors is enabled). Omit for no timeout.", + "description": "Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan alerts when alerts=true, or errors when purlErrors=true.", "schema": { "type": "integer", "minimum": 1, @@ -12173,7 +12269,7 @@ ] } ], - "description": "**This endpoint is deprecated.** Deprecated since 2026-01-05.\n\nBatch retrieval of package metadata and alerts by PURL strings. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs) are an ecosystem agnostic way to identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis endpoint supports fetching metadata and alerts for multiple packages at once by passing an array of purl strings, or by passing an entire CycloneDX report.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.\n\nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\nThis endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\n## Examples:\n\n### Looking up an npm package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\n### Looking up an PyPi package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n }\n ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n },\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n },\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\nThis endpoint consumes 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list", + "description": "**This endpoint is deprecated.** Deprecated since 2026-01-05.\n\nBatch retrieval of package metadata and alerts by PURL strings. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs) are an ecosystem agnostic way to identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis endpoint supports fetching metadata and alerts for multiple packages at once by passing an array of purl strings, or by passing an entire CycloneDX report.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.\n\nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\nThis endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\nWhen `alerts=true`, Socket may synthesize two alert types to make partial\nresults actionable:\n\n- `pendingScan`: the package is known but analysis has not completed yet\n- `notFound`: Socket could not resolve the package/version metadata\n\nWhen `purlErrors=true`, unresolved `notFound` inputs keep the legacy\n`purlError` stream shape instead of emitting synthetic `notFound`\nartifacts.\n\nUse `poll=false` (default) to fail open and return the current known state\nquickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for\npending analysis before returning.\n\n## Examples:\n\n### Looking up an npm package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\n### Looking up an PyPi package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n }\n ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n },\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n },\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\nThis endpoint consumes 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list", "responses": { "200": { "content": { @@ -18432,9 +18528,9 @@ "description": "The last update date of the repository", "default": "" }, - "slug": { + "html_url": { "type": "string", - "description": "The slug of the repository", + "description": "The URL to the repository dashboard page", "default": "" }, "head_full_scan_id": { @@ -18495,6 +18591,11 @@ ], "nullable": true }, + "slug": { + "type": "string", + "description": "The slug of the repository.", + "default": "" + }, "name": { "type": "string", "description": "The name of the repository", @@ -18591,6 +18692,15 @@ "schema": { "type": "string" } + }, + { + "name": "on_duplicate", + "in": "query", + "required": false, + "description": "Set to \"redirect\" to receive a 302 redirect to the existing repo instead of a 409 error when a duplicate slug is detected.", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -18602,7 +18712,7 @@ "properties": { "name": { "type": "string", - "description": "The name of the repository", + "description": "The display name of the repository. When provided without a slug, the slug is automatically derived from the name. When omitted, the slug is used as the name. At least one of name or slug must be provided.", "default": "" }, "description": { @@ -18641,6 +18751,11 @@ "type": "string", "description": "The workspace of the repository", "default": "" + }, + "slug": { + "type": "string", + "description": "The slug of the repository. If provided, used directly instead of being derived from name. Must only contain ASCII letters, digits, and the characters ., -, and _.", + "default": "" } }, "description": "" @@ -18685,9 +18800,9 @@ "description": "The last update date of the repository", "default": "" }, - "slug": { + "html_url": { "type": "string", - "description": "The slug of the repository", + "description": "The URL to the repository dashboard page", "default": "" }, "head_full_scan_id": { @@ -18748,6 +18863,11 @@ ], "nullable": true }, + "slug": { + "type": "string", + "description": "The slug of the repository.", + "default": "" + }, "name": { "type": "string", "description": "The name of the repository", @@ -18797,6 +18917,145 @@ }, "description": "Lists repositories for the specified organization. The authenticated user must be a member of the organization." }, + "302": { + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "string", + "description": "The ID of the repository", + "default": "" + }, + "created_at": { + "type": "string", + "description": "The creation date of the repository", + "default": "" + }, + "updated_at": { + "type": "string", + "description": "The last update date of the repository", + "default": "" + }, + "html_url": { + "type": "string", + "description": "The URL to the repository dashboard page", + "default": "" + }, + "head_full_scan_id": { + "type": "string", + "description": "The ID of the head full scan of the repository", + "default": "", + "nullable": true + }, + "integration_meta": { + "anyOf": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "enum": [ + "github" + ] + }, + "value": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "installation_id": { + "type": "string", + "description": "The GitHub installation_id of the active associated Socket GitHub App", + "default": "" + }, + "installation_login": { + "type": "string", + "description": "The GitHub login name that the active Socket GitHub App installation is installed to", + "default": "" + }, + "repo_name": { + "type": "string", + "description": "The name of the associated GitHub repo.", + "default": "", + "nullable": true + }, + "repo_id": { + "type": "string", + "description": "The id of the associated GitHub repo.", + "default": "", + "nullable": true + } + }, + "required": [ + "installation_id", + "installation_login", + "repo_id", + "repo_name" + ] + } + } + } + ], + "nullable": true + }, + "slug": { + "type": "string", + "description": "The slug of the repository.", + "default": "" + }, + "name": { + "type": "string", + "description": "The name of the repository", + "default": "" + }, + "description": { + "type": "string", + "description": "The description of the repository", + "default": "", + "nullable": true + }, + "homepage": { + "type": "string", + "description": "The homepage URL of the repository", + "default": "", + "nullable": true + }, + "visibility": { + "type": "string", + "enum": [ + "public", + "private" + ], + "description": "The visibility of the repository", + "default": "private" + }, + "archived": { + "type": "boolean", + "default": false, + "description": "Whether the repository is archived or not" + }, + "default_branch": { + "type": "string", + "description": "The default branch of the repository", + "default": "main", + "nullable": true + }, + "workspace": { + "type": "string", + "description": "The workspace of the repository", + "default": "" + } + }, + "description": "" + } + } + }, + "description": "Redirects to the existing repository when on_duplicate=redirect is set and a duplicate slug is detected." + }, "400": { "$ref": "#/components/responses/SocketBadRequest" }, @@ -18809,6 +19068,9 @@ "404": { "$ref": "#/components/responses/SocketNotFoundResponse" }, + "409": { + "$ref": "#/components/responses/SocketConflict" + }, "429": { "$ref": "#/components/responses/SocketTooManyRequestsResponse" } @@ -18889,9 +19151,9 @@ "description": "The last update date of the repository", "default": "" }, - "slug": { + "html_url": { "type": "string", - "description": "The slug of the repository", + "description": "The URL to the repository dashboard page", "default": "" }, "head_full_scan_id": { @@ -18952,6 +19214,11 @@ ], "nullable": true }, + "slug": { + "type": "string", + "description": "The slug of the repository.", + "default": "" + }, "name": { "type": "string", "description": "The name of the repository", @@ -19007,6 +19274,7 @@ "description", "head_full_scan_id", "homepage", + "html_url", "id", "integration_meta", "name", @@ -19166,9 +19434,9 @@ "description": "The last update date of the repository", "default": "" }, - "slug": { + "html_url": { "type": "string", - "description": "The slug of the repository", + "description": "The URL to the repository dashboard page", "default": "" }, "head_full_scan_id": { @@ -19229,6 +19497,11 @@ ], "nullable": true }, + "slug": { + "type": "string", + "description": "The slug of the repository.", + "default": "" + }, "name": { "type": "string", "description": "The name of the repository", @@ -21719,6 +21992,27 @@ "action" ] }, + "pendingScan": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for pendingScan issues." + } + }, + "required": [ + "action" + ] + }, "deprecated": { "type": "object", "additionalProperties": false, @@ -21971,6 +22265,27 @@ "action" ] }, + "notFound": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for notFound issues." + } + }, + "required": [ + "action" + ] + }, "unpopularPackage": { "type": "object", "additionalProperties": false, @@ -24617,6 +24932,27 @@ "action" ] }, + "pendingScan": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for pendingScan issues." + } + }, + "required": [ + "action" + ] + }, "deprecated": { "type": "object", "additionalProperties": false, @@ -24869,6 +25205,27 @@ "action" ] }, + "notFound": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for notFound issues." + } + }, + "required": [ + "action" + ] + }, "unpopularPackage": { "type": "object", "additionalProperties": false, @@ -27828,6 +28185,27 @@ "action" ] }, + "pendingScan": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for pendingScan issues." + } + }, + "required": [ + "action" + ] + }, "deprecated": { "type": "object", "additionalProperties": false, @@ -28080,6 +28458,27 @@ "action" ] }, + "notFound": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for notFound issues." + } + }, + "required": [ + "action" + ] + }, "unpopularPackage": { "type": "object", "additionalProperties": false, @@ -30729,6 +31128,27 @@ "action" ] }, + "pendingScan": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for pendingScan issues." + } + }, + "required": [ + "action" + ] + }, "deprecated": { "type": "object", "additionalProperties": false, @@ -30981,6 +31401,27 @@ "action" ] }, + "notFound": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for notFound issues." + } + }, + "required": [ + "action" + ] + }, "unpopularPackage": { "type": "object", "additionalProperties": false, @@ -33583,6 +34024,27 @@ "action" ] }, + "pendingScan": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for pendingScan issues." + } + }, + "required": [ + "action" + ] + }, "deprecated": { "type": "object", "additionalProperties": false, @@ -33835,6 +34297,27 @@ "action" ] }, + "notFound": { + "type": "object", + "additionalProperties": false, + "description": "", + "properties": { + "action": { + "type": "string", + "enum": [ + "defer", + "error", + "warn", + "monitor", + "ignore" + ], + "description": "The action to take for notFound issues." + } + }, + "required": [ + "action" + ] + }, "unpopularPackage": { "type": "object", "additionalProperties": false, @@ -39149,6 +39632,7 @@ "CreateWebhook", "CreateTicket", "CoanaCliLegacyModeCutoffUpdated", + "CoanaCliLegacyModeDemoteOrg", "CoanaCliLegacyModePromoteOrg", "DeleteAlertTriage", "DeleteApiToken", @@ -39164,6 +39648,7 @@ "DisassociateLabel", "DisconnectJiraIntegration", "DowngradeOrganizationPlan", + "EnqueueAutopatchPrepareJob", "JoinOrganization", "JiraIntegrationConnected", "MemberAdded", @@ -39178,6 +39663,7 @@ "RevokeApiToken", "RotateApiToken", "SendInvitation", + "SessionRevokedByUser", "SetLabelSettingToDefault", "SSOEmailVerificationCompleted", "SSOLoginCompleted", @@ -39190,6 +39676,7 @@ "UpdateApiTokenScopes", "UpdateApiTokenVisibility", "UpdateAutopatchCurated", + "UpdateAutopatchPrepareConfig", "UpdateFirewallCustomRegistry", "UpdateFirewallDeploymentConfig", "UpdateLabel", @@ -41298,11 +41785,21 @@ "default": false } }, + { + "name": "poll", + "in": "query", + "required": false, + "description": "When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors.", + "schema": { + "type": "boolean", + "default": false + } + }, { "name": "cachedResultsOnly", "in": "query", "required": false, - "description": "Return only cached results, do not attempt to scan new artifacts or rescan stale results.", + "description": "Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior.", "schema": { "type": "boolean", "default": false @@ -41322,7 +41819,7 @@ "name": "timeoutSec", "in": "query", "required": false, - "description": "Maximum time in seconds to wait for scan results. PURLs that have not completed processing when the timeout is reached will be returned as errors (when purlErrors is enabled). Omit for no timeout, unless a default timeout is configured for the organization.", + "description": "Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan alerts when alerts=true, or errors when purlErrors=true.", "schema": { "type": "integer", "minimum": 1, @@ -41352,7 +41849,7 @@ ] } ], - "description": "Batch retrieval of package metadata and alerts by PURL strings for a specific organization. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs) are an ecosystem agnostic way to identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis endpoint supports fetching metadata and alerts for multiple packages at once by passing an array of purl strings, or by passing an entire CycloneDX report.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.\n\nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\nThis endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\n## Query Parameters\n\nThis endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `cachedResultsOnly`, and `summary`.\n\nAdditionally, you may provide a `labels` query parameter to apply a repository label's security policies. Pass the label slug as the value (e.g., `?labels=production`). Only one label is currently supported.\n\n## Examples:\n\n### Looking up an npm package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\n### Looking up a PyPi package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n }\n ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n },\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n },\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### With label and options (query parameters):\n\n```\nPOST /v0/orgs/{org_slug}/purl?labels=production&alerts=true&compact=true\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\nThis endpoint consumes 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list", + "description": "Batch retrieval of package metadata and alerts by PURL strings for a specific organization. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs) are an ecosystem agnostic way to identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis endpoint supports fetching metadata and alerts for multiple packages at once by passing an array of purl strings, or by passing an entire CycloneDX report.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.\n\nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\nThis endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\nWhen `alerts=true`, Socket may synthesize two alert types to make partial\nresults actionable:\n\n- `pendingScan`: the package is known but analysis has not completed yet\n- `notFound`: Socket could not resolve the package/version metadata\n\nWhen `purlErrors=true`, unresolved `notFound` inputs keep the legacy\n`purlError` stream shape instead of emitting synthetic `notFound`\nartifacts.\n\nUse `poll=false` (default) to fail open and return the current known state\nquickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for\npending analysis before returning.\n\n## Query Parameters\n\nThis endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `poll`, `cachedResultsOnly`, and `summary`.\n\nAdditionally, you may provide a `labels` query parameter to apply a repository label's security policies. Pass the label slug as the value (e.g., `?labels=production`). Only one label is currently supported.\n\n## Examples:\n\n### Looking up an npm package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\n### Looking up a PyPi package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n }\n ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n },\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n },\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### With label and options (query parameters):\n\n```\nPOST /v0/orgs/{org_slug}/purl?labels=production&alerts=true&compact=true\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\nThis endpoint consumes 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list", "responses": { "200": { "content": { @@ -41388,7 +41885,7 @@ "tags": [ "fixes" ], - "summary": "Fetch fixes for vulnerabilities in a repository or scan", + "summary": "Fetch fixes for vulnerabilities in a repository, scan, or uploaded manifest", "operationId": "fetch-fixes", "parameters": [ { @@ -41418,6 +41915,15 @@ "type": "string" } }, + { + "name": "tar_hash", + "in": "query", + "required": false, + "description": "A tarball hash from the upload-manifest-files endpoint. Mutually exclusive with repo_slug and full_scan_id.", + "schema": { + "type": "string" + } + }, { "name": "vulnerability_ids", "in": "query", @@ -41466,6 +41972,25 @@ "type": "boolean", "default": false } + }, + { + "name": "include_all_detected_ghsas", + "in": "query", + "required": false, + "description": "Set to include an allDetectedGhsas field listing every GHSA detected in the project, regardless of the vulnerability_ids filter. Useful for CLI clients that request a specific GHSA and want to show the user which GHSAs actually exist when the request has no overlap.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "autofix_run_id", + "in": "query", + "required": false, + "description": "The id of an autofix-or-upgrade-cli-run record (created via /fixes/register-autofix-or-upgrade-cli-run) to associate this computation with. When set, the server records per-GHSA fix-computation telemetry into autofix_compute_vulnerability and updates the run's autofix_run row, mirroring the legacy /v0/fixes/compute-fixes endpoint. The caller must own the run's organization; foreign-org or unknown ids return 404.", + "schema": { + "type": "string" + } } ], "security": [ @@ -41480,7 +42005,7 @@ ] } ], - "description": "Fetches available fixes for vulnerabilities in a repository or scan.\nRequires either repo_slug or full_scan_id as well as vulnerability_ids to be provided.\nvulnerability_ids can be a comma-separated list of GHSA or CVE IDs, or \"*\" for all vulnerabilities.\n\n## Response Structure\n\nThe response contains a `fixDetails` object where each key is a vulnerability ID (GHSA or CVE) and the value is a discriminated union based on the `type` field.\n\n### Common Fields\n\nAll response variants include:\n- `type`: Discriminator field (one of: \"fixFound\", \"partialFixFound\", \"noFixAvailable\", \"fixNotApplicable\", \"errorComputingFix\")\n- `value`: Object containing the variant-specific data\n\nThe `value` object always contains:\n- `ghsa`: string | null - The GHSA ID\n- `cve`: string | null - The CVE ID (if available)\n- `advisoryDetails`: object | null - Advisory details (only if include_details=true)\n\n### Response Variants\n\n**fixFound**: A complete fix is available for all vulnerable packages\n- `value.fixDetails.fixes`: Array of fix objects, each containing:\n - `purl`: Package URL to upgrade\n - `fixedVersion`: Version to upgrade to\n - `manifestFiles`: Array of manifest files containing the package\n - `updateType`: \"patch\" | \"minor\" | \"major\" | \"unknown\"\n- `value.fixDetails.responsibleDirectDependencies`: (optional) Map of direct dependencies responsible for the vulnerability\n\n**partialFixFound**: Fixes available for some but not all vulnerable packages\n- Same as fixFound, plus:\n- `value.fixDetails.unfixablePurls`: Array of packages that cannot be fixed, each containing:\n - `purl`: Package URL\n - `manifestFiles`: Array of manifest files\n - `reasons`: Human-readable explanations of why the package cannot be upgraded. May contain multiple distinct entries when different dependency chains are blocked for different causes (e.g. one chain has no compatible upstream version; another would require a major version bump skipped by `--no-major-updates`).\n\n**noFixAvailable**: No fix exists for this vulnerability (no patched version published)\n\n**fixNotApplicable**: A patched version of the vulnerable package exists but cannot be applied. The most common cause is that there is no upgrade path through the dependency tree — for example, given a chain `App → A@1.0.0 → B@1.0.0` where `B < 2.0.0` is vulnerable, if no version of `A` accepts `B@2.0.0` the fix cannot be applied without a manual override (e.g. `pnpm overrides`). Other causes include callers passing `--no-major-updates` when the only patched version is a major bump.\n- `value.vulnerableArtifacts`: Array of vulnerable packages with their manifest files\n\n**errorComputingFix**: An error occurred while computing fixes\n- `value.message`: Error description\n\n### Advisory Details (when include_details=true)\n\n- `title`: string | null\n- `description`: string | null\n- `cwes`: string[] - CWE identifiers\n- `severity`: \"LOW\" | \"MODERATE\" | \"HIGH\" | \"CRITICAL\"\n- `cvssVector`: string | null\n- `publishedAt`: string (ISO date)\n- `kev`: boolean - Whether it's a Known Exploited Vulnerability\n- `epss`: number | null - Exploit Prediction Scoring System score\n- `affectedPurls`: Array of affected packages with version ranges\n\nThis endpoint consumes 10 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- fixes:list", + "description": "Fetches available fixes for vulnerabilities in a repository, scan, or uploaded manifest.\nRequires exactly one of repo_slug, full_scan_id, or tar_hash, as well as vulnerability_ids to be provided.\nvulnerability_ids can be a comma-separated list of GHSA or CVE IDs, or \"*\" for all vulnerabilities.\n\n## Response Structure\n\nThe response contains a `fixDetails` object where each key is a vulnerability ID (GHSA or CVE) and the value is a discriminated union based on the `type` field.\n\n### Common Fields\n\nAll response variants include:\n- `type`: Discriminator field (one of: \"fixFound\", \"partialFixFound\", \"noFixAvailable\", \"fixNotApplicable\", \"errorComputingFix\")\n- `value`: Object containing the variant-specific data\n\nThe `value` object always contains:\n- `ghsa`: string | null - The GHSA ID\n- `cve`: string | null - The CVE ID (if available)\n- `advisoryDetails`: object | null - Advisory details (only if include_details=true)\n\n### Response Variants\n\n**fixFound**: A complete fix is available for all vulnerable packages\n- `value.fixDetails.fixes`: Array of fix objects, each containing:\n - `purl`: Package URL to upgrade\n - `fixedVersion`: Version to upgrade to\n - `manifestFiles`: Array of manifest files containing the package\n - `updateType`: \"patch\" | \"minor\" | \"major\" | \"unknown\"\n- `value.fixDetails.responsibleDirectDependencies`: (optional) Map of direct dependencies responsible for the vulnerability\n\n**partialFixFound**: Fixes available for some but not all vulnerable packages\n- Same as fixFound, plus:\n- `value.fixDetails.unfixablePurls`: Array of packages that cannot be fixed, each containing:\n - `purl`: Package URL\n - `manifestFiles`: Array of manifest files\n - `reasons`: Human-readable explanations of why the package cannot be upgraded. May contain multiple distinct entries when different dependency chains are blocked for different causes (e.g. one chain has no compatible upstream version; another would require a major version bump skipped by `--no-major-updates`).\n\n**noFixAvailable**: No fix exists for this vulnerability (no patched version published)\n\n**fixNotApplicable**: A patched version of the vulnerable package exists but cannot be applied. The most common cause is that there is no upgrade path through the dependency tree — for example, given a chain `App → A@1.0.0 → B@1.0.0` where `B < 2.0.0` is vulnerable, if no version of `A` accepts `B@2.0.0` the fix cannot be applied without a manual override (e.g. `pnpm overrides`). Other causes include callers passing `--no-major-updates` when the only patched version is a major bump.\n- `value.vulnerableArtifacts`: Array of vulnerable packages with their manifest files\n\n**errorComputingFix**: An error occurred while computing fixes\n- `value.message`: Error description\n\n### Advisory Details (when include_details=true)\n\n- `title`: string | null\n- `description`: string | null\n- `cwes`: string[] - CWE identifiers\n- `severity`: \"LOW\" | \"MODERATE\" | \"HIGH\" | \"CRITICAL\"\n- `cvssVector`: string | null\n- `publishedAt`: string (ISO date)\n- `kev`: boolean - Whether it's a Known Exploited Vulnerability\n- `epss`: number | null - Exploit Prediction Scoring System score\n- `affectedPurls`: Array of affected packages with version ranges\n\nThis endpoint consumes 10 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- fixes:list", "responses": { "200": { "content": { @@ -41488,7 +42013,6 @@ "schema": { "type": "object", "additionalProperties": false, - "description": "", "properties": { "fixDetails": { "type": "object", @@ -41499,6 +42023,15 @@ }, "properties": {}, "description": "" + }, + "allDetectedGhsas": { + "type": "array", + "items": { + "type": "string", + "description": "", + "default": "GHSA ID of a vulnerability detected in the project" + }, + "description": "All vulnerability GHSA IDs detected in the project, regardless of the vulnerability_ids filter. Only present when include_all_detected_ghsas=true is set." } }, "required": [ diff --git a/src/types-strict.ts b/src/types-strict.ts index 8cbf4a9d..b71c9fc8 100644 --- a/src/types-strict.ts +++ b/src/types-strict.ts @@ -141,6 +141,7 @@ export type RepositoryListItem = { description: string | null head_full_scan_id: string | null homepage: string | null + html_url?: string | undefined id: string integration_meta?: | { @@ -188,6 +189,7 @@ export type RepositoryItem = { description: string | null head_full_scan_id: string | null homepage: string | null + html_url?: string | undefined id: string integration_meta: { /** @enum {string} */ diff --git a/types/api.d.ts b/types/api.d.ts index ecd18333..b19501d3 100644 --- a/types/api.d.ts +++ b/types/api.d.ts @@ -26,6 +26,20 @@ export interface paths { * This endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate). * Actively running analysis will be returned when available on subsequent runs. * + * When `alerts=true`, Socket may synthesize two alert types to make partial + * results actionable: + * + * - `pendingScan`: the package is known but analysis has not completed yet + * - `notFound`: Socket could not resolve the package/version metadata + * + * When `purlErrors=true`, unresolved `notFound` inputs keep the legacy + * `purlError` stream shape instead of emitting synthetic `notFound` + * artifacts. + * + * Use `poll=false` (default) to fail open and return the current known state + * quickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for + * pending analysis before returning. + * * ## Examples: * * ### Looking up an npm package: @@ -1052,9 +1066,23 @@ export interface paths { * This endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate). * Actively running analysis will be returned when available on subsequent runs. * + * When `alerts=true`, Socket may synthesize two alert types to make partial + * results actionable: + * + * - `pendingScan`: the package is known but analysis has not completed yet + * - `notFound`: Socket could not resolve the package/version metadata + * + * When `purlErrors=true`, unresolved `notFound` inputs keep the legacy + * `purlError` stream shape instead of emitting synthetic `notFound` + * artifacts. + * + * Use `poll=false` (default) to fail open and return the current known state + * quickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for + * pending analysis before returning. + * * ## Query Parameters * - * This endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `cachedResultsOnly`, and `summary`. + * This endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `poll`, `cachedResultsOnly`, and `summary`. * * Additionally, you may provide a `labels` query parameter to apply a repository label's security policies. Pass the label slug as the value (e.g., `?labels=production`). Only one label is currently supported. * @@ -1136,9 +1164,9 @@ export interface paths { } '/orgs/{org_slug}/fixes': { /** - * Fetch fixes for vulnerabilities in a repository or scan - * @description Fetches available fixes for vulnerabilities in a repository or scan. - * Requires either repo_slug or full_scan_id as well as vulnerability_ids to be provided. + * Fetch fixes for vulnerabilities in a repository, scan, or uploaded manifest + * @description Fetches available fixes for vulnerabilities in a repository, scan, or uploaded manifest. + * Requires exactly one of repo_slug, full_scan_id, or tar_hash, as well as vulnerability_ids to be provided. * vulnerability_ids can be a comma-separated list of GHSA or CVE IDs, or "*" for all vulnerabilities. * * ## Response Structure @@ -4081,6 +4109,16 @@ export interface components { usage?: components['schemas']['SocketUsageRef'] } } + | { + /** @enum {string} */ + type?: 'pendingScan' + value?: components['schemas']['SocketIssueBasics'] & { + /** @default */ + description: string + props: Record + usage?: components['schemas']['SocketUsageRef'] + } + } | { /** @enum {string} */ type?: 'deprecated' @@ -4253,6 +4291,16 @@ export interface components { usage?: components['schemas']['SocketUsageRef'] } } + | { + /** @enum {string} */ + type?: 'notFound' + value?: components['schemas']['SocketIssueBasics'] & { + /** @default */ + description: string + props: Record + usage?: components['schemas']['SocketUsageRef'] + } + } | { /** @enum {string} */ type?: 'unpopularPackage' @@ -5535,6 +5583,20 @@ export interface operations { * This endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate). * Actively running analysis will be returned when available on subsequent runs. * + * When `alerts=true`, Socket may synthesize two alert types to make partial + * results actionable: + * + * - `pendingScan`: the package is known but analysis has not completed yet + * - `notFound`: Socket could not resolve the package/version metadata + * + * When `purlErrors=true`, unresolved `notFound` inputs keep the legacy + * `purlError` stream shape instead of emitting synthetic `notFound` + * artifacts. + * + * Use `poll=false` (default) to fail open and return the current known state + * quickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for + * pending analysis before returning. + * * ## Examples: * * ### Looking up an npm package: @@ -5613,11 +5675,13 @@ export interface operations { licensedetails?: boolean /** @description Return errors found with handling PURLs as error objects in the stream. */ purlErrors?: boolean - /** @description Return only cached results, do not attempt to scan new artifacts or rescan stale results. */ + /** @description When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors. */ + poll?: boolean + /** @description Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior. */ cachedResultsOnly?: boolean /** @description Include a summary object at the end of the stream with counts of malformed, resolved, and not found PURLs. */ summary?: boolean - /** @description Maximum time in seconds to wait for scan results. PURLs that have not completed processing when the timeout is reached will be returned as errors (when purlErrors is enabled). Omit for no timeout. */ + /** @description Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan alerts when alerts=true, or errors when purlErrors=true. */ timeoutSec?: number } } @@ -7931,10 +7995,10 @@ export interface operations { */ updated_at?: string /** - * @description The slug of the repository + * @description The URL to the repository dashboard page * @default */ - slug?: string + html_url?: string /** * @description The ID of the head full scan of the repository * @default @@ -7966,6 +8030,11 @@ export interface operations { repo_id: string | null } } | null + /** + * @description The slug of the repository. + * @default + */ + slug?: string /** * @description The name of the repository * @default @@ -8028,6 +8097,10 @@ export interface operations { */ createOrgRepo: { parameters: { + query?: { + /** @description Set to "redirect" to receive a 302 redirect to the existing repo instead of a 409 error when a duplicate slug is detected. */ + on_duplicate?: string + } path: { /** @description The slug of the organization */ org_slug: string @@ -8037,7 +8110,7 @@ export interface operations { content: { 'application/json': { /** - * @description The name of the repository + * @description The display name of the repository. When provided without a slug, the slug is automatically derived from the name. When omitted, the slug is used as the name. At least one of name or slug must be provided. * @default */ name?: string @@ -8072,6 +8145,11 @@ export interface operations { * @default */ workspace?: string + /** + * @description The slug of the repository. If provided, used directly instead of being derived from name. Must only contain ASCII letters, digits, and the characters ., -, and _. + * @default + */ + slug?: string } } } @@ -8096,10 +8174,109 @@ export interface operations { */ updated_at?: string /** - * @description The slug of the repository + * @description The URL to the repository dashboard page + * @default + */ + html_url?: string + /** + * @description The ID of the head full scan of the repository + * @default + */ + head_full_scan_id?: string | null + integration_meta?: { + /** @enum {string} */ + type?: 'github' + value?: { + /** + * @description The GitHub installation_id of the active associated Socket GitHub App + * @default + */ + installation_id: string + /** + * @description The GitHub login name that the active Socket GitHub App installation is installed to + * @default + */ + installation_login: string + /** + * @description The name of the associated GitHub repo. + * @default + */ + repo_name: string | null + /** + * @description The id of the associated GitHub repo. + * @default + */ + repo_id: string | null + } + } | null + /** + * @description The slug of the repository. * @default */ slug?: string + /** + * @description The name of the repository + * @default + */ + name?: string + /** + * @description The description of the repository + * @default + */ + description?: string | null + /** + * @description The homepage URL of the repository + * @default + */ + homepage?: string | null + /** + * @description The visibility of the repository + * @default private + * @enum {string} + */ + visibility?: 'public' | 'private' + /** + * @description Whether the repository is archived or not + * @default false + */ + archived?: boolean + /** + * @description The default branch of the repository + * @default main + */ + default_branch?: string | null + /** + * @description The workspace of the repository + * @default + */ + workspace?: string + } + } + } + /** @description Redirects to the existing repository when on_duplicate=redirect is set and a duplicate slug is detected. */ + 302: { + content: { + 'application/json': { + /** + * @description The ID of the repository + * @default + */ + id?: string + /** + * @description The creation date of the repository + * @default + */ + created_at?: string + /** + * @description The last update date of the repository + * @default + */ + updated_at?: string + /** + * @description The URL to the repository dashboard page + * @default + */ + html_url?: string /** * @description The ID of the head full scan of the repository * @default @@ -8131,6 +8308,11 @@ export interface operations { repo_id: string | null } } | null + /** + * @description The slug of the repository. + * @default + */ + slug?: string /** * @description The name of the repository * @default @@ -8174,6 +8356,7 @@ export interface operations { 401: components['responses']['SocketUnauthorized'] 403: components['responses']['SocketForbidden'] 404: components['responses']['SocketNotFoundResponse'] + 409: components['responses']['SocketConflict'] 429: components['responses']['SocketTooManyRequestsResponse'] } } @@ -8220,10 +8403,10 @@ export interface operations { */ updated_at: string /** - * @description The slug of the repository + * @description The URL to the repository dashboard page * @default */ - slug: string + html_url: string /** * @description The ID of the head full scan of the repository * @default @@ -8255,6 +8438,11 @@ export interface operations { repo_id: string | null } } | null + /** + * @description The slug of the repository. + * @default + */ + slug: string /** * @description The name of the repository * @default @@ -8391,10 +8579,10 @@ export interface operations { */ updated_at?: string /** - * @description The slug of the repository + * @description The URL to the repository dashboard page * @default */ - slug?: string + html_url?: string /** * @description The ID of the head full scan of the repository * @default @@ -8426,6 +8614,11 @@ export interface operations { repo_id: string | null } } | null + /** + * @description The slug of the repository. + * @default + */ + slug?: string /** * @description The name of the repository * @default @@ -9391,6 +9584,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + pendingScan?: { + /** + * @description The action to take for pendingScan issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } deprecated?: { /** * @description The action to take for deprecated issues. @@ -9475,6 +9675,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + notFound?: { + /** + * @description The action to take for notFound issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } unpopularPackage?: { /** * @description The action to take for unpopularPackage issues. @@ -10382,6 +10589,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + pendingScan?: { + /** + * @description The action to take for pendingScan issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } deprecated?: { /** * @description The action to take for deprecated issues. @@ -10466,6 +10680,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + notFound?: { + /** + * @description The action to take for notFound issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } unpopularPackage?: { /** * @description The action to take for unpopularPackage issues. @@ -11527,6 +11748,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + pendingScan?: { + /** + * @description The action to take for pendingScan issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } deprecated?: { /** * @description The action to take for deprecated issues. @@ -11611,6 +11839,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + notFound?: { + /** + * @description The action to take for notFound issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } unpopularPackage?: { /** * @description The action to take for unpopularPackage issues. @@ -12511,6 +12746,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + pendingScan?: { + /** + * @description The action to take for pendingScan issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } deprecated?: { /** * @description The action to take for deprecated issues. @@ -12595,6 +12837,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + notFound?: { + /** + * @description The action to take for notFound issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } unpopularPackage?: { /** * @description The action to take for unpopularPackage issues. @@ -13464,6 +13713,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + pendingScan?: { + /** + * @description The action to take for pendingScan issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } deprecated?: { /** * @description The action to take for deprecated issues. @@ -13548,6 +13804,13 @@ export interface operations { */ action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' } + notFound?: { + /** + * @description The action to take for notFound issues. + * @enum {string} + */ + action: 'defer' | 'error' | 'warn' | 'monitor' | 'ignore' + } unpopularPackage?: { /** * @description The action to take for unpopularPackage issues. @@ -15507,6 +15770,7 @@ export interface operations { | 'CreateWebhook' | 'CreateTicket' | 'CoanaCliLegacyModeCutoffUpdated' + | 'CoanaCliLegacyModeDemoteOrg' | 'CoanaCliLegacyModePromoteOrg' | 'DeleteAlertTriage' | 'DeleteApiToken' @@ -15522,6 +15786,7 @@ export interface operations { | 'DisassociateLabel' | 'DisconnectJiraIntegration' | 'DowngradeOrganizationPlan' + | 'EnqueueAutopatchPrepareJob' | 'JoinOrganization' | 'JiraIntegrationConnected' | 'MemberAdded' @@ -15536,6 +15801,7 @@ export interface operations { | 'RevokeApiToken' | 'RotateApiToken' | 'SendInvitation' + | 'SessionRevokedByUser' | 'SetLabelSettingToDefault' | 'SSOEmailVerificationCompleted' | 'SSOLoginCompleted' @@ -15548,6 +15814,7 @@ export interface operations { | 'UpdateApiTokenScopes' | 'UpdateApiTokenVisibility' | 'UpdateAutopatchCurated' + | 'UpdateAutopatchPrepareConfig' | 'UpdateFirewallCustomRegistry' | 'UpdateFirewallDeploymentConfig' | 'UpdateLabel' @@ -16701,9 +16968,23 @@ export interface operations { * This endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate). * Actively running analysis will be returned when available on subsequent runs. * + * When `alerts=true`, Socket may synthesize two alert types to make partial + * results actionable: + * + * - `pendingScan`: the package is known but analysis has not completed yet + * - `notFound`: Socket could not resolve the package/version metadata + * + * When `purlErrors=true`, unresolved `notFound` inputs keep the legacy + * `purlError` stream shape instead of emitting synthetic `notFound` + * artifacts. + * + * Use `poll=false` (default) to fail open and return the current known state + * quickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for + * pending analysis before returning. + * * ## Query Parameters * - * This endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `cachedResultsOnly`, and `summary`. + * This endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `poll`, `cachedResultsOnly`, and `summary`. * * Additionally, you may provide a `labels` query parameter to apply a repository label's security policies. Pass the label slug as the value (e.g., `?labels=production`). Only one label is currently supported. * @@ -16800,11 +17081,13 @@ export interface operations { licensedetails?: boolean /** @description Return errors found with handling PURLs as error objects in the stream. */ purlErrors?: boolean - /** @description Return only cached results, do not attempt to scan new artifacts or rescan stale results. */ + /** @description When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors. */ + poll?: boolean + /** @description Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior. */ cachedResultsOnly?: boolean /** @description Include a summary object at the end of the stream with counts of malformed, resolved, and not found PURLs. */ summary?: boolean - /** @description Maximum time in seconds to wait for scan results. PURLs that have not completed processing when the timeout is reached will be returned as errors (when purlErrors is enabled). Omit for no timeout, unless a default timeout is configured for the organization. */ + /** @description Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan alerts when alerts=true, or errors when purlErrors=true. */ timeoutSec?: number } path: { @@ -16832,9 +17115,9 @@ export interface operations { } } /** - * Fetch fixes for vulnerabilities in a repository or scan - * @description Fetches available fixes for vulnerabilities in a repository or scan. - * Requires either repo_slug or full_scan_id as well as vulnerability_ids to be provided. + * Fetch fixes for vulnerabilities in a repository, scan, or uploaded manifest + * @description Fetches available fixes for vulnerabilities in a repository, scan, or uploaded manifest. + * Requires exactly one of repo_slug, full_scan_id, or tar_hash, as well as vulnerability_ids to be provided. * vulnerability_ids can be a comma-separated list of GHSA or CVE IDs, or "*" for all vulnerabilities. * * ## Response Structure @@ -16901,6 +17184,8 @@ export interface operations { repo_slug?: string /** @description The ID of the scan to fetch fixes for */ full_scan_id?: string + /** @description A tarball hash from the upload-manifest-files endpoint. Mutually exclusive with repo_slug and full_scan_id. */ + tar_hash?: string /** @description Comma-separated list of GHSA or CVE IDs, or "*" for all vulnerabilities */ vulnerability_ids: string /** @description Whether to allow major version updates in fixes */ @@ -16911,6 +17196,10 @@ export interface operations { include_details?: boolean /** @description Set to include the direct dependencies responsible for introducing the dependency or dependencies with the vulnerability in the response */ include_responsible_direct_dependencies?: boolean + /** @description Set to include an allDetectedGhsas field listing every GHSA detected in the project, regardless of the vulnerability_ids filter. Useful for CLI clients that request a specific GHSA and want to show the user which GHSAs actually exist when the request has no overlap. */ + include_all_detected_ghsas?: boolean + /** @description The id of an autofix-or-upgrade-cli-run record (created via /fixes/register-autofix-or-upgrade-cli-run) to associate this computation with. When set, the server records per-GHSA fix-computation telemetry into autofix_compute_vulnerability and updates the run's autofix_run row, mirroring the legacy /v0/fixes/compute-fixes endpoint. The caller must own the run's organization; foreign-org or unknown ids return 404. */ + autofix_run_id?: string } path: { /** @description The slug of the organization */ @@ -16925,6 +17214,8 @@ export interface operations { fixDetails: { [key: string]: Record } + /** @description All vulnerability GHSA IDs detected in the project, regardless of the vulnerability_ids filter. Only present when include_all_detected_ghsas=true is set. */ + allDetectedGhsas?: string[] } } }