Skip to content
kratex
Docs menu

Quickstart

Run your first command

echo 'console.log("hello from kratex")' > app.js
kratex run node app.js

Output:

[kratex] active policy: builtin-default ((built-in default))
hello from kratex

Kratex ran your command with its built-in rules active. The CLI bundles a default policy that runs in enforce mode, so you get protection with no configuration. The [kratex] active policy: banner is written to stderr; set KRATEX_QUIET=1 to suppress it.

See a real block

Most built-in rules fire only on third-party code; a small family of credential-path protections applies to all code. Here is a real block kratex install produces when a dependency phones home during install.

When a dependency’s postinstall script makes an outbound network call during install, the same shape as the October 2021 ua-parser-js incident, kratex install installs the dependency tree with scripts disabled, then evaluates each lifecycle script against policy before running it. The built-in kratex.builtin.third-party-lifecycle-network rule blocks the outbound network call before it opens and prints a receipt naming the package that tried it:

block receiptprinted by kratex install
block <high> @kratex-corpus/lifecycle-network-2021-10 network:http:request http://127.0.0.1:1 {credentials} [kratex.builtin.third-party-lifecycle-network]
reasons: enforced-block, exposed-subject
to allow: add the following to <project-root>/kratex.policy.json:
{ "id": "allow-kratex-corpus-lifecycle-network-2021-10-network-http-request-127-0-0-1", "subject": { "package": "@kratex-corpus/lifecycle-network-2021-10" }, "target": { "kind": "network", "operation": "connect", "host": "127.0.0.1", "port": 1, "protocol": "http" }, "effect": { "action": "allow" } }
The verdict. Kratex blocked the call, and how serious the match is.
Who called. The package that made the call, by caller-chain attribution.
What and where. The operation it attempted and the address it aimed at.
What's in play. This caller had already touched credentials, which is what makes an outbound call the exfiltration shape.
Which rule, and why. The built-in rule that matched, plus the reasons it fired.
How to allow it. A ready-to-paste rule scoped to this exact package and call, for when a block is a false positive.

(The receipt dials 127.0.0.1:1 as a harmless stand-in for the real exfiltration host. The {credentials} tag appears because npm reads .npmrc during install, and that exposure carries into the script it launches; see How it works.) This block fires in every policy mode, with no policy file present.

Want to run Kratex live in your browser, with nothing to install? The defeat-the-policy challenge plants a credential, runs a dependency that tries to steal it, and dares you to get it past Kratex’s built-in defaults.

Notice the to allow section of the receipt. For every block, Kratex prints a rule scoped to that package and operation; paste it into kratex.policy.json at the project root and the call is allowed on the next run. Here the blocked call is the exfiltration itself, so no allow applies. A prebuilt-binary fetcher like puppeteer or electron trips the same rule during a normal install; that is the case the printed allow exists for. See Policy authoring for the full grammar.

Write your own policy

The bundled default protects you with no setup. To customize, create a kratex.policy.json at your project root. A policy that omits mode runs in enforce (blocking) mode; set "mode": "audit" to record violations without blocking while you take inventory:

{
  "version": 1,
  "mode": "audit",
  "rules": []
}

With an empty rule list in audit mode, every operation proceeds and every violation is recorded, so you can see what your dependencies actually do before you start blocking. When you are ready, switch to "mode": "enforce" and add allow rules for the calls you intend to keep.

Next steps