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:
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
attribText
attribute 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 theattribText
field, but if the license information concerns the presence of an SPDX identifierMIT
in the package.json file,attribText
will contain the base text of the MIT license. - The
attribData
attribute 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. Thepurl
attribute corresponds to thepurl
of the resource in which this license information was found, whilefoundInFilepath
contains the relative path to the location of the license information within the resource (package or artifact).foundInFilepath
may be null if the license information was gleaned from resource metadata.spdxExpr
contains an SPDX expression describing the license content.foundAuthors
is 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 particularattribData
will 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
spdxDisj
attribute contains an SPDX expression identifying the license match - The
provenance
attribute 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
filepath
attribute 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_strength
property 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
.