📘 תיעוד 42

מצב ארגז חול

מצב ארגז חול מגביל את מה שתהליך הסוכן והפקודות שהוא מפעיל יכולים לגשת אליו במערכת הקבצים וברשת שלך, באמצעות מנגנוני ליבה ברמת מערכת ההפעלה (Landlock ב-Linux, Seatbelt ב-macOS). הליבה אוכפת את המגבלות הללו למשך כל זמן הריצה של התהליך.

מצב ארגז חול כבוי כברירת מחדל.

#התחלה מהירה

# הרצה עם ארגז חול של סביבת עבודה (קריאה בכל מקום, כתיבה אל CWD + ספריות זמניות + ~/.grok/)
grok --sandbox workspace

# מצב קריאה בלבד (קריאה בכל מקום, כתיבה רק אל ~/.grok/ + ספריות זמניות)
grok --sandbox read-only

# הפרופיל המגביל ביותר (קריאה מ-CWD + נתיבי מערכת, כתיבה אל CWD + ספריות זמניות + ~/.grok/, ללא רשת לתהליכי צאצא)
grok --sandbox strict

#פרופילים מובנים

¹ חסימת רשת לתהליכי צאצא נאכפת ב-Linux בלבד (באמצעות seccomp). ב-macOS זו פעולה ללא השפעה (no-op), פרופילים אלה אינם מגבילים שם את הרשת של תהליכי צאצא.

