راه‌اندازی Xeniguard و سخت‌سازی سرورهای لینوکسSetting up Xeniguard and hardening Linux servers

مفاهیم اصلیCore concepts#

انتخاب روش استقرارChoosing a deployment#

پیش‌نیازهاRequirements#

سرور مدیریت (محل اجرای پنل)Management server (where the panel runs)

• یک سرور لینوکس با Docker Engine و افزونه Docker Compose نسخه ۲.
• git برای دریافت کد.
• دسترسی شبکه‌ای SSH به سرورهای هدف.

• A Linux server with Docker Engine and the Docker Compose v2 plugin.
• git to fetch the code.
• SSH reachability to the target hosts.

هر سرور هدفEach target host

• توزیعی از خانواده Debian (مثل Debian و Ubuntu) یا خانواده RHEL (مثل RHEL، Rocky Linux و AlmaLinux).
• سرویس SSH در دسترس از سرور مدیریت.
• یک کاربر SSH که root باشد یا sudo بدون رمز داشته باشد.
• systemd؛ بدون آن، تغییراتی که ریسک قفل‌شدن دارند اعمال نمی‌شوند.
• یک راه دسترسی جایگزین (کنسول مجازی یا خارج از شبکه) و یک پشتیبان تازه، پیش از اولین اعمال.

• A Debian-family (e.g. Debian, Ubuntu) or RHEL-family (e.g. RHEL, Rocky Linux, AlmaLinux) distribution.
• SSH reachable from the management server.
• An SSH user that is root or has passwordless sudo.
• systemd; without it, lockout-risk changes will not be applied.
• A fallback access path (virtual console or out-of-band) and a fresh backup before the first apply.

01نصب Docker روی سرور مدیریتInstall Docker on the management server# انجام شدDone

اگر Docker از قبل نصب است، فقط نسخه‌ها را با دو دستور آخر بررسی کنید.

If Docker is already installed, just check the versions with the last two commands.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

docker --version
docker compose version

اگر get.docker.com در دسترس نیست، روی Ubuntu از بسته‌های توزیع استفاده کنید. برای توزیع‌های دیگر راهنمای رسمی Docker را دنبال کنید.

If get.docker.com is unreachable, on Ubuntu use the distribution packages. For other distributions follow Docker's official guide.

sudo apt update
sudo apt install -y docker.io docker-compose-v2 git
sudo systemctl enable --now docker

{
  "registry-mirrors": ["https://<your-mirror-address>"]
}

02دریافت کدGet the code# انجام شدDone

git clone https://github.com/xenitech/xeniguard.git xeniguard
cd xeniguard

به‌جای https://github.com/xenitech/xeniguard.git نشانی مخزن رسمی Xeniguard را بگذارید. پیش از بازتوزیع هر بخش از کد، فایل NOTICE.md را بخوانید؛ مجوز اجزا متفاوت است.

Replace https://github.com/xenitech/xeniguard.git with the official Xeniguard repository address. Read NOTICE.md before redistributing any part; components are licensed differently.

03ساخت و اجراBuild and run# انجام شدDone

از ریشه مخزن اجرا کنید. Dockerfile ابتدا پنل وب را می‌سازد، آن را داخل باینری Go جاسازی می‌کند و نتیجه را در یک ایمیج debian:12-slim با کاربر غیر root قرار می‌دهد.

Run from the repository root. The Dockerfile builds the web panel, embeds it in the Go server binary and ships it in a debian:12-slim image running as a non-root user.

docker compose up -d --build
docker compose ps

Compose کانتینر را با فایل‌سیستم ریشه فقط‌خواندنی، حذف همه capabilityهای لینوکس و no-new-privileges اجرا می‌کند. اگر Compose نمی‌خواهید، معادل ساده آن این است (بدون آن محدودیت‌های اضافه):

Compose runs the container with a read-only root filesystem, all Linux capabilities dropped and no-new-privileges. Without Compose, the plain equivalent is below (without those extra restrictions):

docker build -t xeniguard .
docker run -p 8091:8091 xeniguard

