@landstrip/landstrip 0.18.26 → 0.18.27

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 (3) hide show
  1. package/README.md +120 -76
  2. package/bin/landstrip.js +0 -0
  3. package/package.json +7 -7
package/README.md CHANGED
@@ -3,21 +3,20 @@
3
3
 
4
4
  # landstrip
5
5
 
6
- `landstrip` runs commands in an OS-level sandbox using Landlock on Linux,
7
- Seatbelt on macOS, and AppContainer or restricted users on Windows. Policies use
6
+ `landstrip` runs a command inside an OS sandbox: Landlock on Linux, Seatbelt on
7
+ macOS, and AppContainer or a restricted user on Windows. Its policy format is
8
8
  the supported subset of the Anthropic Sandbox Runtime format.
9
9
 
10
- ## Installation
10
+ ## Install
11
11
 
12
12
  ```sh
13
13
  npm install --save-dev @landstrip/landstrip
14
14
  npx landstrip run -p policy.json -- cargo test
15
15
  ```
16
16
 
17
- The npm package installs a Node.js wrapper and a native binary for the current
18
- platform.
17
+ The npm package selects the native binary for the current platform.
19
18
 
20
- ## Command line
19
+ ## Commands
21
20
 
22
21
  ```text
23
22
  landstrip run [OPTIONS] -- <PROGRAM> [ARGS...]
@@ -29,33 +28,21 @@ landstrip windows status
29
28
  landstrip windows uninstall
30
29
  ```
31
30
 
32
- The `windows` commands exist only in Windows builds.
31
+ The `windows` commands are available only in Windows builds. `doctor` checks
32
+ whether the platform sandbox is usable. Inspection commands print one JSON
33
+ document. `run` returns the program's exit status; usage errors return 2 and
34
+ other Landstrip failures return 1.
33
35
 
34
- Pass policies with `-p, --policy <FILE>`. The option may be repeated; objects
35
- merge recursively, later scalar values replace earlier ones, and arrays combine.
36
- JSON is the default. Use `--policy-format yaml` for YAML and always specify the
37
- format with `-p -`.
36
+ Pass a policy with `-p, --policy <FILE>`. Repeat the option to merge policies
37
+ from left to right: objects merge recursively, arrays combine without duplicate
38
+ entries, and later scalar values replace earlier values. JSON is the default;
39
+ use `--policy-format yaml` for YAML and always specify a format with `-p -`.
38
40
 
39
- `run` also merges policy attached to the program executable. `policy validate`
40
- checks parsing, resolution, and platform support. `policy resolve` prints the
41
- normalized policy; add `--tool <PROGRAM>` to include executable policy.
42
- `doctor` checks that the platform sandbox is usable.
43
-
44
- Inspection and management commands print one JSON document. `run` returns the
45
- program's exit status. Usage errors return 2; other Landstrip failures return 1.
46
-
47
- ### Agent extensions
48
-
49
- Companion extensions integrate Landstrip with Pi and OpenCode. The Pi extension
50
- also provides primary agents and process-backed subagents.
51
-
52
- ```sh
53
- pi install npm:pi-landstrip
54
- opencode plugin install opencode-landstrip
55
- ```
56
-
57
- See [pi-landstrip](packages/pi-landstrip/README.md) and
58
- [opencode-landstrip](packages/opencode-landstrip/README.md).
41
+ `policy validate` parses and resolves the policy and checks platform support.
42
+ `policy resolve` prints the normalized result; `--tool <PROGRAM>` also merges
43
+ policy attached to that executable. Executable policy is applied last from the
44
+ `user.landstrip.policy` extended attribute on Unix or the `landstrip.policy`
45
+ NTFS alternate data stream on Windows.
59
46
 
60
47
  ## Policy
61
48
 
@@ -70,36 +57,69 @@ See [pi-landstrip](packages/pi-landstrip/README.md) and
70
57
  "network": {
71
58
  "allowNetwork": false,
72
59
  "httpProxyPort": 8080,
60
+ "socksProxyPort": 1080,
73
61
  "allowLocalBinding": false,
62
+ "allowAllUnixSockets": false,
74
63
  "allowUnixSockets": []
64
+ },
65
+ "windows": {
66
+ "appContainerMode": "lpac",
67
+ "allowLoopback": false
75
68
  }
76
69
  }
