@oked/sdk 0.6.20 → 0.6.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -38
- package/dist/classify.d.ts +11 -2
- package/dist/classify.js +593 -42
- package/dist/describe.d.ts +7 -0
- package/dist/describe.js +41 -9
- package/dist/index.d.ts +3 -2
- package/dist/index.js +2 -2
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
# @oked/sdk
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@oked/sdk)
|
|
4
|
-
[](./dist/index.d.ts)
|
|
4
|
+
[](./LICENSE)
|
|
6
5
|
|
|
7
|
-
|
|
6
|
+
Programmatic approval API for AI agents. Send a sensitive action to the OKed backend, wait for a person, and continue only when they approve.
|
|
8
7
|
|
|
9
|
-
Use this package
|
|
8
|
+
Use this package from any Node.js agent. For drop-in integrations, see [`@oked/claude-code`](../claude-code), [`@oked/claude-agent-sdk`](../claude-agent-sdk), [`@oked/openai-agents`](../openai-agents), [`@oked/openclaw`](../openclaw), [`@oked/langgraph`](../langgraph), and [`@oked/ai-sdk`](../ai-sdk). Python agents use [`oked`](../../python/oked) and [`oked-langgraph`](../../python/oked-langgraph). Neither is on PyPI yet. Until then, `pip install "oked @ git+https://github.com/oked-ai/oked-sdk#subdirectory=python/oked"` for the client, and `pip install "oked @ git+https://github.com/oked-ai/oked-sdk#subdirectory=python/oked" "oked-langgraph @ git+https://github.com/oked-ai/oked-sdk#subdirectory=python/oked-langgraph"` for LangGraph. Once it is on PyPI, the commands are `pip install oked` and `pip install oked-langgraph`.
|
|
9
|
+
|
|
10
|
+
Decisions are made in Telegram and on the [web dashboard](https://oked.ai/dashboard). The iPhone app is coming soon. [Sign up](https://oked.ai/signup) to get an API key.
|
|
10
11
|
|
|
11
12
|
## Install
|
|
12
13
|
|
|
@@ -14,6 +15,8 @@ Use this package directly from any Node.js agent (OpenAI SDK, LangChain, custom)
|
|
|
14
15
|
npm install @oked/sdk
|
|
15
16
|
```
|
|
16
17
|
|
|
18
|
+
Node.js 18 or newer.
|
|
19
|
+
|
|
17
20
|
## Quick start
|
|
18
21
|
|
|
19
22
|
```ts
|
|
@@ -36,78 +39,89 @@ if (!result.approved) {
|
|
|
36
39
|
}
|
|
37
40
|
```
|
|
38
41
|
|
|
42
|
+
The approval window is 10 minutes. The client waits 630 seconds (`630000` ms, `DEFAULT_APPROVAL_TIMEOUT_MS`), 30 seconds past that window, so the backend's `timeout` answer arrives before the client aborts. A timeout is a denial. If you raise `timeout`, raise the harness hook limit above it. Otherwise the process can be killed before the deny is written.
|
|
43
|
+
|
|
39
44
|
## Configuration
|
|
40
45
|
|
|
41
|
-
Pass to `new OKedClient(config)
|
|
46
|
+
Pass any of these to `new OKedClient(config)`. Constructor values win over environment variables, which win over `~/.oked/config.json`.
|
|
42
47
|
|
|
43
48
|
| Key | Type | Default | Description |
|
|
44
49
|
|---|---|---|---|
|
|
45
|
-
| `apiKey` | `string` | `OKED_API_KEY
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `strictFailClosed` | `boolean` | `false` | When true, backend outages deny every tier. When false, outages deny only `high_stakes` and allow lower tiers. |
|
|
50
|
+
| `apiKey` | `string` | `OKED_API_KEY`, then the config file | OKed API key. Required for `approve`. |
|
|
51
|
+
| `timeout` | `number` | `630000` | How long to wait for a decision, in milliseconds. See above. |
|
|
52
|
+
| `strictFailClosed` | `boolean` | `false` | When true, an unreachable backend denies every tier. When false, it denies only `high_stakes`. |
|
|
49
53
|
| `requireReceipt` | `boolean` | `true` | Deny an approval that arrives without a signed receipt. A receipt that is present but invalid always denies. Set `false` (env `OKED_REQUIRE_RECEIPT=0`) only for a backend that does not sign receipts. |
|
|
50
|
-
| `receiptKeysUrl` | `string` | `https://api.oked.ai/.well-known/oked-receipt-keys.json` | Where to fetch a receipt key the SDK has not seen.
|
|
51
|
-
| `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
+
| `receiptKeysUrl` | `string` | `https://api.oked.ai/.well-known/oked-receipt-keys.json` | Where to fetch a receipt key the SDK has not seen. https only, except loopback. |
|
|
55
|
+
| `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch. For self-hosted backends and tests. |
|
|
56
|
+
| `rulesCacheTtlMs` | `number` | `300000` | How long the on-disk rules cache stays fresh. Env `OKED_RULES_CACHE_TTL` is in seconds. |
|
|
57
|
+
| `heartbeatIntervalMs` | `number` | `86400000` | Minimum gap between presence pings. Env `OKED_HEARTBEAT_INTERVAL` is in seconds. |
|
|
58
|
+
| `client` | `string` | | Your integration's name and version, for example `my-agent@1.2.0`. Recorded on the receipt. |
|
|
59
|
+
| `source` | `string` | `"sdk"` | Where the request came from. Part of the receipt subject. |
|
|
54
60
|
|
|
55
61
|
## API
|
|
56
62
|
|
|
57
63
|
### `approve(request)`
|
|
58
64
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
Request fields:
|
|
65
|
+
Ask for a decision. Resolves when the person responds, the request times out, or the backend returns an error as a thrown exception (see below).
|
|
62
66
|
|
|
63
67
|
| Field | Type | Required | Description |
|
|
64
68
|
|---|---|---|---|
|
|
65
|
-
| `action` | `string` | yes | Short action
|
|
66
|
-
| `description` | `string` | yes |
|
|
67
|
-
| `tier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | yes | Risk tier. Use `classify()` if
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
|
|
72
|
-
Response fields:
|
|
69
|
+
| `action` | `string` | yes | Short action id, for example `"deploy"`. |
|
|
70
|
+
| `description` | `string` | yes | Text shown on the approval card. |
|
|
71
|
+
| `tier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | yes | Risk tier. Use `classify()` if you are not sure. |
|
|
72
|
+
| `fields` | `Record<string, string>` | no | Card fields (title, target, body, and so on). |
|
|
73
|
+
| `tool_input` | `unknown` | no | Raw tool arguments. Included in the receipt subject. |
|
|
74
|
+
| `session_id` | `string` | no | Groups related approvals. |
|
|
75
|
+
| `cwd` | `string` | no | Working directory, shown for context. |
|
|
73
76
|
|
|
74
77
|
| Field | Type | Description |
|
|
75
78
|
|---|---|---|
|
|
76
|
-
| `approved` | `boolean` | `true` only when the
|
|
77
|
-
| `approval_id` | `string \| null` |
|
|
78
|
-
| `decision` | `"approved" \| "denied" \| "timeout"` |
|
|
79
|
-
| `receipt` | `SignedReceipt` |
|
|
79
|
+
| `approved` | `boolean` | `true` only when the person approved. |
|
|
80
|
+
| `approval_id` | `string \| null` | Id for logs. `null` when the backend created no request row. |
|
|
81
|
+
| `decision` | `"approved" \| "denied" \| "timeout"` | Outcome. |
|
|
82
|
+
| `receipt` | `SignedReceipt \| undefined` | Signed receipt, already verified against this request, this decision, and the exact action you sent. Absent for some denials and timeouts that carry no receipt. See [docs/receipts.md](../../docs/receipts.md). |
|
|
80
83
|
|
|
81
84
|
### `ping()`
|
|
82
85
|
|
|
83
|
-
Returns `true` when
|
|
86
|
+
Returns `true` when `GET https://api.oked.ai/health` succeeds within 3 seconds.
|
|
87
|
+
|
|
88
|
+
### `getRules()` and `heartbeat()`
|
|
89
|
+
|
|
90
|
+
`getRules()` returns the operator's rules, cached on disk. `heartbeat()` sends a throttled presence ping and never throws. Integrations call both. You do not need them to use `approve`.
|
|
84
91
|
|
|
85
92
|
### Helpers
|
|
86
93
|
|
|
87
|
-
- `classify(
|
|
88
|
-
- `describe(
|
|
94
|
+
- `classify(toolName, toolInput)` returns a risk tier for a tool call. Pass `{ sandboxEnforced: false }` to ask (`review`) before an opaque runner (`cargo test`, `npm test`, `npm run`, `pytest`, `go test`, `make`, `./script.sh`, `node scripts/x.mjs`, `npx`). Omit the option, or pass `true`, and those commands stay `safe`. Claude Code sets this from sandbox settings. Other hosts omit it.
|
|
95
|
+
- `describe(toolName, toolInput, ctx?)` returns a one-line description.
|
|
96
|
+
- `describeFields(toolName, toolInput, ctx?)` returns the card fields.
|
|
89
97
|
|
|
90
|
-
Full type definitions ship
|
|
98
|
+
Full type definitions ship in the package (`dist/index.d.ts`).
|
|
91
99
|
|
|
92
100
|
## Environment
|
|
93
101
|
|
|
94
102
|
| Var | Required | Description |
|
|
95
103
|
|---|---|---|
|
|
96
|
-
| `OKED_API_KEY` | yes, unless passed in code |
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
104
|
+
| `OKED_API_KEY` | yes, unless passed in code or saved by `oked init` | OKed API key. |
|
|
105
|
+
| `OKED_STRICT_FAIL_CLOSED` | no | `1` or `true` denies every sensitive action when the backend is unreachable. |
|
|
106
|
+
| `OKED_REQUIRE_RECEIPT` | no | `0` allows an approval that has no receipt. On by default. |
|
|
107
|
+
| `OKED_RECEIPT_KEYS_URL` | no | Where to fetch receipt keys. Default is OKed's published set. |
|
|
108
|
+
| `OKED_RULES_CACHE_TTL` | no | Rules cache TTL, in seconds. Default 300. |
|
|
109
|
+
| `OKED_HEARTBEAT_INTERVAL` | no | Minimum seconds between heartbeats. Default 86400. |
|
|
101
110
|
|
|
102
111
|
## Degraded-mode behavior
|
|
103
112
|
|
|
104
|
-
Explicit
|
|
113
|
+
Explicit denials return `{ approved: false }` and are final. Invalid API keys throw `OKedAuthError`. A receipt that does not verify, or an approval with no receipt while `requireReceipt` is on, throws `OKedReceiptError`. A request the backend accepted and nobody answered returns `decision: "timeout"`, not an outage error. HTTP 429 throws `OKedTooManyPendingError` (too many approvals are already waiting). Other HTTP errors throw `OKedHttpError`.
|
|
114
|
+
|
|
115
|
+
If the backend is unreachable, `OKedBackendUnreachableError` is the outage signal. `high_stakes` denies. Lower tiers may proceed unless `strictFailClosed` is set. Treat anything else as a deny.
|
|
105
116
|
|
|
106
117
|
## Development
|
|
107
118
|
|
|
119
|
+
From the repo root:
|
|
120
|
+
|
|
108
121
|
```bash
|
|
109
122
|
npm install
|
|
110
123
|
npm run build
|
|
124
|
+
npm test
|
|
111
125
|
```
|
|
112
126
|
|
|
113
127
|
## License
|
package/dist/classify.d.ts
CHANGED
|
@@ -1,11 +1,20 @@
|
|
|
1
1
|
import type { RiskTier } from "./types.js";
|
|
2
|
-
|
|
2
|
+
/**
|
|
3
|
+
* `sandboxEnforced: false` asks for `review` before an opaque code runner
|
|
4
|
+
* (a test runner, package script, script file, or npx tool). `true` or omitted
|
|
5
|
+
* leaves those commands `safe`. Claude Code sets this from sandbox settings.
|
|
6
|
+
* Other hosts omit it and keep the previous behaviour.
|
|
7
|
+
*/
|
|
8
|
+
export interface ClassifyOptions {
|
|
9
|
+
sandboxEnforced?: boolean;
|
|
10
|
+
}
|
|
11
|
+
export declare function classify(toolName: string, toolInput: Record<string, unknown>, options?: ClassifyOptions): RiskTier;
|
|
3
12
|
/**
|
|
4
13
|
* Tier of each step of a compound command, read the way the whole command is
|
|
5
14
|
* read: a step sees the temp files and temp folders that earlier steps made
|
|
6
15
|
* (`cat > _s.mjs <<EOF … && rm _s.mjs`). `classify` of one step alone does not.
|
|
7
16
|
*/
|
|
8
|
-
export declare function classifyBashSteps(steps: string[]): RiskTier[];
|
|
17
|
+
export declare function classifyBashSteps(steps: string[], sandboxEnforced?: boolean): RiskTier[];
|
|
9
18
|
/** Split a shell command into top-level segments on the operators that
|
|
10
19
|
* sequence separate commands: `|`, `||`, `&&`, `;`, and a bare newline (a
|
|
11
20
|
* newline separates commands in a multi-line script exactly like `;`).
|
package/dist/classify.js
CHANGED
|
@@ -17,12 +17,14 @@ import { TIER_ORDER } from "./degraded.js";
|
|
|
17
17
|
// Tier 3 - review: push notification, tap to approve. Prompt-worthy but not
|
|
18
18
|
// catastrophic: sensitive-path writes (~/.ssh, shell rc, system
|
|
19
19
|
// dirs, OKed's own config), sudo, outward message/email sends,
|
|
20
|
-
// curl POST/PUT/PATCH with an inline body
|
|
20
|
+
// curl POST/PUT/PATCH with an inline body, other cloud CLI writes
|
|
21
|
+
// (create, update, upload, preview deploy, kubectl apply/exec).
|
|
21
22
|
// Tier 4 - high_stakes: push + number matching. Destructive / irreversible /
|
|
22
23
|
// external: rm of non-temp data, DROP/TRUNCATE/DELETE FROM,
|
|
23
24
|
// git push --force / reset --hard / branch -D, mkfs / dd-to-device /
|
|
24
25
|
// shutdown, curl DELETE / file upload / pay-or-send API, ssh/scp,
|
|
25
|
-
// npm publish, kill
|
|
26
|
+
// npm publish, kill, cloud and cluster deletes, terraform apply /
|
|
27
|
+
// pulumi up, production deploys, Stripe CLI writes.
|
|
26
28
|
// Tools that are always safe (read-only, no side effects)
|
|
27
29
|
const SAFE_TOOLS = new Set([
|
|
28
30
|
"Read",
|
|
@@ -90,7 +92,7 @@ const WARNING_SESSION_TOOLS = new Set([
|
|
|
90
92
|
"WebFetch",
|
|
91
93
|
]);
|
|
92
94
|
/** Built-ins whose tier depends on their input. Returns null for other tools. */
|
|
93
|
-
function classifySessionTool(toolName, toolInput) {
|
|
95
|
+
function classifySessionTool(toolName, toolInput, sandboxEnforced) {
|
|
94
96
|
switch (toolName) {
|
|
95
97
|
// "keep" leaves everything on disk. "remove" refuses when there is
|
|
96
98
|
// unsaved work, unless discard_changes deletes it for good.
|
|
@@ -101,7 +103,7 @@ function classifySessionTool(toolName, toolInput) {
|
|
|
101
103
|
// Monitor runs a shell command (classified like Bash) or reads a WebSocket.
|
|
102
104
|
case "Monitor":
|
|
103
105
|
if (typeof toolInput.command === "string")
|
|
104
|
-
return classifyBashCommand(toolInput.command);
|
|
106
|
+
return classifyBashCommand(toolInput.command, new Set(), sandboxEnforced);
|
|
105
107
|
return "warning";
|
|
106
108
|
// Artifact: publishing puts content on claude.ai; delete is permanent;
|
|
107
109
|
// read / list / open / quickstart / pin only look or arrange.
|
|
@@ -325,6 +327,277 @@ const REVIEW_COMMANDS = [
|
|
|
325
327
|
/^gh\s+run\s+(?:cancel|rerun)\b/,
|
|
326
328
|
/^gh\s+(?:gist|label)\s+(?:create|edit)\b/,
|
|
327
329
|
];
|
|
330
|
+
// Cloud, cluster, infrastructure, deploy and payment CLIs change live systems
|
|
331
|
+
// that other people use, so the `safe` default for an unknown command is wrong
|
|
332
|
+
// for their writes. The CLI's own subcommand words pick the tier: a delete, an
|
|
333
|
+
// infrastructure apply, a production deploy or a payment → high_stakes; any
|
|
334
|
+
// other write (create, update, upload, a preview deploy, exec into a pod) →
|
|
335
|
+
// review; reads (`aws s3 ls`, `kubectl get`, `terraform plan`) stay safe, and so
|
|
336
|
+
// do `--help` and dry runs. Matched on the stage's command word, so the CLI name
|
|
337
|
+
// in an argument or a commit message is not the command.
|
|
338
|
+
// A package runner in front of the CLI (`npx vercel@latest --prod`).
|
|
339
|
+
const CLI_RUNNER_RE = /^(?:npx|bunx|pnpx|(?:pnpm|yarn|bun)\s+(?:dlx|exec|x))\s+(?:-\S+\s+)*/;
|
|
340
|
+
// `--dry-run=none` (kubectl) and `--dry-run=false` are real runs.
|
|
341
|
+
const CLI_PREVIEW_ARG_RE = /^(?:--help|-help|--dry-?run(?:=(?:true|client|server))?)$/;
|
|
342
|
+
// Subcommand words that delete, tear down or redeploy a live resource, and
|
|
343
|
+
// words that create or change one. A hyphenated word (`delete-stack`,
|
|
344
|
+
// `add-iam-policy-binding`) is read by its first part.
|
|
345
|
+
const CLOUD_DELETE_WORDS = new Set(["delete", "destroy", "terminate", "purge", "remove", "rm", "rb", "uninstall", "drain"]);
|
|
346
|
+
const CLOUD_DEPLOY_WORDS = new Set(["deploy", "rollback", "promote"]);
|
|
347
|
+
const CLOUD_WRITE_WORDS = new Set([
|
|
348
|
+
"create", "update", "patch", "apply", "set", "unset", "add", "put", "push", "upload", "import",
|
|
349
|
+
"start", "stop", "restart", "reboot", "reset", "resize", "scale", "enable", "disable", "attach",
|
|
350
|
+
"detach", "move", "rename", "restore", "cancel", "upgrade", "install", "invoke", "call", "execute",
|
|
351
|
+
"exec", "ssh", "scp", "submit", "connect", "failover", "issue", "transfer", "clone", "extend",
|
|
352
|
+
"launch", "console",
|
|
353
|
+
]);
|
|
354
|
+
function cloudWordTier(word) {
|
|
355
|
+
const [head, ...rest] = word.split("-");
|
|
356
|
+
if (rest.length === 0) {
|
|
357
|
+
if (CLOUD_DELETE_WORDS.has(word) || CLOUD_DEPLOY_WORDS.has(word))
|
|
358
|
+
return "high_stakes";
|
|
359
|
+
return CLOUD_WRITE_WORDS.has(word) ? "review" : "safe";
|
|
360
|
+
}
|
|
361
|
+
if (/^(?:delete|destroy|terminate|purge|deregister)$/.test(head))
|
|
362
|
+
return "high_stakes";
|
|
363
|
+
return CLOUD_WRITE_WORDS.has(head) || head === "remove" ? "review" : "safe";
|
|
364
|
+
}
|
|
365
|
+
function maxCloudWordTier(words) {
|
|
366
|
+
return words.reduce((t, w) => maxTier(t, cloudWordTier(w)), "safe");
|
|
367
|
+
}
|
|
368
|
+
/** The non-flag arguments, without the values of `valueFlags` and redirects. */
|
|
369
|
+
function cliPositionals(args, valueFlags = new Set()) {
|
|
370
|
+
const out = [];
|
|
371
|
+
for (let i = 0; i < args.length; i++) {
|
|
372
|
+
const a = args[i];
|
|
373
|
+
if (/^(?:\d|&)?>{1,2}$|^<$/.test(a)) {
|
|
374
|
+
i++;
|
|
375
|
+
continue;
|
|
376
|
+
} // `> log`
|
|
377
|
+
if (/^(?:\d|&)?>|^</.test(a))
|
|
378
|
+
continue; // `2>&1`, `>log`
|
|
379
|
+
if (a.startsWith("-")) {
|
|
380
|
+
if (valueFlags.has(a))
|
|
381
|
+
i++;
|
|
382
|
+
continue;
|
|
383
|
+
}
|
|
384
|
+
out.push(a);
|
|
385
|
+
}
|
|
386
|
+
return out;
|
|
387
|
+
}
|
|
388
|
+
/** `aws s3`, `gsutil`, `gcloud storage`: delete, upload, or download. */
|
|
389
|
+
function objectStoreTier(op, pos, args, scheme) {
|
|
390
|
+
if (op === "rm" || op === "rb")
|
|
391
|
+
return "high_stakes";
|
|
392
|
+
if (op === "mv" || op === "mb")
|
|
393
|
+
return "review";
|
|
394
|
+
if (op === "cp" || op === "sync" || op === "rsync") {
|
|
395
|
+
if (op !== "cp" && args.some((a) => /^(?:--delete|-d|--delete-unmatched-destination-objects)$/.test(a)))
|
|
396
|
+
return "high_stakes";
|
|
397
|
+
return (pos[pos.length - 1] ?? "").startsWith(scheme) ? "review" : "safe"; // to a bucket, or a download
|
|
398
|
+
}
|
|
399
|
+
return null;
|
|
400
|
+
}
|
|
401
|
+
const AWS_VALUE_FLAGS = new Set(["--profile", "--region", "--output", "--endpoint-url", "--query", "--color",
|
|
402
|
+
"--ca-bundle", "--cli-read-timeout", "--cli-connect-timeout", "--cli-binary-format"]);
|
|
403
|
+
// Operations that only read. An aws operation that is not a read is a write.
|
|
404
|
+
const AWS_READ_OP_RE = /^(?:describe|list|get|head|batch-get|search|scan|query|lookup|filter|select|estimate|validate|simulate|test|preview|wait|tail|ls|help|check|presign)(?:-|$)/;
|
|
405
|
+
const AWS_LOCAL_SERVICES = new Set(["configure", "sso", "sso-oidc", "sts", "help", "history"]);
|
|
406
|
+
function awsTier(args) {
|
|
407
|
+
const pos = cliPositionals(args, AWS_VALUE_FLAGS);
|
|
408
|
+
const [service, op] = pos;
|
|
409
|
+
if (!service || !op || AWS_LOCAL_SERVICES.has(service))
|
|
410
|
+
return "safe";
|
|
411
|
+
if (service === "s3")
|
|
412
|
+
return objectStoreTier(op, pos, args, "s3://") ?? (op === "ls" ? "safe" : "review");
|
|
413
|
+
if (/^(?:delete|terminate|purge|deregister|destroy)-/.test(op) || op === "deploy")
|
|
414
|
+
return "high_stakes";
|
|
415
|
+
return AWS_READ_OP_RE.test(op) ? "safe" : "review";
|
|
416
|
+
}
|
|
417
|
+
const KUBECTL_VALUE_FLAGS = new Set(["-n", "--namespace", "--context", "--kubeconfig", "--cluster", "--user",
|
|
418
|
+
"-s", "--server", "--as", "--as-group", "--token", "--request-timeout", "-l", "--selector", "-f",
|
|
419
|
+
"--filename", "-c", "--container", "-o", "--output"]);
|
|
420
|
+
const KUBECTL_WRITE_VERBS = new Set(["apply", "create", "patch", "replace", "edit", "scale", "autoscale", "set",
|
|
421
|
+
"label", "annotate", "taint", "cordon", "uncordon", "expose", "run", "exec", "cp", "attach", "debug", "certificate"]);
|
|
422
|
+
function kubectlTier(args) {
|
|
423
|
+
const [verb, sub] = cliPositionals(args, KUBECTL_VALUE_FLAGS);
|
|
424
|
+
if (verb === "delete" || verb === "drain")
|
|
425
|
+
return "high_stakes";
|
|
426
|
+
if (verb === "rollout")
|
|
427
|
+
return ["restart", "undo", "pause", "resume"].includes(sub) ? "review" : "safe";
|
|
428
|
+
return KUBECTL_WRITE_VERBS.has(verb) ? "review" : "safe";
|
|
429
|
+
}
|
|
430
|
+
function terraformTier(args) {
|
|
431
|
+
let [verb, sub] = cliPositionals(args);
|
|
432
|
+
// terragrunt `run-all apply`
|
|
433
|
+
if (verb === "run-all" || verb === "run")
|
|
434
|
+
[verb, sub] = cliPositionals(args).slice(1);
|
|
435
|
+
if (verb === "apply" || verb === "destroy")
|
|
436
|
+
return "high_stakes";
|
|
437
|
+
if (["import", "taint", "untaint", "force-unlock", "refresh"].includes(verb))
|
|
438
|
+
return "review";
|
|
439
|
+
if (verb === "state" && ["rm", "mv", "push", "replace-provider"].includes(sub))
|
|
440
|
+
return "review";
|
|
441
|
+
if (verb === "workspace" && sub === "delete")
|
|
442
|
+
return "review";
|
|
443
|
+
return "safe";
|
|
444
|
+
}
|
|
445
|
+
const VERCEL_VALUE_FLAGS = new Set(["--scope", "-S", "--token", "-t", "--cwd", "-A", "--local-config", "-Q",
|
|
446
|
+
"--global-config", "--target", "-e", "--env", "-b", "--build-env", "-m", "--meta", "--regions", "--archive"]);
|
|
447
|
+
// Subcommands other than a deploy. A first word that is none of these is a
|
|
448
|
+
// path to deploy, as vercel reads it.
|
|
449
|
+
const VERCEL_SUBCOMMANDS = new Set(["alias", "bisect", "blob", "build", "cache", "certs", "curl", "dev", "dns",
|
|
450
|
+
"domains", "env", "git", "help", "init", "inspect", "install", "integration", "link", "list", "login",
|
|
451
|
+
"logout", "logs", "ls", "mcp", "microfrontends", "open", "project", "projects", "promote", "pull",
|
|
452
|
+
"redeploy", "remove", "rm", "rollback", "switch", "target", "teams", "telemetry", "whoami"]);
|
|
453
|
+
function vercelTier(args) {
|
|
454
|
+
const [sub, op] = cliPositionals(args, VERCEL_VALUE_FLAGS);
|
|
455
|
+
const prod = args.some((a, i) => a === "--prod" || a === "--target=production" ||
|
|
456
|
+
(a === "--target" && args[i + 1] === "production"));
|
|
457
|
+
if (sub === undefined || sub === "deploy" || !VERCEL_SUBCOMMANDS.has(sub))
|
|
458
|
+
return prod ? "high_stakes" : "review";
|
|
459
|
+
if (sub === "redeploy")
|
|
460
|
+
return prod ? "high_stakes" : "review";
|
|
461
|
+
if (["rm", "remove", "promote", "rollback"].includes(sub))
|
|
462
|
+
return "high_stakes";
|
|
463
|
+
if (sub === "alias")
|
|
464
|
+
return op === "set" || op === "rm" || op === "remove" ? "high_stakes" : "safe";
|
|
465
|
+
if (["env", "domains", "dns", "certs", "project", "projects", "teams", "blob", "integration"].includes(sub)) {
|
|
466
|
+
return op === undefined ? "safe" : cloudWordTier(op);
|
|
467
|
+
}
|
|
468
|
+
return "safe";
|
|
469
|
+
}
|
|
470
|
+
/** Tier of a single stage that runs a cloud CLI, or null for any other stage. */
|
|
471
|
+
function classifyCloudCliStage(stage) {
|
|
472
|
+
// The same wrappers the delete scan strips (`xargs kubectl delete`, `do aws
|
|
473
|
+
// s3 rb …`, `time terraform apply`), then a package runner.
|
|
474
|
+
const args = splitArgs(stage.replace(DELETE_LEAD, "").replace(CLI_RUNNER_RE, ""));
|
|
475
|
+
const tool = (args.shift() ?? "").replace(/^.*\//, "").replace(/(?<=.)@.*$/, "");
|
|
476
|
+
const known = ["aws", "kubectl", "helm", "terraform", "tofu", "terragrunt", "pulumi", "cdk", "serverless",
|
|
477
|
+
"sls", "gcloud", "gsutil", "az", "doctl", "eksctl", "vercel", "netlify", "fly", "flyctl", "heroku",
|
|
478
|
+
"wrangler", "firebase", "stripe"];
|
|
479
|
+
if (!known.includes(tool))
|
|
480
|
+
return null;
|
|
481
|
+
// Arguments after `--` belong to another command (`kubectl exec pod -- x
|
|
482
|
+
// --help`), so a `--help` there does not make this one a preview.
|
|
483
|
+
const sep = args.indexOf("--");
|
|
484
|
+
if ((sep === -1 ? args : args.slice(0, sep)).some((a) => CLI_PREVIEW_ARG_RE.test(a)))
|
|
485
|
+
return "safe";
|
|
486
|
+
const pos = cliPositionals(args);
|
|
487
|
+
if (pos[0] === "help")
|
|
488
|
+
return "safe";
|
|
489
|
+
const has = (re) => args.some((a) => re.test(a));
|
|
490
|
+
switch (tool) {
|
|
491
|
+
case "aws": return awsTier(args);
|
|
492
|
+
case "kubectl": return kubectlTier(args);
|
|
493
|
+
case "helm": {
|
|
494
|
+
const [verb] = cliPositionals(args, new Set(["-n", "--namespace", "--kube-context", "--kubeconfig"]));
|
|
495
|
+
if (["uninstall", "delete", "del", "un", "rollback"].includes(verb))
|
|
496
|
+
return "high_stakes";
|
|
497
|
+
return ["install", "upgrade", "push"].includes(verb) ? "review" : "safe";
|
|
498
|
+
}
|
|
499
|
+
case "terraform":
|
|
500
|
+
case "tofu":
|
|
501
|
+
case "terragrunt": return terraformTier(args);
|
|
502
|
+
case "pulumi": {
|
|
503
|
+
const [verb, sub] = cliPositionals(args, new Set(["-s", "--stack", "-C", "--cwd"]));
|
|
504
|
+
if (["up", "update", "destroy"].includes(verb) || (verb === "stack" && sub === "rm"))
|
|
505
|
+
return "high_stakes";
|
|
506
|
+
if (["refresh", "import", "cancel"].includes(verb))
|
|
507
|
+
return "review";
|
|
508
|
+
return verb === "state" && ["delete", "move", "unprotect"].includes(sub) ? "review" : "safe";
|
|
509
|
+
}
|
|
510
|
+
case "cdk": return ["deploy", "destroy"].includes(pos[0]) ? "high_stakes" : pos[0] === "bootstrap" ? "review" : "safe";
|
|
511
|
+
case "serverless":
|
|
512
|
+
case "sls":
|
|
513
|
+
if (["deploy", "remove"].includes(pos[0]))
|
|
514
|
+
return "high_stakes";
|
|
515
|
+
return pos[0] === "invoke" && pos[1] !== "local" ? "review" : "safe";
|
|
516
|
+
case "gcloud":
|
|
517
|
+
case "az":
|
|
518
|
+
case "doctl":
|
|
519
|
+
case "eksctl": {
|
|
520
|
+
const flags = {
|
|
521
|
+
gcloud: ["--project", "--account", "--configuration", "--format", "--verbosity", "--impersonate-service-account"],
|
|
522
|
+
az: ["--subscription", "-o", "--output", "--query"],
|
|
523
|
+
doctl: ["--context", "-t", "--access-token", "-o", "--output", "--config"],
|
|
524
|
+
eksctl: [],
|
|
525
|
+
}[tool];
|
|
526
|
+
const words = cliPositionals(args, new Set(flags));
|
|
527
|
+
// Local CLI config and sign-in (`gcloud config set project x`).
|
|
528
|
+
const local = { gcloud: ["config", "auth", "components", "info", "init", "version", "topic"],
|
|
529
|
+
az: ["account", "config", "configure", "login", "logout", "extension", "version", "upgrade", "cloud", "find"],
|
|
530
|
+
doctl: ["auth", "version", "completion"], eksctl: ["version", "info"] }[tool];
|
|
531
|
+
if (local.includes(words[0]))
|
|
532
|
+
return "safe";
|
|
533
|
+
if (tool === "gcloud" && words[0] === "storage") {
|
|
534
|
+
const t = objectStoreTier(words[1], words, args, "gs://");
|
|
535
|
+
if (t !== null)
|
|
536
|
+
return t;
|
|
537
|
+
}
|
|
538
|
+
// The first word of gcloud, az and doctl is a product group (`gcloud
|
|
539
|
+
// deploy`, `gcloud run`), not a verb. eksctl is verb first.
|
|
540
|
+
return maxCloudWordTier(tool === "eksctl" ? words : words.slice(1));
|
|
541
|
+
}
|
|
542
|
+
case "gsutil": {
|
|
543
|
+
const words = cliPositionals(args, new Set(["-o", "-h", "-u"]));
|
|
544
|
+
const t = objectStoreTier(words[0], words, args, "gs://");
|
|
545
|
+
if (t !== null)
|
|
546
|
+
return t;
|
|
547
|
+
return words[1] === "set" || words[1] === "ch" || words[0] === "setmeta" ? "review" : "safe";
|
|
548
|
+
}
|
|
549
|
+
case "vercel": return vercelTier(args);
|
|
550
|
+
case "netlify": {
|
|
551
|
+
const words = cliPositionals(args, new Set(["--site", "--dir", "-d", "--auth", "--filter", "-a", "-s", "-m", "--message", "--alias"]));
|
|
552
|
+
if (words[0] === "deploy")
|
|
553
|
+
return has(/^(?:--prod|-p|--prodIfUnlocked|--prod-if-unlocked)$/) ? "high_stakes" : "review";
|
|
554
|
+
return cloudWordTier((words[0] ?? "").split(":").pop() ?? "");
|
|
555
|
+
}
|
|
556
|
+
case "fly":
|
|
557
|
+
case "flyctl": {
|
|
558
|
+
const words = cliPositionals(args, new Set(["-a", "--app", "-c", "--config", "-r", "--region", "--image", "-t", "--access-token"]));
|
|
559
|
+
return words.includes("run") ? maxTier("review", maxCloudWordTier(words)) : maxCloudWordTier(words);
|
|
560
|
+
}
|
|
561
|
+
case "heroku": {
|
|
562
|
+
const parts = (cliPositionals(args, new Set(["-a", "--app", "-r", "--remote"]))[0] ?? "").split(":");
|
|
563
|
+
const last = parts[parts.length - 1];
|
|
564
|
+
if (parts[0] === "pg" && ["reset", "copy", "push"].includes(last))
|
|
565
|
+
return "high_stakes";
|
|
566
|
+
return last === "run" ? "review" : cloudWordTier(last);
|
|
567
|
+
}
|
|
568
|
+
case "wrangler": {
|
|
569
|
+
const words = cliPositionals(args, new Set(["-c", "--config", "-e", "--env", "--name"]))
|
|
570
|
+
// `d1 execute` runs on a local database unless `--remote`.
|
|
571
|
+
.filter((w) => w !== "execute" || args.includes("--remote"));
|
|
572
|
+
return words.includes("publish") ? "high_stakes" : maxCloudWordTier(words);
|
|
573
|
+
}
|
|
574
|
+
case "firebase": {
|
|
575
|
+
const words = cliPositionals(args, new Set(["-P", "--project", "--only", "--except", "--token"]));
|
|
576
|
+
const parts = (words[0] ?? "").split(":");
|
|
577
|
+
const last = parts[parts.length - 1];
|
|
578
|
+
if (parts[0] === "emulators")
|
|
579
|
+
return "safe";
|
|
580
|
+
if (words[0] === "deploy" || words[0] === "hosting:disable")
|
|
581
|
+
return "high_stakes";
|
|
582
|
+
// A preview channel deploy (`hosting:channel:deploy`) does not reach the live site.
|
|
583
|
+
return last === "deploy" ? "review" : cloudWordTier(last);
|
|
584
|
+
}
|
|
585
|
+
case "stripe": {
|
|
586
|
+
const [resource, op] = cliPositionals(args, new Set(["--api-key", "--project-name", "-p", "--device-name",
|
|
587
|
+
"--color", "--log-level", "--config"]));
|
|
588
|
+
// A raw API write, or any resource operation that is not a read. Matches
|
|
589
|
+
// the curl rule for the Stripe API: it can move money.
|
|
590
|
+
if (resource === "post" || resource === "delete")
|
|
591
|
+
return "high_stakes";
|
|
592
|
+
const local = ["get", "listen", "logs", "login", "logout", "config", "samples", "trigger", "open",
|
|
593
|
+
"status", "version", "completion", "serve", "resources", "feedback", "community", "daemon", "plugin", "fixtures"];
|
|
594
|
+
if (!resource || !op || local.includes(resource))
|
|
595
|
+
return "safe";
|
|
596
|
+
return ["list", "retrieve", "search"].includes(op) ? "safe" : "high_stakes";
|
|
597
|
+
}
|
|
598
|
+
}
|
|
599
|
+
return null;
|
|
600
|
+
}
|
|
328
601
|
/**
|
|
329
602
|
* `gh api` is curl for GitHub: a mutating method, or fields without a method
|
|
330
603
|
* (gh then sends a POST), is an outward write like a curl POST. A GraphQL call
|
|
@@ -348,12 +621,13 @@ function classifyGhApiStage(stage) {
|
|
|
348
621
|
// (silent) label, and cover the local mutations we can recognize by shape but
|
|
349
622
|
// that aren't a plain file write (those are handled by extractShellWriteOps).
|
|
350
623
|
//
|
|
351
|
-
// Opaque code execution (node
|
|
352
|
-
//
|
|
353
|
-
//
|
|
354
|
-
//
|
|
355
|
-
//
|
|
356
|
-
//
|
|
624
|
+
// Opaque code execution (node -e, npx, python -c, test runners, script files)
|
|
625
|
+
// is intentionally NOT a warning marker. A warning only adds a log line, and
|
|
626
|
+
// the hook still cannot see what the child process runs. When the host sandbox
|
|
627
|
+
// is not enforcing containment, classify() with `sandboxEnforced: false` raises
|
|
628
|
+
// test runners and script files to `review` (see isOpaqueCodeRunner). Other
|
|
629
|
+
// hosts omit that option, so those commands stay `safe`. Inline interpreter
|
|
630
|
+
// bodies stay unscanned as shell, because shell tokens in the body are data.
|
|
357
631
|
const WARNING_COMMANDS = [
|
|
358
632
|
// Local, reversible git writes — stage/commit/switch/stash. They mutate the
|
|
359
633
|
// local repo but can be undone (amend, reset, checkout). Destructive git
|
|
@@ -544,7 +818,8 @@ function isSensitiveWritePath(filePath) {
|
|
|
544
818
|
return true;
|
|
545
819
|
return false;
|
|
546
820
|
}
|
|
547
|
-
export function classify(toolName, toolInput) {
|
|
821
|
+
export function classify(toolName, toolInput, options) {
|
|
822
|
+
const sandboxEnforced = options?.sandboxEnforced;
|
|
548
823
|
// Check tool-level classification first
|
|
549
824
|
if (SAFE_TOOLS.has(toolName))
|
|
550
825
|
return "safe";
|
|
@@ -558,7 +833,7 @@ export function classify(toolName, toolInput) {
|
|
|
558
833
|
return "safe";
|
|
559
834
|
if (WARNING_SESSION_TOOLS.has(toolName))
|
|
560
835
|
return "warning";
|
|
561
|
-
const sessionTier = classifySessionTool(toolName, toolInput);
|
|
836
|
+
const sessionTier = classifySessionTool(toolName, toolInput, sandboxEnforced);
|
|
562
837
|
if (sessionTier !== null)
|
|
563
838
|
return sessionTier;
|
|
564
839
|
// File-editing tools: a write/edit can't act on its own — whatever later
|
|
@@ -578,7 +853,7 @@ export function classify(toolName, toolInput) {
|
|
|
578
853
|
return "safe";
|
|
579
854
|
// Bash commands need deeper analysis
|
|
580
855
|
if (toolName === "Bash") {
|
|
581
|
-
return classifyBashCommand(toolInput.command);
|
|
856
|
+
return classifyBashCommand(toolInput.command, new Set(), sandboxEnforced);
|
|
582
857
|
}
|
|
583
858
|
// MCP tools: mcp__<server>__<tool>
|
|
584
859
|
if (toolName.startsWith("mcp__")) {
|
|
@@ -589,7 +864,7 @@ export function classify(toolName, toolInput) {
|
|
|
589
864
|
// command/cmd field. Route through bash classification.
|
|
590
865
|
const shellCommand = (toolInput.command ?? toolInput.cmd);
|
|
591
866
|
if (typeof shellCommand === "string") {
|
|
592
|
-
return classifyBashCommand(shellCommand);
|
|
867
|
+
return classifyBashCommand(shellCommand, new Set(), sandboxEnforced);
|
|
593
868
|
}
|
|
594
869
|
// File-write-style tools from other agents (OpenClaw `write`, generic
|
|
595
870
|
// `create_file`, `file_write`). Detect by signature: string path field
|
|
@@ -607,13 +882,13 @@ export function classify(toolName, toolInput) {
|
|
|
607
882
|
* read: a step sees the temp files and temp folders that earlier steps made
|
|
608
883
|
* (`cat > _s.mjs <<EOF … && rm _s.mjs`). `classify` of one step alone does not.
|
|
609
884
|
*/
|
|
610
|
-
export function classifyBashSteps(steps) {
|
|
885
|
+
export function classifyBashSteps(steps, sandboxEnforced) {
|
|
611
886
|
const vars = new Set();
|
|
612
887
|
for (const step of steps)
|
|
613
888
|
for (const stage of splitTopLevel(step))
|
|
614
889
|
collectMktempVars(stage, vars);
|
|
615
890
|
return steps.map((step) => {
|
|
616
|
-
const tier = classifyBashCommand(step, vars);
|
|
891
|
+
const tier = classifyBashCommand(step, vars, sandboxEnforced);
|
|
617
892
|
for (const stage of splitTopLevel(step))
|
|
618
893
|
noteEphemeralEffects(stripHeredocBodies(stage), vars);
|
|
619
894
|
return tier;
|
|
@@ -784,7 +1059,7 @@ function isBuildOutputOnlyDeletion(command) {
|
|
|
784
1059
|
* values, plus any trailing command. A purely literal assignment is `safe`.
|
|
785
1060
|
* Returns null if the stage is not assignment-prefixed.
|
|
786
1061
|
*/
|
|
787
|
-
function classifyAssignmentStage(stage) {
|
|
1062
|
+
function classifyAssignmentStage(stage, sandboxEnforced) {
|
|
788
1063
|
if (!/^\w+=/.test(stage))
|
|
789
1064
|
return null;
|
|
790
1065
|
const inners = [];
|
|
@@ -839,9 +1114,9 @@ function classifyAssignmentStage(stage) {
|
|
|
839
1114
|
const rest = stage.slice(i).trim();
|
|
840
1115
|
let tier = "safe";
|
|
841
1116
|
for (const inner of inners)
|
|
842
|
-
tier = maxTier(tier, classifyBashCommand(inner));
|
|
1117
|
+
tier = maxTier(tier, classifyBashCommand(inner, new Set(), sandboxEnforced));
|
|
843
1118
|
if (rest)
|
|
844
|
-
tier = maxTier(tier, classifyBashCommand(rest));
|
|
1119
|
+
tier = maxTier(tier, classifyBashCommand(rest, new Set(), sandboxEnforced));
|
|
845
1120
|
return tier;
|
|
846
1121
|
}
|
|
847
1122
|
/**
|
|
@@ -852,7 +1127,7 @@ function classifyAssignmentStage(stage) {
|
|
|
852
1127
|
* (quote-preserving) offset. `env` with no command just prints the environment
|
|
853
1128
|
* → safe. Returns null if the stage doesn't start with `env`.
|
|
854
1129
|
*/
|
|
855
|
-
function classifyEnvStage(stage) {
|
|
1130
|
+
function classifyEnvStage(stage, sandboxEnforced) {
|
|
856
1131
|
const lead = /^env\b[ \t]*/.exec(stage);
|
|
857
1132
|
if (!lead)
|
|
858
1133
|
return null;
|
|
@@ -903,7 +1178,7 @@ function classifyEnvStage(stage) {
|
|
|
903
1178
|
}
|
|
904
1179
|
if (/^\w+=/.test(tok))
|
|
905
1180
|
continue; // NAME=VALUE
|
|
906
|
-
return classifyBashCommand(stage.slice(start).trim()); // first real word → the command
|
|
1181
|
+
return classifyBashCommand(stage.slice(start).trim(), new Set(), sandboxEnforced); // first real word → the command
|
|
907
1182
|
}
|
|
908
1183
|
return "safe"; // `env` / `env -u X` with no command just prints the environment
|
|
909
1184
|
}
|
|
@@ -921,7 +1196,7 @@ const GIT_GLOBAL_ARG_OPTS = new Set([
|
|
|
921
1196
|
* can define a shell command, so it gets a `review` floor. Returns null if the
|
|
922
1197
|
* stage is not a git call with global options.
|
|
923
1198
|
*/
|
|
924
|
-
function classifyGitGlobalOptsStage(stage, ephemeralVars) {
|
|
1199
|
+
function classifyGitGlobalOptsStage(stage, ephemeralVars, sandboxEnforced) {
|
|
925
1200
|
const lead = /^git[ \t]+(?=-)/.exec(stage);
|
|
926
1201
|
if (!lead)
|
|
927
1202
|
return null;
|
|
@@ -958,7 +1233,7 @@ function classifyGitGlobalOptsStage(stage, ephemeralVars) {
|
|
|
958
1233
|
i = readToken(i);
|
|
959
1234
|
const tok = stage.slice(start, i);
|
|
960
1235
|
if (!tok.startsWith("-")) {
|
|
961
|
-
const inner = classifyBashCommand(`git ${stage.slice(start).trim()}`, ephemeralVars);
|
|
1236
|
+
const inner = classifyBashCommand(`git ${stage.slice(start).trim()}`, ephemeralVars, sandboxEnforced);
|
|
962
1237
|
return maxTier(floor, inner);
|
|
963
1238
|
}
|
|
964
1239
|
let value = "";
|
|
@@ -992,7 +1267,7 @@ const SSH_ARG_OPTS = new Set([
|
|
|
992
1267
|
* isn't an ssh invocation. Excludes `ssh-keygen`/`ssh-add`/`ssh-keyscan` (the
|
|
993
1268
|
* `^ssh\s` anchor requires whitespace, not a hyphen).
|
|
994
1269
|
*/
|
|
995
|
-
function classifySshStage(stage) {
|
|
1270
|
+
function classifySshStage(stage, sandboxEnforced) {
|
|
996
1271
|
const lead = /^ssh\s+/.exec(stage);
|
|
997
1272
|
if (!lead)
|
|
998
1273
|
return null;
|
|
@@ -1050,7 +1325,7 @@ function classifySshStage(stage) {
|
|
|
1050
1325
|
if (rest.length >= 2 && (rest[0] === '"' || rest[0] === "'") && rest[rest.length - 1] === rest[0]) {
|
|
1051
1326
|
rest = rest.slice(1, -1);
|
|
1052
1327
|
}
|
|
1053
|
-
return classifyBashCommand(rest);
|
|
1328
|
+
return classifyBashCommand(rest, new Set(), sandboxEnforced);
|
|
1054
1329
|
}
|
|
1055
1330
|
return "review"; // only options / a bare host token → treat as remote access
|
|
1056
1331
|
}
|
|
@@ -1062,11 +1337,11 @@ function classifySshStage(stage) {
|
|
|
1062
1337
|
* `grep -c`) is unaffected because the stage doesn't start with a shell name.
|
|
1063
1338
|
* Returns null if the stage isn't a `sh -c`-style invocation.
|
|
1064
1339
|
*/
|
|
1065
|
-
function classifyShellCStage(stage) {
|
|
1340
|
+
function classifyShellCStage(stage, sandboxEnforced) {
|
|
1066
1341
|
const m = stage.match(/^(?:bash|sh|zsh|ksh|dash)\b[^'"]*?\s-[A-Za-z]*c\s+(['"])([\s\S]*?)\1/);
|
|
1067
1342
|
if (!m)
|
|
1068
1343
|
return null;
|
|
1069
|
-
return classifyBashCommand(m[2]);
|
|
1344
|
+
return classifyBashCommand(m[2], new Set(), sandboxEnforced);
|
|
1070
1345
|
}
|
|
1071
1346
|
// A curl/wget whose target host is loopback (localhost, 127.0.0.0/8, 0.0.0.0,
|
|
1072
1347
|
// ::1). A request to a server on this machine is a LOCAL action, not an outward
|
|
@@ -1095,7 +1370,7 @@ function isLoopbackHttpStage(stage) {
|
|
|
1095
1370
|
return false;
|
|
1096
1371
|
return /(?:^|[\s@])(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1\])(?::\d+)?(?:[/\s'"]|$)/i.test(stage);
|
|
1097
1372
|
}
|
|
1098
|
-
function classifyBashCommand(command, ephemeralVars = new Set()) {
|
|
1373
|
+
function classifyBashCommand(command, ephemeralVars = new Set(), sandboxEnforced) {
|
|
1099
1374
|
if (!command)
|
|
1100
1375
|
return "safe";
|
|
1101
1376
|
// Two views of the command:
|
|
@@ -1157,7 +1432,7 @@ function classifyBashCommand(command, ephemeralVars = new Set()) {
|
|
|
1157
1432
|
// before the create still counts as a real delete.
|
|
1158
1433
|
let worst = pipesToShell ? "review" : "safe";
|
|
1159
1434
|
for (const stage of stages) {
|
|
1160
|
-
worst = maxTier(worst, classifyBashCommand(stage, vars));
|
|
1435
|
+
worst = maxTier(worst, classifyBashCommand(stage, vars, sandboxEnforced));
|
|
1161
1436
|
noteEphemeralEffects(stripHeredocBodies(stage), vars);
|
|
1162
1437
|
}
|
|
1163
1438
|
return worst;
|
|
@@ -1169,14 +1444,278 @@ function classifyBashCommand(command, ephemeralVars = new Set()) {
|
|
|
1169
1444
|
// shell pass short-circuits to `safe` (e.g. an assignment-prefixed node -e).
|
|
1170
1445
|
const sql = findSqlInCommand(intact);
|
|
1171
1446
|
const sqlTier = sql ? classifySqlSeverity(sql) : "safe";
|
|
1172
|
-
return maxTier(maxTier(sqlTier, pipesToShell ? "review" : "safe"), classifyStageShellEffects(stripped, ephemeralVars));
|
|
1447
|
+
return maxTier(maxTier(sqlTier, pipesToShell ? "review" : "safe"), classifyStageShellEffects(stripped, ephemeralVars, sandboxEnforced));
|
|
1173
1448
|
}
|
|
1174
1449
|
/**
|
|
1175
1450
|
* Shell-effect classification of a SINGLE, already-body-stripped stage. No SQL
|
|
1176
1451
|
* detection here — that runs on the body-intact view in classifyBashCommand and
|
|
1177
1452
|
* is folded in by the caller. Returns the stage's tier (default `safe`).
|
|
1453
|
+
* A cloud CLI tier is a floor: it never lowers what the other detectors find
|
|
1454
|
+
* (`kubectl exec pod -- curl -X DELETE …` stays high_stakes).
|
|
1178
1455
|
*/
|
|
1179
|
-
|
|
1456
|
+
// Package-manager subcommands that do not run a package script. `yarn build`
|
|
1457
|
+
// and `pnpm build` do: those tools treat an unknown word as a script name.
|
|
1458
|
+
const PM_NON_SCRIPT = new Set([
|
|
1459
|
+
"access", "add", "adduser", "approve-builds", "audit", "bin", "bugs", "cache", "ci", "cit",
|
|
1460
|
+
"completion", "config", "create", "dedupe", "deploy", "deprecate", "diff", "dist-tag", "docs",
|
|
1461
|
+
"doctor", "env", "explain", "explore", "fetch", "find", "fund", "get", "help", "hook", "i",
|
|
1462
|
+
"import", "info", "init", "install", "install-ci-test", "install-test", "it", "licenses",
|
|
1463
|
+
"link", "list", "ll", "login", "logout", "ls", "node", "org", "outdated", "owner", "pack",
|
|
1464
|
+
"patch", "ping", "pkg", "prefix", "profile", "prune", "publish", "query", "rebuild", "repo",
|
|
1465
|
+
"root", "search", "set", "setup", "shrinkwrap", "star", "stars", "store", "team", "token",
|
|
1466
|
+
"uninstall", "unlink", "unplug", "unstar", "update", "upgrade", "up", "version", "view",
|
|
1467
|
+
"whoami", "why",
|
|
1468
|
+
]);
|
|
1469
|
+
/**
|
|
1470
|
+
* A test runner, package script, script file, or package executor. The hook
|
|
1471
|
+
* sees the runner command, not the processes it starts (a `cargo test` can
|
|
1472
|
+
* run `rm` without a second tool call). Command position only: `echo cargo
|
|
1473
|
+
* test` and `git commit -m "npm test"` are not runners.
|
|
1474
|
+
*/
|
|
1475
|
+
function isOpaqueCodeRunner(stage) {
|
|
1476
|
+
const words = stripRunnerPrefixes(withoutShellRedirects(splitArgs(stage)));
|
|
1477
|
+
if (words.length === 0)
|
|
1478
|
+
return false;
|
|
1479
|
+
const [cmd, ...args] = words;
|
|
1480
|
+
if (isDirectScript(cmd))
|
|
1481
|
+
return true;
|
|
1482
|
+
const base = commandBase(cmd);
|
|
1483
|
+
if (base === "source" || cmd === ".")
|
|
1484
|
+
return args.some((w) => w !== "--" && !w.startsWith("-"));
|
|
1485
|
+
if (base === "bash" || base === "sh" || base === "zsh" || base === "dash" || base === "ksh")
|
|
1486
|
+
return shellInvokesFile(args);
|
|
1487
|
+
if (base === "node" || base === "nodejs" || base === "tsx" || base === "deno")
|
|
1488
|
+
return nodeInvokesFile(args);
|
|
1489
|
+
if (base === "npx" || base === "bunx")
|
|
1490
|
+
return npxInvokes(args);
|
|
1491
|
+
if (base === "bun")
|
|
1492
|
+
return pmInvokes(base, args) || bunInvokesFile(args);
|
|
1493
|
+
if (base === "npm" || base === "pnpm" || base === "yarn")
|
|
1494
|
+
return pmInvokes(base, args);
|
|
1495
|
+
if (base === "pytest" || base === "py.test")
|
|
1496
|
+
return true;
|
|
1497
|
+
if (base === "python" || base === "python3" || /^python3\.\d+$/.test(base))
|
|
1498
|
+
return pythonInvokes(args);
|
|
1499
|
+
if (base === "cargo")
|
|
1500
|
+
return cargoInvokesTest(args);
|
|
1501
|
+
if (base === "go")
|
|
1502
|
+
return goInvokesTest(args);
|
|
1503
|
+
if (base === "make" || base === "gmake")
|
|
1504
|
+
return makeInvokes(args);
|
|
1505
|
+
return false;
|
|
1506
|
+
}
|
|
1507
|
+
function commandBase(cmd) {
|
|
1508
|
+
const slash = Math.max(cmd.lastIndexOf("/"), cmd.lastIndexOf("\\"));
|
|
1509
|
+
return slash >= 0 ? cmd.slice(slash + 1) : cmd;
|
|
1510
|
+
}
|
|
1511
|
+
function isDirectScript(cmd) {
|
|
1512
|
+
if (cmd.startsWith("./") || cmd.startsWith("../"))
|
|
1513
|
+
return true;
|
|
1514
|
+
return cmd.includes("/") && /\.(?:sh|bash|zsh|py|rb|pl|[cm]?js|[cm]?ts|mjs|cjs|mts|cts)$/i.test(cmd);
|
|
1515
|
+
}
|
|
1516
|
+
function withoutShellRedirects(words) {
|
|
1517
|
+
const out = [];
|
|
1518
|
+
for (let i = 0; i < words.length; i++) {
|
|
1519
|
+
const w = words[i];
|
|
1520
|
+
if (w === ">" || w === ">>" || w === "<" || w === "<<" || w === ">&" || w === "&>") {
|
|
1521
|
+
i++;
|
|
1522
|
+
continue;
|
|
1523
|
+
}
|
|
1524
|
+
if (/^(?:&>>?|\d*>&?\d*|\d*>>?|[<>])\S*$/.test(w))
|
|
1525
|
+
continue;
|
|
1526
|
+
out.push(w);
|
|
1527
|
+
}
|
|
1528
|
+
return out;
|
|
1529
|
+
}
|
|
1530
|
+
function stripRunnerPrefixes(words) {
|
|
1531
|
+
let i = 0;
|
|
1532
|
+
while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
|
|
1533
|
+
i++;
|
|
1534
|
+
while (i < words.length && (words[i] === "command" || words[i] === "builtin"))
|
|
1535
|
+
i++;
|
|
1536
|
+
return words.slice(i);
|
|
1537
|
+
}
|
|
1538
|
+
function shellInvokesFile(args) {
|
|
1539
|
+
for (let i = 0; i < args.length; i++) {
|
|
1540
|
+
const w = args[i];
|
|
1541
|
+
if (w === "--")
|
|
1542
|
+
return Boolean(args[i + 1]);
|
|
1543
|
+
// `-c` / `-lc` is inline shell. classifyShellCStage already classified a
|
|
1544
|
+
// quoted body. `-n` checks syntax and does not run the file.
|
|
1545
|
+
if (w === "-c" || w === "--command" || /^-[^-]*c/.test(w))
|
|
1546
|
+
return false;
|
|
1547
|
+
if (w === "-n" || w === "--noexec" || /^-[^-]*n/.test(w))
|
|
1548
|
+
return false;
|
|
1549
|
+
if (w.startsWith("-"))
|
|
1550
|
+
continue;
|
|
1551
|
+
return true;
|
|
1552
|
+
}
|
|
1553
|
+
return false;
|
|
1554
|
+
}
|
|
1555
|
+
function nodeInvokesFile(args) {
|
|
1556
|
+
const argTaking = new Set(["-r", "--require", "--import", "--loader", "--experimental-loader", "-C", "--conditions"]);
|
|
1557
|
+
for (let i = 0; i < args.length; i++) {
|
|
1558
|
+
const w = args[i];
|
|
1559
|
+
if (w === "--")
|
|
1560
|
+
return Boolean(args[i + 1]);
|
|
1561
|
+
if (w === "-e" || w === "--eval" || w === "-p" || w === "--print" || w === "-c" || w === "--check")
|
|
1562
|
+
return false;
|
|
1563
|
+
if (w.startsWith("--eval=") || w.startsWith("--print="))
|
|
1564
|
+
return false;
|
|
1565
|
+
if (w === "--test" || w.startsWith("--test"))
|
|
1566
|
+
return true;
|
|
1567
|
+
if (w.startsWith("-")) {
|
|
1568
|
+
if (argTaking.has(w) && !w.includes("="))
|
|
1569
|
+
i++;
|
|
1570
|
+
continue;
|
|
1571
|
+
}
|
|
1572
|
+
return true;
|
|
1573
|
+
}
|
|
1574
|
+
return false;
|
|
1575
|
+
}
|
|
1576
|
+
function npxInvokes(args) {
|
|
1577
|
+
const argTaking = new Set(["-p", "--package", "-c", "--call", "--npm", "--node-options"]);
|
|
1578
|
+
for (let i = 0; i < args.length; i++) {
|
|
1579
|
+
const w = args[i];
|
|
1580
|
+
if (w === "--")
|
|
1581
|
+
return Boolean(args[i + 1]);
|
|
1582
|
+
if (w === "-v" || w === "--version" || w === "-h" || w === "--help")
|
|
1583
|
+
return false;
|
|
1584
|
+
if (w.startsWith("-")) {
|
|
1585
|
+
if ((argTaking.has(w) || w.startsWith("--package=") || w.startsWith("--call=")) && !w.includes("="))
|
|
1586
|
+
i++;
|
|
1587
|
+
continue;
|
|
1588
|
+
}
|
|
1589
|
+
return true;
|
|
1590
|
+
}
|
|
1591
|
+
return false;
|
|
1592
|
+
}
|
|
1593
|
+
function pmPositionals(args) {
|
|
1594
|
+
const skip = new Set(["--prefix", "-C", "--dir", "--workspace", "-w", "--filter", "--cwd"]);
|
|
1595
|
+
const out = [];
|
|
1596
|
+
for (let i = 0; i < args.length; i++) {
|
|
1597
|
+
const w = args[i];
|
|
1598
|
+
if (w === "--")
|
|
1599
|
+
break;
|
|
1600
|
+
if (w.startsWith("-")) {
|
|
1601
|
+
if (skip.has(w))
|
|
1602
|
+
i++;
|
|
1603
|
+
continue;
|
|
1604
|
+
}
|
|
1605
|
+
out.push(w);
|
|
1606
|
+
}
|
|
1607
|
+
return out;
|
|
1608
|
+
}
|
|
1609
|
+
function bunInvokesFile(args) {
|
|
1610
|
+
const file = pmPositionals(args)[0];
|
|
1611
|
+
if (!file)
|
|
1612
|
+
return false;
|
|
1613
|
+
return file.startsWith("./") || file.startsWith("../") || file.includes("/") || /\.(?:[cm]?[jt]sx?|mjs|cjs)$/i.test(file);
|
|
1614
|
+
}
|
|
1615
|
+
function pmInvokes(pm, args) {
|
|
1616
|
+
const pos = pmPositionals(args);
|
|
1617
|
+
const sub = pos[0];
|
|
1618
|
+
if (!sub)
|
|
1619
|
+
return false;
|
|
1620
|
+
if (sub === "test" || sub === "t" || sub === "tst" || sub === "start" || sub === "stop" || sub === "restart")
|
|
1621
|
+
return true;
|
|
1622
|
+
if ((sub === "run" || sub === "run-script") && pos[1])
|
|
1623
|
+
return true;
|
|
1624
|
+
if ((sub === "exec" || sub === "dlx") && pos[1])
|
|
1625
|
+
return true;
|
|
1626
|
+
// yarn and pnpm run a package script named by the first word (`yarn build`).
|
|
1627
|
+
if ((pm === "yarn" || pm === "pnpm") && !PM_NON_SCRIPT.has(sub))
|
|
1628
|
+
return true;
|
|
1629
|
+
return false;
|
|
1630
|
+
}
|
|
1631
|
+
function pythonInvokes(args) {
|
|
1632
|
+
const takes = new Set(["-W", "-X"]);
|
|
1633
|
+
for (let i = 0; i < args.length; i++) {
|
|
1634
|
+
const w = args[i];
|
|
1635
|
+
if (w === "-c" || w === "--command")
|
|
1636
|
+
return false;
|
|
1637
|
+
if (w === "-m" || w === "--module") {
|
|
1638
|
+
const mod = args[i + 1];
|
|
1639
|
+
return mod === "pytest" || mod === "unittest";
|
|
1640
|
+
}
|
|
1641
|
+
if (w.startsWith("-")) {
|
|
1642
|
+
if (takes.has(w))
|
|
1643
|
+
i++;
|
|
1644
|
+
continue;
|
|
1645
|
+
}
|
|
1646
|
+
return true;
|
|
1647
|
+
}
|
|
1648
|
+
return false;
|
|
1649
|
+
}
|
|
1650
|
+
function cargoInvokesTest(args) {
|
|
1651
|
+
let i = 0;
|
|
1652
|
+
if (args[0]?.startsWith("+"))
|
|
1653
|
+
i++;
|
|
1654
|
+
const takes = new Set([
|
|
1655
|
+
"--manifest-path", "--target", "--target-dir", "--config", "-Z", "--color",
|
|
1656
|
+
"--features", "-F", "--package", "-p", "--exclude", "--bin", "--example", "--test", "--bench",
|
|
1657
|
+
]);
|
|
1658
|
+
for (; i < args.length; i++) {
|
|
1659
|
+
const w = args[i];
|
|
1660
|
+
if (w.startsWith("-")) {
|
|
1661
|
+
if (takes.has(w) && !w.includes("="))
|
|
1662
|
+
i++;
|
|
1663
|
+
continue;
|
|
1664
|
+
}
|
|
1665
|
+
return w === "test";
|
|
1666
|
+
}
|
|
1667
|
+
return false;
|
|
1668
|
+
}
|
|
1669
|
+
function goInvokesTest(args) {
|
|
1670
|
+
const takes = new Set(["-C", "-o", "-p"]);
|
|
1671
|
+
for (let i = 0; i < args.length; i++) {
|
|
1672
|
+
const w = args[i];
|
|
1673
|
+
if (w.startsWith("-")) {
|
|
1674
|
+
if ((takes.has(w) || w === "-ldflags" || w === "-gcflags") && !w.includes("="))
|
|
1675
|
+
i++;
|
|
1676
|
+
continue;
|
|
1677
|
+
}
|
|
1678
|
+
return w === "test";
|
|
1679
|
+
}
|
|
1680
|
+
return false;
|
|
1681
|
+
}
|
|
1682
|
+
function makeInvokes(args) {
|
|
1683
|
+
let dry = false;
|
|
1684
|
+
let help = false;
|
|
1685
|
+
const positionals = [];
|
|
1686
|
+
const takes = new Set([
|
|
1687
|
+
"-C", "--directory", "-f", "--file", "--makefile", "-I", "--include-dir",
|
|
1688
|
+
"-o", "--old-file", "-W", "--what-if", "--assume-new", "--eval",
|
|
1689
|
+
]);
|
|
1690
|
+
for (let i = 0; i < args.length; i++) {
|
|
1691
|
+
const w = args[i];
|
|
1692
|
+
if (w === "-n" || w === "--dry-run" || w === "--just-print" || w === "--recon") {
|
|
1693
|
+
dry = true;
|
|
1694
|
+
continue;
|
|
1695
|
+
}
|
|
1696
|
+
if (w === "--version" || w === "-v" || w === "--help" || w === "-h") {
|
|
1697
|
+
help = true;
|
|
1698
|
+
continue;
|
|
1699
|
+
}
|
|
1700
|
+
if (w.startsWith("-")) {
|
|
1701
|
+
if (/^-[^-]*n/.test(w))
|
|
1702
|
+
dry = true;
|
|
1703
|
+
if (takes.has(w))
|
|
1704
|
+
i++;
|
|
1705
|
+
continue;
|
|
1706
|
+
}
|
|
1707
|
+
positionals.push(w);
|
|
1708
|
+
}
|
|
1709
|
+
if (dry)
|
|
1710
|
+
return false;
|
|
1711
|
+
if (help && positionals.length === 0)
|
|
1712
|
+
return false;
|
|
1713
|
+
return true;
|
|
1714
|
+
}
|
|
1715
|
+
function classifyStageShellEffects(stage, ephemeralVars = new Set(), sandboxEnforced) {
|
|
1716
|
+
return maxTier(classifyCloudCliStage(stage) ?? "safe", classifyStageEffects(stage, ephemeralVars, sandboxEnforced));
|
|
1717
|
+
}
|
|
1718
|
+
function classifyStageEffects(stage, ephemeralVars, sandboxEnforced) {
|
|
1180
1719
|
// File deletion in COMMAND POSITION, per-stage so the ephemeral-temp carve-out
|
|
1181
1720
|
// can win: deleting only throwaway temp files (/tmp, $TMPDIR, /var/folders, …)
|
|
1182
1721
|
// → warning; any non-temp target (or the temp root itself) → high_stakes.
|
|
@@ -1186,7 +1725,7 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
|
|
|
1186
1725
|
return "warning";
|
|
1187
1726
|
// `git -C repo …` / `git -c k=v …`: classify the subcommand without the
|
|
1188
1727
|
// global options, so the git patterns below and in the full scan apply.
|
|
1189
|
-
const gitTier = classifyGitGlobalOptsStage(stage, ephemeralVars);
|
|
1728
|
+
const gitTier = classifyGitGlobalOptsStage(stage, ephemeralVars, sandboxEnforced);
|
|
1190
1729
|
if (gitTier !== null)
|
|
1191
1730
|
return gitTier;
|
|
1192
1731
|
if (isBuildOutputOnlyDeletion(stage.replace(DELETE_LEAD, "")))
|
|
@@ -1246,19 +1785,19 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
|
|
|
1246
1785
|
// / capture). Classify the command-substitution inners and any trailing
|
|
1247
1786
|
// command; a purely literal assignment is safe. Dangerous substitutions were
|
|
1248
1787
|
// already caught by the high-stakes/delete scans above.
|
|
1249
|
-
const assignTier = classifyAssignmentStage(stage);
|
|
1788
|
+
const assignTier = classifyAssignmentStage(stage, sandboxEnforced);
|
|
1250
1789
|
if (assignTier !== null)
|
|
1251
1790
|
return assignTier;
|
|
1252
1791
|
// `env [opts] [NAME=VAL]... cmd` runs cmd with a modified environment. Strip
|
|
1253
1792
|
// the env prefix and classify the inner command (a dangerous inner was already
|
|
1254
1793
|
// caught by the high-stakes full scan). Bare `env` just prints the env → safe.
|
|
1255
|
-
const envTier = classifyEnvStage(stage);
|
|
1794
|
+
const envTier = classifyEnvStage(stage, sandboxEnforced);
|
|
1256
1795
|
if (envTier !== null)
|
|
1257
1796
|
return envTier;
|
|
1258
1797
|
// ssh is a transport — classify the remote command it runs (interactive /
|
|
1259
1798
|
// port-forwarding ssh has no inspectable command → review floor). scp/rsync
|
|
1260
1799
|
// to a remote are file transfers and stay high_stakes (HIGH_STAKES_STAGE).
|
|
1261
|
-
const sshTier = classifySshStage(stage);
|
|
1800
|
+
const sshTier = classifySshStage(stage, sandboxEnforced);
|
|
1262
1801
|
if (sshTier !== null)
|
|
1263
1802
|
return sshTier;
|
|
1264
1803
|
// `sh -c '<shell>'` / `bash -c "<shell>"` runs the quoted argument AS shell —
|
|
@@ -1266,7 +1805,7 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
|
|
|
1266
1805
|
// is why the command-position delete scan above can ignore quoted text: a real
|
|
1267
1806
|
// shell-out like `bash -c 'rm -rf /important'` is caught HERE, by re-running
|
|
1268
1807
|
// the body as a command, while `echo 'rm …'` (data) is not.
|
|
1269
|
-
const shellCTier = classifyShellCStage(stage);
|
|
1808
|
+
const shellCTier = classifyShellCStage(stage, sandboxEnforced);
|
|
1270
1809
|
if (shellCTier !== null)
|
|
1271
1810
|
return shellCTier;
|
|
1272
1811
|
// sudo: privilege escalation. A high-stakes inner command was already caught
|
|
@@ -1298,6 +1837,12 @@ function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
|
|
|
1298
1837
|
}
|
|
1299
1838
|
// Default: safe. No destructive/outward/sensitive effect was detected, so we
|
|
1300
1839
|
// do NOT put a human in the loop just for "running a command".
|
|
1840
|
+
// Exception: an opaque runner (test runner, package script, script file, npx)
|
|
1841
|
+
// hides child processes from this hook. When the host sandbox is not
|
|
1842
|
+
// enforcing containment, that asks for review. A higher tier above already
|
|
1843
|
+
// returned. Other hosts leave sandboxEnforced unset and stay safe.
|
|
1844
|
+
if (sandboxEnforced === false && isOpaqueCodeRunner(stage))
|
|
1845
|
+
return "review";
|
|
1301
1846
|
return "safe";
|
|
1302
1847
|
}
|
|
1303
1848
|
function classifySqlSeverity(sql) {
|
|
@@ -1450,13 +1995,13 @@ export function blankTextCommandArgs(command) {
|
|
|
1450
1995
|
.join("\n");
|
|
1451
1996
|
}
|
|
1452
1997
|
// Interpreters whose inline `-e`/`-c`/`--eval` (and perl/deno one-liner) body is
|
|
1453
|
-
// opaque CODE
|
|
1998
|
+
// opaque CODE, not shell. We blank that body before the SHELL-pattern scans so
|
|
1454
1999
|
// tokens embedded as code or data (`rm`, `curl -d`, a `>` redirect) don't trip a
|
|
1455
|
-
// destructive/outward rule.
|
|
1456
|
-
//
|
|
1457
|
-
//
|
|
1458
|
-
//
|
|
1459
|
-
//
|
|
2000
|
+
// destructive/outward rule. Inline interpreter bodies stay unscanned as shell
|
|
2001
|
+
// (see the WARNING_COMMANDS note): we can't tell what a `node -e`/`python -c`
|
|
2002
|
+
// body does, and scanning it for shell tokens only manufactures false positives.
|
|
2003
|
+
// A test runner or a script file is different: its body is not in the command
|
|
2004
|
+
// at all. Those ask for review when sandboxEnforced is false.
|
|
1460
2005
|
//
|
|
1461
2006
|
// NOTE: SQL is the deliberate exception. classifyBashCommand still runs SQL
|
|
1462
2007
|
// detection on the body-INTACT view, so inline SQL in a `node -e`/`python -c`
|
|
@@ -1887,6 +2432,12 @@ function classifyMcpTool(toolName, toolInput = {}) {
|
|
|
1887
2432
|
// but each push is gated on its own. Log it, no prompt.
|
|
1888
2433
|
if (parts.includes("ccd_pr") && tool === "set_monitor")
|
|
1889
2434
|
return "warning";
|
|
2435
|
+
// The PR bar's auto-merge switch. On, GitHub merges the PR when checks pass
|
|
2436
|
+
// and no other card comes, the same as `gh pr merge --auto`. Off only stops
|
|
2437
|
+
// a merge that has not happened yet: log it, no prompt.
|
|
2438
|
+
if (parts.includes("ccd_pr") && tool === "set_auto_merge") {
|
|
2439
|
+
return toolInput.enabled === false ? "warning" : "high_stakes";
|
|
2440
|
+
}
|
|
1890
2441
|
// Start a new local Claude session, or move this task into one. Its own tool
|
|
1891
2442
|
// calls are gated by OKed like this one's, so log it, no prompt. A cloud or
|
|
1892
2443
|
// SSH session runs outside this machine's hook, so it stays `review`.
|
package/dist/describe.d.ts
CHANGED
|
@@ -18,6 +18,8 @@ export interface Rendered {
|
|
|
18
18
|
link?: string;
|
|
19
19
|
kind: OperationKind;
|
|
20
20
|
}
|
|
21
|
+
/** Shown when an opaque runner asks for review because the sandbox is off. */
|
|
22
|
+
export declare const OPAQUE_RUNNER_FOOTNOTE = "OKed cannot see the commands inside this run. Enable Claude Code's Bash sandbox and set allowUnsandboxedCommands to false to allow these without a prompt.";
|
|
21
23
|
/** Optional caller context. `cwd` lets describers read local files (e.g. the
|
|
22
24
|
* package.json behind `npm publish`) to show what an action will touch. */
|
|
23
25
|
export interface DescribeContext {
|
|
@@ -25,6 +27,11 @@ export interface DescribeContext {
|
|
|
25
27
|
/** Title of the PR the card links to, when the command does not say it.
|
|
26
28
|
* `lookupPrTitle()` gets it from GitHub. */
|
|
27
29
|
prTitle?: string;
|
|
30
|
+
/**
|
|
31
|
+
* `false` when the host sandbox is not enforcing containment. An opaque
|
|
32
|
+
* runner then gets a footnote explaining how to skip the prompt.
|
|
33
|
+
*/
|
|
34
|
+
sandboxEnforced?: boolean;
|
|
28
35
|
}
|
|
29
36
|
export declare function describe(toolName: string, toolInput: Record<string, unknown>, ctx?: DescribeContext): string;
|
|
30
37
|
export declare function describeFields(toolName: string, toolInput: Record<string, unknown>, ctx?: DescribeContext): Record<string, string> | null;
|
package/dist/describe.js
CHANGED
|
@@ -15,6 +15,8 @@ import { TIER_ORDER } from "./degraded.js";
|
|
|
15
15
|
const BODY_PREVIEW_MAX = 200;
|
|
16
16
|
const COMMAND_INLINE_MAX = 50;
|
|
17
17
|
const DIFF_HUNK_MAX_LINES = 10;
|
|
18
|
+
/** Shown when an opaque runner asks for review because the sandbox is off. */
|
|
19
|
+
export const OPAQUE_RUNNER_FOOTNOTE = "OKed cannot see the commands inside this run. Enable Claude Code's Bash sandbox and set allowUnsandboxedCommands to false to allow these without a prompt.";
|
|
18
20
|
export function describe(toolName, toolInput, ctx = {}) {
|
|
19
21
|
// Single-line consumers (audit logs, SMS) get title + target inlined.
|
|
20
22
|
const r = summarize(toolName, toolInput, ctx);
|
|
@@ -54,7 +56,17 @@ export function describeFields(toolName, toolInput, ctx = {}) {
|
|
|
54
56
|
// ───────────────────────────────────────────────────────────────────────
|
|
55
57
|
function summarize(toolName, toolInput, ctx) {
|
|
56
58
|
const r = summarizeTool(toolName, toolInput, ctx);
|
|
57
|
-
|
|
59
|
+
const named = ctx.prTitle ? namePr(r, ctx.prTitle) : r;
|
|
60
|
+
if (ctx.sandboxEnforced !== false || named.footnote)
|
|
61
|
+
return named;
|
|
62
|
+
// The runner is the reason for the card: the same call is safe when the
|
|
63
|
+
// sandbox flag is omitted. A higher effect (rm, a force push) keeps its
|
|
64
|
+
// own text.
|
|
65
|
+
const plain = classify(toolName, toolInput);
|
|
66
|
+
const gated = classify(toolName, toolInput, { sandboxEnforced: false });
|
|
67
|
+
if (plain === "safe" && gated === "review")
|
|
68
|
+
return { ...named, footnote: OPAQUE_RUNNER_FOOTNOTE };
|
|
69
|
+
return named;
|
|
58
70
|
}
|
|
59
71
|
/**
|
|
60
72
|
* "Merge PR #49 in o/r" says which PR, not what it does. Put the PR title after
|
|
@@ -73,7 +85,7 @@ function summarizeTool(toolName, toolInput, ctx) {
|
|
|
73
85
|
const fileSizeBytes = typeof toolInput._file_size_bytes === "number" ? toolInput._file_size_bytes : undefined;
|
|
74
86
|
switch (toolName) {
|
|
75
87
|
case "Bash":
|
|
76
|
-
return summarizeBash(toolInput.command || "", fileSizeBytes, ctx.cwd);
|
|
88
|
+
return summarizeBash(toolInput.command || "", fileSizeBytes, ctx.cwd, ctx.sandboxEnforced);
|
|
77
89
|
case "Write":
|
|
78
90
|
return summarizeWrite(toolInput);
|
|
79
91
|
case "Edit":
|
|
@@ -96,7 +108,7 @@ function summarizeTool(toolName, toolInput, ctx) {
|
|
|
96
108
|
// Shell-exec wrappers: signature is a string command/cmd field
|
|
97
109
|
const shellCommand = (toolInput.command ?? toolInput.cmd);
|
|
98
110
|
if (typeof shellCommand === "string") {
|
|
99
|
-
return summarizeBash(shellCommand, fileSizeBytes);
|
|
111
|
+
return summarizeBash(shellCommand, fileSizeBytes, undefined, ctx.sandboxEnforced);
|
|
100
112
|
}
|
|
101
113
|
// File-write wrappers: signature is a path + content/data string
|
|
102
114
|
const writePath = (toolInput.file_path ?? toolInput.path);
|
|
@@ -192,11 +204,11 @@ function extractCurlPayload(cmd) {
|
|
|
192
204
|
const parts = [data.join("&"), json.join(""), form.join("\n")].filter(Boolean);
|
|
193
205
|
return parts.length ? parts.join("\n") : undefined;
|
|
194
206
|
}
|
|
195
|
-
function summarizeBash(command, sizeBytes, cwd) {
|
|
207
|
+
function summarizeBash(command, sizeBytes, cwd, sandboxEnforced) {
|
|
196
208
|
let cmd = (command || "").trim();
|
|
197
209
|
if (!cmd)
|
|
198
210
|
return { title: "Run empty command", kind: "unknown_bash" };
|
|
199
|
-
const compound = summarizeCompoundBash(cmd, sizeBytes, cwd);
|
|
211
|
+
const compound = summarizeCompoundBash(cmd, sizeBytes, cwd, sandboxEnforced);
|
|
200
212
|
if (compound)
|
|
201
213
|
return compound;
|
|
202
214
|
// SQL detection runs before shell-write detection so that inline-interpreter
|
|
@@ -458,17 +470,18 @@ function summarizeBash(command, sizeBytes, cwd) {
|
|
|
458
470
|
* from a pattern that spans steps (`curl … | sh`): the whole-command rules
|
|
459
471
|
* below describe those.
|
|
460
472
|
*/
|
|
461
|
-
function summarizeCompoundBash(cmd, sizeBytes, cwd) {
|
|
473
|
+
function summarizeCompoundBash(cmd, sizeBytes, cwd, sandboxEnforced) {
|
|
462
474
|
const steps = splitTopLevel(cmd, { pipes: false });
|
|
463
475
|
if (steps.length < 2)
|
|
464
476
|
return null;
|
|
465
477
|
// Each step sees what earlier steps made (a temp file a later `rm` deletes),
|
|
466
478
|
// as the whole command does. Alone, that `rm` would outrank the real step.
|
|
467
|
-
const rank = classifyBashSteps(steps).map((t) => TIER_ORDER[t]);
|
|
479
|
+
const rank = classifyBashSteps(steps, sandboxEnforced).map((t) => TIER_ORDER[t]);
|
|
468
480
|
const top = Math.max(...rank);
|
|
469
481
|
if (top < TIER_ORDER.review)
|
|
470
482
|
return null;
|
|
471
|
-
|
|
483
|
+
const whole = classify("Bash", { command: cmd }, sandboxEnforced === undefined ? undefined : { sandboxEnforced });
|
|
484
|
+
if (TIER_ORDER[whole] !== top)
|
|
472
485
|
return null;
|
|
473
486
|
const lead = rank.indexOf(top);
|
|
474
487
|
// Variables set by earlier steps (`D=/dir; rm $D/x`) show as their values.
|
|
@@ -1015,7 +1028,7 @@ function summarizeSql(sql, originalCommand) {
|
|
|
1015
1028
|
* to X", "Delete email N", "Purge folder Y") instead of a raw shell line.
|
|
1016
1029
|
*
|
|
1017
1030
|
* Used for both the approval-card display (so the user sees "Send email to
|
|
1018
|
-
*
|
|
1031
|
+
* contact@oked.ai" with the subject + sender, not a printf|himalaya
|
|
1019
1032
|
* pipeline) and the analytics `operation_kind`.
|
|
1020
1033
|
*
|
|
1021
1034
|
* Returns null if the command mentions himalaya but doesn't match a known
|
|
@@ -1362,6 +1375,25 @@ function summarizeDesktopApp(server, tool, input) {
|
|
|
1362
1375
|
};
|
|
1363
1376
|
}
|
|
1364
1377
|
}
|
|
1378
|
+
if (server === "ccd_pr" && tool === "set_auto_merge") {
|
|
1379
|
+
// Same card as `gh pr merge --auto`: the PR, the method, and when it merges.
|
|
1380
|
+
const pr = str(input.url)?.match(/^https:\/\/github\.com\/([^/\s]+\/[^/\s]+)\/pull\/(\d+)/);
|
|
1381
|
+
const where = pr ? `PR #${pr[2]} in ${pr[1]}` : "PR";
|
|
1382
|
+
const link = pr ? `https://github.com/${pr[1]}/pull/${pr[2]}` : undefined;
|
|
1383
|
+
if (input.enabled === false) {
|
|
1384
|
+
return { title: `Turn off auto-merge for ${where}`, link, kind: "git_pr_write" };
|
|
1385
|
+
}
|
|
1386
|
+
return {
|
|
1387
|
+
title: `Merge ${where}`,
|
|
1388
|
+
annotation: [str(input.merge_method), "when checks pass"].filter(Boolean).join(", "),
|
|
1389
|
+
link,
|
|
1390
|
+
kind: "git_pr_merge",
|
|
1391
|
+
};
|
|
1392
|
+
}
|
|
1393
|
+
if (server === "ccd_session_mgmt" && tool === "send_message") {
|
|
1394
|
+
const message = str(input.message);
|
|
1395
|
+
return { title: "Send a message to another Claude session", body: message ? truncateBody(message) : undefined, kind: "agent_message" };
|
|
1396
|
+
}
|
|
1365
1397
|
if (server === "ccd_turn" && tool === "update_plan") {
|
|
1366
1398
|
return { title: "Update the task list in the Claude app", kind: "session_housekeeping" };
|
|
1367
1399
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -46,8 +46,9 @@ export { checkReceipt, keysFor, keysUrlAllowed, OKED_RECEIPT_KEYS_URL } from "./
|
|
|
46
46
|
export { PINNED_RECEIPT_KEYS } from "./receipt-keys.js";
|
|
47
47
|
export { verifyReceipt, verifyChain, shortReceiptId, type SignedReceipt, type ReceiptBody, type ReceiptKey, } from "@oked/receipt-core";
|
|
48
48
|
export { TIER_ORDER, degradedDecision } from "./degraded.js";
|
|
49
|
-
export { classify } from "./classify.js";
|
|
50
|
-
export { describe, describeFields } from "./describe.js";
|
|
49
|
+
export { classify, splitTopLevel, type ClassifyOptions } from "./classify.js";
|
|
50
|
+
export { describe, describeFields, OPAQUE_RUNNER_FOOTNOTE } from "./describe.js";
|
|
51
|
+
export type { DescribeContext } from "./describe.js";
|
|
51
52
|
export { lookupPrTitle } from "./pr-title.js";
|
|
52
53
|
export { applyRules } from "./rules.js";
|
|
53
54
|
export type { Rule, RuleMatch, RuleAction, RuleDecision, FieldOp, } from "./rules.js";
|
package/dist/index.js
CHANGED
|
@@ -397,8 +397,8 @@ export { checkReceipt, keysFor, keysUrlAllowed, OKED_RECEIPT_KEYS_URL } from "./
|
|
|
397
397
|
export { PINNED_RECEIPT_KEYS } from "./receipt-keys.js";
|
|
398
398
|
export { verifyReceipt, verifyChain, shortReceiptId, } from "@oked/receipt-core";
|
|
399
399
|
export { TIER_ORDER, degradedDecision } from "./degraded.js";
|
|
400
|
-
export { classify } from "./classify.js";
|
|
401
|
-
export { describe, describeFields } from "./describe.js";
|
|
400
|
+
export { classify, splitTopLevel } from "./classify.js";
|
|
401
|
+
export { describe, describeFields, OPAQUE_RUNNER_FOOTNOTE } from "./describe.js";
|
|
402
402
|
export { lookupPrTitle } from "./pr-title.js";
|
|
403
403
|
export { applyRules } from "./rules.js";
|
|
404
404
|
export { CLASSIFIER_VERSION } from "./kinds.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oked/sdk",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.22",
|
|
4
4
|
"description": "OKed SDK - human approval layer for AI agents",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -45,11 +45,11 @@
|
|
|
45
45
|
"access": "public"
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@oked/receipt-core": "0.6.
|
|
48
|
+
"@oked/receipt-core": "0.6.22"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"@types/node": "^
|
|
52
|
-
"tsx": "^4.
|
|
53
|
-
"typescript": "^
|
|
51
|
+
"@types/node": "^26.6.5",
|
|
52
|
+
"tsx": "^4.23.15",
|
|
53
|
+
"typescript": "^7.0.2"
|
|
54
54
|
}
|
|
55
55
|
}
|