04بررسی سلامتHealth check# انجام شدDone

curl http://127.0.0.1:8091/healthz

اگر پاسخ سالم گرفتید، پنل روی https://127.0.0.1:8091/ در دسترس است.

If the health check succeeds, the panel is available at https://127.0.0.1:8091/.

05دسترسی امن به پنلReaching the panel safely# انجام شدDone

پنل کلیدهای دسترسی به همه سرورهای شما را در اختیار دارد. پورت 8091 را روی اینترنت باز نکنید. ساده‌ترین روش امن برای باز کردن پنل از لپ‌تاپ خودتان، تونل SSH است:

The panel holds the keys to every server you manage. Do not expose port 8091 to the internet. The simplest safe way to open the panel from your own laptop is an SSH tunnel:

ssh -N -L 8091:127.0.0.1:8091 <user>@<management-server>

سپس در مرورگر لپ‌تاپ خودتان https://127.0.0.1:8091/ را باز کنید.

Then open https://127.0.0.1:8091/ in your laptop's browser.

06آماده‌سازی سرور هدفPrepare a target host# انجام شدDone

روی هر سرور هدف یک کاربر اختصاصی برای Xeniguard بسازید که فقط با کلید وارد شود و sudo بدون رمز داشته باشد. Xeniguard با sudo -n کار می‌کند و هرگز رمز نمی‌پرسد. دستورهای زیر روی هر دو خانواده Debian و RHEL کار می‌کنند:

On each target, create a dedicated user for Xeniguard that logs in with a key only and has passwordless sudo. Xeniguard uses sudo -n and never prompts for a password. These commands work on both Debian and RHEL families:

sudo useradd -m -s /bin/bash xeniguard
sudo install -d -m 700 -o xeniguard -g xeniguard /home/xeniguard/.ssh

# paste the public key the panel gives you for this host
echo '<PUBLIC_KEY_FROM_PANEL>' | sudo tee /home/xeniguard/.ssh/authorized_keys
sudo chown xeniguard:xeniguard /home/xeniguard/.ssh/authorized_keys
sudo chmod 600 /home/xeniguard/.ssh/authorized_keys

# passwordless sudo, validated before it takes effect
echo 'xeniguard ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/xeniguard
sudo chmod 440 /etc/sudoers.d/xeniguard
sudo visudo -cf /etc/sudoers.d/xeniguard

برای محدود کردن کلید به سرور مدیریت، ابتدای همان خط در authorized_keys گزینه from را اضافه کنید:

To restrict the key to your management server, prefix that line in authorized_keys with a from option:

from="<MANAGEMENT_SERVER_IP>" ssh-ed25519 AAAA... xeniguard

اثر انگشت کلید میزبان را برای گام بعد یادداشت کنید:

Note the host-key fingerprint for the next step:

for f in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf "$f"; done
systemctl --version | head -n1   # confirms systemd is present

07ثبت میزبان و پین کلیدRegister and pin the host# انجام شدDone

1. در پنل به صفحه Hosts بروید و میزبان جدید را با نشانی و کاربر SSH ثبت کنید.
2. کلیدهای SSH را مبادله کنید و کلید عمومی را مطابق گام قبل روی سرور هدف قرار دهید.
3. پنل اثر انگشت کلید میزبان را نشان می‌دهد. آن را با خروجی ssh-keygen -lf که روی خود سرور گرفتید مقایسه کنید و فقط در صورت تطابق تأیید کنید.
4. از این لحظه کلید پین شده است. هر اتصالی با کلید متفاوت، بدون استثنا رد می‌شود.

1. In the panel, open Hosts and register the new host with its address and SSH user.
2. Exchange SSH keys and install the public key on the target as in the previous step.
3. The panel shows the host-key fingerprint. Compare it with the ssh-keygen -lf output you took on the host itself and confirm only if they match.
4. From now on the key is pinned. Any connection presenting a different key is refused outright.

بررسی، برنامه، اعمال، بازگردانیCheck, Plan, Apply, Rollback#

