مواد پر جائیں

سینڈ باکس بیک اینڈز

بیک اینڈ ویلیو پلیٹ فارم دستیابی
بند VM microvm macOS، Linux، Windows (microVM ہائپر وائزر) microVM رن ٹائم پر پروب سے مشروط؛ انٹرایکٹو ٹرمنلز پر لاگو ہوتا ہے — شیل ہوسٹ پر نہیں، ایک رگ کے اندر چلتا ہے
نیٹو native macOS (Seatbelt)، Linux اور WSL2 (bubblewrap) بوٹ پر پروب ہوتا ہے؛ Linux ایسے رن سے انکار کر دیتا ہے جس میں فائل نام گلوب رائٹ انکار درکار ہوں، جنہیں bubblewrap نافذ نہیں کر سکتا
None none سب پارس کا ڈیفالٹ، ٹرمنل کا ڈیفالٹ، اور وہ فال بیک جب کوئی بیک اینڈ دستیاب نہ ہو یا --sandbox off مقرر ہو

SandboxBackend.fromName null یا ناقابلِ شناخت محفوظ ویلیو کے لیے none واپس کرتا ہے۔ محفوظ "docker" کو native پر میپ کیا جاتا ہے۔

microvm واحد بیک اینڈ ہے جس کی کرنل سرحد ہوتی ہے — ورک لوڈ واقعی ہوسٹ پر نہیں چلتا۔ یہ کسی بھی سمت خاموش فال بیک نہیں ہوتا: جو ہوسٹ VM بوٹ نہ کر سکے، اس پر اسے واضح طور پر طلب کرنا بلند آواز میں ناکام ہوتا ہے (“میں نے VM مانگا تھا اور مجھے اپنا لیپ ٹاپ مل گیا” ہی وہ واحد گراوٹ ہے جو انکلوژر برداشت نہیں کر سکتا)، اور صرف غیر متعین ڈیفالٹ ہی native تک نیچے اترتا ہے، اور لاگ کی ایک لائن یہ بتا دیتی ہے۔ سیشن کا حقیقی بیک اینڈ کلائنٹ کو واپس بتایا جاتا ہے اور اس پر بیج دکھایا جاتا ہے، اس لیے کوئی ٹرمنل ہوسٹ پر چلتے ہوئے یہ دعویٰ نہیں کر سکتا کہ وہ انکلوژر میں ہے۔ خود VM کے لائف سائیکل، امیجز اور ایگریس کے لیے رگز کا حوالہ دیکھیں۔

Windows میں کوئی نیٹو سینڈ باکس نہیں۔ NativeSandboxAdapter.probe ہر ایسے ہوسٹ پر available: false واپس کرتا ہے جو macOS یا Linux/WSL2 نہ ہو۔ اس لیے Windows پر ایجنٹ ڈسپیچ none استعمال کرتا ہے۔ microvm بیک اینڈ الگ ہے: یہ microVM رن ٹائم پر پروب سے مشروط ہے اور انٹرایکٹو ٹرمنلز اور رگز پر لاگو ہوتا ہے، ہوسٹ پر bash لپیٹنے پر نہیں۔

پروب ہی نافذ کاری کو گیٹ کرتا ہے۔ یہ ایک بار، سرور بوٹ پر چلتا ہے۔

ہوسٹ available نوٹ / اشارہ
macOS true sandbox-exec (Seatbelt) — نین اسپیس تنہائی، کوئی کرنل سرحد نہیں
bwrap اور socat والا Linux یا WSL2 true bubblewrap — نین اسپیس تنہائی، کوئی کرنل سرحد نہیں
Linux یا WSL2 جس میں کوئی ایک ٹول بھی غائب ہو false requiresInstall: true، ساتھ انسٹال کا اشارہ جو غائب پیکیجز کے نام بتاتا ہے
کوئی بھی دوسرا پلیٹ فارم false اس پلیٹ فارم پر نیٹو سینڈ باکس پیش نہیں کیا جاتا

سرور نتیجہ اسٹارٹ اپ کی ایک لائن پر لاگ کرتا ہے: agent sandbox ON کے ساتھ نوٹ، no OS-native agent sandbox on this host کے ساتھ اشارہ، یا agent sandbox DISABLED by --sandbox off۔ GET /healthz میں سینڈ باکس کا کوئی فیلڈ نہیں ہوتا۔

--sandbox / CC_SERVER_SANDBOX on (ڈیفالٹ) یا off قبول کرتا ہے۔ یہ آپٹ آؤٹ ہے، آپٹ اِن نہیں: on کا مطلب ہے “جب ہوسٹ کوئی بیک اینڈ پیش کرے تو لپیٹ دو”، کبھی “کوئی بیک اینڈ لازم ہے” نہیں۔

