Socket Package URLs (purl)

This page describes how Socket purls work

What is a Socket purl?

A Socket purl is based on the standard as documented here. There is a good description from that page:

A packageUrl (commonly pronounced and referred to as "purl") is an attempt to standardize package representations in order to reliably identify and locate software packages. A purl is a URL string which represents a package in a mostly universal and uniform way across programming languages, package managers, packaging conventions, tools, APIs and databases.

A Socket purl as used with the packages API and the specific definition for the format can be found at the Github Spec.

Constructing a Socket purl

The format for a purl is like the following:

scheme:type/namespace/name@version

In the case of the Socket Packages endpoint the scheme is always going to be pkg. Here are some examples for different ecosystems:

npm

pkg:npm/[email protected]

Python

pkg:pypi/[email protected]

Maven

pkg:maven/log4j/[email protected]

Chrome extensions

The name is the 32-character extension ID from the Chrome Web Store listing URL.

pkg:chrome/[email protected]

Firefox add-ons

The name is the add-on ID, the browser_specific_settings.gecko.id value from the add-on's manifest.json, also returned as guid by the Mozilla API. Mozilla allows two forms, an email-style string or a GUID in braces:

pkg:firefox-extension/uBlock0%[email protected]
pkg:firefox-extension/{d10d0bf8-f5b5-c8b4-a8b2-2b9879e08c5d}@4.14
📘

Use the add-on ID, not the marketplace slug

The slug in an addons.mozilla.org listing URL (for example ublock-origin) is a mutable website label. Mozilla does not redirect renamed slugs, and a freed slug can be claimed by a different add-on. Only the add-on ID is stable identity, so the Socket API accepts add-on IDs alone.

The @ in an email-style add-on ID is percent-encoded as %40 per the purl spec, but Socket also accepts it raw: pkg:firefox-extension/[email protected]@1.66.4, and pkg:firefox-extension/[email protected] with no version.

VS Code and Open VSX extensions

VS Code extensions use a different purl type for each registry. In both, the namespace is the publisher ID and the name is the extension name, the two halves of the publisher.name identifier shown on the extension's listing page.

Extensions from the VS Code Marketplace use the vscode-extension type:

pkg:vscode-extension/ms-python/[email protected]

Extensions from the Open VSX registry use the vscode type:

pkg:vscode/ms-python/[email protected]?platform=universal&repository_url=https%3A%2F%2Fopen-vsx.org

The repository_url qualifier is optional, since vscode purls always refer to Open VSX, so this is equivalent:

pkg:vscode/ms-python/[email protected]?platform=universal

Platform-specific builds can be selected with the platform qualifier, for example ?platform=darwin-arm64. When platform is omitted, Socket uses the universal build.