نصب و راه‌اندازی Xenitex روی سرور لینوکسInstalling and running Xenitex on a Linux server

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

• یک سرور لینوکس ۶۴ بیتی (مجازی یا فیزیکی) که به شبکه‌هایی که می‌خواهید اسکن کنید دسترسی داشته باشد.
• دسترسی sudo روی سرور.
• Docker Engine و افزونه Docker Compose نسخه ۲ (دستور docker compose، نه docker-compose).
• git و openssl.
• مجوز کتبی برای اسکن محدوده‌هایی که تعریف می‌کنید. ویزارد راه‌اندازی این تعهد را از شما ثبت می‌کند.
• اختیاری: دسترسی خروجی به NVD و FIRST EPSS، اگر می‌خواهید داده آسیب‌پذیری را از اینترنت به‌روز کنید.

• A 64-bit Linux server (virtual or physical) with network reachability to the ranges you want to scan.
• sudo access on that server.
• Docker Engine and the Docker Compose v2 plugin (the docker compose command, not docker-compose).
• git and openssl.
• Written authorisation to scan the ranges you define. The setup wizard records this attestation.
• Optional: outbound access to NVD and FIRST EPSS if you want to update vulnerability data from the internet.

01نصب DockerInstall Docker# انجام شدDone

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

If Docker is already installed, just check the versions with the last command in this section. On Ubuntu and Debian the simplest route is Docker's official convenience script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# run docker without sudo (log out and back in afterwards)
sudo usermod -aG docker $USER
newgrp docker

# both commands must succeed
docker --version
docker compose version

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

If get.docker.com is not reachable, on Ubuntu you can use the distribution's own packages. For other distributions, follow Docker's official installation guide.

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

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

sudo systemctl restart docker

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

مخزن را کلون کنید و وارد پوشه استقرار مرجع شوید. همه دستورهای بعدی از همین پوشه اجرا می‌شوند.

Clone the repository and change into the reference deployment folder. Every following command runs from there.

git clone https://github.com/xenitech/xenitex-scanner.git xenitex
cd xenitex/deploy/compose

به‌جای <REPOSITORY_URL> نشانی مخزن رسمی Xenitex را قرار دهید.

Replace <REPOSITORY_URL> with the address of the official Xenitex repository.

03پیکربندی .envConfigure .env# انجام شدDone

از فایل نمونه یک کپی بسازید و دسترسی آن را فقط به خودتان محدود کنید. سپس فایل را باز کنید و هر مقدار را مرور کنید؛ توضیح هر متغیر در خود فایل نمونه آمده است.

Create a copy of the example file and restrict it to your own user. Then open it and review each value; every variable is described in the example file itself.

cp .env.example .env
chmod 600 .env
nano .env

04ساخت SecretهاCreate secrets# انجام شدDone

نام کاربری و رمز پایگاه داده به‌صورت Docker Secret و از فایل خوانده می‌شوند. برخلاف .env، این فایل‌ها باید پیش از اجرای Compose وجود داشته باشند. رمز را به‌صورت تصادفی بسازید:

The database user and password are provided as file-based Docker secrets. Unlike .env, these files must exist before you run Compose. Generate the password randomly:

mkdir -p secrets
printf '%s' 'xenitex' > secrets/postgres_user.txt
openssl rand -base64 24 > secrets/postgres_password.txt
chmod 644 secrets/postgres_user.txt secrets/postgres_password.txt

پوشه secrets/ در Git نادیده گرفته می‌شود؛ روی هر سرور یا هر کلون جدید باید دوباره ساخته شود.

The secrets/ folder is git-ignored; it has to be recreated on every server and every fresh clone.

05اجرا و بررسیStart and verify# انجام شدDone

ایمیج‌ها را بسازید و سرویس‌ها را در پس‌زمینه اجرا کنید. اولین ساخت چند دقیقه طول می‌کشد.

Build the images and start the services in the background. The first build takes a few minutes.

docker compose up -d --build