هر چهار عمل را از صفحه میزبان در پنل اجرا می‌کنید. ترتیب پیشنهادی همیشه همین است:

You run all four from the host's page in the panel. The recommended order is always:

1. Check: وضعیت فعلی و امتیاز را ببینید. هیچ چیزی تغییر نمی‌کند.
2. Plan: فهرست تغییرات را مرور کنید، به‌خصوص مواردی که ریسک قفل‌شدن دارند.
3. Apply: برنامه را اعمال کنید. یک نشست SSH یا کنسول جداگانه باز نگه دارید.
4. Check دوباره: امتیاز جدید را ببینید و مطمئن شوید سرویس‌ها سالم‌اند. اگر مشکلی بود، Rollback.

1. Check: see the current state and score. Nothing changes.
2. Plan: review the change list, especially lockout-risk items.
3. Apply: execute the plan. Keep a separate SSH session or console open.
4. Check again: confirm the new score and that services are healthy. If something is wrong, Rollback.

پشت صحنه در حالت SSHWhat happens in SSH mode

• اتصال SSH برقرار می‌شود و هر کلیدی جز کلید پین‌شده رد می‌شود.
• یک نسخه تازه از موتور و کاتالوگ در پوشه‌ای که با mktemp -d ساخته شده بارگذاری می‌شود.
• موتور با sudo -n به‌عنوان root اجرا و نتیجه به‌صورت زنده به پنل فرستاده می‌شود.
• نسخه بارگذاری‌شده پس از پایان کار پاک می‌شود.

• An SSH connection is made, refusing anything but the pinned host key.
• A fresh copy of the engine and catalog is uploaded into a mktemp -d directory.
• The engine runs as root via sudo -n and results stream back to the panel.
• The uploaded copy is removed when the run finishes.

محافظ قفل‌شدنThe lockout guard#

بعضی کنترل‌ها، مثل تغییر تنظیمات SSH یا سیاست فایروال، اگر اشتباه پیش بروند می‌توانند دسترسی شما به سرور را قطع کنند. Xeniguard این تغییرات را در برنامه به‌عنوان «ریسک قفل‌شدن» علامت می‌زند و فقط وقتی اعمالشان می‌کند که بتواند روی سرور هدف یک محافظ از طریق systemd فعال کند.

Some controls, such as SSH settings or firewall policy, can cut off your access if something goes wrong. Xeniguard marks these as lockout-risk in the plan and applies them only when it can arm a guard through systemd on the target.

محافظ جایگزین احتیاط شما نیست: پیش از اعمال، یک راه دسترسی جایگزین داشته باشید.

The guard does not replace your own caution: have a fallback access path before you apply.

کاتالوگ و امتیاز سخت‌سازیCatalog and Hardening Score#

صفحه Catalog در پنل همه کنترل‌ها و جدول وزن هر کدام در امتیاز را نشان می‌دهد. خواندن کاتالوگ به هیچ دسترسی ممتازی نیاز ندارد. روش محاسبه و وزن‌دهی امتیاز در docs/scoring.md مستند شده است.

The panel's Catalog page lists every control and its weight in the score. Reading the catalog needs no privilege. How the score is computed and weighted is documented in docs/scoring.md.

سقف به محتوای کاتالوگ بستگی دارد، نه به موتور. امتیاز ۷۰ در نسخه Community یعنی همه کنترل‌های موجود در آن نسخه اعمال شده‌اند.

The ceiling depends on catalog content, not on the engine. A score of 70 in Community means every control available in that edition is applied.

حالت محلیLocal mode#

برای سخت کردن خود ماشینی که پنل رویش اجرا می‌شود، این اجزا باید مستقیماً و بدون کانتینر روی همان ماشین اجرا شوند: server، کمک‌کننده ممتاز cmd/helper، engine/ و catalog/، به‌صورت سرویس‌های systemd.

To harden the machine the panel runs on, run these directly on that machine as systemd services, with no container: server, the privileged helper cmd/helper, engine/ and catalog/.

