# Supply-chain signals

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> Malicious-package, typosquat, install-hook, package-content and dependency-confusion signals, per ecosystem; the --online refresh of malicious-package data; keryn sca malicious; and what the signals do not establish.

Source: https://keryn.dev/docs/reference/sca/supply-chain/

> **Caution: Ships in the next release**
> On main; not in Keryn 0.5.2, the latest release. Keryn 0.5.2 has no supply-chain stage.

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.

## Signals

| 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](https://keryn.dev/docs/reference/suppressions/#ruleoverrides-and-roles), and the signals there are suppressed like other findings in those roles.

## Per ecosystem

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

## Data dates and `--online`

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

```text
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).

## `keryn sca malicious`

```sh
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](https://keryn.dev/docs/reference/cli/): 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.

## What these signals do not establish

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