@landstrip/landstrip 0.17.16 → 0.17.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +51 -57
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -3,9 +3,9 @@
3
3
 
4
4
  # landstrip
5
5
 
6
- `landstrip` runs a tool in an OS-level sandbox using Landlock LSM on Linux,
7
- Seatbelt on macOS, and LPAC AppContainer on Windows. It accepts the Anthropic
8
- Sandbox Runtime JSON subset as the policy, in JSON or YAML syntax.
6
+ `landstrip` runs commands in an OS-level sandbox using Landlock LSM on Linux,
7
+ Seatbelt on macOS, and LPAC AppContainer on Windows. It accepts the Anthropic
8
+ Sandbox Runtime policy subset in JSON or YAML.
9
9
 
10
10
  ## Installation
11
11
 
@@ -25,10 +25,10 @@ binary package.
25
25
  ### Agent extensions
26
26
 
27
27
  The bundled extensions integrate Landstrip with Pi and OpenCode. The Pi
28
- extension sandboxes the main agent's Bash execution, provides OpenCode-compatible
29
- primary agent selection, and runs subagents as full Pi RPC processes. Subagents
30
- normally receive an outer Landstrip sandbox; explicitly disabling sandboxing
31
- uses a warned process-only fallback:
28
+ extension sandboxes Bash execution, provides OpenCode-compatible primary-agent
29
+ selection, and runs subagents as full Pi RPC processes. Subagents normally run
30
+ inside an outer Landstrip sandbox; explicitly disabling sandboxing emits a
31
+ warning and uses a process-only fallback:
32
32
 
33
33
  ```sh
34
34
  pi install npm:pi-landstrip
@@ -41,12 +41,12 @@ details.
41
41
 
42
42
  ## Platforms
43
43
 
44
- | Area | macOS | Linux | Windows |
45
- | ------------ | ------------------------ | ---------------------------- | ------------------------------- |
46
- | Policy | path based rules | file based rules | per-run AppContainer ACLs |
47
- | Timing | dynamic subset of paths | file based static ruleset | per-run ACL grants |
48
- | TCP | proxy or loopback | proxy or loopback | allow all or deny all |
49
- | Unix sockets | allowlist | allowlist via seccomp broker | allow all or deny all |
44
+ | Area | macOS | Linux | Windows |
45
+ | ------------ | ----------------------- | --------------------------- | ------------------------- |
46
+ | Policy | path-based rules | file-based rules | per-run AppContainer ACLs |
47
+ | Timing | dynamic path subset | static file-based ruleset | per-run ACL grants |
48
+ | TCP | proxy or loopback | proxy or loopback | allow all or deny all |
49
+ | Unix sockets | allowlist | seccomp-brokered allowlist | allow all or deny all |
50
50
 
51
51
  ### Linux
52
52
 
@@ -55,9 +55,9 @@ Landlock carves the denied subtrees out of the allowed roots, and then grants
55
55
  added to the ruleset, and the kernel enforces the path directly.
56
56
 
57
57
  Seccomp is applied when a policy needs more than Landlock can express
58
- statically, e.g. for many filesystem mutator syscalls, or when denials must be
59
- reported back to the launcher. The broker intercepts `openat`/`openat2` via
60
- seccomp user-notifications, resolves the real path, and validates it
58
+ statically, such as filesystem mutator filtering or denial reporting. The broker
59
+ intercepts `openat` and `openat2` through seccomp user notifications, resolves
60
+ the real path, and validates it.
61
61
 
62
62
  Landlock and seccomp cover mostly disjoint filesystem operations: Landlock
63
63
  handles kernel-enforced path access, while seccomp mediates unsupported mutators
@@ -65,7 +65,7 @@ and reports broker decisions.
65
65
 
66
66
  ### Windows
67
67
 
68
- Win32 API provides AppContainer for application level sandboxing. The platform
68
+ Windows provides AppContainer for application-level sandboxing. Landstrip
69
69
  creates a per-run LPAC AppContainer profile, grants its SID access to the lowered
70
70
  read and write roots, and removes those grants after the sandboxed process tree
71
71
  exits. Windows policies must use explicit read allowlists.
@@ -78,12 +78,11 @@ are terminated when the launcher exits.
78
78
  capabilities, while the default container holds none and denies all network
79
79
  access.
80
80
 
81
- AppContainer capabilities are coarse: fine-grained TCP policies by host or port
82
- require Windows Filtering Platform rules keyed by the AppContainer SID. I.e.,
83
- this would require elevated privileges, which is not sustainable for a agent
84
- sandbox runtime, which should rely on unprivileged tools and techniques.
81
+ AppContainer capabilities are coarse. Fine-grained TCP policies by host or port
82
+ require elevated Windows Filtering Platform rules keyed by the AppContainer SID,
83
+ which is unsuitable for an unprivileged agent sandbox runtime.
85
84
 
86
- ## Policy Format
85
+ ## Policy format
87
86
 
88
87
  JSON is the default policy format. Use `--format yaml` for YAML policy files or
89
88
  YAML read from standard input.
@@ -107,34 +106,31 @@ network:
107
106
  allowNetwork: true
108
107
  ```