# every service should be running (or healthy)
docker compose ps

# follow the logs; Ctrl+C only stops following, not the services
docker compose logs -f

در خروجی docker compose ps ستون PORTS نشان می‌دهد پنل روی کدام پورت منتشر شده است. پنل را در مرورگر با نشانی سرور و همان پورت باز کنید. اگر پنل بالا نیامد، به بخش رفع اشکال بروید.

In the docker compose ps output, the PORTS column shows which port the panel is published on. Open the panel in a browser using the server address and that port. If it does not come up, see Troubleshooting.

06دسترسی شبکه و فایروالNetwork and firewall# انجام شدDone

پنل فقط باید از شبکه مدیریتی شما در دسترس باشد، نه از اینترنت. با ufw دسترسی را محدود کنید و به‌جای <PANEL_PORT> و <ADMIN_NET> پورت پنل و محدوده شبکه مدیریتی را بگذارید:

The panel should be reachable only from your management network, never from the internet. Restrict access with ufw, replacing <PANEL_PORT> and <ADMIN_NET> with the panel port and your management range:

sudo ufw default deny incoming
sudo ufw allow OpenSSH
sudo ufw allow from <ADMIN_NET> to any port <PANEL_PORT> proto tcp
sudo ufw enable
sudo ufw status verbose

پایگاه داده و Valkey نباید هیچ پورتی را بیرون از سرور منتشر کنند.

The database and Valkey should not publish any port outside the server.

07ویزارد راه‌اندازی اولیهFirst-run setup wizard# انجام شدDone

بار اول که پنل را باز می‌کنید، ویزارد راه‌اندازی شما را گام‌به‌گام جلو می‌برد:

The first time you open the panel, the setup wizard walks you through:

1. حساب مدیر: ساخت اولین کاربر با نقش مدیر.
2. سازمان و منطقه زمانی: نام سازمان و منطقه زمانی برای زمان‌بندی‌ها و گزارش‌ها.
3. TLS: انتخاب نحوه ارائه HTTPS برای پنل.
4. دامنه اولیه: تعریف اولین محدوده مجاز و ثبت تعهد اینکه اجازه اسکن آن را دارید.
5. پیش‌فرض‌های ایمنی: مرور و تأیید محدودیت‌های پیش‌فرض اسکن.
6. پایان: ورود به پنل.

1. Administrator: create the first user with the administrator role.
2. Organisation and timezone: used for schedules and reports.
3. TLS: choose how HTTPS is served for the panel.
4. Initial scope: define the first authorised range and attest that you are allowed to scan it.
5. Safety defaults: review and acknowledge the default scan limits.
6. Complete: continue into the panel.

ورود، MFA و نقش‌هاSign-in, MFA and roles#

ورود شامل رمز عبور و سپس کد یک‌بار مصرف TOTP یا کد بازیابی است. کاربری که مدیر برایش حساب ساخته، پیش از هر کاری باید رمز خودش را تعیین کند. برای نقش‌های اپراتور و مدیر، فعال‌سازی TOTP الزامی است و تا انجام نشود وارد پنل نمی‌شوند.

Sign-in takes a password followed by a TOTP code or a recovery code. A user whose account was created by an administrator must set their own password before anything else. Operators and administrators must enrol TOTP; they cannot reach the panel until they do.

کدهای بازیابی را هنگام فعال‌سازی MFA در جای امنی بیرون از سرور نگه دارید.

Store your recovery codes somewhere safe, off the server, when you enrol MFA.

اولین اسکنYour first scan#

پیش از اسکن، در صفحه دامنه و استثناها مطمئن شوید محدوده درست تعریف شده است. آن‌جا می‌توانید استثنا (همراه با دلیل)، پروفایل اسکن و پنجره‌های ممنوع مثل ساعت‌های پشتیبان‌گیری را هم تعریف کنید. سپس از صفحه اسکن‌ها گزینه اسکن جدید را بزنید:

