نام (NAME)

syd - قالب مستندات برای نگارش پروفایل‌های Syd

رابط برنامه‌نویسی (API)

نسخه فعلی رابط برنامه‌نویسی دستورات Syd برابر با 3 است. این نسخه پایدار (stable) است.

پیکربندی (CONFIGURATION)

ابزار Syd از طریق دستورات جعبه‌شنی پیکربندی می‌شود. در صورت وجود چندین قانون منطبق (برای نمونه دو قانون منطبق بر یک مسیر یکسان)، آخرین قانون منطبق برنده است (اولویت دارد). دو روش برای ارائه دستورات جعبه‌شنی وجود دارد. نخست، Syd می‌تواند با استفاده از یک فایل پیکربندی تنظیم شود. مسیر فایل پیکربندی با استفاده از سوییچ خط فرمان -P مشخص می‌شود. از این طریق می‌توان بیش از یک فایل پیکربندی را مشخص کرد. دستورات منفرد نیز می‌توانند از طریق سوییچ خط فرمان -m ارسال شوند. پروفایل‌های پیکربندی را می‌توان با استفاده از سوییچ خط فرمان -p اعمال نمود. برای اطلاعات بیشتر به بخش «پروفایل‌ها (PROFILES)» مراجعه کنید. دوم، Syd می‌تواند با استفاده از فراخوانی‌های جادویی stat(2) در زمان اجرا پیکربندی شود. این کار با اجرای فراخوانی سیستمی stat(2) روی مسیر ویژه /dev/syd و به دنبال آن دستور جعبه‌شنی انجام می‌گیرد. پیکربندی زمان اجرا تنها در صورتی ممکن است که قفل جعبه‌شنی در وضعیت off (خاموش) باشد. فراخوانی سیستمی stat(2) به این دلیل انتخاب شده است که فراخوانی آن با استفاده از دستورات توکار پوسته عملی است، مانند:

; test -c /dev/syd/sandbox/read:on

که «سندباکس خواندن» (Read Sandboxing) را برای پوسته‌ای که تحت نظارت Syd اجرا می‌شود فعال می‌کند. همچنین می‌توان مقادیر مشخصی را با استفاده از مقدار بازگشتی فراخوانی stat(2) استعلام کرد:

test -c /dev/syd/sandbox/read? && echo read sandboxing on || echo read sandboxing off

برخی از این دستورات توکار پوسته ممکن است در عمل فراخوانی‌های سیستمی دیگری مانند fstat(2)، lstat(2)، newfstatat(2) یا statx(2) را فراخوانی کنند. Syd به‌طور شفاف از همین رابط از طریق تمامی این فراخوانی‌های سیستمی پشتیبانی می‌کند. برای شرح رابط stat(2) به صفحه راهنمای syd(2) مراجعه کنید.

نام‌گذاری (NAMING)

نام‌گذاری فایل‌های پیکربندی Syd از یک الگوی نام‌گذاری پیروی می‌کند که استخراج نسخه رابط برنامه‌نویسی دستور را از نام فایل امکان‌پذیر می‌سازد. یک فایل پیکربندی Syd باید دارای پسوند syd- و به دنبال آن نسخه رابط برنامه‌نویسی باشد (برای مثال "syd-3" برای نسخه رابط برنامه‌نویسی 3).

نحو (SYNTAX)

فایل‌های ورودی باید از کدگذاری UTF-8 استفاده کنند. قالب پیکربندی خط‌محور است. کامنت‌ها با "#" آغاز می‌شوند. کامنت‌های درون‌خطی پشتیبانی نمی‌شوند. خطوط خالی نادیده گرفته می‌شوند. با تمامی خطوط دیگر به‌گونه‌ای رفتار می‌شود که گویی از طریق سوییچ خط فرمان -m به Syd ارسال شده‌اند. برای فهرستی از دستورات جعبه‌شنی در دسترس، به syd(2) مراجعه نمایید. برای دریافت فایل نحو VIM ویژه پروفایل‌های Syd به این نشانی مراجعه کنید: https://gitlab.exherbo.org/sydbox/sydbox/-/tree/main/vim

از نسخه 3.15.1، برنامه Syd دو قابلیت دیگر را به تجزیه فایل پیکربندی اضافه می‌کند:

