NPM.Security.Compromised (NPM v0.7.4)

Checks lockfiles against known malicious or compromised npm package reports.

Local reports use the OSV schema used by the OpenSSF malicious-packages repository and OSV.dev MAL-* advisories. This keeps the default check offline and reproducible while allowing callers to supply an updated database path through configuration.

Summary

Types

finding()

source()

Functions

affects?(advisory, package, version)

Return whether an OSV advisory affects an npm package version.

cache_path()

Return the shared global cache path for OSV-format compromised-package reports.

check(lockfile, opts \\ [])

Check a lockfile map against configured compromised-package sources.

check_osv(lockfile, opts \\ [])

Check a lockfile against OSV.dev and return query errors to the caller.

check_package(name, version, opts \\ [])

Check one package version against configured compromised-package sources.

finding_to_json(finding)

Convert a finding to a JSON-encodable map.

format_findings(findings)

Formats compromised-package findings for CLI output.

merge_advisories(existing, new)

Merge advisory lists by OSV id and return stable sorted advisories.

merge_database(path, advisories)

Merge new OSV advisories into an existing local database.

read_database(path \\ cache_path())

Read OSV advisory reports from a local JSON database.

write_database(path, advisories)

Write OSV advisory reports to a local JSON database.

Types

finding()

@type finding() :: %{
  package: String.t(),
  version: String.t(),
  source: source(),
  advisory: map()
}

source()

@type source() :: :local | :osv

Functions

affects?(advisory, package, version)

@spec affects?(map(), String.t(), String.t()) :: boolean()

Return whether an OSV advisory affects an npm package version.

cache_path()

@spec cache_path() :: String.t()

Return the shared global cache path for OSV-format compromised-package reports.

check(lockfile, opts \\ [])

@spec check(
  NPM.Lockfile.t(),
  keyword()
) :: [finding()]

Check a lockfile map against configured compromised-package sources.

check_osv(lockfile, opts \\ [])

@spec check_osv(
  NPM.Lockfile.t(),
  keyword()
) :: {:ok, [finding()]} | {:error, term()}

Check a lockfile against OSV.dev and return query errors to the caller.

check_package(name, version, opts \\ [])

@spec check_package(String.t(), String.t(), keyword()) :: [finding()]

Check one package version against configured compromised-package sources.

finding_to_json(finding)

@spec finding_to_json(finding()) :: map()

Convert a finding to a JSON-encodable map.

format_findings(findings)

@spec format_findings([finding()]) :: [String.t()]

Formats compromised-package findings for CLI output.

merge_advisories(existing, new)

@spec merge_advisories([map()], [map()]) :: [map()]

Merge advisory lists by OSV id and return stable sorted advisories.

merge_database(path, advisories)

@spec merge_database(String.t(), [map()]) :: {:ok, [map()]} | {:error, term()}

Merge new OSV advisories into an existing local database.

read_database(path \\ cache_path())

@spec read_database(String.t()) :: {:ok, [map()]} | {:error, term()}

Read OSV advisory reports from a local JSON database.

write_database(path, advisories)

@spec write_database(String.t(), [map()]) :: :ok | {:error, term()}

Write OSV advisory reports to a local JSON database.