כדי לחסום קבצים ספציפיים (לדוגמה .env או נתיבי אישורים) בנוסף לפרופיל, הגדר פרופיל מותאם אישית עם רשימת deny: היא נאכפת ברמת הליבה (קריאה + כתיבה/שינוי שם) ותומכת בתבניות glob כמו **/*.pem.

#פרטי הפרופילים

workspace: הפרופיל המומלץ לפיתוח יומיומי. הסוכן יכול לקרוא כל קובץ במערכת (כדי להבין תלויות, ספריות מערכת וכדומה), אך יכול לכתוב רק לספריית העבודה הנוכחית, ל-~/.grok/, ולספריות זמניות (/tmp, /var/tmp, בנוסף לספריות ה-temp של macOS). גישת רשת מורשית עבור כלים כמו web_search ושרתי MCP.

devbox: פרופיל מובנה שמור עבור מכונות וירטואליות חד-פעמיות לפיתוח. הסוכן יכול לקרוא בכל מקום ולכתוב לכל ספרייה ברמה העליונה מלבד /data ומערכות הקבצים הווירטואליות (/proc, /sys, /dev), כולל ספריית הבית. גישת רשת מורשית. הרצת grok --sandbox devbox מפעילה את הפרופיל המובנה, שדורס כל [profiles.devbox] שמוגדר ב-sandbox.toml.

read-only: השתמש בפרופיל זה כאשר ברצונך שהסוכן ינתח קוד מבלי לשנות את קובצי הפרויקט שלך. הסוכן יכול לקרוא הכל, אך יכול לכתוב רק ל-~/.grok/ (נדרש לשמירת הפעלות) ולספריות זמניות. גישת רשת של תהליכי צאצא חסומה ב-Linux (ללא השפעה ב-macOS).

strict: הפרופיל המגביל ביותר, מיועד לסקירת קוד לא מהימן. הסוכן יכול לקרוא קבצים רק בתוך ספריית העבודה הנוכחית ובנתיבי מערכת חיוניים. כתיבה מוגבלת ל-CWD, ל-~/.grok/, ולספריות זמניות. גישת רשת של תהליכי צאצא חסומה ב-Linux (ללא השפעה ב-macOS).

#הגנת כתיבה ישירה על הוקים גלובליים

תחת workspace, read-only, ו-strict (ופרופילים מותאמים אישית שמרחיבים בסיסים אלה), ספריית המצב של Grok נשארת פתוחה לכתיבה עבור קובצי הפעלה וזמן ריצה, אך הליבה חוסמת כתיבה (write-denies) לנתיבי הדיסק הישירים שבבעלות Grok המשמשים כמקורות הוקים גלובליים של המשתמש (הם נשארים ניתנים לקריאה):

• ~/.grok/hooks/ (ספריית ההוקים)
• ~/.grok/hooks-paths (קובץ רישום, אינו נטען כ-JSON של הוק, רק יעדיו המוחלטים נטענים)
• יעדים מוחלטים הרשומים ב-hooks-paths (שורות יחסיות זוכות להתעלמות, יעדים חסרים גורמים לסירוב להפעלת ארגז החול)

בהפעלה ראשונה תחת פרופילים אלה, Grok יוצר ספריית hooks/ ריקה אמיתית וקובץ hooks-paths ריק כאשר הם חסרים (לעולם לא קישורים סמליים או סוגים שגויים). הגדרות גלובליות של Claude/Cursor אינן מכוסות על ידי חסימת כתיבה זו, גילוי של ספקים אלה נותר מבוקר בנפרד על ידי הגדרות תאימות.

נתיב $GROK_HOME שהוא קישור סמלי, או רשומה ב-hooks-paths הכוללת רכיב של קישור סמלי, נדחים בעת הפעלת ארגז החול (מונע שינוי יעד). ספריות אב קיימות של נתיבים מוגנים מוצמדות כך שלא ניתן לשנות את שמן כדי לחמוק מהחסימה (ספריות אחיות נשארות פתוחות לכתיבה). ב-Linux, מרחבי שמות של משתמשים מקוננים מושבתים בתוך bubblewrap כך שלא ניתן לסדר מחדש חיבורי נקודות עיגון (mount binds). הוקים של פרויקט נותרים מבוקרים על ידי מהימנות התיקייה (folder trust). הפרופיל devbox אינו מחיל הגנה זו (מכונות וירטואליות חד-פעמיות). פרופילים הדורשים זאת מסרבים להתחיל אם לא ניתן להחיל את מדיניות הליבה (כולל Linux ללא נקודות עיגון מאומתות לקריאה בלבד).

#פרופילים מותאמים אישית

צור פרופילי ארגז חול מותאמים אישית ב-~/.grok/sandbox.toml (גלובלי) או ב-.grok/sandbox.toml (ברמת הפרויקט):

[profiles.project]
# התחל מפרופיל מובנה, ולאחר מכן הוסף דריסות
extends = "workspace"
restrict_network = true

# נתיבים שהסוכן יכול לקרוא אך לא לכתוב או למחוק
read_only = ["/data"]

# נתיבים נוספים הניתנים לכתיבה
read_write = ["/tmp/scratch"]

# נתיבים או תבניות glob לחסימה ברמת הליבה (קריאה + כתיבה/שינוי שם, נאכף, ראה הערות להלן)
deny = ["/data/shared-secrets", "**/.env", "**/*.pem"]

השתמש בפרופיל המותאם אישית:

grok --sandbox project

פרופיל מותאם אישית אינו יכול לעשות שימוש חוזר בשם מובנה. הרצת grok --sandbox devbox תמיד מפעילה את הפרופיל המובנה devbox, ודורסת כל [profiles.devbox] שאתה מגדיר.

אם קובץ המשתמש וקובץ הפרויקט מגדירים את אותו פרופיל מותאם אישית באופן שונה, Grok משתמש בפרופיל המשתמש ומציג אזהרה בעת ההפעלה. הרץ /doctor כדי לראות את שני מיקומי הקבצים וכיצד לפתור את ההתנגשות. הגדרות זהות אינן מפיקות אזהרה.

#שדות של פרופיל מותאם אישית

הערה לגבי read_only ו-read_write: אלו הן הרשאות ספריות מפורשות, ולא תבניות glob. סיומת /** (או /*) נחשבת כספריית האב, כך ש-.../cache/** מעניק הרשאה ל-.../cache (ורק /** מעניק הרשאה ל-/). כל רשומה שעדיין מכילה *, ?, או [ לאחר מכן (למשל /home/**/cache, או ספרייה ששמה המפורש הוא dir[1]) נדלגת עם אזהרה: פרט את הספריות הקונקרטיות שאתה צריך, או מקם תבניות glob תחת deny. רשומות עם רווחים מובילים או עוקבים נדלגות גם הן עם אזהרה: רווחים הם בעלי משמעות בנתיבים מפורשים, לכן תקן את הרשומה במקום להסתמך על חיתוך רווחים.