• گسترش متغیرهای محیطی روی آرگومان‌ها با استفاده از کریت shellexpand انجام می‌شود. متغیرهای محیطی تنظیم‌نشده به رشته‌های خالی گسترش نمی‌یابند. در صورت بروز خطای جستجوی متغیر محیطی و خطاهای رمزگشایی UTF-8، برنامه Syd تجزیه را متوقف کرده و با خطا خارج می‌شود. این کار برای حفظ امنیت انجام می‌گیرد چرا که گسترش ناخواسته به رشته خالی می‌تواند به‌طور بالقوه باعث شود قانون جعبه‌شنیِ حاصل، مسیرهای ناخواسته را بدون اینکه کاربر به‌سادگی متوجه شود در فهرست مجاز قرار دهد. به کاربر توصیه می‌شود مقادیر پیش‌فرضی را برای متغیرهای محیطی با استفاده از نمادگذاری آشنای ${HOME:-/var/empty} تعیین کند. اگر واقعاً خواهان گسترش رشته خالی برای متغیرهای محیطی تعیین‌نشده هستید، می‌توانید با استفاده از نمادگذاری ${HOME:-} به این اثر دست یابید، اما این روش توصیه نمی‌شود و باید با احتیاط استفاده شود.
• دستورالعمل‌های include می‌توانند برای درخواست گنجاندن یک فایل پیکربندی دیگر استفاده شوند. با خواندن خط include، برنامه Syd تجزیه فایل جاری را متوقف کرده، مسیر include ارائه‌شده را اعتبارسنجی می‌کند و تجزیه فایل پیکربندی جدید را آغاز می‌نماید. فایل به دلایل امنیتی نباید توسط گروه یا دیگران قابل نوشتن باشد. برای فایل‌های گنجانده‌شده با مسیرهای نسبی، Syd به منظور امنیت و سهولت در پیکربندی، فایل را به جای دایرکتوری کاری جاری، در زیر دایرکتوریِ فایل پیکربندی قبلی جستجو می‌کند. حلقه‌ها در دستورالعمل‌های include با کش کردن شناسه دستگاه (device id) و اینود (inode) فایل‌های پیکربندی شناسایی می‌شوند. این دستورالعمل هنگام بارگذاری پیکربندی از یک توصیف‌گر فایل با استفاده از دستور load مجاز نیست.

از نسخه 3.17.6، ابزار Syd دستورالعمل include_profile را اضافه می‌کند که می‌تواند برای گنجاندن یک پروفایل Syd به کار رود. برای مشاهده فهرست پروفایل‌ها، به syd-cat -plist مراجعه کنید.

پروفایل‌ها (PROFILES)

ابزار Syd دارای تعدادی پروفایل از پیش‌تعریف‌شده برای آسان‌تر ساختن پیکربندی است. این پروفایل‌ها می‌توانند به‌صورت مستقل یا پشته‌سازی‌شده با دیگر پروفایل‌ها و پیکربندی‌های سفارشی استفاده شوند تا سطوح گوناگونی از ایزولاسیون و محدودسازی ایجاد گردد. برای مشاهده فهرست کامل پروفایل‌ها، از syd-cat -plist استفاده کنید. برای فهرست کردن قوانین یک پروفایل، از syd-cat -p<profile-name> استفاده نمایید. در زیر فهرست کوتاهی از پروفایل‌های متداول و کارکرد آن‌ها آمده است:

امنیت (SECURITY)

از نسخه 3.30.0، اگر مسیر فایل پیکربندی مشخص‌شده در هر یک از اجزای مسیر خود دارای پیوند نمادین (symbolic link) باشد، Syd با خطا متوقف می‌شود. بنابراین، کاربر باید مسیرهای استانداردسازی‌شده (canonicalized) را به عنوان آرگومان‌های فایل پیکربندی ارائه دهد. از نسخه 3.46.0، وجود بخش والد ("..") در مسیر فایل پیکربندی مجاز نبوده و فایل‌های پیکربندی باید فایل‌های عادی (regular files) باشند.

از نسخه 3.56.0، Syd حل مسیر دستورالعمل include را با استفاده از فلگ‌های RESOLVE_IN_ROOT و RESOLVE_NO_XDEV از openat2(2) به دایرکتوری حاوی فایل پیکربندی محدود می‌کند. این بدان معناست که فایل‌های گنجانده‌شده باید در همان دایرکتوری (یا زیرشاخه‌های آن) که فایل پیکربندی اصلی قرار دارد مستقر باشند، و مسیرهای مطلق در دستورالعمل‌های include به جای ریشه واقعی سیستم‌فایل، به عنوان مسیر نسبی نسبت به ریشه آن دایرکتوری تفسیر می‌شوند. پیوندهای نمادین، پیمایش مسیر از طریق ".." و گنجاندن‌های بین‌دستگاهی (cross-device) رد می‌شوند. این تدبیر مقاوم‌سازی از تزریق پیکربندی از دایرکتوری‌های خارج از درخت پیکربندی مورد اعتماد جلوگیری می‌کند.