Apple کے Seatbelt سینڈ باکس میکنزم کو استعمال کرتا ہے (وہی نظام جو macOS App Sandbox استعمال کرتا ہے)۔

بنایا گیا پروفائل ڈیفالٹ کے اعتبار سے اجازت دینے والا ہوتا ہے ((allow default)) اور انکار تراشتا ہے، کیونکہ مکمل ڈیفالٹ سے انکار کرنے والا پروفائل انٹرایکٹو شیل کو ناقابلِ استعمال بنا دیتا ہے — dyld، XPC اور Mach کالز اتنی زیادہ ہیں کہ گنی نہ جائیں۔ عملی نتیجہ یہ ہے کہ ایجنٹ پھر بھی ہوسٹ کا بیشتر حصہ پڑھ سکتا ہے؛ آپ کے رجسٹرڈ چیک آؤٹس واضح رائٹ اور رینیم انکاروں سے محفوظ رہتے ہیں، نہ کہ نظر نہ آنے سے۔

  • فائل سسٹم ریڈز: خفیہ پاتھوں کے لیے انکار (~/.ssh، ~/.aws، ~/.gnupg، ~/.config/gh، ~/Library/Keychains اور ریڈ سے انکار والا باقی سیٹ)
  • فائل سسٹم رائٹس: انکار پر ری سیٹ، پھر واضح سب پاتھ اجازتیں، اور لازمی انکار والے پاتھ (شیل rc فائلیں، .git/hooks، Claude کنفیگ، محفوظ چیک آؤٹس) کسی رائٹ ایبل روٹ کے اندر بھی بلاک۔ file-write-unlink ہر انکار شدہ پاتھ اور اس کے آباؤ اجداد پر انکار ہوتا ہے، اس لیے رینیم کسی رائٹ سے انکار کو بائی پاس نہیں کر سکتا
  • پروسیس: ہمیشہ خطرناک بائنریز کے لیے process-exec انکار، نیز کسی رائٹ ایبل ڈائریکٹری سے کچھ بھی ایگزیکیوٹ کرنے پر پابندی
  • نیٹ ورک: اِن پروسیس پراکسی پورٹس اور DNS تک محدود — loopback کو کلی اجازت نہیں اور Unix سوکٹس کی بھی اجازت نہیں۔ پراکسیاں فی سیشن ڈومین اجازت فہرست نافذ کرتی ہیں (نیٹ ورک ایگریس دیکھیں)
  • کنفیگریشن: پروفائلز ہر لانچ پر SandboxSpec سے بنائے جاتے ہیں

تقاضے:

  • sandbox-exec (/usr/bin/sandbox-exec)، جو ہر macOS انسٹال کا حصہ ہے — کسی اضافی ٹولنگ کی ضرورت نہیں

ماؤنٹ اور PID نین اسپیس بنانے کے لیے bubblewrap (bwrap) استعمال کرتا ہے۔

  • فائل سسٹم: ایسا ماؤنٹ نین اسپیس بناتا ہے جس میں صرف بائنڈ شدہ پاتھ نظر آتے ہیں
  • نیٹ ورک: اَن شیئرڈ نیٹ ورک نین اسپیس میں چلتا ہے؛ ٹریفک socat Unix سوکٹ برجز کے ذریعے ہوسٹ پراکسیوں تک پہنچتی ہے
  • پروسیس: PID نین اسپیس تنہائی

تقاضے:

  • bubblewrap اور socat انسٹال ہوں (Debian/Ubuntu پر sudo apt-get install bubblewrap socat)
  • کرنل نین اسپیس سپورٹ (جدید Linux پر معیاری)

Bubblewrap کسی موجودہ پاتھ کو چھپا سکتا ہے، لیکن کسی رائٹ ایبل بائنڈ کے اندر نئی .env، *.key یا *.pem فائل کو منع نہیں کر سکتا۔ معیاری ڈسپیچ پالیسی کو ان فائل نام گلوب انکاروں کی ضرورت ہوتی ہے، اس لیے Linux/WSL2 پر نیٹو ایجنٹ ڈسپیچ اس وقت fail closed ہوتا ہے، چاہے پروب کو bubblewrap مل ہی جائے۔ یہ خاموشی سے کمزور پالیسی کے ساتھ نہیں چلتا۔ Linux پر نیٹو ڈسپیچ بحال کرنے کے لیے ایسا بیک اینڈ درکار ہے جس میں فائل نام کے قواعد تخلیق کے وقت لاگو ہوں۔ سینڈ باکسنگ بند کرنا ایک واضح غیر محدود آپٹ آؤٹ ہے، کوئی مساوی کام چلاؤ راستہ نہیں۔

