0 Fork 0

Files

T

kingwl 0a486f09c9 chore: adopt node-addon-landlock-run source as native/ subtree

Bring the node-addon-landlock-run tree (tag v0.0.1, commit 614f7fd) into
native/landlock-run as its source of record: launcher development happens
here, next to the harness consumers, and the standalone repository becomes
the release mirror the tree is exported to for packing and publishing
(procedure in native/README.md). The subtree keeps its own pnpm workspace
and lockfile and is NOT added to the harness workspace: harness installs,
gates, and CI never touch it. The mirror's .github/ stays out of the
subtree; a separate manually-dispatched workflow
(.github/workflows/landlock-run.yml) runs the subtree's CI legs — the
per-architecture native builds, real-kernel launcher proofs, and pack
rehearsal — adapted with working-directory/cache paths.

eslint ignores the subtree like vendor/; AGENTS.md gains the native/
layout line (+5 words on its budget ceiling).

2026-07-14 23:39:58 +08:00

2.9 KiB

Raw Blame History

node-addon-landlock-run

A Landlock self-restrict-then-exec launcher for confining subprocesses on Linux, distributed as prebuilt per-platform npm packages plus a thin JS entry package that resolves the binary and speaks its CLI contract. Built for agent harnesses and other hosts that need to run untrusted commands under a filesystem allow-list without confining themselves.

The first tool is landlock-run — a self-restrict-then-exec Landlock launcher (~300 lines of C11 over the raw kernel UAPI, statically linked against musl). It installs a Landlock ruleset on itself and execs the wrapped command; the ruleset is inherited across execve, so the command and every process it spawns run confined while the invoking process stays unrestricted. Fail-closed: if the kernel cannot enforce, it exits without running the command.

Install

npm install node-addon-landlock-run

Published packages use an entry package plus platform optional packages:

node-addon-landlock-run
node-addon-landlock-run-linux-x64
node-addon-landlock-run-linux-arm64

npm's os/cpu fields make installers fetch only the matching platform package. There is no install-time build fallback on purpose: on a host without a platform package the resolved path never exists, the probe reports unusable, and the consumer falls closed.

Usage

import { grantArgs, launcherPath, probe } from 'node-addon-landlock-run';

const launcher = launcherPath();
if (probe(launcher) !== 'unusable') {
  const argv = [launcher, ...grantArgs({ readOnly: ['/'], readWrite: ['/tmp/work'] }), '--', 'bash', '-c', command];
  // spawn argv with your process runner of choice
}

The public API is intentionally small:

launcherPath(): absolute path of this host's launcher (existence deliberately unchecked — the probe is the availability signal).
probe(launcher?, { timeoutMs? }): functional enforcement probe — 'full' | 'partial' | 'unusable'.
grantArgs({ readOnly?, readWrite? }): the launcher's grant argv; everything not granted is denied.
LAUNCHER_BIN, LAUNCHER_FAILURE_EXIT (125): contract constants.

The full binary contract (argv grammar, exit codes, report lines) is pinned in docs/cli-contract.md.

Support

linux-x64 and linux-arm64, kernel with Landlock enabled (5.13+; ABI level determines full vs partial enforcement — see docs/support-matrix.md). Other platforms deliberately have no package: consumers run different confinement backends there.

Development

corepack enable
pnpm install
pnpm build:ts        # entry packages → lib/
pnpm build:native    # this Linux architecture's binaries (apt-get install musl-tools)
pnpm test

Binaries are git-ignored and built natively per architecture — locally for your own machine, by CI's per-arch runners as the builders of record. Release flow: docs/release.md.

2.9 KiB Raw Blame History