List vulnerable packages
List vulnerable packages, with filters.
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.
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.
Path: https://external.sealsecurity.io/authenticated/api/v1/packages/vulnerable
Method: GET
Authentication: Bearer token. See Authentication.
Request parameters
All query parameters are optional.
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 building a sealed version at your tenant's request.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.
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:
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:
Response Fields:
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:
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.
safest_sealed_version
string or null
The latest released sealed version for this package version, chosen across public sealed versions and any private versions enabled for this Seal Project. Reported independently of any Sealing Rule. null when none exist.
safer_version_in_preparation
boolean
Whether Seal is building a new sealed version for this package version at your tenant's request. It is a property of the origin version, so every entry in the sealed chain (2.7.4, 2.7.4-sp1, 2.7.4-sp2) reports the same value. Can be true while fix_availability is already seal_available, pending_deploy, or sealed, which is the case when you have asked for a newer sealed version of a package you have already sealed.
The vulnerability object:
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):
Example Response (truncated):
2. Filter packages by name and fix availability:
Request (cURL):
Example Response:
3. List the builds your tenant has requested:
Request (cURL):
Example Response:
4. A sealed package with a newer sealed version being built:
safer_version_in_preparation is independent of fix_availability. Here a new vulnerability was found in a sealed version already in use, and your tenant has requested the next sealed version:
Last updated