Before scanning, check on the Scope & exclusions screen that the range is defined correctly. There you can also add exclusions (with a reason), scan profiles and blackout windows such as backup hours. Then start a new scan from the Scans screen:

1. دامنه: یکی از محدوده‌های مجاز را انتخاب کنید.
2. پروفایل: پروفایل اسکن را انتخاب کنید. پروفایل standard تماس بیشتری با دارایی‌ها دارد و فقط با تایپ CONFIRM انتخاب می‌شود.
3. زمان: اجرای فوری یا زمان‌بندی.
4. بازبینی: تعداد هدف، حجم بسته‌ها، مدت تخمینی، استثناها با دلیلشان، دستگاه‌های شکننده‌ای که ملایم‌تر اسکن می‌شوند و نرخ ارسال نسبت به سقف مجاز. دکمه شروع تا وقتی همه این اعداد واقعی محاسبه نشده‌اند فعال نمی‌شود.

1. Scope: pick one of your authorised ranges.
2. Profile: choose a scan profile. The standard profile is more intrusive and can only be selected by typing CONFIRM.
3. When: run now or schedule.
4. Review: target count, packet volume, estimated duration, exclusions with their reasons, fragile devices that will be scanned more gently, and pacing versus the allowed ceiling. Start scan stays disabled until every one of these is a real, computed number.

در نمای اسکن در حال اجرا می‌توانید اسکن را مکث، ادامه یا لغو کنید و خروجی خام را دانلود کنید.

From the live run view you can pause, resume or abort the scan and download the raw artifacts.

رسیدگی به مسائلWorking with issues#

صفحه مسائل اصلی‌ترین صفحه کار روزانه است: فهرست در یک سمت و جزئیات در سمت دیگر. با فیلترهای وضعیت و اطمینان، فهرست را محدود کنید. همه فیلترها در نشانی صفحه ذخیره می‌شوند، پس می‌توانید یک نمای فیلترشده را با همکارتان به اشتراک بگذارید.

The Issues screen is the core of day-to-day work: a list on one side and details on the other. Narrow the list with the state and confidence filters. Every filter lives in the page URL, so you can share a filtered view with a colleague.

در جزئیات هر مسئله، توضیح امتیاز ریسک نشان می‌دهد امتیاز چطور ساخته شده: از شدت پایه، ضرب در وضعیت بهره‌برداری، میزان در معرض بودن، اهمیت دارایی و اطمینان تطبیق. شواهد هر مشاهده هم با پیوند به خروجی خام در دسترس است.

In each issue's details, the risk explainer shows how the score was built: base severity, multiplied by exploit status, exposure, asset criticality and match confidence. Evidence for every observation is shown with a link to the raw artifact.

پذیرش ریسک و راستی‌آزماییAccepting risk and verifying fixes

• پذیرش ریسک یک درخواست استثنا می‌سازد که باید توسط کسی غیر از درخواست‌دهنده تأیید شود. استثناها تاریخ انقضا دارند و در صفحه استثناها با شمارش معکوس دیده می‌شوند.
• راستی‌آزمایی رفع یک اسکن تأیید درخواست می‌دهد. وضعیت «رفع‌شده و تأییدشده» را فقط خود سیستم پس از این اسکن تعیین می‌کند.

• Risk accept creates an exception request that must be approved by someone other than the requester. Exceptions expire and appear on the Exceptions screen with a countdown.
• Verify fix requests a verification scan. Only the system itself can mark an issue as verified resolved, after that scan.

به‌روزرسانی داده آسیب‌پذیریUpdating vulnerability data#

Xenitex داده آسیب‌پذیری را از NVD و احتمال بهره‌برداری را از FIRST EPSS دریافت می‌کند. از مسیر مدیریت ← اطلاعات تهدید دکمه به‌روزرسانی را بزنید. فقط آسیب‌پذیری‌هایی نگه داشته می‌شوند که بهره‌برداری‌شده باشند، شدتشان از آستانه بالاتر باشد یا احتمال بهره‌برداریشان بالا باشد؛ بقیه کنار گذاشته می‌شوند تا پایگاه داده کوچک بماند. داده‌ها مرحله‌ای بارگذاری و یکجا اعمال می‌شوند.

