Version comparison and range matching for Hex, Erlang and OTP versions.
Version.parse/1 rejects many legitimate versions published by Erlang
packages ("2.8", "1.0.2.1", "25"). This module accepts any number of
numeric segments, compares them numerically (missing segments count as
0), and follows SemVer 2.0 for pre-release identifiers
(1.19.0-rc.0 < 1.19.0-rc.1 < 1.19.0) while ignoring +build metadata.
It also evaluates OSV ranges/versions, CVE 5.1 versions and OTP
runtime constraints such as "<= 25" or ">= 24 and <= 25".
Summary
Functions
Returns true when the installed version is affected by the advisory.
Checks a single source's numbered intervals and explicit versions.
Compares two versions.
Collects the fixed versions declared by a list of ranges.
Numbered range hints for a CVE affected product. An affected or unknown default keeps the set open.
Converts the versionType: "git" entries of a CVE 5.1 affected product into
commit intervals (type: :git). Unaffected entries are dropped.
Converts numbered CVE 5.1 versions entries into ranges. Affected and
unknown segments are retained.
Converts the GIT ranges of an OSV ranges array into commit intervals
(type: :git). They are kept apart from numbered ranges and never take part
in version matching.
Converts an OSV ranges array (decoded JSON) into version ranges.
Evaluates whether a git dependency is confirmed, unaffected, or uncertainly
affected by an advisory. Without git commit history, a git dependency is
only marked :unaffected when the upstream repository identity is confirmed
and a non-commit SemVer tag lies outside the advisory's numbered ranges.
Returns true when version lies inside the range.
Evaluates an OTP runtime constraint against an OTP release.
Parses a version string into {numeric_segments, pre_release_identifiers}.
Returns the closest upgrade that fixes the advisory for the installed version, preferring the fix of the release branch the version belongs to.
true when two strings designate the same commit: both are hexadecimal
object ids of at least 12 characters and one is a prefix of the other.
Placeholders such as "0" never match.
Sorts versions in ascending order.
Returns true when the string is a version this module understands.
Types
@type parsed() :: {[non_neg_integer()], [String.t() | non_neg_integer()]}
Functions
@spec affected?(String.t(), VulnCheck.Types.Advisory.t()) :: boolean()
Returns true when the installed version is affected by the advisory.
An advisory with neither ranges nor explicit versions is considered to affect every version (fail-safe). Unparseable installed versions are also considered affected.
@spec affected?(String.t(), [VulnCheck.Types.VersionRange.t()], [String.t()]) :: boolean()
Checks a single source's numbered intervals and explicit versions.
Compares two versions.
iex> VulnCheck.Semver.compare("2.8", "2.8.0")
:eq
iex> VulnCheck.Semver.compare("27.2", "25.3.2.12")
:gt
iex> VulnCheck.Semver.compare("1.19.0-rc.1", "1.19.0")
:ltUnparseable versions are compared as plain strings.
@spec fixed_versions([VulnCheck.Types.VersionRange.t()]) :: [String.t()]
Collects the fixed versions declared by a list of ranges.
@spec from_cve_affected(map()) :: [VulnCheck.Types.VersionRange.t()]
Numbered range hints for a CVE affected product. An affected or unknown default keeps the set open.
@spec from_cve_git_versions(map()) :: [VulnCheck.Types.VersionRange.t()]
Converts the versionType: "git" entries of a CVE 5.1 affected product into
commit intervals (type: :git). Unaffected entries are dropped.
@spec from_cve_versions([map()] | nil) :: [VulnCheck.Types.VersionRange.t()]
Converts numbered CVE 5.1 versions entries into ranges. Affected and
unknown segments are retained.
@spec from_osv_git_ranges([map()] | nil) :: [VulnCheck.Types.VersionRange.t()]
Converts the GIT ranges of an OSV ranges array into commit intervals
(type: :git). They are kept apart from numbered ranges and never take part
in version matching.
@spec from_osv_ranges([map()] | nil) :: [VulnCheck.Types.VersionRange.t()]
Converts an OSV ranges array (decoded JSON) into version ranges.
Each range's events are processed in version order: an introduced event
opens an interval that the next fixed or last_affected event closes.
A limit restricts the range without declaring a fixed release.
GIT ranges are ignored because they cannot be compared with package
versions.
@spec git_affected?(VulnCheck.Types.Package.t(), VulnCheck.Types.Advisory.t()) :: :confirmed | :uncertain | :unaffected
Evaluates whether a git dependency is confirmed, unaffected, or uncertainly
affected by an advisory. Without git commit history, a git dependency is
only marked :unaffected when the upstream repository identity is confirmed
and a non-commit SemVer tag lies outside the advisory's numbered ranges.
@spec in_range?(String.t(), VulnCheck.Types.VersionRange.t()) :: boolean()
Returns true when version lies inside the range.
Evaluates an OTP runtime constraint against an OTP release.
Supported expressions: "< 26", "<= 25", ">= 24 and <= 25",
"24 || 25", "== 25", "25". Comparison happens at the precision of the
constraint, so "<= 25" matches OTP 25.3.2. When the known release
prefix matches a more precise boundary, the comparison remains open.
A nil or unparseable constraint is treated as affecting every runtime.
iex> VulnCheck.Semver.otp_affected?("27", "<= 25")
false
iex> VulnCheck.Semver.otp_affected?("25.3", "<= 25")
true
Parses a version string into {numeric_segments, pre_release_identifiers}.
iex> VulnCheck.Semver.parse("1.19.0-rc.1+build.5")
{:ok, {[1, 19, 0], ["rc", 1]}}
iex> VulnCheck.Semver.parse("2.8")
{:ok, {[2, 8], []}}
iex> VulnCheck.Semver.parse("not a version")
:error
@spec recommended_fix(String.t(), VulnCheck.Types.Advisory.t()) :: String.t() | nil
Returns the closest upgrade that fixes the advisory for the installed version, preferring the fix of the release branch the version belongs to.
For plug 1.16.2 affected by 1.16.0..<1.16.4 and 1.19.0..<1.19.3 this
returns "1.16.4", not "1.19.3".
true when two strings designate the same commit: both are hexadecimal
object ids of at least 12 characters and one is a prefix of the other.
Placeholders such as "0" never match.
Sorts versions in ascending order.
Returns true when the string is a version this module understands.