הערה לגבי deny: רשימת deny שאינה ריקה היא נאכפת ברמת הליבה. נתיבים שנחסמו זוכים לחסימת קריאה וחסימת כתיבה/שינוי שם באמצעות Seatbelt ב-macOS ועגינה עליונה של bwrap (bind-over) ב-Linux, כך שלא ניתן לקרוא נתיב חסום (באמצעות bash, grep, או סוכני משנה) ולא ניתן להעביר אותו אל מחוץ לקבוצת החסימה ולקרוא אותו במקום אחר (המעקף של mv secret x && cat x חסום). ב-Linux, חסימת קריאה דורשת את bubblewrap: אם הוא חסר (או שלא ניתן לעגן נתיב חסימה יחיד כלשהו), Grok מסרב לפעול במקום לפעול כאשר נתיבים חסומים חשופים (הפרופיל devbox, שרק חוסם כתיבה ל-/data, עדיין משתמש ב-Landlock כחלופה). כתיבה לנתיבים שאינם ב-deny נשלטת על ידי מה שאתה מעניק ב-read_write.

תבניות glob בתוך deny: רשומה נחשבת תבנית glob אם היא מכילה *, ?, או [. תווים אלה תמיד מציינים glob: כדי לחסום קובץ מפורש ששמו מכיל אותם, ציין במקום זאת ספריית אב. תת-הקבוצה הנתמכת, בסגנון gitignore, היא:

• *: כל רצף תווים בתוך מקטע נתיב יחיד (נעצר ב-/)
• ?: בדיוק תו אחד בתוך מקטע
• **: משתרע על פני ספריות (כמקטע נתיב שלם, למשל **/, a/**), **/ תואם גם לאפס ספריות, כך ש-**/.env תואם ל-.env ול-sub/.env
• [abc] / [a-z]: מחלקות תווים, סימן ! או ^ בהתחלה שולל ([!a] ו-[^a] שניהם פירושם "לא a")

החלפה באמצעות סוגריים מסולסלים ({a,b}), תווי מילוט בלוכסן שמאלי (backslash-escapes), מקטעי נתיב ריקים (לוכסן כפול // או לוכסן בסוף /), מקטעי . או .., וצורות המחלקה החריגות []...] (התו המפורש ] ראשון) ו-POSIX [[:...:]] אינם נתמכים, כך ששתי הפלטפורמות לעולם אינן יכולות לפרש תבנית glob באופן שונה. תבנית glob המשתמשת בתו מיוחד שאינו נתמך, או תבנית בעלת מבנה שגוי, גורמת ל-Grok לסרב להתחיל (נכשל במצב סגור, fail closed) בשתי הפלטפורמות: כתוב *.pem ו-*.key כרשומות נפרדות במקום *.{pem,key}.

תבניות glob יחסיות מעוגנות בסביבת העבודה, תבניות glob מוחלטות (למשל /home/**/.ssh) מעוגנות בקידומת המפורשת שלהן. רשומות שאינן תבניות glob שומרות על התאמת נתיב מדויקת. תבנית glob יחסית תואמת רק בתוך סביבת העבודה. כדי לחסום קבצים במקומות אחרים, כתוב את הרשומה כנתיב מוחלט. פרט לכך, האכיפה נבדלת לפי פלטפורמה:

• macOS הרמטי: כל תבנית glob הופכת לביטוי רגולרי של Seatbelt המוחל בזמן ריצה, כך שקבצים תואמים נחסמים גם אם נוצרו לאחר ש-Grok הופעל.
• Linux בשיטת מרב המאמצים (best-effort): מרחב שמות של נקודות עיגון (mount namespace) אינו יכול לפרוס תבניות glob בזמן ריצה, לכן כל תבנית glob מורחבת לקבצים שקיימים בעת ההפעלה ועליהם מבוצעת עגינה עליונה (bind over). קבצים שנוצרו מאוחר יותר ותואמים לתבנית glob אינם מכוסים: ציין נתיבים מדויקים עבור כל דבר שחייב להיות הרמטי ב-Linux. קישור סמלי תואם מוסווה יחד עם יעד הפתרון שלו. תבנית glob התואמת ליותר מדי קבצים, או שעץ הקבצים שלה עמוק או רחב מכדי לסרוק אותו, גורמת ל-Grok לסרב להתחיל במקום לבצע אכיפה חלקית. הודעת השגיאה מציינת את שמות תבניות ה-glob ואת הספרייה שבה הסריקה נעצרה. סריקת ההפעלה מתחילה בקידומת המפורשת של כל תבנית glob וכוללת קבצים שמופיעים ב-gitignored וקבצים מוסתרים, לכן בסביבות עבודה גדולות מאוד מומלץ להעדיף תבניות glob מעוגנות (certs/**/*.pem סורק רק את certs/) על פני תבניות ** בלבד.

#כיצד זה עובד

ארגז החול מוחל על כל תהליך grok בעת ההפעלה באמצעות מנגנוני ליבה, ולא באמצעות עטיפה לכל פקודה בנפרד. המשמעות היא שכל פעולות הכלים מכוסות:

• read_file, search_replace, list_dir: מוגבלים על ידי Landlock/Seatbelt בתוך התהליך
• פקודות bash, grep (rg): תהליכי צאצא יורשים הגבלות מערכת קבצים באופן אוטומטי
• רשת: ב-Linux, ניתן לחסום תהליכי צאצא באמצעות seccomp, ב-macOS זו פעולה ללא השפעה

כאשר מתבצעת בקשה לפרופיל ארגז חול שאינו off (בשורת הפקודה, ב-GROK_SANDBOX, בהגדרות התצורה, או כדרישה מנוהלת):

• הסוכן פועל בתוך התהליך (in-process), ולא דרך המנהל המשותף (shared leader), כך שקריאות לכלים נשארות בתהליך זה כאשר הפרופיל נאכף. אם מצב מנהל (leader mode) אמור היה לפעול אלמלא כן, הערה של שורה אחת בעת ההפעלה מציינת זאת
• אם החלת פרופיל מובנה נכשלת, Grok מתריע וממשיך ללא אכיפה (ראה תמיכה בפלטפורמות), אך עדיין דוחה את המנהל כך שכלים אינם מואצלים למקום אחר
• הפקודות grok workspace start, restart, ו-resume אינן זמינות, pause, stop, ו-status עדיין פועלות

השבת את הפרופיל במקור שבחר בו כדי להשתמש בפקודות שנדחו.

ארגז החול הוא בלתי הפיך מרגע שהוחל. הסוכן אינו יכול להקל בהגבלות בזמן ריצה.

#חידוש הפעלות

הפרופיל שאיתו התחילה הפעלה נשמר יחד עם ההפעלה והוא קבוע למשך כל חיי ההפעלה. כאשר אתה מחדש אותה (grok --resume <id>, grok --continue, או grok -r), Grok משחזר את אותו פרופיל באופן אוטומטי, כך שהפעלה שהחלה עם --sandbox workspace לא תחזור באופן שקט תחת ברירת מחדל מחמירה יותר ותשבור פקודות שפעלו בעבר.

חידוש הפעלה לא ישנה את ארגז החול של ההפעלה:

• השמטת --sandbox בעת חידוש משתמשת בפרופיל השמור של ההפעלה.
• העברת --sandbox <profile> שתואם לפרופיל השמור מורשית.
• העברת --sandbox <profile> ששונה מהפרופיל השמור נדחית עם שגיאה: שינוי ארגז החול של הפעלה מחודשת הוא סיכון בטיחותי (הוא עלול להרחיב גישה שההפעלה נועדה להיות מוגבלת ממנה, או לשבור הפעלה שהסתמכה על גישה רחבה יותר). התחל הפעלה חדשה כדי להשתמש בפרופיל שונה.

סדר קביעת הפרופיל עבור הפעלה חדשה:

1. דגל מפורש --sandbox <profile> או משתנה הסביבה GROK_SANDBOX
2. ההגדרה [sandbox] profile בקובץ התצורה שלך
3. off (ללא ארגז חול)

#תמיכה בפלטפורמות

אם לא ניתן להחיל את ארגז החול (למשל, ליבה שאינה נתמכת, הרשאות חסרות), Grok רושם אזהרה ביומן וממשיך ללא אכיפה. החריג לכך הוא פרופיל מותאם אישית שהתבקש במפורש: ב-macOS וב-Linux כאחד, אם לא ניתן להחיל אותו (פרופיל לא מוכר, מבנה שגוי של sandbox.toml, או, ב-Linux, חוסר זמינות של bubblewrap עבור רשימת deny שאינה ריקה), Grok מסרב לפעול במקום לפעול כאשר הנתיבים החסומים שלו חשופים.

#הגבלות רשת

ב-Linux, פרופילים עם restrict_network חוסמים גישת רשת בתהליכי צאצא (פקודות bash, סקריפטים) באמצעות seccomp. ב-macOS, חסימת רשת היא ללא השפעה. כלים מובנים המבצעים בקשות HTTP בתוך התהליך (חיפוש באינטרנט, קריאות ל-API של מודל השפה) אינם מושפעים לעולם, הסוכן זקוק לגישת רשת כדי לתפקד.

בפועל, ב-Linux המשמעות היא:

• ל-web_search, web_fetch, ול-API של מודל השפה יש תמיד גישת רשת
• פקודות bash כמו curl, wget, ו-npm install נחסמות כאשר restrict_network מופעל

#מדיניות סביבת המעטפת

ארגז החול שולט באילו קבצים ורשת תהליך צאצא יכול לגשת אליהם. הטבלה ברמה העליונה [shell_environment_policy] שולטת באילו משתני סביבה הוא יורש, כך שפקודת כלי שהמודל מריץ לא תוכל לקרוא סוד שבמקרה נמצא בסביבת המעטפת שלך.

[shell_environment_policy]
inherit = "core"                 
# all (ברירת מחדל) | core | none
ignore_default_excludes = false  
# להשמיט גם *KEY* / *SECRET* / *TOKEN*
exclude = ["ACME_*", "CI_*"]     
# להשמיט שמות אלה
include_only = ["PATH", "HOME"]  
# אם מוגדר, לשמור רק שמות אלה
set = { MY_FLAG = "1" }          
# לכפות ערכים אלה

Grok בונה את סביבת הצאצא לפי הסדר: הוא מתחיל מ-inherit (all שומר הכל, core שומר קבוצה מצומצמת של הפלטפורמה כגון PATH ו-HOME, none מתחיל ריק); משמיט את תבניות הסודות המובנות *KEY*, *SECRET*, ו-*TOKEN* אלא אם כן ignore_default_excludes = true; משמיט כל התאמה ל-exclude; מחיל את set; וכאשר include_only אינו ריק, שומר רק את השמות התואמים. תבניות הן תבניות glob שאינן רגישות לאותיות גדולות או קטנות (*, ?).

ברירת המחדל (inherit = "all", ignore_default_excludes = true) משאירה את הסביבה ללא שינוי, כך ששום דבר אינו משתנה עד שתגדיר מדיניות. בצד השרת הלא קבוע (non-persistent backend), המדיניות מסננת גם משתנים שנלכדו ממעטפת ההתחברות שלך, כך שייצוא מקובץ .rc אינו יכול להגניב סוד מעבר ל-exclude או include_only. המעטפת הקבועה (persistent shell) היא חריג אחד: היא מחילה את המדיניות על סביבת הבסיס שלה, אך משתנים שקובץ .rc מייצא במהלך ההתחברות מושמעים מחדש מתוך תמונת מצב (snapshot) ואינם מסוננים שוב, לכן הרחק סודות מקובצי הפעלת המעטפת שם. האכיפה מכסה את הכלי bash ומסופים ב-macOS, Linux, ו-Windows.

#רישום אירועים

אירועי ארגז החול נרשמים אל ~/.grok/sandbox-events.jsonl לצורכי ניפוי שגיאות. האירועים כוללים:

• פרופיל שהוחל (איזה פרופיל, חותמת זמן)
• הפרות (ניסיונות גישה לנתיבים חסומים)

#מתי להשתמש במצב ארגז חול

השתמש ב-workspace כאשר:

• אתה עובד על הפרויקטים שלך ורוצה הגנת כתיבה בסיסית
• אתה מריץ בסביבות משותפות שבהן ברצונך להגביל את היקף השינויים

הגדר פרופיל מותאם אישית עם רשימת deny כאשר:

• עליך לחסום קבצים ספציפיים (לדוגמה .env או נתיבי אישורים) בנוסף לפרופיל בסיס
• דרושה לך אכיפת ליבה המכסה את bash, grep, וסוכני משנה, ולא רק את הכלי read_file

השתמש ב-read-only כאשר:

• אתה סוקר קוד שאינך בוטח בו
• אתה חוקר בסיס קוד ללא סיכון לשינוי מקרי
• אתה מריץ ניתוח קוד או ביקורות

השתמש ב-strict כאשר:

• אתה מנתח קוד לא מהימן או קוד צד שלישי
• אתה מריץ בסביבות רגישות מבחינה אבטחתית
• אתה מעוניין בבידוד מרבי

דלג על ארגז חול כאשר:

• הסוכן צריך להתקין תלויות (npm install, pip install)
• הסוכן צריך לשנות קבצים מחוץ לספריית העבודה
• אתה עובד בסביבה מהימנה ומעוניין בגמישות מרבית

#פשרות

ארגז החול אוכף מגבלות ברמת מערכת ההפעלה: באמצעות Landlock או מרחב שמות של נקודות עיגון (mount namespace) ב-Linux, ו-Seatbelt ב-macOS, ולא באמצעות מכונה וירטואלית נפרדת.