کوئی سینڈ باکسنگ نہیں۔ پروسیس براہِ راست ہوسٹ پر چلتا ہے، ہوسٹ کے فائل سسٹم، نیٹ ورک اور پروسیس تک رسائی کے ساتھ۔ ACP اور ہارنس کے bash ٹول کو پھر بھی ماحول کی صفائی اور کمانڈ پالیسی ملتی ہے؛ NoSandboxAdapter کے ذریعے Claude Code ہوسٹ کا ماحول ورثے میں پاتا ہے۔ ایسے ہوسٹ پر جہاں کوئی بیک اینڈ دستیاب نہ ہو یا --sandbox off لگا ہو، ایجنٹ ڈسپیچ اسی پر واپس چلتا ہے، اور جب کوئی کلائنٹ کوئی بیک اینڈ نہ بتائے تو یہی ٹرمنل کا ڈیفالٹ ہے۔

ٹرمنل اپنے الگ اصولوں پر سینڈ باکس ہوتا ہے، ڈسپیچ پروب سے نہیں۔ TerminalSessionService کا defaultBackend none ہے اور cc_server اسے اوور رائیڈ نہیں کرتا، اس لیے ٹرمنل سیشن ہوسٹ شیل چلاتا ہے جب تک کوئی کلائنٹ واضح طور پر native نہ مانگے — ڈیسک ٹاپ کا ٹرمنل پینل نہیں مانگتا۔

جب native طلب کیا جائے تو شیل کو SandboxManager کے ذریعے ایک مقررہ ٹرمنل پروفائل کے تحت لپیٹا جاتا ہے: $HOME اور سیشن کی ورکنگ ڈائریکٹری رائٹ ایبل ہوتی ہیں، نیٹ ورک کھلا ہوتا ہے اور ~/.ssh، ~/.aws، ~/.gnupg، ~/.config/gh اور ~/Library/Keychains پر ریڈ سے انکار ہوتا ہے۔ صرف پڑھنے والا ٹوکن اور پش گیٹ وے لاگو نہیں ہوتے — وہ ڈسپیچ کا معاملہ ہے۔ اگر لپیٹنے کی سپورٹ نہ ہو تو سیشن ناکام ہو جاتا ہے، بجائے اس کے کہ ہوسٹ شیل والے PTY پر نیٹو بیج دکھائے۔

جب کوئی سینڈ باکس لانچ ہوتا ہے تو آؤٹ باؤنڈ نیٹ ورک رسائی اِن پروسیس پراکسیوں سے نافذ ہوتی ہے، کرنل فائر وال قواعد سے نہیں۔ ایسے ہوسٹ پر جہاں کوئی بیک اینڈ دستیاب نہ ہو، اس میں سے کچھ بھی لاگو نہیں ہوتا اور اسپان شدہ پروسیس نیٹ ورک تک بالکل اسی طرح پہنچتا ہے جیسے سرور صارف پہنچتا۔

  • سینڈ باکس رن ٹائم cc_server پروسیس کے اندر 127.0.0.1 پر ایک HTTP/HTTPS پراکسی اور ایک SOCKS5 پراکسی چلاتا ہے، ہر محدود سیشن کے لیے ایک جوڑا (http_proxy.dart، socks_proxy.dart)۔ بیک وقت چلنے والے رنز ایک جوڑا شیئر نہیں کرتے۔
  • سینڈ باکس شدہ پروسیسز کو پراکسی ماحول متغیرات ملتے ہیں (HTTP_PROXY/HTTPS_PROXY → HTTP پراکسی، ALL_PROXY → SOCKS پراکسی؛ GIT_SSH_COMMAND git-over-SSH کو SOCKS پراکسی سے گزارتا ہے)۔ Linux پر نیٹ ورک نین اسپیس اَن شیئرڈ ہوتا ہے، اس لیے باہر نکلنے کا واحد راستہ پراکسیاں ہی ہیں؛ macOS پر سینڈ باکس ہوسٹ loopback شیئر کرتا ہے اور ان سے براہِ راست بات کرتا ہے۔
  • ہر کنکشن کے ٹارگٹ ہوسٹ کو سیشن کی ڈومین اجازت فہرست سے میچ کیا جاتا ہے؛ باقی سب کچھ مسترد ہو جاتا ہے۔ وائلڈ کارڈ کی دو صورتیں، ہر ایک میں بالکل ایک *: شروع والا *.example.com کسی بھی سب ڈومین سے میچ کرتا ہے (a.b.example.com سمیت) لیکن خود apex سے نہیں؛ درمیانی لیبل والا bedrock.*.amazonaws.com بالکل ایک لیبل سے میچ کرتا ہے (bedrock.us-east-1.amazonaws.com، نہ کہ bedrock.evil.attacker.amazonaws.com)۔
  • اجازت فہرست فی سیشن منتخب بیس لائن (kBaselineAllowedDomains: LLM فراہم کنندگان، Git ہوسٹنگ، پیکیج رجسٹریاں) سے حل ہوتی ہے، نیز GitHub ڈومینز (kGithubDomains)، نیز SandboxSpec.egressAllowlist۔ ڈسپیچ پاتھ اضافی egressAllowlist اندراجات کبھی نہیں بھیجتا، اس لیے عملاً ہر رن کو بیس لائن کے ساتھ GitHub ملتا ہے۔
  • ایک مقررہ انکار فہرست (kBaselineDeniedDomains: کلاؤڈ میٹاڈیٹا اینڈپوائنٹس، ٹیلی میٹری سنکس) تمام اجازتوں پر غالب آتی ہے۔
  • networkEnabled: false پھر بھی فی سیشن پراکسیاں شروع کرتا ہے، مگر اجازت فہرست خالی ہوتی ہے، اس لیے ہر آؤٹ باؤنڈ کنکشن مسترد ہو جاتا ہے۔ ڈسپیچ رن کے آغاز پر یہ قدر نیٹ ورک تک رسائی قاعدے سے مقرر کرتا ہے: منع کرنا نیٹ ورک بند کرتا ہے، اجازت اور پہلے پوچھیں اسے آن رکھتے ہیں۔

