@landstrip/landstrip 0.16.23 → 0.17.0

package/README.md

@@ -42,8 +42,9 @@ statically, e.g. for many filesystem mutator syscalls, or when denials must be
 reported back to the launcher. The broker intercepts `openat`/`openat2` via
 seccomp user-notifications, resolves the real path, and validates it
 
-Finally there's some logic to deduce that Landlock and Seccomp (mostly for
-mutator syscall, which take fd) are fairly disjoint entities.
+Landlock and seccomp cover mostly disjoint filesystem operations: Landlock
+handles kernel-enforced path access, while seccomp mediates unsupported mutators
+and reports broker decisions.
 
 ### Windows
 
@@ -135,18 +136,20 @@ For a filesystem-only sandbox with unrestricted direct network access, set:
 policy enforcement in place. On Windows this grants the AppContainer its network
 capabilities; without it the container denies all network access.
 
-## Denial Traps
+## Traps
 
-Sandbox denials are reported as JSON objects, one per line, each with a fixed
-`kind` discriminant and a stable `code`. Consumers route on `kind` for coarse
-grouping and on `code` for the policy denial class. Traps go to standard error
-by default; `--trap-fd FD` writes them to an already-open descriptor instead.
+Every landstrip event — a sandbox denial, and every failure that keeps the tool
+from running — is reported as a JSON object, one per line, with a fixed `kind`
+discriminant and a stable `code`. Consumers route on `kind` for the shape of the
+record and on `code` for what happened. Failure traps and completed denial traps
+go to standard error by default. On Linux, pending query traps go only to
+`--trap-fd FD`, which writes them to an already-open descriptor.
 
 ```sh
 landstrip --trap-fd 3 -p policy.json cargo test 3>landstrip-traps.txt
 ```
 
-The two trap kinds are:
+The trap kinds are:
 
 - `filesystem` (`code` `FILESYSTEM_DENIED`): `operation` is `read` or `write`,
   `path` is the resolved path, `requested_path` is the tool's original path when
@@ -154,21 +157,43 @@ The two trap kinds are:
   `process` carry routing context.
 - `network` (`code` `NETWORK_DENIED`): `operation` is `connect` or `bind` and
   `target` is `address:port`, with `syscall`, `errno`, and `process` context.
-
-`reason` is a platform-independent classification of the decision, derived from
-the policy and the requested path:
+- `launch` (`code` `LAUNCH_FAILED`): the sandbox was installed but the tool did
+  not start. `program` is the tool, `errno` its symbolic errno where the platform
+  has one, and `message` the system's text.
+- `usage` (`code` `USAGE_ERROR`): the command line was rejected. Exits with
+  status 2, and reaches standard error only — the trap descriptor is part of the
+  arguments that failed to parse.
+- `internal`: everything that fails before the tool runs. `code` names the stage:
+  `POLICY_PARSE_FAILED`, `POLICY_IO_FAILED`, `SANDBOX_SETUP_FAILED`,
+  `SUPERVISE_FAILED`, `PLATFORM_UNSUPPORTED`, `INTEGER_TOO_LARGE`, a
+  `POLICY_*` validation rejection (`POLICY_UNRESTRICTED_READ`,
+  `POLICY_TCP_BIND_UNSUPPORTED`, `POLICY_UNIX_SOCKET_UNSUPPORTED`,
+  `POLICY_UNIX_SOCKET_PATH`, `POLICY_DENY_WRITE_SYMLINK_ANCESTOR`,
+  `POLICY_INVALID_PORT`, `POLICY_EMPTY_PATH`, `POLICY_HOME_UNAVAILABLE`,
+  `POLICY_TRAVERSAL_DEPTH`), or `INTERNAL_ERROR` for a failure the code space
+  does not name.
+
+A code names the stage that failed, not the operating system that reported it:
+the same `LAUNCH_FAILED` or `SANDBOX_SETUP_FAILED` is raised by every backend
+that has that stage. The platform detail rides along in the record instead.
+
+`mechanism` records the kernel layer an event is attributed to: `landlock`,
+`seccomp`, `seatbelt`, or `appcontainer`. Per-denial traps are always `seccomp`,
+the only layer with a per-denial callback; Landlock enforces in-kernel without
+one. `SANDBOX_SETUP_FAILED` carries the mechanism that could not be installed.
+
+`reason` is a platform-independent classification of a filesystem decision,
+derived from the policy and the requested path:
 
 - `allow_miss`: the path matched no allow root and was denied by default.
 - `deny_match`: the path matched an explicit deny root that overrides an allow.
 
