از نسخه‌ی 2.1.219 در ۲۴ ژوئیه‌ی ۲۰۲۶، تنظیم strictAllowlist در لایه‌ی شبکه‌ی سندباکس کلاد کد اضافه شد: به‌جای اینکه هنگام نیاز به یک دامنه‌ی تازه از شما اجازه بگیرد، هر میزبان بیرون از فهرست را بی‌صدا رد می‌کند. راه‌اندازی آن سه خط پیکربندی است، اما روی سرور لینوکسی یک پیش‌نیاز پنهان دارد که در بیشتر نصب‌ها غایب است.

این تنظیم دقیقا چه چیزی را عوض می‌کند

سندباکس کلاد کد دو لایه‌ی مستقل دارد: یکی فایل‌سیستم و یکی شبکه. لایه‌ی شبکه از طریق یک پروکسی بیرون از سندباکس کنترل می‌شود.

رفتار پیش‌فرض آن ساده است. کلاد کد در ابتدا هیچ دامنه‌ای را مجاز نمی‌داند، و در اولین باری که یک دستور به یک دامنه‌ی تازه نیاز پیدا می‌کند، از شما اجازه می‌گیرد. اگر بزنید «بله»، آن میزبان تا پایان همان نشست مجاز می‌ماند.

تفاوت strictAllowlist در همین یک فعل است: به‌جای پرسیدن، رد می‌کند. مستندات می‌گویند وقتی این کلید را در تنظیمات کاربر، مدیریت‌شده یا فلگ --settings روی true بگذارید، کلاد کد دسترسی دستورهای داخل سندباکس به هر میزبانی بیرون از فهرست را بدون پرسش رد می‌کند. فهرست پایه همان چیزی است که سندباکس در حالت عادی از شما درباره‌اش می‌پرسد: یعنی allowedDomains به‌علاوه‌ی دامنه‌هایی که از قاعده‌های مجوز WebFetch(domain:...) آمده‌اند.

این تفاوت در عمل با تنظیم allowManagedDomainsOnly فرق دارد و نباید این دو را یکی گرفت. آن یکی فقط از تنظیمات مدیریت‌شده پذیرفته می‌شود و برای قفل سازمانی است؛ این یکی از فایل شخصی خودتان هم پذیرفته می‌شود و مهاجرت هر تیمی از حالت «هر بار تأیید کن» به حالت «فقط این فهرست» با همین یک کلید انجام می‌شود.

پیکربندی کامل در سه خط

کلید زیر یک بلوک تنظیمات JSON است که می‌توانید آن را در ~/.claude/settings.json بگذارید یا فقط برای یک نشست با فلگ --settings به کلاینت بدهید. برای اینکه موتور سندباکس استوار بماند و روی نبودِ پیش‌نیازها به‌جای هشدار، واقعا متوقف شود، دو کلید دیگر را هم اضافه کرده‌ام.

# اول کلاینت را نصب کنید و پیش‌نیازهای سندباکس را
$ sudo apt-get install bubblewrap socat
$ claude --version
2.1.283 (Claude Code)

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "strictAllowlist": true,
      "allowedDomains": ["github.com", "*.npmjs.org", "pypi.org", "files.pythonhosted.org"]
    }
  }
}

# یک نشست تک‌باره را بدون دست‌زدن به فایل باز کنید
$ claude --settings '{"sandbox": {"enabled": true, "network": {"strictAllowlist": true, "allowedDomains": ["github.com"]}}}'
# خروجی این نشست: هر اتصال به میزبانی بیرون از github.com بدون پرسش رد می‌شود
# یعنی یک npm install که به registry.npmjs.org می‌رود، دیگر اجازه‌ی تعاملی نمی‌گیرد

دو کلید failIfUnavailable و allowUnsandboxedCommands: false تنظیم را از یک توصیه‌ی اختیاری به یک دروازه‌ی امنیتی تبدیل می‌کنند. اولی وقتی سندباکس به هر دلیل بالا نیامد، اجرا را متوقف می‌کند به‌جای اینکه فقط هشدار بدهد و بدون سندباکس ادامه دهد. دومی دریچه‌ی فرار را می‌بندد: به‌صورت پیش‌فرض، وقتی دستوری داخل سندباکس اجرا نمی‌شود، کلاد کد تخلف را تحلیل می‌کند و ممکن است همان دستور را با پارامتر dangerouslyDisableSandbox دوباره اجرا کند؛ آن تلاش دوباره بیرون از سندباکس می‌رود و از مسیر عادی مجوز می‌گذرد. با این فلگ، پارامتر نادیده گرفته می‌شود و هر دستوری که کلاد اجرا کند باید داخل سندباکس اجرا شود.