SandboxPort.launch کو دی جانے والی اسپیسفیکیشن:

فیلڈ قسم تفصیل
sessionId String مستحکم سیشن شناخت کنندہ (عموماً اسپیس آئی ڈی)
workspaceId String مالک ورک اسپیس آئی ڈی
agentId String? فی الحال سینڈ باکس سے منسلک ایجنٹ، اگر کوئی ہو
bindMounts List<SandboxBindMount> ہوسٹ→گیسٹ ماؤنٹس؛ سینڈ باکس صرف وہی ہوسٹ پاتھ دیکھتا ہے جو یہاں درج ہوں
networkEnabled bool (ڈیفالٹ true) ڈسپیچ کے وقت نیٹ ورک ایگریس قاعدے سے مقرر ہوتا ہے (صرف منع پر حل ہونے کی صورت میں بند)۔ بند ہونے پر فی سیشن پراکسیاں پھر بھی شروع ہوتی ہیں مگر اجازت فہرست خالی ہوتی ہے، اس لیے ہر آؤٹ باؤنڈ کنکشن مسترد ہوتا ہے
egressAllowlist List<String> (ڈیفالٹ []) اضافی اجازت یافتہ ایگریس ڈومینز؛ وائلڈ کارڈز کی سپورٹ (*.example.com، نیز درمیانی ایک لیبل والی صورت)۔ ڈسپیچ اسے کبھی نہیں بھرتا، اس لیے لپیٹا گیا رن منتخب بیس لائن کے ساتھ GitHub ڈومینز پاتا ہے
guestWorkdir String? سینڈ باکس کے اندر ڈیفالٹ ورکنگ ڈائریکٹری؛ انفرادی exec کالز اسے اوور رائیڈ کر سکتی ہیں
mode Mode (ڈیفالٹ chat) فائل سسٹم کے رائٹ قواعد تراشتا ہے: chat بائنڈ ماؤنٹس کو رائٹ ایبل رکھتا ہے؛ review، plan اور orchestrate ریڈ-اونلی ہیں
protectedPaths List<String> (ڈیفالٹ []) ایسے ہوسٹ پاتھ جو کسی بھی موڈ میں سینڈ باکس کے اندر کبھی رائٹ ایبل نہ ہوں
runnerStateDirs List<String> (ڈیفالٹ []) ایسی ہوسٹ ڈائریکٹریاں جن میں رنر اپنی اسٹیٹ رکھتا ہے، ہر موڈ میں رائٹ ایبل (Control Center کے زیرِ انتظام CLAUDE_CONFIG_DIR اس وقت کی واحد ہے)
execGrantRoots List<String> (ڈیفالٹ []) آپریٹر سے منظور شدہ ڈائریکٹری درخت جو macOS پر رائٹ ایبل ڈائری والا exec بلاک دوبارہ کھول دیتے ہیں۔ Linux انہیں نظر انداز کرتا ہے — bwrap میں دوبارہ کھولنے کے لیے کوئی $HOME exec بلاک ہی نہیں

