דוגמאות

סקירה כללית

הכנו כמה דוגמאות כדי להראות איך להשתמש ב-Sandbox2 בתרחישים שונים ואיך לכתוב מדיניות.

אפשר למצוא אותן בכתובת //sandboxed_api/sandbox2/examples. בהמשך מופיעים הסברים מפורטים.

CRC4

הדוגמה של CRC4 היא חישוב של סכום ביקורת CRC4 עם באגים מכוונים, שממחיש איך להריץ תוכנית אחרת בסביבת ארגז חול ואיך לתקשר איתה.

• ‫crc4bin.cc: התוכנית שאנחנו רוצים להריץ בארגז חול (כלומר, Sandboxee)
• ‫crc4sandbox.cc: תוכנית ארגז החול שתפעיל אותו (כלומר, המבצע).

איך זה עובד:

1. ה-executor מפעיל את Sandboxee מנתיב הקובץ שלו באמצעות ::sandbox2::GetDataDependencyFilePath().
2. ה-executor שולח קלט ל-Sandboxee דרך ערוץ התקשורת Comms באמצעות SendBytes().
3. ה-Sandboxee מחשב את ה-CRC4 ושולח את התשובות שלו בחזרה ל-Executor דרך ערוץ התקשורת Comms, שמקבל אותן עם RecvUint32().

אם התוכנית מבצעת קריאת מערכת (syscall) כלשהי מלבד תקשורת (read() ו-write()), היא מופסקת בגלל הפרת מדיניות.

סטטי

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

• ‫static_bin.cc: Sandboxee הוא קובץ בינארי סטטי של C שממיר טקסט ASCII מקלט רגיל לאותיות רישיות.
• ‫static_sandbox.cc: קובץ ההפעלה עם המדיניות, המגבלות והשימוש בתיאור קובץ לקלט של Sandboxee.

איך זה עובד:

1. הקובץ המפעיל מתחיל את Sandboxee מנתיב הקובץ שלו באמצעות GetDataDependencyFilepath, בדיוק כמו ב-CRC4.
2. הוא מגדיר מגבלות, פותח מתאר קובץ ב-/proc/version ומסמן אותו למיפוי ב-Sandboxee באמצעות MapFd.
3. המדיניות מאפשרת לחלק מקריאות המערכת (open) להחזיר שגיאה (ENOENT) במקום להפסיק את הפעולה שלהן בגלל הפרת מדיניות. זה יכול להיות שימושי כשמריצים תוכנית של צד שלישי בסביבת ארגז חול, שבה אי אפשר לשנות את קריאות המערכת שמתבצעות, ולכן אפשר לגרום להן להיכשל בצורה מסודרת.

כלי

הדוגמה לכלי היא גם כלי לפיתוח מדיניות משלכם ולניסוי ממשקי API של Sandbox2, וגם הדגמה של התכונות שלו.

• ‫sandbox2tool.cc: קובץ ההפעלה שמדגים:
  • איך להריץ עוד קובץ בינארי בארגז חול,
  • איך מגדירים בדיקות של מערכת הקבצים, וגם
  • איך הרצת Sandboxee יכולה להתבצע באופן אסינכרוני כדי לקרוא את הפלט שלה בהדרגה.

רוצים לנסות בעצמכם?

Bazel

bazel run //sandboxed_api/sandbox2/examples/tool:sandbox2tool -- \
--sandbox2tool_resolve_and_add_libraries \
--sandbox2tool_additional_bind_mounts /etc \
/bin/cat /etc/hostname

‫CMake + Ninja

cd build-dir
ninja sandbox2_sandbox2tool && \
./sandbox2_sandbox2tool \
--sandbox2tool_resolve_and_add_libraries \
--sandbox2tool_additional_bind_mounts /etc \
/bin/cat /etc/hostname

‫Google3 (Blaze)

blaze run //third_party/sandboxed_api/sandbox2/examples/tool:sandbox2tool -- \
 --sandbox2tool_resolve_and_add_libraries \
 --sandbox2tool_additional_bind_mounts /etc \
 /bin/cat /etc/hostname

סימונים:

• ‫--sandbox2tool_resolve_and_add_libraries כדי לפתור את הבעיה ולהפעיל את הספריות הנדרשות עבור Sandboxee
• ‫--sandbox2tool_additional_bind_mounts <PATHS> כדי להפוך ספריות נוספות לזמינות ל-Sandboxee
• ‫--sandbox2tool_keep_env כדי לשמור את משתני הסביבה הנוכחיים
• ‫--sandbox2tool_redirect_fd1 כדי לקבל את Sandboxee STDOUT_FILENO (1) ולהוציא אותו באופן מקומי
• ‫--sandbox2tool_cpu_timeout כדי להגדיר את הזמן הקצוב לשימוש במעבד בשניות
• ‫--sandbox2tool_walltime_timeout כדי להגדיר את הזמן הקצוב לתפוגה של זמן שעון הקיר בשניות
• --sandbox2tool_file_size_creation_limit כדי להגדיר את הגודל המקסימלי של הקבצים שנוצרו
• ‫--sandbox2tool_cwd כדי להגדיר את ספריית העבודה הנוכחית של ארגז החול

custom_fork

בדוגמה custom_fork אפשר לראות איך ליצור ארגז חול שיפעיל את הקובץ הבינארי, ואז יחכה לבקשות fork() שמגיעות מהמבצע הראשי.

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

• ‫custom_fork_bin.cc: שרת הפיצול המותאם אישית, שמקבל בקשות אל fork() (דרך ForkingClient::EnterForkLoop) כדי ליצור Sandboxee חדשים.
• ‫custom_fork_sandbox.cc: קובץ ההפעלה, שמפעיל שרת מותאם אישית של fork. לאחר מכן, הוא שולח אליו בקשות (דרך מנהלי ביצוע חדשים) ליצירת (דרך fork()) Sandboxee חדשים.

רשת

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

החיבור מאותחל בתוך רכיב ההפעלה, והשקע שנוצר מועבר דרך ::sandbox2::Comms::SendFD(). ה-Sandboxee מקבל את השקע באמצעות ::sandbox2::Comms::RecvFD() ואז הוא יכול להשתמש בשקע הזה כדי להחליף את הנתונים כרגיל.

• ‫network_bin.cc: התוכנית שאנחנו רוצים להריץ בארגז חול (כלומר, Sandboxee).
• ‫network_sandbox.cc: תוכנית ארגז החול שתפעיל אותו (כלומר, תוכנית ההפעלה).

network_proxy

בדוגמה הזו מוצגת דרך חלופית להתמודדות עם מרחב שמות ברשת. היא פועלת באופן פנימי בדיוק כמו בדוגמה שלמעלה, אבל היא מוצגת כ-API נוח יותר.

ה-Sandboxee יכול ליצור חיבור לרשת ב-2 דרכים שונות:

• אוטומטי – על ידי התקנת handler אוטומטי ואז שליחת שיחות חיבור רגילות.
• ידני – באמצעות קבלת NetworkProxyClient ושימוש ישיר ב-NetworkProxyClient::Connect.

בדוגמה הזו מוצגות שתי השיטות. המצב האוטומטי מופעל כשמגדירים את הדגל connect_with_handler, אחרת מופעל המצב הידני.

• ‫network_bin.cc: התוכנית שאנחנו רוצים להריץ בארגז חול (כלומר, Sandboxee).
• ‫network_sandbox.cc: תוכנית ארגז החול שתפעיל אותו (הקובץ להרצה).