Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Supply-chain signals

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    Every keryn scan checks the packages it finds against published malicious-package data, and looks at install hooks and registry configuration. This is offline and needs no flag. The signals are indicators for review, not proof: a package that matches nothing is not shown to be safe, and a content signal does not establish malicious intent.

    Rule id Class Severity Confidence Raised when
    supply-chain:malicious/<ecosystem>/<name> malicious_package error P1 the name, and the version when the record lists versions, matches a published OSV MAL- record. A registry’s 0.0.1-security holding package is not matched
    supply-chain:typosquat/<ecosystem>/<name> possible_typosquat warning P1 the name is not widely used and is one edit, a separator, a repeated letter or another scope away from a popular name
    supply-chain:install-script/repository, …/dependency install_script_risk warning P1 an npm preinstall, install or postinstall hook, or top-level setup.py code, reaches the network or a shell
    supply-chain:content/obfuscated-install obfuscated_install warning P2 an install hook decodes data (base64, character codes, escape runs) and executes code dynamically
    supply-chain:content/network-exec-install network_exec_install warning P2 an install or build hook combines network access and command execution, including an MSBuild .targets or .props Exec with a URL or encoded command
    supply-chain:content/maintainer-hook-change maintainer_hook_change warning P2 with --base: an npm package’s version changed, a new maintainer appears in its metadata, and an install hook was added
    supply-chain:dependency-confusion/<ecosystem> dependency_confusion_risk warning P1 (npm, PyPI), P2 (NuGet, RubyGems, Go) public and private package sources are mixed so that a public package could stand in for a private one

    The P2 signals come from static reading only. Their messages end with Static indicator only; this does not establish malicious intent. A malicious-package match says that package metadata alone does not authenticate where a package came from: remove it and rotate the credentials an install could have read.

    Test fixtures and vendored code get their code role, and the signals there are suppressed like other findings in those roles.

    Ecosystem Malicious data Typosquat Install or build hooks Source configuration
    npm yes yes package.json hooks, and a local node, python or ruby script a hook runs .npmrc maps other scopes to a private registry but not yours
    PyPI yes yes setup.py --extra-index-url with unranked names and no --hash
    crates.io yes no build.rs no
    RubyGems yes no extconf.rb Gemfile with both rubygems.org and another global source
    Go yes no no GOPROXY falls back between a private proxy and proxy.golang.org without GOPRIVATE or GONOPROXY
    NuGet yes no .targets and .props nuget.config with public and private sources and no packageSourceMapping
    • Malicious data: the OSV MAL- records of the OpenSSF malicious-packages project, shipped with the rules and dated per ecosystem.
    • Typosquat: needs a popularity list, which exists for npm and PyPI only. For the others the report says so (“popularity corpus unavailable”).
    • Name matching: PyPI names are normalised as in PEP 503. npm and NuGet names are compared case-insensitively, and Go module paths case-sensitively.
    • Packages that are not from the registry are never matched against published names: entries resolved from git, a folder, a workspace, a URL or an npm alias.
    • Where package contents are read: in a scan, from installed or vendored folders (node_modules, site-packages, vendor, third_party, registry/src) and from archives in the tree. keryn sca malicious reads them anywhere in its target.
    • Withheld values: messages about source configuration do not repeat the source or proxy values.

    The report states, for every ecosystem it checked, which data was used and how old it is:

    Malicious-package data: npm; source date 2026-11-09T17:30:04.644913803Z; shipped. Published MAL records are not proof that unlisted packages are safe.

    The --online switch is opt-in:

    • keryn scan --online also asks OSV.dev for current MAL- records. The same switch checks advisories against OSV.dev and looks up missing licences on deps.dev.
    • keryn sca malicious --online does the malicious-package refresh only.

    What --online sends:

    • Sent: the ecosystem, name and version of each package resolved from a public registry. Packages that are only declared, without a resolved version, are not queried.
    • Kept: records that are not withdrawn. Version ranges are evaluated on your machine.
    • Cache: records are cached by their id and modification time, so an edited record is fetched again.
    • In the report: online and the time of the check. OSV.dev supplies no snapshot date for its whole database, so “no match” is not a safety verdict.

    If the refresh fails, or a record’s ranges cannot be decided, the shipped data is kept, the report says the current assessment is unknown, and the scan is incomplete (exit 3).

    Terminal window
    keryn sca malicious node_modules --out out/hooks
    keryn sca malicious vendor/acme-1.2.0.tgz --out out/acme --base out/hooks/hook-snapshot.json

    It inspects package contents, a folder or an archive (.tar, .tar.gz, .tgz, .crate, .gem), without installing, building or running anything. Symbolic links are not followed, and there are limits on file count, size and archive nesting.

    • --base <hook-snapshot.json|directory>: compares npm maintainer and install-hook metadata with an earlier snapshot at the same package path. A folder snapshot and an archive with different internal paths, as above, are not comparable: static content inspection still runs, but the maintainer transition is reported as unknown. keryn scan --base <ref> builds that snapshot itself.
    • --online: see above. --offline is the default and the two together are a usage error.
    • --fail-on: defaults to error.

    It writes these to the --out directory:

    • the usual run.json, result.json, results.sarif and summary.md;
    • hook-snapshot.json, for a later --base;
    • the raw inspection;
    • execution.json, which records whether the network was used and the data dates.

    The exit codes are those of the keryn sca stages: 0 pass, 1 findings, 2 usage, 3 incomplete (for example a hook target that could not be read, or a failed refresh), 4 internal error.

    • No proof of safety. No match against published records is not proof that a package is safe.
    • Static reading only. Content signals are read statically. Nothing is executed, so behaviour that only appears at run time is not seen.
    • Maintainer history is not authenticated. The maintainer comparison is npm only and uses the package metadata, hashed. It is not authenticated owner history from the registry.
    • No measured false-positive rate yet. The rates of the content signals on popular packages in each ecosystem have not been measured and certified.