@kratex/cli

The Kratex command-line tool: Node.js supply-chain enforcement at install and at runtime.

npm i -g @kratex/cli

Requires Node.js 18.17+.

This page is the CLI command reference. For what Kratex does and why, see the project README.

Get started

kratex ci                 # policy-gated install
kratex run node app.js    # run a command under runtime enforcement

kratex ci and kratex install run npm ci / npm install --ignore-scripts, then evaluate each package's lifecycle scripts against your policy before running them. kratex run injects the same enforcement into your running Node process. With no kratex.policy.json present, both fall back to the built-in default policy.

Commands

| Command | What it does | | ------------------------ | ------------------------------------------------------------------ | | kratex run <command> | Run any Node command under the active policy | | kratex npx <pkg> | Fetch and run a package with full-lifecycle protection (see below) | | kratex install | npm install --ignore-scripts plus lifecycle gating | | kratex ci | npm ci --ignore-scripts plus lifecycle gating | | kratex audit | npm dependency and signature audit | | kratex policy validate | Parse and summarize the active policy | | kratex profile docker | Print a hardened Dockerfile derived from your policy | | kratex doctor | Check local setup and configuration |

kratex run accepts a script shorthand: kratex run serve expands to npm run serve.

kratex npx <pkg> [args]

Fetches and runs an npx package with full-lifecycle protection, equivalent to kratex i <pkg> followed by kratex run. The fetched package's preinstall/install/postinstall scripts run under install-phase guards (third-party-lifecycle-network, third-party-lifecycle-spawn); the bin runs under runtime guards. The command never refuses to run. It contains what the package can do rather than preventing execution:

• credential reads (~/.npmrc, AWS keys, SSH keys) are blocked.
• network calls from lifecycle scripts are blocked.
• non-node subprocess escapes from lifecycle scripts are blocked.
• the bin executes as third-party code under the active policy.

Known limitation: shebang-based node-launcher detection has a TOCTOU window (a file swapped between check and exec).

Policy

Policy lives in kratex.policy.json in your project root. It is plain JSON; version it with the rest of your repo. With no config file present, Kratex falls back to the built-in default policy, which blocks several categories of dangerous third-party behavior and allows everything else (see the project README for the list).

A rule specifies:

• Subject: first-party code, third-party code, or a named package.
• Target: a filesystem path, network host, process command, environment variable, or install lifecycle script.
• Effect: allow, audit, or block.

Unmatched operations are allowed by default. To parse the policy Kratex would use and print a summary of it:

kratex policy validate

The full policy schema lives in @kratex/shared (src/policy/schema.ts).

Environment variables

| Variable | Effect | | -------------- | ---------------------------------------------------------------- | | KRATEX_MODE | audit or enforce; overrides the mode declared in the policy | | KRATEX_DEBUG | 1 prints the resolved policy summary to stderr on startup | | KRATEX_QUIET | 1 suppresses the active-policy banner (violations still print) |

License

Apache License 2.0. See the root LICENSE.