پیش‌نیاز پنهان روی لینوکس: bubblewrap

سندباکس کلاد کد روی مک، لینوکس و WSL2 اجرا می‌شود و روی ویندوز بومی پشتیبانی نمی‌شود. روی لینوکس به دو بسته تکیه می‌کند: bubblewrap که مرز ایزوله‌سازی فایل‌سیستم را در سطح سیستم‌عامل اعمال می‌کند و socat که ترافیک شبکه را از سندباکس عبور می‌دهد. بدون این دو، کلاد کد فقط یک هشدار نشان می‌دهد و دستورها را بدون سندباکس اجرا می‌کند.

اگر bwrap را در دسترس ندارید، یعنی نصب در بلوک قبلی نیمه‌کاره مانده و سندباکس اصلا بالا نمی‌آید. پس از نصب باید کلاد کد را ری‌استارت کنید، چون بررسی پیش‌نیازها در شروع اجرا انجام می‌شود و نشست باز که این بررسی را رد کند، همان را نگه می‌دارد. آزمون پایه این است:

$ bwrap --ro-bind / / --unshare-all --die-with-parent /bin/echo "sandbox core works"
sandbox core works

اگر می‌خواهید مطمئن شوید ایزوله‌سازی واقعا فعال است و فقط یک echo موفق نبوده، یک آزمون منفی بزنید. هر چیزی که در مسیری خارج از bindهای سندباکس بنویسد باید رد شود و فایل ساخته نشود:

$ bwrap --ro-bind / / --unshare-all --die-with-parent \
      /bin/sh -c 'echo leak > /tmp/escape.txt'
# خروجی واقعی روی این سرور:
# /bin/sh: 1: cannot create /tmp/escape.txt: Read-only file system
$ ls /tmp/escape.txt
# ls: cannot access '/tmp/escape.txt': No such file or directory

اگر دستور اول بدون خطا تمام شد، یعنی ایزوله‌سازی فایل‌سیستم در کار نیست و هر تنظیم مجوزی بی‌اثر است. همان آزمون روی شبکه هم کار می‌کند: با --unshare-net هیچ مسیری برای resolve کردن نام دامنه وجود ندارد و همان خطای دسترسی می‌گیرید.

تله‌ی AppArmor در اوبونتو

اگر sysctl روی سیستم شما عدد 1 برگرداند، بسته نصب است اما سندباکس هنوز بالا نمی‌آید. مستندات می‌گویند در اوبونتو نسخه‌ی ۲۴ و جدیدتر، سیاست پیش‌فرض AppArmor جلوی ساخت user namespace مورد نیاز bubblewrap را می‌گیرد. آزمون گام اول این است:

$ sysctl kernel.apparmor_restrict_unprivileged_userns
kernel.apparmor_restrict_unprivileged_userns = 1
# عدد 1 یعنی سیاست فعال است و باید پروفایل AppArmor را بسازید
# خطای No such file or directory یعنی این کلید وجود ندارد و می‌توانید این گام را رد کنید

روی یک سرور اوبونتو که همین آزمون را روی آن اجرا کردم، bubblewrap به‌عنوان root بدون خطا کار می‌کرد و به‌عنوان یک کاربر عادی در همه‌ی ترکیب‌های namespace شکست می‌خورد. این جدول خروجی واقعی همان آزمون است، با اجرای هر حالت دوبار: یک بار به‌عنوان root و یک بار به‌عنوان کاربر غیر‌ریشه.

BWRAP ARGS                    AS ROOT    AS bob (unpriv)
--unshare-all                 OK         FAIL: loopback: Failed RTM_NEWADDR
--unshare-user                OK         FAIL: setting up uid_map
--unshare-user --unshare-pid  OK         FAIL: setting up uid_map
--unshare-net                 OK         FAIL: loopback: Failed RTM_NEWADDR
--unshare-pid                 OK         FAIL: setting up uid_map