کمک‌کننده به root واقعی روی فایل‌سیستم واقعی نیاز دارد، و مرز فضای نام کانتینر دقیقاً برای جلوگیری از همین دسترسی است. به همین دلیل این حالت در بسته Docker پشتیبانی نمی‌شود.

The helper needs real root on the real filesystem, which a container's namespace boundary exists specifically to prevent. That is why this mode is not supported in the Docker packaging.

امنیت سرور مدیریتSecuring the control plane#

سرور مدیریت می‌تواند با root به همه سرورهای ثبت‌شده وصل شود. آن را حساس‌ترین ماشین مجموعه بدانید:

The management server can reach every registered host as root. Treat it as the most sensitive machine you own:

• پنل را فقط از طریق تونل SSH یا شبکه مدیریتی در دسترس بگذارید.
• ورود SSH به خود سرور مدیریت را فقط با کلید و برای افراد محدود مجاز کنید.
• کانتینر را با docker compose اجرا کنید تا محدودیت‌های فایل‌سیستم فقط‌خواندنی و capabilityها اعمال شوند.
• سیستم‌عامل و Docker را به‌روز نگه دارید؛ خود این سرور را هم می‌توانید با Xeniguard در حالت SSH از یک ماشین دیگر سخت کنید.

• Expose the panel only through an SSH tunnel or the management network.
• Allow key-only SSH to the management server itself, for a small set of people.
• Run the container with docker compose so the read-only filesystem and capability restrictions apply.
• Keep the OS and Docker updated; you can also harden this server with Xeniguard in SSH mode from another machine.

تحلیل تهدید کامل پروژه در docs/threat-model.md آمده است.

The project's full threat analysis is in docs/threat-model.md.

به‌روزرسانیUpgrading#

cd xeniguard
git pull
docker compose up -d --build
curl http://127.0.0.1:8091/healthz

چون در حالت SSH هر اجرا یک نسخه تازه از موتور و کاتالوگ را روی هدف بارگذاری می‌کند، با به‌روزرسانی پنل، سرورهای هدف هم از اجرای بعدی نسخه جدید را می‌گیرند. پیش از به‌روزرسانی یادداشت‌های انتشار را بخوانید.

Because every SSH-mode run uploads a fresh copy of the engine and catalog, target hosts pick up the new version on their next run once the panel is upgraded. Read the release notes before upgrading.

رفع اشکالTroubleshooting#

docker compose ps
docker compose logs --tail=200

sudo -u xeniguard sudo -n true && echo ok

sudo ss -tulpn | grep 8091

ساختار مخزن و CIRepository and CI#

هر جزء ابزار ساخت خودش را دارد و راهنمای آن در README.md همان پوشه است. در هر push این بررسی‌ها اجرا می‌شوند:

Each component has its own toolchain, documented in that folder's README.md. Every push runs:

اسناد کلیدی برای مشارکت: docs/threat-model.md (تحلیل STRIDE)، docs/scoring.md (امتیازدهی) و docs/assumptions.md (فرض‌هایی که هر جا مشخصات ساکت بوده ثبت شده‌اند).

Key documents for contributors: docs/threat-model.md (STRIDE analysis), docs/scoring.md (scoring) and docs/assumptions.md (every assumption made where the spec was silent).

وضعیت، محدودیت‌ها و مجوزStatus, limitations and licensing#

• Xeniguard در مرحله پایه‌گذاری (Phase 0) است و در حال توسعه فعال.
• بسته Docker فقط پنل مدیریت و سخت‌سازی از راه SSH را پوشش می‌دهد و حالت محلی را اجرا نمی‌کند.
• ایجنت و اتصال به اسکنرها (از جمله Xenitex) مربوط به نسخه Enterprise هستند و در این مخزن فقط رابط‌هایشان وجود دارد.

• Xeniguard is in Phase 0 (Foundations) and under active development.
• The Docker packaging covers the control plane and SSH-mode hardening only; it does not run local mode.
• The agent and scanner integrations (including Xenitex) belong to Enterprise; only their interfaces exist in this repository.

پیش از بازتوزیع، NOTICE.md را بخوانید.

Read NOTICE.md before redistributing.