דוגמאות

סקירה כללית

הכנו כמה דוגמאות כדי להראות איך להשתמש ב-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 ושולח את התשובות שלו בחזרה למבצע דרך ערוץ התקשורת 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. המדיניות מאפשרת לחלק מה-syscalls ‏ (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() (דרך Client::WaitAndFork) כדי ליצור Sandboxee חדשים.
  • ‫custom_fork_sandbox.cc: קובץ ההפעלה, שמתחיל שרת מותאם אישית של fork. לאחר מכן, הוא שולח אליו בקשות (דרך מנהלי ביצוע חדשים) ליצירה (דרך fork()) של Sandboxees חדשים.

רשת

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

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

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

network_proxy

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

יש שתי דרכים שבהן Sandboxee יכול ליצור חיבור לרשת:

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

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

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