109
108
 
110
- ## Filesystem Policy
109
+ ## Filesystem policy
111
110
 
112
- Write access is denied by default. `allowWrite` paths grant write access and
113
- `denyWrite` paths subtract from them, with the most specific rule winning where
114
- an allow and a deny overlap. Read access is unrestricted by default; setting
111
+ Write access is denied by default. `allowWrite` paths grant write access and
112
+ `denyWrite` paths subtract from them, with the most specific rule winning when
113
+ allow and deny rules overlap. Read access is unrestricted by default; setting
115
114
  `denyRead` lowers it to an allowlist, and `allowRead` adds paths back.
116
115
 
117
- ### Write Denial Semantics
116
+ ### Write-denial semantics
118
117
 
119
118
  Concrete (non-glob) `denyWrite` paths are canonicalized and enforced
120
119
  eagerly on all platforms.
121
120
 
122
- Glob `denyWrite` patterns (`**/.env`, `**/*.pem`, etc.) behave differently
121
+ Glob `denyWrite` patterns (`**/.env`, `**/*.pem`, and so on) behave differently
123
122
  by platform:
124
123
 
125
124
  - **Linux**: Globs are evaluated dynamically by the seccomp broker at each write
126
- attempt. Files created after sandbox startup that match a denyWrite glob are
127
- blocked. The glob is never walked at startup, so large trees do not cause
128
- startup latency.
125
+ attempt. Files created after sandbox startup that match a `denyWrite` glob are
126
+ blocked. Globs are not walked at startup, avoiding latency on large trees.
129
127
  - **macOS**: Globs are snapshot-expanded when the Seatbelt profile is compiled.
130
- Files created after `sandbox_init` are not protected by glob denies — use
131
- concrete paths for those. A warning is logged when glob deny patterns are
132
- used.
133
- - **Windows**: Glob denyWrite entries are not enforced by the AppContainer
128
+ Files created after `sandbox_init` are not protected by glob denies; use
129
+ concrete paths for them. A warning is logged when glob deny patterns are used.
130
+ - **Windows**: Glob `denyWrite` entries are not enforced by the AppContainer
134
131
  backend.
135
132
 
136
-
137
- ## Network Policy
133
+ ## Network policy
138
134
 
139
135
  Sandbox mode denies direct network access by default. Proxy ports, loopback TCP
140
136
  binding and connections, and Unix sockets can be allowed with the Anthropic
@@ -154,18 +150,18 @@ For a filesystem-only sandbox with unrestricted direct network access, set:
154
150
  }
155
151
  ```
156
152
 
157
- `allowNetwork` disables landstrip network enforcement while leaving filesystem
153
+ `allowNetwork` disables Landstrip network enforcement while leaving filesystem
158
154
  policy enforcement in place. On Windows this grants the AppContainer its network
159
155
  capabilities; without it the container denies all network access.
160
156
 
161
157
  ## Traps
162
158
 
163
- Every landstrip event — a sandbox denial, and every failure that keeps the tool
164
- from running — is reported as a JSON object, one per line, with a fixed `kind`
165
- discriminant and a stable `code`. Consumers route on `kind` for the shape of the
166
- record and on `code` for what happened. Failure traps and completed denial traps
167
- go to standard error by default. On Linux, pending query traps go only to
168
- `--trap-fd FD`, which writes them to an already-open descriptor.
159
+ Every Landstrip event, whether a sandbox denial or a failure that prevents the
160
+ tool from running, is reported as one JSON object per line, with a fixed `kind`
161
+ discriminant and stable `code`. Consumers route on `kind` for the record shape
162
+ and `code` for the event. Failures and completed denials go to standard error by
163
+ default. On Linux, pending query traps go only to `--trap-fd FD`, which must name
164
+ an already-open descriptor.
169
165
 
170
166
  ```sh
