Batch retrieval of package metadata and alerts by PURL strings. Compatible witch CycloneDX reports.
Package URLs (PURLs) are an ecosystem agnostic way to identify packages.
CycloneDX SBOMs use the purl format to identify components.
This 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.
More information on purl and CycloneDX:
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.
Examples:
Looking up an npm package:
{
"components": [
{
"purl": "pkg:npm/[email protected]"
}
]
}
Looking up an PyPi package:
{
"components": [
{
"purl": "pkg:pypi/[email protected]"
}
]
}
Looking up a Maven package:
{
"components": [
{
"purl": "pkg:maven/log4j/[email protected]"
}
]
}
Batch lookup
{
"components": [
{
"purl": "pkg:npm/[email protected]"
},
{
"purl": "pkg:pypi/[email protected]"
},
{
"purl": "pkg:maven/log4j/[email protected]"
}
]
}
This endpoint consumes 100 units of your quota.
This endpoint requires the following org token scopes:
- packages:list
License Attribution
License attribution information for a resource at a given PURL can be requested by setting the query parameter licenseattrib=true. License attribution information is returned as a JSON object in the following format:
attribText: string
attribData: Array<{
purl: string,
foundInFilepath?: string
spdxExpr: string,
foundAuthors: Array<string>
}>
- The
attribTextattribute contains the contents of the license that was found, or the model text of the license if the license information was found via package metadata. For example, if an npm package contains a LICENSE file with slight modifications inserting the actual author names and copyright dates, the precise contents of that LICENSE file will occupy theattribTextfield, but if the license information concerns the presence of an SPDX identifierMITin the package.json file,attribTextwill contain the base text of the MIT license. - The
attribDataattribute is an array with one element for each occurrence of the license text in question. Because an identical license text may be used an arbitrary number of times in a large code base, this helps keep the size of responses manageable. Thepurlattribute corresponds to thepurlof the resource in which this license information was found, whilefoundInFilepathcontains the relative path to the location of the license information within the resource (package or artifact).foundInFilepathmay be null if the license information was gleaned from resource metadata.spdxExprcontains an SPDX expression describing the license content.foundAuthorsis an array of additional author information found which is relevant to that particular appearance/instance of the license. For example, if a python package has a pyproject.toml file which identifies the MIT license and contains an array of author names and email addresses, the array entry for that particularattribDatawill have a purl pointing to that package/artifact, a relative path to the pyproject.toml file, an SPDX expression identifying the MIT license, and an array containing the author information present in the pyproject.toml file.
License Details
More fine-grained details concerning license identification can be requested by setting the query parameter licensedetails=true. License details are returned as a JSON object in the following format:
spdxDisj: string
provenance: string
filepath?: string
match_strength: float
- The
spdxDisjattribute contains an SPDX expression identifying the license match - The
provenanceattribute contains information concerning the provenance of the license data (in a more detailed sense than just resource path, where did we find this license info?) - The
filepathattribute contains a relative path to the resource used to identify this license information if it exists (for license information taken from something like package metadata, there may not be an appropriate filepath) - The
match_strengthproperty contains a value between 0 and 1 describing the strength of the license match (0 for no similarity, 1 for identical contents). For license data found by examining SPDX expressions, this property will be1.