Xenitex pulls vulnerability records from NVD and exploit-probability scores from FIRST EPSS. Go to Administration → Intelligence and click Update now. Only vulnerabilities that are known-exploited, above the severity floor or above the exploit-probability threshold are kept; the rest are discarded to keep the database small. Data is staged and applied atomically.

• هر ارتباط بیرونی برای همگام‌سازی در لاگ ممیزی ثبت می‌شود.
• در شبکه‌های کاملاً بدون اینترنت، می‌توانید همگام‌سازی را برای همیشه غیرفعال کنید.
• در نسخه فعلی همگام‌سازی دستی است و زمان‌بندی خودکار ندارد.

• Every outbound connection made for a sync is recorded in the audit log.
• On fully air-gapped networks you can disable syncing permanently.
• In the current version syncing is manual; there is no automatic schedule yet.

گزارش‌ها و داشبوردReports and dashboard#

داشبورد شش کاشی دارد: وضعیت ریسک با روند، مسائل پرریسک، رعایت مهلت رفع (با تمرکز بر موارد عقب‌افتاده)، پوشش اسکن، اسکن‌های فعال و استثناهای نزدیک به انقضا. هر کاشی به نمای فیلترشده همان موضوع پیوند دارد.

The dashboard has six tiles: risk posture with a trend line, top issues by risk, SLA compliance (leading with overdue items), scan coverage, active scans and exceptions approaching expiry. Every tile links to a pre-filtered view.

در صفحه گزارش‌ها یکی از قالب‌ها را انتخاب کنید و گزارش را بسازید؛ پس از آماده شدن، پیوند دانلود ظاهر می‌شود.

On the Reports screen, pick a template and generate; a download link appears when it is ready.

پشتیبان‌گیری و به‌روزرسانیBackup and upgrade#

در مسیر مدیریت ← پشتیبان‌گیری سوابق پشتیبان‌ها را می‌بینید و می‌توانید پشتیبان فوری بگیرید. مستقل از آن، پیش از هر به‌روزرسانی یک خروجی کامل از پایگاه داده روی سرور بگیرید:

Under Administration → Backups you can see backup records and trigger an on-demand backup. Independently of that, take a full database dump on the server before every upgrade:

cd xenitex/deploy/compose
docker compose exec -T postgres pg_dumpall -U xenitex > xenitex-$(date +%F).sql

اگر در فایل postgres_user.txt نام دیگری گذاشته‌اید، به‌جای xenitex همان را بنویسید. فایل پشتیبان را بیرون از سرور نگه دارید و بازیابی آن را گاهی روی یک سرور آزمایشی امتحان کنید.

If you used a different name in postgres_user.txt, use it instead of xenitex. Keep the dump off the server and test restoring it on a staging machine from time to time.

به‌روزرسانی به نسخه جدیدUpgrading to a new version

cd xenitex
git pull
cd deploy/compose
docker compose up -d --build
docker compose ps

سیاست نگهداری داده را از مدیریت ← نگهداری تنظیم کنید. برای هر نوع داده یک حداقل مجاز وجود دارد و پنل مقدار کمتر از آن را نمی‌پذیرد.

Configure data retention under Administration → Retention. Each data class has a minimum floor and the panel will not accept a lower value.

امن‌سازی سرور میزبانSecuring the host#

سروری که Xenitex روی آن اجراست نقشه آسیب‌پذیری‌های کل شبکه شما را نگه می‌دارد. آن را مثل یک دارایی حساس محافظت کنید:

The server running Xenitex holds a map of every weakness in your network. Protect it like the sensitive asset it is:

