Node.js supply-chain enforcement at install and at runtime. Open source, Apache 2.0, no service to sign up for.
npm i -g @kratex/cli
Requires Node.js 18.17+. Policy is a local JSON file in your repo.
[](https://github.com/kratex-security/kratex/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@kratex/cli)
[](LICENSE)
[](https://scorecard.dev/viewer/?uri=github.com/kratex-security/kratex)
Static scanners catch packages they have already seen. Kratex enforces what every package can actually do (which files it can read, which hosts it can reach, which processes it can spawn) every time it runs, including the ones nobody has flagged yet.
The output is a receipt:
allow first-party net:connect api.example.com:443
block esbuild install:lifecycle-script [default-block]
audit lodash fs:read ./package.json
## What it does, concretely
- **Install hardening.** `kratex install` / `kratex ci` run `npm install --ignore-scripts` and gate each package's lifecycle scripts against your policy before running them. A package that asks to make a network call from `postinstall` is blocked unless the policy says otherwise.
- **Runtime enforcement.** `kratex run` injects an in-process hook into Node that intercepts filesystem, network, child-process, and environment access. Every operation is attributed to the package that made it (first-party code, a direct dependency, or a transitive) and evaluated against the policy in the caller's chain.
- **Built-in block-tier rules.** Six categories of rules ship enabled out of the box for third-party packages: credential reads (npmrc, AWS, SSH, browser profiles), post-credential-read outflow (network calls and process spawns after a caller touches a credential), lifecycle-script network calls, lifecycle-script shell escapes, crypto-wallet reads, and self-propagation. The lifecycle, wallet, and self-propagation rules fire even in audit mode. These mirror patterns from publicly-disclosed npm compromises since 2018.
## How it's different from static scanners
| | Static scanners (Snyk, Socket, GHAS) | Kratex |
| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| What they check | A package's manifest, lockfile, and known-bad CVE/IOC database | What a package's code actually does when it runs |
| Coverage of unknown attacks | None; flags only what has been reported | Same coverage for known and unknown. The rule fires on the behavior a package exhibits at runtime |
| When they run | At PR time, on a scanner schedule | At `npm install` and on every Node process the developer or CI runs |
| What they block | Nothing; they advise, the install proceeds | The lifecycle script, the file read, the network call, at the source |
Kratex complements static scanners. Static scanners are good at known-bad; Kratex covers the day-zero gap.
## Quickstart
kratex install # policy-gated npm install
kratex run node app.js # run any command under runtime enforcement
kratex run dev # shorthand for `kratex run npm run dev`
With no config file present, Kratex runs the built-in default policy: it blocks the six block-tier patterns above and allows everything else. Drop a `kratex.policy.json` in your project root to tighten or loosen it. See [`cli/README.md`](cli/README.md) for the policy reference.
## Components
- [`@kratex/cli`](cli/), the command-line tool published as `@kratex/cli`. Install with `npm i -g @kratex/cli`.
- [`@kratex/shared`](shared/), the policy schema, rule types, and normalizer, published to npm as `@kratex/shared`. Consumed by the CLI and available as a standalone policy-schema library.
- `@kratex/runtime` ([source](runtime/)), an internal workspace bundled into the CLI at build time. Not separately published.
## Threat model and design
The threat model and security boundary are documented in [`cli/docs/threat-model.md`](cli/docs/threat-model.md). In short:
- Enforcement is **in-process and language-native**: Node's monkey-patchable surface. No eBPF, no seccomp, no `LD_PRELOAD`. The mechanism that makes this work is **caller-chain attribution**: every intercepted operation is traced back to the specific package in the call stack that triggered it.
- The runtime is **defense in depth**. It layers on top of OS and container sandboxing without replacing them. Supported versions and the reporting channel are in [`SECURITY.md`](SECURITY.md).
## Telemetry
Kratex emits telemetry only when a policy declares a sink (`telemetry.sinks`); there is no default sink, so out of the box nothing leaves your machine. When a sink is configured, each event envelope carries: a SHA-256-truncated (non-reversible) machine hostname, platform, arch, Node version, CLI version, a random per-machine install id (`/install-id`), a run id, and the policy/install-lifecycle event payload (filesystem paths are workspace-relative or tildified; `project.root` is tildified; a `package.json`/lockfile hash is included for correlation).
Telemetry is opt-in: it runs only for the sinks you declare. To disable it, remove the `telemetry.sinks` from your policy (or run with no sink configured); enforcement and on-terminal violation display are unaffected.
## Reporting vulnerabilities
See [`SECURITY.md`](SECURITY.md). Please use private GitHub Security Advisories. Do not file public issues for suspected security bugs.
## Brand and assets
The umbrella brand system (mark, wordmark, social card, color and typography rules) lives in [`DESIGN.md`](DESIGN.md). Positioning lives in [`PRODUCT.md`](PRODUCT.md). Source SVGs are in [`assets/`](assets/).
## License
Apache License 2.0. See [LICENSE](LICENSE).
