VulnCheck.Semver (VulnCheck v1.0.1)

Copy Markdown View Source

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

parsed()

@type parsed() :: {[non_neg_integer()], [String.t() | non_neg_integer()]}

Functions

affected?(version, advisory)

@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.

affected?(version, ranges, versions)

@spec affected?(String.t(), [VulnCheck.Types.VersionRange.t()], [String.t()]) ::
  boolean()

Checks a single source's numbered intervals and explicit versions.

compare(a, b)

@spec compare(String.t(), String.t()) :: :lt | :eq | :gt

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")
:lt

Unparseable versions are compared as plain strings.

fixed_versions(ranges)

@spec fixed_versions([VulnCheck.Types.VersionRange.t()]) :: [String.t()]

Collects the fixed versions declared by a list of ranges.

from_cve_affected(entry)

@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.

from_cve_git_versions(entry)

@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.

from_cve_versions(versions)

@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.

from_osv_git_ranges(ranges)

@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.

from_osv_ranges(ranges)

@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.

git_affected?(package, advisory)

@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.

in_range?(version, range)

@spec in_range?(String.t(), VulnCheck.Types.VersionRange.t()) :: boolean()

Returns true when version lies inside the range.

otp_affected?(otp_release, constraints)

@spec otp_affected?(String.t(), String.t() | nil) :: boolean()

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

parse(version)

@spec parse(String.t()) :: {:ok, parsed()} | :error

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

same_commit?(a, b)

@spec same_commit?(term(), term()) :: boolean()

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.

sort(versions)

@spec sort([String.t()]) :: [String.t()]

Sorts versions in ascending order.

valid?(version)

@spec valid?(String.t()) :: boolean()

Returns true when the string is a version this module understands.