محیط (ENVIRONMENT)

برنامه Syd متغیرهای محیطی زیر را برای پیکربندی در دسترس قرار می‌دهد:

متغیرهای محیطی با پیشوند SYD_ به فرایند جعبه‌شنی منتقل نمی‌شوند. از دستور setenv! برای ارسال صریح آن‌ها استفاده کنید، برای نمونه: setenv!PWD=$SYD_PWD. برای اطلاعات بیشتر به بخش setenv در صفحه راهنمای syd(2) مراجعه نمایید.

مثال (EXAMPLE)

# پروفایل Syd برای OpenNTPD
# جعبه‌شنی Seccomp
sandbox/read,stat,write,exec,net:on
# قابلیت Landlock
sandbox/lock:on
# ایجاد ایزولاسیون با استفاده از فضاهای نام.
unshare/mount,uts,pid,ipc,cgroup:1
# مجاز ساختن adjtimex و نگه‌داشتن CAP_SYS_TIME.
trace/allow_unsafe_time:1
# متصل کردن همه بخش‌ها به‌صورت ro به جز /var
bind+tmpfs:/dev/shm:nodev,nosuid,noexec
bind+tmpfs:/tmp:nodev,nosuid
bind+/etc:/etc:ro,nodev,noexec,nosuid,noatime
bind+/home:/home:ro,nodev,noexec,nosuid,noatime
bind+/media:/media:ro,nodev,noexec,nosuid,noatime
bind+/mnt:/mnt:ro,nodev,noexec,nosuid,noatime
bind+/opt:/opt:ro,nodev,nosuid,noatime
bind+/srv:/srv:ro,nodev,noexec,nosuid,noatime
bind+/usr:/usr:ro,nodev,noatime
# پنهان‌سازی Syd
deny/read,stat,write+/proc/1/***
# مجاز ساختن شنود روی پورت ntp در لوپ‌بک.
allow/net/bind+loopback!123
# مجاز ساختن اتصالات به سرورهای NTP.
allow/net/connect+any!53
allow/net/connect+any!123
allow/net/connect+any!65535
# مجاز ساختن ثبت وقایع در syslog.
allow/net/connect+/dev/log
# مجاز ساختن «listen wildcard»
allow/net/bind+0.0.0.0!0
allow/net/connect+0.0.0.0!0
# مجاز ساختن شنود روی سوکت ntpd.
allow/net/bind+/run/ntpd.sock
allow/net/bind+/var/run/ntpd.sock
allow/write+/run/ntpd.sock
allow/write+/var/run/ntpd.sock
# مجاز ساختن دسترسی به مسیرهای سیستم
allow/read,stat+/dev/urandom
allow/lock/read+/dev/urandom
allow/read,stat+/etc/hosts
allow/lock/read+/etc/hosts
allow/read,stat+/etc/ntpd.conf
allow/lock/read+/etc/ntpd.conf
allow/read,stat+/etc/passwd
allow/lock/read+/etc/passwd
allow/read,stat+/etc/resolv.conf
allow/lock/read+/etc/resolv.conf
allow/read,stat+/etc/services
allow/lock/read+/etc/services
allow/read,stat+/usr/share/zoneinfo-posix/UTC
# chroot /var/empty && cd /
allow/stat+/
allow/stat+/var/empty
allow/write+/dev/null
allow/lock/write+/dev/null
# مجاز ساختن اجرای باینری ntp.
allow/lock/read+/proc
allow/lock/read+/usr
allow/lock/write+/run
allow/lock/write+/var/run
allow/exec+/usr/**/bin/openntpd*
# مجاز ساختن نوشتن فایل drift.
allow/write+/var/db/ntpd.drift
allow/lock/write+/var/db/ntpd.drift
# قفل کردن پیکربندی
lock:on

همچنین ببینید (SEE ALSO)

syd(1)، syd(2)، syd(7)

صفحه اصلی syd: https://sydbox.exherbo.org

نویسندگان (AUTHORS)

نگهداری‌شده توسط Ali Polatel. سورس‌کدهای به‌روز را می‌توان در https://gitlab.exherbo.org/sydbox/sydbox.git و روی Radicle در rad:z38HCnbmcDegA2BMxuPaPRPMdp6wF یافت. گزارش خطاها و وصله‌ها را می‌توان به https://gitlab.exherbo.org/groups/sydbox/-/issues ارسال نمود. برای بحث و گفتگو به کانال #sydbox در Libera Chat یا به #sydbox:mailstation.de در Matrix بپیوندید.