171
167
  landstrip --trap-fd 3 -p policy.json cargo test 3>landstrip-traps.txt
@@ -254,12 +250,11 @@ derived from the policy and the requested path:
254
250
  }
255
251
  ```
256
252
 
257
- Denial traps are informational; the configured policy always applies. landstrip
258
- is otherwise quiet on success — standard error belongs to landstrip, standard
259
- output to the sandboxed tool. Failure traps are accompanied by a human-readable
260
- log line; the JSON is what machines should read. Usage errors exit with status 2,
261
- every other landstrip failure with 1; the tool's own status is passed through
262
- otherwise.
253
+ Denial traps are informational; the configured policy always applies. Landstrip
254
+ is otherwise quiet on success: standard error belongs to Landstrip and standard
255
+ output to the sandboxed tool. Failure traps include a human-readable log line;
256
+ machines should read the JSON. Usage errors exit with status 2, other Landstrip
257
+ failures with 1, and the tool's own status is otherwise passed through.
263
258
 
264
259
  Writing to `--trap-fd` is best-effort: it needs an already-open descriptor (3 or
265
260
  greater; 0-2 are reserved), and if the write fails the trap is dropped while the
@@ -270,21 +265,20 @@ policy stays in effect. On Linux, a broker launch failure also reaches
270
265
 
271
266
  ### Commit messages
272
267
 
273
- - **`<subsystem>: <message>`**
274
- - Long description for non-trivial changes.
275
- - Kernel style commit messages.
276
- - **`Signed-off-by`**
268
+ - Use `<subsystem>: <message>` as the subject.
269
+ - Add a body for non-trivial changes.
270
+ - Follow kernel-style commit message conventions.
271
+ - Include a `Signed-off-by:` trailer.
277
272
 
278
273
  ### Documenting errors
279
274
 
280
275
  The following snippet demonstrates the recommended pattern for documenting
281
276
  the return values on error:
282
277
 
283
- ```
278
+ ```rust
284
279
  /// # Errors
285
280
  ///
286
- /// Returns [`<variant's unqualified name>`](<variant's unqualified name>)
287
- /// Returns ...
281
+ /// Returns [`Variant`] when ...
288
282
  ```
289
283
 
290
284
  ## Licensing
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@landstrip/landstrip",
3
- "version": "0.17.16",
3
+ "version": "0.17.18",
4
4
  "description": "Sandbox runner using Landlock, Seatbelt, and AppContainer",
5
5
  "license": "Apache-2.0 AND LGPL-2.1-or-later",
6
6
  "homepage": "https://github.com/landstrip/landstrip#readme",
@@ -30,12 +30,12 @@
30
30
  "LICENSE-LGPL-2.1"
31
31
  ],
32
32
  "optionalDependencies": {
33
- "@landstrip/landstrip-darwin-arm64": "0.17.16",
34
- "@landstrip/landstrip-darwin-x64": "0.17.16",
35
- "@landstrip/landstrip-linux-x64": "0.17.16",
36
- "@landstrip/landstrip-linux-arm64": "0.17.16",
37
- "@landstrip/landstrip-win32-x64": "0.17.16",
38
- "@landstrip/landstrip-win32-arm64": "0.17.16"
33
+ "@landstrip/landstrip-darwin-arm64": "0.17.18",
34
+ "@landstrip/landstrip-darwin-x64": "0.17.18",
35
+ "@landstrip/landstrip-linux-x64": "0.17.18",
36
+ "@landstrip/landstrip-linux-arm64": "0.17.18",
37
+ "@landstrip/landstrip-win32-x64": "0.17.18",
38
+ "@landstrip/landstrip-win32-arm64": "0.17.18"
39
39
  },
40
40
  "publishConfig": {
41
41
  "access": "public"