-`mechanism` records the kernel layer that detected the denial. Per-denial traps
-are always `seccomp`, the only layer with a per-denial callback; Landlock
-enforces in-kernel without one.
-
 ```json
 {
   "kind": "filesystem",
   "code": "FILESYSTEM_DENIED",
+  "state": "info",
+  "query_id": "0",
   "operation": "write",
   "path": "/repo/out",
   "requested_path": "out",
@@ -183,6 +208,8 @@ enforces in-kernel without one.
 {
   "kind": "network",
   "code": "NETWORK_DENIED",
+  "state": "info",
+  "query_id": "0",
   "operation": "connect",
   "target": "127.0.0.1:9999",
   "syscall": "connect",
@@ -190,15 +217,32 @@ enforces in-kernel without one.
   "mechanism": "seccomp",
   "process": { "pid": 1234, "exe": "/usr/bin/nc", "cwd": "/repo" }
 }
+{
+  "kind": "launch",
+  "code": "LAUNCH_FAILED",
+  "program": "/usr/bin/cargo",
+  "errno": "ENOENT",
+  "message": "No such file or directory (os error 2)"
+}
+{
+  "kind": "internal",
+  "code": "SANDBOX_SETUP_FAILED",
+  "mechanism": "landlock",
+  "message": "not enforced by the kernel (Linux 5.13+ with CONFIG_SECURITY_LANDLOCK required, and not disabled via the lsm= boot parameter)"
+}
 ```
 
-Traps are informational; the configured policy always applies. landstrip is
-otherwise quiet on success — standard error belongs to landstrip, standard
-output to the sandboxed tool. Usage, policy, launch, and platform errors are
-printed as plain text; usage errors exit with status 2. Writing to `--trap-fd`
-is best-effort: it needs an already-open descriptor (3 or greater; 0-2 are
-reserved), and if the write fails the denial is dropped while the policy stays
-in effect.
+Denial traps are informational; the configured policy always applies. landstrip
+is otherwise quiet on success — standard error belongs to landstrip, standard
+output to the sandboxed tool. Failure traps are accompanied by a human-readable
+log line; the JSON is what machines should read. Usage errors exit with status 2,
+every other landstrip failure with 1; the tool's own status is passed through
+otherwise.
+
+Writing to `--trap-fd` is best-effort: it needs an already-open descriptor (3 or
+greater; 0-2 are reserved), and if the write fails the trap is dropped while the
+policy stays in effect. On Linux, a broker launch failure also reaches
+`--trap-fd` while the descriptor remains open.
 
 ## Development
 