77
70
  ```
78
71
 
79
- Paths may be absolute, relative to the starting directory, or prefixed with
80
- `~`. Path lists also accept `*`, `**`, `?`, and character-class globs.
72
+ Paths may be absolute, relative to the command's starting directory, or start
73
+ with `~`. Path fields accept arrays or newline-separated strings. Entries accept
74
+ `*`, `**`, `?`, and character-class globs.
81
75
 
82
- Writes are denied by default. `allowWrite` grants writable roots; `denyWrite`
83
- always takes precedence. Reads are unrestricted until `denyRead` is non-empty;
84
- `allowRead` then adds exceptions, with the most specific read rule winning.
76
+ ### Filesystem
85
77
 
86
- Concrete `denyWrite` paths work on every platform. Glob denies are evaluated at
87
- access time on Linux and macOS, including for newly created files. Windows does
88
- not enforce glob `denyWrite` entries.
78
+ | Field | Default | Effect |
79
+ | --- | --- | --- |
80
+ | `allowWrite` | `[]` | Writable roots |
81
+ | `denyWrite` | `[]` | Hard write denials; takes precedence over `allowWrite` |
82
+ | `denyRead` | `[]` | Read restrictions; empty means unrestricted reads |
83
+ | `allowRead` | `[]` | Exceptions to `denyRead` |
84
+
85
+ When read rules overlap, the most specific rule wins. Concrete `denyWrite` paths
86
+ work on every platform. Linux and macOS also enforce glob denials at access time,
87
+ including for newly created files; Windows does not enforce glob `denyWrite`.
88
+
89
+ ### Network
90
+
91
+ | Field | Default | Effect |
92
+ | --- | --- | --- |
93
+ | `allowNetwork` | `false` | Disables network enforcement when `true` |
94
+ | `httpProxyPort` | unset | Allows loopback connection to this port |
95
+ | `socksProxyPort` | unset | Allows loopback connection to this port |
96
+ | `allowLocalBinding` | `false` | Allows local TCP binding and loopback connections |
97
+ | `allowAllUnixSockets` | `false` | Allows every Unix socket |
98
+ | `allowUnixSockets` | `[]` | Allows listed pathname Unix sockets |
89
99
 
90
- Direct TCP and new Unix sockets are denied by default. Proxy ports allow
91
- loopback connections only to those ports; Landstrip does not start a proxy or
92
- filter domains. `allowLocalBinding` permits local TCP binding and loopback
93
- connections. `allowUnixSockets` grants pathname sockets, and
94
- `allowAllUnixSockets` allows all Unix sockets. Set `allowNetwork` to `true` to
95
- disable network enforcement while keeping filesystem restrictions.
100
+ Landstrip does not start a proxy or filter domains. Direct TCP and new Unix
101
+ sockets are denied unless allowed by these fields.
96
102
 
97
- On Unix, supplementary executable policy is read from the
98
- `user.landstrip.policy` extended attribute. On Windows it is read from the
99
- `landstrip.policy` NTFS alternate data stream. Executable policy is merged
100
- after `--policy` files.
103
+ ### Windows
101
104
 
102
- ## Platforms
105
+ `windows.appContainerMode` is `"lpac"` by default; `"standard"` is weaker
106
+ because it can read resources granted to `ALL APPLICATION PACKAGES`.
107
+ `windows.allowLoopback` exposes every local loopback service in AppContainer;
108
+ without it, proxy ports are blocked. The removed `windows.backend` field is an
109
+ error.
110
+
111
+ Windows requires explicit read roots. ACL allow roots must exist when policy is
112
+ resolved; missing `allowRead` and `allowWrite` targets are omitted and remain
113
+ inaccessible. Windows does not support `allowLocalBinding` or Unix socket
114
+ policy.
115
+
116
+ Use `landstrip windows install` when software such as Git Bash cannot start in
117
+ AppContainer. It provisions restricted local users and activates that mode.
118
+ `windows uninstall` removes it. An unhealthy installation fails closed; inspect
119
+ it with `windows status`. Restricted-user mode permits proxy ports only from the
120
+ range selected at installation and does not support `windows.allowLoopback`.
121
+
122
+ ## Platform enforcement
103
123
 
104
124
  | Platform | Filesystem | Network |
105
125
  | --- | --- | --- |
@@ -107,39 +127,63 @@ after `--policy` files.
107
127
  | macOS | Seatbelt | TCP and Unix socket rules |
108
128
  | Windows | AppContainer or restricted user | AppContainer capabilities or account-scoped WFP |
109
129
 
110
- Windows requires an explicit read allowlist. AppContainer is used without
111
- installation; core Landstrip defaults to LPAC. `windows.appContainerMode` may
112
- select `standard`, which is weaker because it can see resources granted to
113
- `ALL APPLICATION PACKAGES`. In AppContainer, `windows.allowLoopback` exposes
114
- every local loopback service; without it, proxy ports are blocked.
130
+ ## Agent extensions
115
131
 
116
- Use `landstrip windows install` when software such as Git Bash cannot start in
117
- AppContainer. It provisions restricted local users and activates that mode.
118
- `windows uninstall` removes it and returns to AppContainer. An unhealthy
119
- installation fails closed; inspect it with `windows status`.
132
+ [pi-landstrip](packages/pi-landstrip/README.md) and
133
+ [opencode-landstrip](packages/opencode-landstrip/README.md) integrate Landstrip
134
+ with coding agents.
135
+
136
+ - **Agent permissions** authorize tool dispatch.
137
+ - **Sandbox permissions** authorize filesystem and network access.
138
+
139
+ An agent approval does not bypass the sandbox. Each plugin documents its prompt
140
+ order, approval scopes, and configuration files.
120
141
 
121
- Windows does not support `allowLocalBinding` or Unix socket policy.
122
- Restricted-user mode permits proxy ports only from the range chosen at install
123
- time and does not support `windows.allowLoopback`.
142
+ ```sh
143
+ pi install npm:pi-landstrip
144
+ opencode plugin install opencode-landstrip
145
+ ```
124
146
 
125
147
  ## Traps
126
148
 
127
- Landstrip failures and broker-reported denials are JSON objects with a stable
128
- `kind` and `code`. Failures and completed denials go to standard error. The
129
- sandboxed program may also write to standard error.
149
+ Landstrip failures and broker-reported denials are JSON objects with stable
150
+ `kind` and `code` fields. Completed records go to standard error.
130
151
 
131
- On Unix, `--trap-fd FD` sends structured events to an already-open descriptor
132
- numbered 3 or higher. On Linux, a socket trap descriptor can carry a
133
- `state: "query"` filesystem or network event that pauses an operation for the
134
- integrating host to answer. Query events go only to that socket. Kernel-only
135
- and static-profile denials do not always produce a per-access event.
152
+ On Unix, `--trap-fd FD` writes structured events to an already-open descriptor
153
+ numbered 3 or higher. On Linux, a socket trap descriptor can receive a
154
+ filesystem or network event with `state: "query"`; the operation waits for its
155
+ host to answer. Kernel-only and static-profile denials do not always emit a
156
+ per-access event. Trap kinds are `filesystem`, `network`, `launch`, `usage`, and
157
+ `internal`.
158
+
159
+ ## Development
160
+
161
+ ```sh
162
+ make ci
163
+ CI_MSRV=1 make ci
164
+ make package
165
+ make package PLATFORMS='linux-x64 win32-x64'
166
+ PACKAGE_STRICT=1 make package
167
+ ```
168
+
169
+ `scripts/ci.sh` checks Rust and every agent-extension workspace, stages the host
170
+ binary, and smoke-tests the npm wrapper. Packaging uses `cross` and Docker for
171
+ cross targets. macOS targets build natively on macOS; Linux hosts require local
172
+ osxcross images. Windows Arm64 requires the local
173
+ `ghcr.io/cross-rs/aarch64-pc-windows-msvc-cross:local` image.
174
+
175
+ After `scripts/release.sh <version>` and pushing the tag:
176
+
177
+ ```sh
178
+ make ci
179
+ PACKAGE_STRICT=1 make package
180
+ make publish
181
+ ```
136
182
 
137
- Trap kinds are `filesystem`, `network`, `launch`, `usage`, and `internal`.
138
- Filesystem and network records describe denied operations; the other kinds
139
- report failures in Landstrip itself.
183
+ `make publish` publishes the crates.io and npm packages and uploads release
184
+ archives from locally packaged artifacts.
140
185
 
141
186
  ## Licensing
142
187
 
143
- The JavaScript npm wrapper is licensed under `Apache-2.0`. The Rust source and
144
- native binaries are licensed under `LGPL-2.1-or-later`. Corresponding source for
145
- each native package is available from the matching repository tag.
188
+ The JavaScript wrapper is `Apache-2.0`. Rust source and native binaries are
189
+ `LGPL-2.1-or-later`; corresponding source is available from the matching tag.
package/bin/landstrip.js CHANGED
File without changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@landstrip/landstrip",
3
- "version": "0.18.26",
3
+ "version": "0.18.27",
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.18.26",
34
- "@landstrip/landstrip-darwin-x64": "0.18.26",
35
- "@landstrip/landstrip-linux-x64": "0.18.26",
36
- "@landstrip/landstrip-linux-arm64": "0.18.26",
37
- "@landstrip/landstrip-win32-x64": "0.18.26",
38
- "@landstrip/landstrip-win32-arm64": "0.18.26"
33
+ "@landstrip/landstrip-darwin-arm64": "0.18.27",
34
+ "@landstrip/landstrip-darwin-x64": "0.18.27",
35
+ "@landstrip/landstrip-linux-x64": "0.18.27",
36
+ "@landstrip/landstrip-linux-arm64": "0.18.27",
37
+ "@landstrip/landstrip-win32-x64": "0.18.27",
38
+ "@landstrip/landstrip-win32-arm64": "0.18.27"
39
39
  },
40
40
  "publishConfig": {
41
41
  "access": "public"