github / github/copilot-cli

Document safe parsing for preToolUse.toolArgs when it is a JSON-encoded string

Đang mở Phù hợp với người mới
#3,349 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
area:plugins
Ngôn ngữ chính
Shell
Star
11.2k
Fork
1.9k
Merge trung bình
14 giờ 16 phút
Pull request đã merge (30 ngày)
6

Mô tả

## Summary

The Hooks reference documents `preToolUse.toolArgs` as `unknown`, but does not show how hook authors should safely parse it.

In actual Copilot CLI hook invocations I tested, `toolArgs` arrived as a JSON-encoded string rather than a parsed object. That may be valid under the current `unknown` contract, but it is easy for hook authors to assume object-style access and accidentally write hooks that fail to inspect tool arguments.

Because hook failures are fail-open, this is a security footgun for policy-enforcing hooks.

## Observed behavior

For `preToolUse`, the documentation shows the camelCase payload shape as:

```ts
{
sessionId: string;
timestamp: number;
cwd: string;
toolName: string;
toolArgs: unknown;
}
```

In tested CLI/App-backed hook invocations, the payload effectively behaved like:

```json
{
"toolName": "bash",
"toolArgs": "{\"command\":\"echo hello\"}"
}
```

rather than:

```json
{
"toolName": "bash",
"toolArgs": {
"command": "echo hello"
}
}
```

I am not claiming the string form is invalid. Since the schema says `unknown`, this may be intentional or implementation-defined. The problem is that the docs do not tell hook authors how to handle it safely.

## Why this matters

Security hooks commonly inspect fields like:

```bash
.toolArgs.command
.toolArgs.path
.toolArgs.url
```

If `toolArgs` is a JSON-encoded string, this kind of access does not work as expected. Depending on the script and shell settings, the hook may fail, emit invalid output, or skip the intended check.

Since hook failures are fail-open, a parsing mistake can silently bypass a security policy.

## Request

Please document the expected handling for `toolArgs` and provide safe parsing examples.

At minimum, the docs should say something like:

> `toolArgs` is `unknown` and may be a JSON-encoded string. Hook scripts should check its runtime type and parse it before inspecting tool arguments.

A Bash example would help:

```bash
INPUT="$(cat)"

TOOL_ARGS_JSON="$(
jq -c '
(.toolArgs // .tool_args // .tool_input // {}) as $args
| if ($args | type) == "string" then ($args | fromjson? // {}) else $args end
' <<< "$INPUT"
)"

COMMAND="$(jq -r '.command // ""' <<< "$TOOL_ARGS_JSON")"
```

Python example:

```python
import json
import sys

payload = json.load(sys.stdin)
tool_args = payload.get("toolArgs", payload.get("tool_input", {}))

if isinstance(tool_args, str):
try:
tool_args = json.loads(tool_args)
except json.JSONDecodeError:
tool_args = {}

if not isinstance(tool_args, dict):
tool_args = {}

command = tool_args.get("command", "")
```

## Expected improvement

This would make hook authoring safer, especially for security-focused `preToolUse` hooks, and reduce the chance of fail-open bypasses caused by incorrect assumptions about the runtime type of `toolArgs`.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu với tài liệu tham chiếu Hooks và phần payload preToolUse. Ghi lại rằng toolArgs có thể là một chuỗi được mã hóa JSON, sau đó thêm các ví dụ phân tích an toàn bằng Bash và Python để xử lý các giá trị không hợp lệ hoặc không phải đối tượng; công việc được hoàn thành khi các tác giả hook có thể kiểm tra đáng tin cậy các trường như command, path hoặc url.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python, shell
Lĩnh vực
documentation, security
Loại issue
Tài liệu
Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
68/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.