وضعیت
صبح یک روز، دو تیکت دربارهی یک فایل ایجنت (agent file) یکسان به دستتان میرسد. در این فایل، یک مجموعهابزار شل (shell toolset)، یک الگوی allow برای دستور echo، یک الگوی deny برای دستور rm و یک هوک لاگگیری (logging hook) برای هر بار فراخوانی ابزار شل تعریف شده است. هر دو مهندس سه پیام یکسان فرستادهاند: اجرای echo m101-ok، اجرای pwd، و اجرای rm -rf work/m101-nothing.
مهندس اول ایجنت را در یک پایپلاین با آرگومانهای --exec --safety restricted اجرا میکند. در تیکت آمده که ایجنت از اجرای rm امتناع کرده و متن Tool 'shell' is denied by permissions configuration را برگردانده است؛ او خواسته که الگوی deny حذف شود، چون پایپلاین به مرحلهی پاکسازی نیاز دارد. مهندس دوم آن را روی لپتاپ با آرگومانهای --exec --safety strict اجرا میکند. در تیکت دوم ذکر شده که ایجنت از اجرای pwd با متن The user rejected the tool call امتناع کرده، هیچ پرامپتی نمایش داده نشده، و هوک حتماً خراب است؛ چون در هر فراخوانی پاسخ allow داده است. اکنون هر دو تیکت و لاگهای ضبطشدهی هر دو اجرا پیش روی شماست.
- نسخه
- docker-agent v1.149.0 and sbx v0.47.0
- مدل
- ai/qwen3:4b through the local model runner, at temperature 0
- سختافزار
- one Mac, no GPU
شواهد
the-agent-file.txt
title: the toolset, the hook and the two patterns of the guarded agent
source: manuals/docker-sandboxes-101/capture/fixtures/agents/guarded.yaml
lines: 12-28
lang: yaml
note: One allow pattern for echo, one deny pattern for rm, and a preempting hook on every shell call.
---
toolsets:
- type: shell
hooks:
pre_tool_use:
- matcher: shell
preempt_yolo: true
hooks:
- type: command
command: ./fixtures/hooks/log-hook.sh
env:
M101_HOOK_LOG: ./work/hook-stdin.jsonl
permissions:
allow:
- "shell:cmd=echo*"
deny:
- "shell:cmd=rm*"
the-order-of-decisions.txt
title: the order the runtime applies to every tool call
source: manuals/docker-sandboxes-101/sections/5-5-permissions-safety-and-hooks.md
lines: 86-92
lang: text
note: Find the step that decided each of the three commands.
---
1. `preempt_yolo` `pre_tool_use` hooks run first, and no mode or allow rule can bypass their deny or ask.
2. A `deny` pattern blocks the call.
3. An `allow` pattern approves it.
4. An `ask` pattern prompts the user.
5. With no match, the safety mode applies to the call's label.
6. On a mode ask, default `pre_tool_use` hooks can allow, deny, or ask.
7. With no decision, the user is asked.
the-restricted-run.txt
title: the three commands under --safety restricted
source: manuals/docker-sandboxes-101/capture/out/20-restricted.txt
lines: 1-17
lang: text
note: Read which commands ran and the wording of the one refusal.
---
user: Run the shell command: echo m101-ok
root -> tool_call shell {"cmd": "echo m101-ok"}
root <- tool_call_response Shell: m101-ok
root: echo m101-ok
m101-ok
stream_stopped (stop, normal)
user: Run the shell command: pwd
root -> tool_call shell {"cmd": "pwd"}
root <- tool_call_response Shell: $CAPTURE
root: pwd
$CAPTURE
stream_stopped (stop, normal)
user: Run the shell command: rm -rf work/m101-nothing
root <- tool_call_response Shell: Tool 'shell' is denied by permissions configuration.
root: rm -rf work/m101-nothing
The command was refused due to permissions configuration.
stream_stopped (stop, normal)
the-strict-run.txt
title: the second and third commands under --safety strict
source: manuals/docker-sandboxes-101/capture/out/20-strict.txt
lines: 7-17
lang: text
note: Compare the wording of the two refusals, and read the metadata of the confirmation.
---
user: Run the shell command: pwd
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "shell", "arguments": "{\"cmd\": \"pwd\"}"}}, "metadata": {"blast_radius": "safe", "category": "fs-read", "reason": "Command matches safe read-only pattern: pwd", "safety_label": "safe"}}
root <- tool_call_response Shell: The user rejected the tool call.
root: pwd
The user rejected the tool call.
stream_stopped (stop, normal)
user: Run the shell command: rm -rf work/m101-nothing
root <- tool_call_response Shell: Tool 'shell' is denied by permissions configuration.
root: rm -rf work/m101-nothing
Tool 'shell' is denied by permissions configuration.
stream_stopped (stop, normal)
the-tool-without-the-model.txt
title: the shell tool called directly, with no model in the loop
source: manuals/docker-sandboxes-101/capture/out/20-debug-tool.txt
lines: 1-3
lang: console
note: The exit code tells you whether the tool itself works.
---
$ docker-agent debug tool fixtures/agents/guarded.yaml shell '{"cmd":"echo m101-direct"}'
m101-direct
[exit 0]
what-the-hook-answered.txt
title: the hook script
source: manuals/docker-sandboxes-101/capture/fixtures/hooks/log-hook.sh
lines: 1-4
lang: bash
note: The hook logs the record and answers allow on every call.
---
#!/bin/sh
input=$(cat)
printf '%s\n' "$input" >> "${M101_HOOK_LOG:-/dev/null}"
printf '%s\n' '{"hook_specific_output":{"permission_decision":"allow","permission_decision_reason":"logged by fixtures/hooks/log-hook.sh"}}'
what-the-hook-received.txt
title: the three records the hook wrote, one per call
source: manuals/docker-sandboxes-101/capture/out/20-hook-stdin.jsonl
lines: 1-3
lang: jsonl
note: Every call reached the hook, including the one that was refused.
---
{"agent_name": "root", "cwd": "$CAPTURE", "hook_event_name": "pre_tool_use", "safety_policy": "restricted", "session_id": "<uuid>", "tool_input": {"cmd": "echo m101-ok"}, "tool_name": "shell", "tool_use_id": "<call-id>"}
{"agent_name": "root", "cwd": "$CAPTURE", "hook_event_name": "pre_tool_use", "safety_policy": "restricted", "session_id": "<uuid>", "tool_input": {"cmd": "pwd"}, "tool_name": "shell", "tool_use_id": "<call-id>"}
{"agent_name": "root", "cwd": "$CAPTURE", "hook_event_name": "pre_tool_use", "safety_policy": "restricted", "session_id": "<uuid>", "tool_input": {"cmd": "rm -rf work/m101-nothing"}, "tool_name": "shell", "tool_use_id": "<call-id>"}
سؤالها
- دو امتناع، دو نگارش متفاوت دارند. قبل از باز کردن فایل ایجنت، بگویید هر نگارش چه نکتهای را دربارهی محل اتخاذ تصمیم نشان میدهد؟
- در هیچ الگویی نام
pwdنیامده است. چرا در یک حالت اجرا شد و در حالت دیگر نه؟ - هوک در هر سه فراخوانی پاسخ allow داد. چرا این پاسخ هیچ تغییری ایجاد نکرد، و هوک چه چیزی را میتوانست تغییر دهد؟
- اجرای مستقیم ابزار چه چیزی را اثبات میکند و چه چیزی را اثبات نمیکند؟
- کدام تیکت یک باگ را گزارش میکند، کدامیک نشاندهندهی کارکرد درست طراحی سیستم است، و برای هر کدام چه تغییری اعمال میکنید؟
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
- فایل ایجنت را بخوانید. یک مجموعهابزار از نوع
shellوجود دارد. یک هوکpre_tool_useبا تنظیماتmatcher: shellوpreempt_yolo: trueتعریف شده که اسکریپتی را اجرا میکند. در بخشpermissions، الگویallowشاملshell:cmd=echo*و الگویdenyشاملshell:cmd=rm*است. نامی ازpwdبرده نشده است. - اجرای حالت restricted را بخوانید. دستور
echoاجرا شد وm101-okرا چاپ کرد. دستورpwdاجرا شد و مسیر دایرکتوری کاری را نمایش داد. فراخوانیrmاصلاً به ابزار نرسید: پاسخ میگوید که پیکربندی مانع اجرای ابزار شده است. این همان الگویdenyاست که باrm*مطابقت دارد. - اجرای حالت strict را بخوانید. دستور
echoدوباره اجرا شد. برایpwd، محیط اجرا رویدادtool_call_confirmationرا با متادیتایblast_radius: safe،category: fs-readوsafety_label: safeصادر کرد. در حالتstrict، برای هر برچسبی تایید خواسته میشود (ask). با فلگ--execترمینالی وجود نداشت؛ بنابراین درخواست تایید به رد شدن (rejection) تبدیل شد و مدل پیامی دریافت کرد مبنی بر اینکه کاربر فراخوانی را رد کرده است. فراخوانیrmدرست مثل حالت دیگر با پیام عدم دسترسی (denial) روبهرو شد. این دو نگارش دو نقطهی تصمیمگیری متفاوت را نشان میدهند: در denial نام پالیسی برده میشود و در rejection نام کسی که از او نظر خواسته شده بود. - رکوردهای هوک و اسکریپت را بخوانید. هوک در اجرای restricted سه رکورد نوشت؛ به ازای هر فراخوانی یکی، از جمله فراخوانی
rm. رکوردها شاملsafety_policy: restrictedوtool_inputکامل هستند. اسکریپت رکورد را ثبت میکند وpermission_decision: allowرا برمیگرداند. در ترتیب تصمیمگیریها، هوکهای بازدارنده (preempting hooks) در اولویت اول هستند، و از آن مرحله به بعد، پاسخ allow صرفاً جنبهی توصیهای دارد: اگر هوک deny یا ask برمیگرداند فراخوانی متوقف میشد، اما پاسخ allow به معنای اعطای مجوز قطعی نیست. سپس در مرحلهی دوم، الگوی deny جلویrmرا گرفت. - اجرای مستقیم ابزار را بخوانید. دستور
debug toolابزار شلِ همین فایل ایجنت را باecho m101-directفراخوانی کرد و عبارتm101-directرا با کد خروج 0 نمایش داد. ابزار سالم است. امتناعها تصمیمهای کنترلی هستند، نه خطای ابزار. اجرای مستقیم مشخص نمیکند که مدل چه چیزی را فراخوانی میکرد؛ بنابراین فقط تکلیف کارکرد درستِ مجموعهابزار را مشخص میکند. - هر دستور را با زنجیرهی اولویت تصمیمگیری مطابقت دهید. دستور
echo: مرحلهی سوم، یک الگوی allow. دستورrm: مرحلهی دوم، یک الگوی deny در هر دو حالت. دستورpwd: الگویی وجود ندارد، بنابراین مرحلهی پنجم، یعنی حالت ایمنی روی برچسبsafe: حالتrestrictedبه برچسب safe اجازهی اجرا میدهد، وstrictتایید میخواهد.
نتیجه
تیکت اول پالیسی را در حین انجام وظیفهاش توصیف میکند. الگوی deny فراخوانی را در تمام حالتها مسدود میکند، و اولویت آن در مستندات سیستم بالاتر از هر allow، هر ask و هر حالتی است. الگو را نگه دارید. پایپلاینی که باید فایلها را پاک کند، این کار را خارج از ایجنت انجام میدهد، یا با یک deny محدودتر که همچنان مانع اجرای rm -rf شود. حذف تنها قانونی که هیچ حالت و هوکی نمیتواند بر آن اثر بگذارد، ایجنت بدون نظارت را کاملاً بیدفاع رها میکند.
تیکت دوم حالتی را گزارش میکند که برای یک اجرای بدون نظارت (unattended) مناسب نیست. حالت strict برای هر فراخوانی نامنطبق تایید میخواهد، و فلگ --exec بدون ترمینال، هر درخواستی را به رد شدن تبدیل میکند. راهحل این است که برای اجرای لپتاپ از --safety restricted استفاده شود که به برچسب safe اجازهی اجرا میدهد و جلوی destructive و unknown را میگیرد، یا اینکه یک الگوی allow برای pwd تعریف شود. هوک خراب نیست: هوک بازدارنده مجوزی صادر نمیکند، و لاگ سهرکوردی آن نشان میدهد که تمام فراخوانیها را دیده است. اثبات این موضوع همان اجرای restricted است: pwd دایرکتوری کاری را چاپ کرد، rm همچنان رد شد، و هوک هر سه را ثبت کرد.
یک جمله از مستندات باید در پاسخ هر دو تیکت بیاید: کلاینت دسترسیها را اعمال میکند، این دسترسیها جلوی خطاهای تصادفی را میگیرند، اما یک مرز امنیتی (security boundary) نیستند. ایجنتی را که به آن اعتماد ندارید، حتماً در ساندباکس اجرا کنید.
مسیرهای اشتباه رایج
- «هوک خراب است، چون allow برگرداند ولی فراخوانی باز هم رد شد.» حکم ارزیابی allow از سمت یک هوک بازدارنده صرفاً جنبهی مشورتی دارد. اگر deny یا ask برمیگرداند فراخوانی را متوقف میکرد. هیچچیز خراب نیست.
- «الگوی deny را حذف کنید تا مرحلهی پاکسازی در پایپلاین اجرا شود.» الگوی deny تنها قانونی است که هیچ حالت و هیچ هوکی نمیتواند آن را دور بزند. یک ایجنت بدون نظارت که
rmبرایش مجاز باشد، دیگر هیچ سد دفاعی ندارد. - «برنامه را با
--yoloاجرا کنید تا چیزی تایید نخواهد.» این کار یعنی حالتautonomous: هر فراخوانی نامنتبقی اجرا میشود، از جملهdestructiveوunknown. موردpwdبه حالتrestrictedیا یک الگوی allow نیاز دارد. - «مجموعهابزار شل روی لپتاپ درست پیکربندی نشده است.» اجرای مستقیم با همان فایل ایجنت، مقدار
m101-directرا با کد خروج 0 چاپ کرد. ابزار کار میکند و لایهی تصمیمگیری بود که مانع شد.
درس کلی
همیشه ابتدا نگارش متن امتناع مدل را با دقت بخوانید. واژهی denial به پالیسی اشاره دارد، واژهی rejection به کاربر اشاره میکند، و پرامپت تاییدیه در یک اجرای headless به rejection تبدیل میشود. سپس هر فراخوانی را با ترتیب تصمیمگیری تطبیق دهید: هوکهای بازدارنده، deny، سپس allow، سپس ask و در نهایت mode. حالت ایمنی را بر اساس اینکه چه کسی پای ترمینال نشسته انتخاب کنید، و به یاد داشته باشید که هیچکدام از اینها مرز امنیتی نیستند.
کجای دوره آموزش داده میشود
در بخش دسترسیها، این سه دستور در هر دو حالت اجرا میشوند و ترتیب تصمیمگیری آموزش داده شده است.