• ورود SSH فقط با کلید و بدون ورود مستقیم root.
• نصب منظم به‌روزرسانی‌های امنیتی سیستم‌عامل و Docker.
• دسترسی به پنل فقط از شبکه مدیریتی (بخش فایروال).
• مجوز 600 برای .env و محدود کردن کاربرانی که روی سرور حساب دارند.
• نگهداری پشتیبان‌ها و کدهای بازیابی MFA بیرون از سرور.

• Key-only SSH login with direct root login disabled.
• Regular security updates for the operating system and Docker.
• Panel reachable from the management network only (see firewall).
• Mode 600 on .env, and as few user accounts on the server as possible.
• Backups and MFA recovery codes kept off the server.

Xeniguard، هم‌خانواده Xenitex، این موارد را روی سرورهای لینوکس بررسی و اصلاح می‌کند.

Xeniguard, Xenitex's sibling project, audits and applies these settings on Linux servers.

رفع اشکالTroubleshooting#

نقطه شروع همیشه وضعیت و لاگ سرویس‌هاست:

Always start with service status and logs:

docker compose ps
docker compose logs --tail=200 <service>   # web | api | worker | postgres | valkey

chmod 644 secrets/postgres_user.txt secrets/postgres_password.txt
docker compose up -d

sudo ss -tulpn | grep <PORT>

اجرای محلی برای توسعهLocal development with mocks#

مخزن یک monorepo با pnpm است. برای کار روی پنل بدون نیاز به backend واقعی، یک سرور Mock وجود دارد که مستقیماً از روی قرارداد OpenAPI داده واقعی‌نما تولید می‌کند.

The repository is a pnpm monorepo. To work on the panel without a real backend, a mock server generates realistic data directly from the OpenAPI contract.

pnpm install
pnpm build
pnpm lint
pnpm typecheck
pnpm test

pnpm --filter @xenitex/contracts build     # generate types from openapi.yaml
pnpm --filter @xenitex/mock-server dev     # terminal 1: http://127.0.0.1:8081
pnpm --filter @xenitex/web dev             # terminal 2: http://localhost:5173

اگر Corepack در دسترس نیست، npx pnpm@9 را جایگزین pnpm کنید. متغیر MOCK_SERVER_FIXTURE_SCALE=small داده کوچک‌تری برای اجرای سریع می‌سازد و MOCK_SERVER_SETUP_INCOMPLETE=true پنل را با ویزارد راه‌اندازی ناتمام بالا می‌آورد.

If Corepack is unavailable, use npx pnpm@9 in place of pnpm. MOCK_SERVER_FIXTURE_SCALE=small generates a smaller fixture for fast iteration, and MOCK_SERVER_SETUP_INCOMPLETE=true boots with an unfinished setup wizard.

کاربران آزمایشی MockSeeded mock users

رمز همه password123 و کد MFA همه 000000 است.

All use password password123 and MFA code 000000.

هدرهای کمکی MockMock testing headers

وضعیت فعلی و محدودیت‌هاCurrent status and limitations#

Xenitex در حال توسعه فعال است. پیش از استفاده در محیط عملیاتی این موارد را بدانید:

Xenitex is under active development. Know the following before using it in production:

• استقرار با Docker Compose، شکل مرجع استقرار است. بسته نصب امضاشده برای شبکه‌های بدون اینترنت هنوز منتشر نشده است.
• کشف با اتصال TCP و خواندن بنر انجام می‌شود. Nmap به دلیل ملاحظات مجوز همراه Xenitex عرضه نمی‌شود.
• همگام‌سازی داده آسیب‌پذیری دستی است و زمان‌بندی خودکار ندارد.
• تطبیق محصول و نسخه هنوز در حال گسترش است؛ اطمینان هر تطبیق در امتیاز ریسک لحاظ می‌شود.

• The Docker Compose setup is the reference deployment. A signed installer for air-gapped networks is not released yet.
• Discovery uses TCP connect and banner grabbing. Nmap is not bundled with Xenitex for licensing reasons.
• Vulnerability-data sync is manual; there is no automatic schedule yet.
• Product and version matching is still being extended; each match's confidence is factored into the risk score.