PURL (Package URL) Generation

flowchart TB subgraph Input["Input Fields (CVEAffected)"] PkgName["packageName"] Vendor["vendor"] Product["product"] CollURL["collectionURL"] Eco["ecosystem (derived)"] end subgraph TypeDerivation["PURL Type Derivation"] EcoMap["Ecosystem → PURL Type
50+ mappings"] URLPattern["Registry URL Pattern
20+ regex patterns"] HashFallback["Hash Present → github"] GenericFallback["Default → generic"] end subgraph NamespaceDerivation["Namespace Derivation"] Maven["maven: vendor or group:artifact split"] Golang["golang: path segments (all but last)"] Docker["docker: org from image path"] GitHub["github/bitbucket: owner from repo URL"] Composer["composer: vendor/package split"] DistPkg["deb/rpm/apk: vendor"] NoNS["npm/pypi/cargo/etc: no namespace"] end subgraph Build["PURL Assembly"] Scheme["pkg:{type}"] NS["/{namespace} (optional)"] Name["/{name}"] Version["@{version} (optional)"] Quals["?{qualifiers} (optional)"] Subpath["#{subpath} (optional)"] end subgraph Validate["Version Validation"] Wildcards["Reject wildcards: x, X, *"] Ranges["Reject ranges: <, >, =, ^, ~, !"] Boolean["Reject boolean: ||, &&, -"] Multi["Reject multi-constraint"] end PkgName --> Build Product -->|"fallback if packageName empty"| Build CollURL --> URLPattern Eco --> EcoMap EcoMap -->|"matched"| TypeDerivation URLPattern -->|"matched"| TypeDerivation HashFallback -->|"matched"| TypeDerivation GenericFallback -->|"no match"| TypeDerivation TypeDerivation --> NamespaceDerivation NamespaceDerivation --> Build Validate --> Build Build --> Scheme --> NS --> Name --> Version --> Quals --> Subpath

pkg:<type>[/<namespace>]/<name>[@<version>][?<qualifiers>][#<subpath>]

flowchart TD Start["BuildPurl(config)"] CheckEco{"config.Ecosystem
non-empty?"} EcoLookup["ecosystemToPurlType map
normalise lowercase → lookup"] ValidType{"Valid PURL type?
[a-z][a-z0-9+.-]*"} UseEcoType["Use mapped/raw type"] CheckURL{"config.RepoURL
non-empty?"} URLMatch["registryURLPatterns
20+ regex matchers"] UseURLType["Use pattern-matched type"] CheckHash{"config.Hash
non-empty?"} UseGithub["type = 'github'"] UseGeneric["type = 'generic'"] Start --> CheckEco CheckEco -->|"yes"| EcoLookup EcoLookup -->|"found"| UseEcoType EcoLookup -->|"not found"| ValidType ValidType -->|"valid"| UseEcoType ValidType -->|"invalid"| CheckURL CheckEco -->|"no"| CheckURL CheckURL -->|"yes"| URLMatch URLMatch -->|"matched"| UseURLType URLMatch -->|"no match"| CheckHash CheckURL -->|"no"| CheckHash CheckHash -->|"yes"| UseGithub CheckHash -->|"no"| UseGeneric

flowchart TD Type["PURL Type determined"] Maven{"maven?"} MavenNS["Package contains ':'?
group:artifact → namespace = group
else namespace = vendor"] Golang{"golang?"} GolangNS["Package contains '/'?
github.com/org/pkg → ns = github.com/org
else no namespace"] Docker{"docker?"} DockerNS["Package contains '/'?
org/image → namespace = org
else no namespace"] GH{"github/bitbucket?"} GHNS["RepoURL available?
parse path → namespace = owner
else namespace = vendor"] Composer{"composer?"} ComposerNS["Package contains '/'?
vendor/package → namespace = vendor
else namespace = vendor"] Dist{"deb/rpm/apk?"} DistNS["namespace = vendor
(redhat, debian, alpine, etc.)"] Other{"npm/pypi/cargo/gem/
nuget/hex/pub/hackage/
cran/cocoapods/swift/
conda/conan/etc."} NoNS["No namespace"] Type --> Maven Type --> Golang Type --> Docker Type --> GH Type --> Composer Type --> Dist Type --> Other Maven -->|"yes"| MavenNS Golang -->|"yes"| GolangNS Docker -->|"yes"| DockerNS GH -->|"yes"| GHNS Composer -->|"yes"| ComposerNS Dist -->|"yes"| DistNS Other -->|"yes"| NoNS

Input:  @angular/core
Output: pkg:npm/%40angular/core

Input:  @babel/parser@7.22.5
Output: pkg:npm/%40babel/parser@7.22.5

flowchart TD Raw["Raw version string"] Unknown{"'unknown'?"} Wild{"Contains x, X, *?"} Range{"Starts with < > = ^ ~ !?"} Bool{"Contains || && -?"} Multi{"Multiple constraints?"} Strip["Strip operator prefix
(fallback from VersionWithOperator)"] Valid["Valid PURL version"] Invalid["Version omitted from PURL"] Raw --> Unknown Unknown -->|"yes"| Invalid Unknown -->|"no"| Wild Wild -->|"yes"| Invalid Wild -->|"no"| Range Range -->|"yes"| Strip Strip --> Valid Range -->|"no"| Bool Bool -->|"yes"| Invalid Bool -->|"no"| Multi Multi -->|"yes"| Invalid Multi -->|"no"| Valid

pkg:generic/AWS/CloudWatch
pkg:generic/AWS/EC2
pkg:generic/Azure/Key%20Vault
pkg:generic/GCP/Cloud%20SQL

flowchart TD Start["BuildPurl(config)"] PkgName{"config.PackageName
non-empty?"} UsePkg["name = PackageName"] Product{"config.Product
non-empty?"} UseProd["name = Product"] Empty["return '' (empty)"] GenericFallback["fmt.Sprintf('pkg:generic/%s',
url.PathEscape(pkgId))"] Start --> PkgName PkgName -->|"yes"| UsePkg PkgName -->|"no"| Product Product -->|"yes"| UseProd Product -->|"no"| Empty Empty -->|"in handler"| GenericFallback