> For the complete documentation index, see [llms.txt](https://docs.sealsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealsecurity.io/reference/public-api/list-vulnerable-packages.md). # List vulnerable packages **Description:** Retrieves a list of vulnerable packages, with options to filter the results based on various criteria such as package name, visibility, token role, and remediation status. {% hint style="warning" %} Because sometimes a new vulnerability comes out after a sealed version already exists, a newer sealed version is released. For example, `ejs@2.7.4` had two vulnerabilities that were sealed in `ejs@2.7.4-sp1`. Another vulnerability was then discovered, which required the release of `ejs@2.7.4-sp2`. In that case, if `ejs@2.7.4-sp1` is being used by the tenant, since that package contains an open unpatched vulnerability, it is returned by this endpoint. {% endhint %} **Path:** `https://external.sealsecurity.io/authenticated/api/v1/packages/vulnerable` **Method:** GET **Authentication:** Bearer token. See [Authentication](/reference/public-api.md#authentication). #### Request parameters All query parameters are optional. | Parameter | Type | Description | Accepted values | | ----------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `package_name_contains` | string | Filter packages whose name contains this substring. | Any string | | `is_hidden` | boolean | Filter packages by hide state. | `true`, `false` | | `access_token_role` | string | Filter packages by the role of the token that detected them. | `Production`, `Development` | | `fix_availability` | string | Filter packages by their remediation state. | `cant_generate_sealed_version`, `can_generate_sealed_version`, `generating_sealed_version`, `sealed_version_available`, `sealed_version_pending_deploy`, `sealed_version_deployed` | | `is_dev_dependency` | string | Filter packages by dev-dependency status. `yes` returns dev dependencies; `maybe` returns packages whose dev-dependency status Seal could not determine. Omit the parameter to return both. There is no `no` value — filtering for "definitely not a dev dependency" is not supported. | `maybe`, `yes` | | `since` | string (ISO 8601 datetime) | Return only packages with state updates after this time. | Any ISO 8601 datetime | | `vulnerability_name` | string | Return only packages affected by a vulnerability with this identifier. | Any string | | `version_id` | UUID | Return only the row matching a specific library-version ID. | Any UUID | | `project_id` | UUID (repeatable) | Restrict results to one or more Seal Project IDs. | UUID(s) | | `open_severities` | string (repeatable) | Restrict results to packages with at least one open vulnerability at the listed severities. | `Low`, `Medium`, `High`, `Critical` | | `package_manager` | string (repeatable) | Restrict to one or more ecosystems. | `NPM`, `PyPI`, `Maven`, `GO`, `Composer`, `RubyGems`, `NuGet`, `APK`, `DEB`, `RPM`, and so on | | `limit` | integer | Page size. Default 50, max 100. | 1 to 100 | | `offset` | integer | Page offset. Default 0. | Non-negative integer | | `sort_by` | string | Sort key. | `default`, `ecosystem`, `fix_availability`, `package`, `time`, `score`, `project`, `version` | | `sort_direction` | string | Sort direction. | `asc`, `desc` | **Details for `fix_availability` request values:** * `cant_generate_sealed_version`: the package has no sealed version, and Seal cannot generate one. * `can_generate_sealed_version`: the package has no sealed version yet; you can request one with the Generate fix button. * `generating_sealed_version`: Seal is currently building a sealed version. * `sealed_version_available`: a sealed version is available; no Sealing Rule has been applied yet. * `sealed_version_pending_deploy`: a Sealing Rule has been created; the next CLI run will substitute the sealed version. * `sealed_version_deployed`: the sealed version is in use. {% hint style="warning" %} **The request and response use different value sets for the same concept.** The query parameter accepts the long-form values above; the response field returns the short-form values listed under Response Fields. To filter for sealed packages, send `?fix_availability=sealed_version_deployed`, not `?fix_availability=sealed`. The mapping: {% endhint %} | Request value (filter) | Response value (state) | | ------------------------------- | ---------------------- | | `sealed_version_deployed` | `sealed` | | `sealed_version_pending_deploy` | `pending_deploy` | | `sealed_version_available` | `seal_available` | | `generating_sealed_version` | `fix_in_preparation` | | `can_generate_sealed_version` | `generate_fix` | | `cant_generate_sealed_version` | `unfixable` | #### Response The API returns a paginated JSON object containing a page of vulnerable packages. **Response Structure:** ```json { "items": [ { "package_name": "string", "package_version": "string", "ecosystem": "string", "project_name": "string", "open_vulnerabilities_in_original_package": [ { "cve": "string", "score": "float" } ], "fix_availability": "string", "replaced_by_sealed_version": "string", "open_vulnerabilities_in_sealed_version": [ { "cve": "string", "score": "float" } ], "sealed_vulnerabilities_in_sealed_version": [ { "cve": "string", "score": "float" } ], "last_seen": "string", "access_token_role": "string", "is_hidden": "boolean" } ], "total": "integer", "limit": "integer", "offset": "integer" } ``` **Response Fields:** | Field | Type | Description | | -------- | ----------------------------------- | -------------------------------------------------------------------------- | | `items` | array of vulnerable package objects | The page of vulnerable packages. See the per-object fields below. | | `total` | integer | Total number of vulnerable packages matching the filters across all pages. | | `limit` | integer | The page size that was used. | | `offset` | integer | The offset that was used. | Each vulnerable package object: | Field | Type | Description | | ------------------------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `package_name` | string | The name of the package. | | `package_version` | string | The version of the package. | | `ecosystem` | string | The ecosystem (for example, `NPM`, `PyPI`, `Maven`). | | `project_name` | string | The name of the Seal Project where the package was discovered. | | `open_vulnerabilities_in_original_package` | array of vulnerability objects | Vulnerabilities open in the original (unsealed) package. | | `fix_availability` | string | Remediation state of the package. Response values: `sealed`, `pending_deploy`, `seal_available`, `fix_in_preparation`, `generate_fix`, `unfixable`. These are the short-form values; the request parameter accepts a different (long-form) set — see the mapping table in the Request parameters section. | | `replaced_by_sealed_version` | string or null | The sealed version currently in use as a replacement (when `fix_availability` is `sealed`); `null` otherwise. | | `open_vulnerabilities_in_sealed_version` | array of vulnerability objects | Vulnerabilities still open in the sealed version currently in use (a safer sealed version may exist). | | `sealed_vulnerabilities_in_sealed_version` | array of vulnerability objects | Vulnerabilities patched in the sealed version currently in use. | | `last_seen` | string (ISO 8601) | When the package was last discovered. | | `access_token_role` | string | The role of the token that detected the package (`Production` or `Development`). | | `is_hidden` | boolean | Whether the package is hidden. | The vulnerability object: | Field | Type | Description | | ------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `cve` | string | Vulnerability identifier (for example, `CVE-2023-1234`). If no public CVE exists, a GHSA identifier is used; if neither, a Snyk identifier. | | `score` | float or null | CVSS risk score. `null` means the vulnerability is rated Low severity. | #### Example requests and responses **1. Get all vulnerable packages:** **Request (cURL):** ```bash curl -X GET \ 'https://external.sealsecurity.io/authenticated/api/v1/packages/vulnerable' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` **Example Response (truncated):** ```json { "items": [ { "package_name": "lodash", "package_version": "4.17.21", "ecosystem": "NPM", "project_name": "MyWebApp", "open_vulnerabilities_in_original_package": [ { "cve": "CVE-2021-23336", "score": 7.5 } ], "fix_availability": "seal_available", "replaced_by_sealed_version": null, "open_vulnerabilities_in_sealed_version": [], "sealed_vulnerabilities_in_sealed_version": [], "last_seen": "2025-05-10T14:30:00Z", "access_token_role": "Production", "is_hidden": false }, { "package_name": "spring-core", "package_version": "5.3.2", "ecosystem": "Maven", "project_name": "InternalService", "open_vulnerabilities_in_original_package": [ { "cve": "CVE-2022-22965", "score": 9.8 } ], "fix_availability": "unfixable", "replaced_by_sealed_version": null, "open_vulnerabilities_in_sealed_version": [], "sealed_vulnerabilities_in_sealed_version": [], "last_seen": "2025-05-09T10:00:00Z", "access_token_role": "Development", "is_hidden": false } ], "total": 124, "limit": 50, "offset": 0 } ``` **2. Filter packages by name and fix availability:** **Request (cURL):** ```bash curl -X GET \ 'https://external.sealsecurity.io/authenticated/api/v1/packages/vulnerable?package_name_contains=spring&fix_availability=sealed_version_deployed' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` **Example Response:** ```json { "items": [ { "package_name": "spring-webflux", "package_version": "5.3.2", "ecosystem": "Maven", "project_name": "UserFacingApp", "open_vulnerabilities_in_original_package": [ { "cve": "CVE-2021-22096", "score": 7.0 } ], "fix_availability": "sealed", "replaced_by_sealed_version": "5.3.2+sp1", "open_vulnerabilities_in_sealed_version": [], "sealed_vulnerabilities_in_sealed_version": [ { "cve": "CVE-2021-22096", "score": 7.0 } ], "last_seen": "2025-05-08T11:45:00Z", "access_token_role": "Production", "is_hidden": false } ], "total": 1, "limit": 50, "offset": 0 } ```