package/lib/index.d.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/** The kernel layer an event is attributed to. */
+export type LandstripMechanism =
+  | 'landlock'
+  | 'seccomp'
+  | 'seatbelt'
+  | 'appcontainer';
+
+/**
+ * `query` holds the syscall until the launcher answers with a
+ * {@link LandstripControlResponse}; `info` is terminal. Queries need a socket on
+ * `--trap-fd`, and only the Linux broker raises them.
+ */
+export type LandstripTrapState = 'query' | 'info';
+
+/** Why a filesystem access was mediated. */
+export type LandstripTrapReason = 'allow_miss' | 'deny_match';
+
+export interface LandstripProcess {
+  pid: number;
+  exe: string | null;
+  cwd: string | null;
+}
+
+/** A filesystem access the policy denies. */
+export interface LandstripFilesystemTrap {
+  kind: 'filesystem';
+  code: 'FILESYSTEM_DENIED';
+  state: LandstripTrapState;
+  /** Decimal `u64`; `"0"` marks a terminal `info` event. */
+  query_id: string;
+  operation: 'read' | 'write';
+  /** The resolved path. */
+  path: string;
+  /** The path the tool asked for, before resolution. */
+  requested_path: string;
+  syscall: string;
+  errno: string;
+  flags: string[];
+  reason: LandstripTrapReason;
+  /** The policy edit that would permit this access. */
+  suggested_grant: { allowRead?: string; allowWrite?: string };
+  process: LandstripProcess;
+  mechanism: 'seccomp';
+}
+
+/** A network access the policy denies. */
+export interface LandstripNetworkTrap {
+  kind: 'network';
+  code: 'NETWORK_DENIED';
+  state: LandstripTrapState;
+  /** Decimal `u64`; `"0"` marks a terminal `info` event. */
+  query_id: string;
+  operation: 'connect' | 'bind';
+  /** `address:port`. */
+  target: string;
+  syscall: string;
+  errno: string;
+  mechanism: 'seccomp';
+  process: LandstripProcess;
+}
+
+/** The sandbox was installed but the tool did not start. */
+export interface LandstripLaunchTrap {
+  kind: 'launch';
+  code: 'LAUNCH_FAILED';
+  program: string;
+  /** Absent where the platform has no POSIX errno for the failure. */
+  errno?: string;
+  message: string;
+}
+
+/** The command line was rejected. Reaches stderr only; landstrip exits 2. */
+export interface LandstripUsageTrap {
+  kind: 'usage';
+  code: 'USAGE_ERROR';
+  message: string;
+}
+
+/** A policy the platform sandbox cannot enforce, rejected before launch. */
+export type LandstripPolicyErrorCode =
+  | 'POLICY_PARSE_FAILED'
+  | 'POLICY_IO_FAILED'
+  | 'POLICY_UNRESTRICTED_READ'
+  | 'POLICY_TCP_BIND_UNSUPPORTED'
+  | 'POLICY_UNIX_SOCKET_UNSUPPORTED'
+  | 'POLICY_UNIX_SOCKET_PATH'
+  | 'POLICY_DENY_WRITE_SYMLINK_ANCESTOR'
+  | 'POLICY_INVALID_PORT'
+  | 'POLICY_EMPTY_PATH'
+  | 'POLICY_HOME_UNAVAILABLE'
+  | 'POLICY_TRAVERSAL_DEPTH';
+
+/** The stage that failed before the tool ran. */
+export type LandstripInternalCode =
+  | LandstripPolicyErrorCode
+  | 'SANDBOX_SETUP_FAILED'
+  | 'SUPERVISE_FAILED'
+  | 'PLATFORM_UNSUPPORTED'
+  | 'INTEGER_TOO_LARGE'
+  | 'INTERNAL_ERROR';
+
+/** Everything that fails before the tool runs. */
+export type LandstripInternalTrap =
+  | {
+      kind: 'internal';
+      code: 'SANDBOX_SETUP_FAILED';
+      mechanism: LandstripMechanism;
+      message: string;
+    }
+  | {
+      kind: 'internal';
+      code: Exclude<LandstripInternalCode, 'SANDBOX_SETUP_FAILED'>;
+      mechanism?: never;
+      message: string;
+    };
+
+/**
+ * One landstrip event. Failure and completed-denial events are written to
+ * stderr; pending Linux query events are written only to `--trap-fd`.
+ */
+export type LandstripTrap =
+  | LandstripFilesystemTrap
+  | LandstripNetworkTrap
+  | LandstripLaunchTrap
+  | LandstripUsageTrap
+  | LandstripInternalTrap;
+
+/** Every code landstrip reports, across all trap kinds. */
+export type LandstripCode = LandstripTrap['code'];
+
+/**
+ * The answer to a `state: "query"` trap, written back to the trap socket as one
+ * JSON line. `query_id` is an opaque decimal `u64` copied verbatim from the
+ * trap. An unanswered query holds the sandboxed syscall.
+ */
+export interface LandstripControlResponse {
+  query_id: string;
+  action: 'allow' | 'deny';
+}
+
+/**
+ * Path to the native landstrip binary for the running platform.
+ *
+ * @throws if the platform is unsupported, or the binary package is not installed.
+ */
+export function binaryPath(platform?: string, arch?: string): string;
+
+/** Name of the binary package for the given platform. */
+export function packageName(platform?: string, arch?: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@landstrip/landstrip",
-  "version": "0.16.23",
+  "version": "0.17.0",
   "description": "Sandbox runner using Landlock, Seatbelt, and AppContainer",
   "license": "Apache-2.0 AND LGPL-2.1-or-later",
   "homepage": "https://github.com/landstrip/landstrip#readme",
@@ -12,7 +12,13 @@
     "url": "https://github.com/landstrip/landstrip/issues"
   },
   "main": "lib/index.js",
-  "exports": "./lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
   "bin": {
     "landstrip": "bin/landstrip.js"
   },
@@ -24,10 +30,10 @@
     "LICENSE-LGPL-2.1"
   ],
   "optionalDependencies": {
-    "@landstrip/landstrip-darwin-arm64": "0.16.23",
-    "@landstrip/landstrip-darwin-x64": "0.16.23",
-    "@landstrip/landstrip-linux-x64": "0.16.23",
-    "@landstrip/landstrip-win32-x64": "0.16.23"
+    "@landstrip/landstrip-darwin-arm64": "0.17.0",
+    "@landstrip/landstrip-darwin-x64": "0.17.0",
+    "@landstrip/landstrip-linux-x64": "0.17.0",
+    "@landstrip/landstrip-win32-x64": "0.17.0"
   },
   "publishConfig": {
     "access": "public"