protectedPaths اصل رجسٹرڈ ریپو چیک آؤٹس رکھتا ہے، جو فی ڈسپیچ ورک اسپیس کے ریپوز سے حل ہوتے ہیں۔ ایجنٹس صرف فی گفتگو copy-on-write worktrees میں کام کرتے ہیں، اس لیے اصل کاپیاں سینڈ باکس کے اندر سے کبھی رائٹ ایبل نہیں ہونی چاہئیں — ورنہ macOS پر Seatbelt کی $HOME کو دی جانے والی عام رائٹ اجازت انہیں bash کے ذریعے رائٹ ایبل چھوڑ دیتی۔ یہ ہر موڈ میں، chat سمیت، خفیہ پاتھوں کے رائٹ سے انکار والے سیٹ میں شامل ہو جاتے ہیں۔

ہر deny-read اور deny-write پاتھ اپنی لفظی اور symlink سے حل شدہ دونوں ہجوں میں خارج ہوتا ہے۔ کرنل انکار کے اصول کو resolved پاتھ کے مقابلے میں میچ کرتا ہے، اس لیے symlink والے پاتھ کے خلاف لکھا گیا اصول کبھی فعال نہیں ہوتا — اور macOS پر یہ غیر معمولی کے بجائے عام صورت ہے، کیونکہ /tmp حل ہو کر /private/tmp بنتا ہے اور /var/folders/… حل ہو کر /private/var/folders/…۔ جن اندراجات میں * یا ? ہو انہیں گلوب سمجھا جاتا ہے اور چھوڑ دیا جاتا ہے؛ جو پاتھ حل نہ ہو اسے جیسا لکھا گیا ہے ویسا ہی رکھا جاتا ہے۔

فیلڈ قسم تفصیل
hostPath String ہوسٹ پر مطلق پاتھ
guestPath String سینڈ باکس کے اندر پاتھ (نیٹو سینڈ باکس کے ساتھ یہ hostPath کے برابر ہوتا ہے؛ اڈاپٹر کی ہم شکلی کے لیے رکھا گیا ہے)
readOnly bool (ڈیفالٹ false) true ہونے پر ریڈ-اونلی ماؤنٹ

SandboxPort.launch سے واپس ملتا ہے:

فیلڈ قسم تفصیل
sessionId String سیشن شناخت کنندہ
backend SandboxBackend کون سا بیک اینڈ چل رہا ہے
state SandboxState لائف سائیکل حالت
error Object? جب state کی ویلیو error ہو تو مقرر ہوتا ہے
details Map<String, Object?> اڈاپٹر کا نجی حساب کتاب (ورکنگ ڈائریکٹری، PID، پروفائل پاتھ وغیرہ)
حالت تفصیل
created اسپیک بن گئی مگر VM ابھی شروع نہیں ہوئی
warm چل رہا ہے اور کمانڈز ایگزیکیوٹ کرنے کے لیے تیار
active اس وقت کوئی کمانڈ ایگزیکیوٹ ہو رہی ہے
suspended RAM بچانے کے لیے روکا گیا / ڈسک پر چیک پوائنٹ شدہ
destroyed ختم کر دیا گیا؛ ہینڈل اب درست نہیں
error لانچ ناکام — SandboxHandle.error دیکھیں
ایونٹ کی قسم تفصیل
stdout سینڈ باکس سے معیاری آؤٹ پٹ
stderr سینڈ باکس سے معیاری ایرر
exit سینڈ باکس پروسیس ختم ہو گیا (exitCode ساتھ لاتا ہے)
starting سینڈ باکس شروع ہو رہا ہے
ready سینڈ باکس exec کالز قبول کرنے کے لیے تیار ہے
killed پروسیس کو ہوسٹ نے مار دیا (OOM، ٹائم آؤٹ، دستی اسٹاپ)
violation سینڈ باکس کی کوئی پالیسی توڑی گئی (SandboxViolation ساتھ لاتا ہے)
فیلڈ قسم تفصیل
action String وہ فعل جس سے انکار ہوا (مثلاً file-read*، network-outbound)
target String وہ پاتھ یا ہوسٹ جو انکار شدہ آپریشن کا ہدف تھا
raw String? خام لاگ لائن، ڈی بگنگ کے لیے مفید