@landstrip/landstrip 0.14.8 → 0.15.1

package/README.md

@@ -110,35 +110,79 @@ capabilities; without it the container denies all network access.
 ## Error Output
 
 Failures reported by `landstrip` are printed as JSON objects on standard
-error, one object per line. Each object is tagged by the trap kind, with the
-kind name as the single top-level key.
+error, one object per line. Each object is a flat record with a fixed `kind`
+discriminant and a stable `code`, so consumers can route on `kind` for the
+coarse grouping and on `code` for the specific case.
 
 ```json
-{"Internal":{"file":"policy.json","source":"expected value at line 1 column 1"}}
+{"kind":"internal","code":"INTERNAL_ERROR","detail":{"file":"policy.json","source":"expected value at line 1 column 1"}}
 ```
 
 ```json
-{"Launch":["cargo","No such file or directory"]}
+{"kind":"launch","code":"LAUNCH_FAILED","program":"cargo","message":"No such file or directory"}
 ```
 
 The trap kinds are:
 
-- `Filesystem`: a filesystem access denial, as `[operation, path, mechanism]`
-  where the operation is `read` or `write` and the mechanism is the kernel
-  enforcement layer that detected the denial.
-- `Network`: a denied TCP connect or bind, as `[operation, target, mechanism]`
-  where the operation is `connect` or `bind` and the target is `address:port`.
-- `Launch`: the tool could not be started, as `[program, message]`.
-- `Usage`: a command-line usage error, as a message string. Usage errors exit
-  with status 2.
-- `Internal`: any other policy, platform, or system error, as an object of
-  diagnostic key/value pairs (for example `source`, `file`, or platform API
-  details).
+- `filesystem`: a filesystem access denial. The stable `code` is
+  `FS_READ_DENIED` or `FS_WRITE_DENIED`; `operation` is `read` or `write`;
+  `path` is the resolved path; `requested_path` is the original path supplied by
+  the tool when available; `syscall`, `errno`, `flags`, `reason`,
+  `suggested_grant`, and `process` provide machine-readable routing context.
+- `network`: a denied TCP connect or bind. The stable `code` is
+  `NET_CONNECT_DENIED` or `NET_BIND_DENIED`; `operation` is `connect` or `bind`;
+  `target` is `address:port`; `syscall`, `errno`, and `process` provide routing
+  context.
+- `launch`: the tool could not be started. The stable `code` is `LAUNCH_FAILED`;
+  `program` and `message` give the program and the failure detail.
+- `usage`: a command-line usage error. The stable `code` is `USAGE_ERROR`;
+  `message` is the error text. Usage errors exit with status 2.
+- `internal`: any other policy, platform, or system error. The stable `code` is
+  `INTERNAL_ERROR`; `detail` is an object of diagnostic key/value pairs (for
+  example `source`, `file`, or platform API details).
+
+The `reason` field is a platform-independent classification of the policy
+decision, derived from the policy and the requested path rather than from the
+enforcement mechanism. Its stable values are:
+
+- `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.
+- `unclassified`: a denial occurred but landstrip could not attribute it to a
+  specific rule.
+
+Example of a filesystem denial:
+
+```json
+{
+  "kind": "filesystem",
+  "code": "FS_WRITE_DENIED",
+  "operation": "write",
+  "path": "/repo/out",
+  "requested_path": "out",
+  "syscall": "openat",
+  "errno": "EACCES",
+  "flags": [
+    "O_WRONLY",
+    "O_CREAT",
+    "O_TRUNC"
+  ],
+  "reason": "allow_miss",
+  "suggested_grant": {
+    "allowWrite": "/repo/out"
+  },
+  "mechanism": "seccomp",
+  "process": {
+    "pid": 1234,
+    "exe": "/usr/bin/sh",
+    "cwd": "/repo"
+  }
+}
+```
 
 Logs and sandboxed tool output are not part of the response. Normal successful
 tool execution does not print a landstrip response unless a write denial was
-observed (`{"Filesystem":["write","/repo/out","seccomp"]}`), because standard error
-belongs to landstrip; standard output belongs to the sandboxed tool.
+observed, because standard error belongs to landstrip; standard output belongs
+to the sandboxed tool.
 
 ## Trap FD
 
@@ -151,15 +195,55 @@ landstrip --trap-fd 3 -p policy.json cargo test 3>landstrip-traps.txt
 ```
 
 Linux filesystem and network denials observed by the seccomp broker are
-emitted with the same shapes as standard error:
+emitted with the same object shapes as standard error:
 
 ```json
-{"Filesystem":["write","/repo/out","seccomp"]}
-{"Network":["connect","127.0.0.1:9999","seccomp"]}
+{
+  "kind": "filesystem",
+  "code": "FS_WRITE_DENIED",
+  "operation": "write",
+  "path": "/repo/out",
+  "requested_path": "out",
+  "syscall": "openat",
+  "errno": "EACCES",
+  "flags": [
+    "O_WRONLY",
+    "O_CREAT",
+    "O_TRUNC"
+  ],
+  "reason": "allow_miss",
+  "suggested_grant": {
+    "allowWrite": "/repo/out"
+  },
+  "mechanism": "seccomp",
+  "process": {
+    "pid": 1234,
+    "exe": "/usr/bin/sh",
+    "cwd": "/repo"
+  }
+}
+{
+  "kind": "network",
+  "code": "NET_CONNECT_DENIED",
+  "operation": "connect",
+  "target": "127.0.0.1:9999",
+  "syscall": "connect",
+  "errno": "EACCES",
+  "mechanism": "seccomp",
+  "process": {
+    "pid": 1234,
+    "exe": "/usr/bin/nc",
+    "cwd": "/repo"
+  }
+}
 ```
 
-The mechanism element records the kernel enforcement layer that detected
-the denial (e.g. `seccomp` or `landlock`).
+The `mechanism` field records the kernel enforcement layer that detected the
+denial. Per-denial `Filesystem` and `Network` traps are always `seccomp`,
+because the user-notification broker is the only layer with a per-denial
+callback; Landlock enforces in-kernel without one. The `landlock` value
+appears only as a `mechanism` detail in an `Internal` trap when Landlock
+ruleset setup fails.
 
 This stream is separate from the sandboxed tool's output. If the option is
 omitted, landstrip is quiet unless it has to report a policy, launch, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@landstrip/landstrip",
-  "version": "0.14.8",
+  "version": "0.15.1",
   "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",
@@ -24,10 +24,10 @@
     "LICENSE-LGPL-2.1"
   ],
   "optionalDependencies": {
-    "@landstrip/landstrip-darwin-arm64": "0.14.8",
-    "@landstrip/landstrip-darwin-x64": "0.14.8",
-    "@landstrip/landstrip-linux-x64": "0.14.8",
-    "@landstrip/landstrip-win32-x64": "0.14.8"
+    "@landstrip/landstrip-darwin-arm64": "0.15.1",
+    "@landstrip/landstrip-darwin-x64": "0.15.1",
+    "@landstrip/landstrip-linux-x64": "0.15.1",
+    "@landstrip/landstrip-win32-x64": "0.15.1"
   },
   "publishConfig": {
     "access": "public"