دو خطای متفاوت، یک ریشه. خطای RTM_NEWADDR یعنی ساخت namespace شبکه در خودِ بسته شکست می‌خورد، و خطای uid_map یعنی namespace کاربر ساخته می‌شود ولی نگاشت شناسه‌ها نوشته نمی‌شود. خطای دوم همان چیزی است که سیاست AppArmor مسدود می‌کند: بسته به ساخت namespace کاربر می‌رسد، اما نوشتن روی /proc/self/uid_map را رد می‌کند. تعداد حالت‌هایی که به‌عنوان کاربر غیر‌ریشه شکست خوردند برابر ۵ از ۵ بود.

راه‌حلی که مستندات پیشنهاد می‌دهند یک پروفایل AppArmor است که فقط به خودِ bwrap اجازه‌ی userns می‌دهد و روی دستورهای داخل سندباکس اثری ندارد. این پروفایل را در این اجرا اعمال نکردم، چون نوشتن در /etc/apparmor.d/ یک تغییر امنیتی روی سرور فعال است و نه یک تنظیم. خروجی «پیش از تغییر» و «پس از تغییر» که در جدول بالا می‌بینید واقعی است، ولی سنجش پس از اعمال پروفایل انجام نشده است.

وقتی خروجی با این مقاله فرق کرد، چه کنید

سه نتیجه‌ی متفاوت ممکن است ببینید و هر کدام معنای جداگانه‌ای دارد. اگر یک npm install بی‌صدا شکست بخورد و پیام مجوز نیاید، این strictAllowlist دارد کار می‌کند و فهرست دامنه ناقص است؛ راه‌حل، افزودن همان دامنه به allowedDomains است، نه خاموش‌کردن کلید. اگر /sandbox فقط زبانه‌ی Dependencies را نشان می‌دهد، بسته‌ها جا افتاده‌اند و باید bubblewrap و socat را نصب کنید.

اگر کلید را true گذاشته‌اید و باز هم پیام اجازه می‌بینید، به این دلیل است که این تنظیم فقط روی دستورهای داخل سندباکس اعمال می‌شود. ابزارهای درون‌فرایندی مانند WebFetch همچنان از قاعده‌های مجوز خودشان پیروی می‌کنند و با فهرست دامنه‌ی سندباکس بسته نمی‌شوند. برای بستن همان دریچه‌ی درون‌فرایندی، کلید جداگانه‌ی allowManagedDomainsOnly در تنظیمات مدیریت‌شده وجود دارد، و این دو مکمل یکدیگرند و جایگزین هم نیستند.

برای سازمانی که می‌خواهد مرز را از یک فایل قابل‌تعقیب در مخزن تعریف کند، sandbox.network.strictAllowlist همان چیزی است که لازم دارد: رفتار شبکه از حالت «تصمیم تعاملی هر بار» به یک قاعده‌ی قابل‌بازبینی تبدیل می‌شود. این همان نقطه‌ای است که پست لایه‌ی مجوز ایجنت و اعداد واقعی یک بازبین خودکار از بیرون رفتن دستورها شروع می‌کرد: آنجا مجوز را می‌سنجیدیم، اینجا تعیین می‌کنیم دستور اصا بتواند به کجا برود. باقی می‌ماند اینکه روی لینوکس، پیش از هر چیز، خودِ موتور سندباکس باید واقعا بالا بیاید.

منابع

  1. Changelog رسمی Claude Code روی GitHub — نسخه‌ی 2.1.219 و کلید strictAllowlist.
  2. صفحه‌ی changelog کلاد کد در مستندات — تاریخ انتشار ۲۴ ژوئیه‌ی ۲۰۲۶.
  3. مستندات sandboxing کلاد کد — لایه‌های ایزوله‌سازی و تنظیم شبکه.
  4. مرجع کامل تنظیمات کلاد کد — توضیح و دامنه‌ی کاربرد کلید strictAllowlist.
  5. مستندات مجوزها — قاعده‌های WebFetch و رابطه‌ی آن‌ها با سندباکس.
  6. مستندات حالت‌های مجوز — تفاوت حالت خودکار و حالت دستی.
  7. مستندات فایل‌های تنظیمات — ترتیب تقدم فایل‌ها و محل هر کلید.
  8. مستندات پیکربندی پروکسی شبکه — عبور ترافیک از پروکسی سندباکس.
  9. مرجع متغیرهای محیطی کلاد کد — متغیرهای مؤثر بر رفتار سندباکس.
  10. مخزن bubblewrap — ابزار ایزوله‌سازی که سندباکس به آن تکیه می‌کند.
  11. مخزن رسمی Claude Code — کد و انتشار نسخه‌ها.