ZTTP — وكيل شفاف قائم على مبدأ الثقة الصفرية

مضيف حصن SSH ذاتي الاستضافة ومُحصّن مع إدارة مفاتيح مدعومة بـ Vault، وفرض سياسات RBAC، وتسجيل كامل للجلسات، وواجهة إدارة تفاعلية TUI — مصمم للفرق التي تحتاج وصولاً قابلاً للتدقيق وقائماً على مبدأ الثقة الصفرية إلى البنية التحتية للإنتاج.

جدول المحتويات

• لماذا ZTTP؟
• نظرة عامة على البنية
• أبرز الميزات
• المتطلبات الأساسية
• بدء سريع — الخادم
• بدء سريع — العميل
• الإعدادات
• الأدوار وسياسة RBAC
• وحدة التحكم الإدارية
• سجلات التدقيق وتسجيلات الجلسات
• البناء من المصدر
• مرجع Makefile
• لقطات الشاشة والعرض التوضيحي
• هيكل المشروع
• نموذج الأمان
• المساهمة
• الترخيص

لماذا ZTTP؟

تحتاج فرق الهندسة الحديثة إلى طريقة تمنح المطورين الحد الأدنى من الوصول المطلوب لأداء مهامهم — لا أكثر ولا أقل. توزيع مفاتيح SSH التقليدي عرضة للأخطاء: تتم مشاركة المفاتيح، وتُنسى على أجهزة الكمبيوتر المحمولة، ويتم إبطالها بعد فوات الأوان.

يحل ZTTP هذه المشكلة من خلال العمل كـالباب الوحيد إلى بنيتك التحتية:

نظرة عامة على البنية

Developer Laptop
      │
      │  zttp
      │  (Under the hood: SSH over port 2224)
      ▼
┌─────────────────────────────────────────────────────────┐
│                     ZTTP Proxy                          │
│                                                         │
│  ① Auth Gate     — bcrypt/Argon2id login TUI           │
│  ② RBAC Engine   — environment-aware policy check      │
│  ③ Vault Fetch   — ephemeral SSH key retrieval         │
│  ④ Bridge        — transparent TCP tunnel              │
│  ⑤ Audit Writer  — ttyrec frame recorder               │
└──────────┬──────────────────────────────────────────────┘
           │  ssh (private IP, ephemeral key)
           ▼
     Target Server

خدمات البنية التحتية (Docker Compose):

أبرز الميزات

• 🔐 مصادقة قائمة على مبدأ الثقة الصفرية — واجهة تسجيل دخول SSH تفاعلية TUI مع تجزئة كلمات مرور bcrypt، وتحديد معدل، وقفل الحساب بعد 5 محاولات فاشلة
• 🛡️ محرك سياسات RBAC — تحكم في الوصول لكل دور ولكل بيئة مع استعلام PostgreSQL JOIN واحد مُحسَّن (بدون رحلات ذهاب وإياب)
• 🗝️ مفاتيح SSH مدعومة بـ Vault — المفاتيح الخاصة لا تلمس القرص أبداً؛ يتم جلبها مؤقتاً لكل جلسة من HashiCorp Vault
• 📹 تسجيل كامل للجلسات — يتم تسجيل جميع الجلسات بصيغة .ttyrec مع إطارات زمنية
• 🖥️ واجهة إدارية تفاعلية TUI — واجهة طرفية كاملة لإدارة المستخدمين، وتسجيل الخوادم، ومنح الوصول، ومراجعة السجلات
• 🔍 عارض سجلات التدقيق — تصفح الجلسات حسب الخادم، أو إعادة تشغيل التسجيلات، أو قراءة سجلات نصية نظيفة مباشرة من وحدة التحكم الإدارية
• ⚡ مفتاح الإيقاف — نقطة نهاية gRPC لإنهاء أي جلسة حية فوراً
• 📋 سجل الإجراءات الإدارية — يتم تسجيل كل إجراء إداري (إنشاء مستخدم، منح وصول، عرض سجلات) في مسار تدقيق دائم
• 🌍 عميل متعدد المنصات — CLI بملف ثنائي واحد لنظامي Linux وmacOS (amd64/arm64) وWindows

المتطلبات الأساسية

الخادم (مضيف الوكيل):

• Docker ≥ 24 و Docker Compose ≥ 2.20
• عنوان IP عام أو قابل للوصول عبر الشبكة المحلية على المنفذ 2224
• make (اختياري، لكن موصى به)

المطور (العميل):

• أي عميل SSH (أمر ssh)
• جهاز Linux أو macOS أو Windows

بدء سريع — الخادم

1. استنساخ المستودع

git clone https://gitlab.com/Nihal799/zttp.git
cd zttp

2. تكوين بيئتك

cp .env.example .env

قم بتحرير .env واضبط على الأقل:

PROXY_NODE_IP=<your-server-public-ip>
POSTGRES_PASSWORD=<a-strong-password>
VAULT_TOKEN=<a-strong-vault-token>

⚠️ لا تقم أبداً بتضمين ملف .env الخاص بك في الالتزامات. إنه مدرج في .gitignore.

3. تشغيل جميع الخدمات

make docker-up
# أو مباشرة:
docker compose -f deploy/docker-compose.yml up -d --build

4. التحقق من سلامة الخدمات

make docker-ps
curl http://localhost:8080/healthz

5. بناء ونشر مثبتات CLI

make release PROXY_ADDR=<your-server-ip>:2224

يقوم هذا بتجميع العملاء لجميع المنصات وتحديث dist/install.sh و dist/install.ps1 تلقائياً بعنوان الخادم الصحيح. تقدم حاوية Nginx هذه الملفات على http://<your-server-ip>:8555/.

بدء سريع — العميل

Linux / macOS

curl -fsSL http://<proxy-ip>:8555/install.sh | bash

Windows (PowerShell، تشغيل كمسؤول)

irm http://<proxy-ip>:8555/install.ps1 | iex

الاتصال

بمجرد التثبيت، اتصل ببوابة ZTTP:

zttp
# أو مباشرة:
ssh -p 2224 <your-username>@<proxy-ip>

ستظهر لك شاشة تسجيل دخول طرفية. بعد المصادقة، سترى قائمة بالخوادم المصرح لك بالوصول إليها.

الإعدادات

جميع الإعدادات عبر متغيرات البيئة (أو ملف .env). راجع .env.example للمرجع الكامل.

الأدوار وسياسة RBAC

يستخدم ZTTP نموذجاً قائماً على الأدوار. يتم تعيين دور لكل مستخدم؛ ولكل دور سياسة تحدد بيئات الخوادم التي يمكنه الوصول إليها.

تتم إدارة الأدوار وتعيينات الخوادم من خلال وحدة التحكم الإدارية (انظر أدناه). يقوم محرك RBAC بجميع الفحوصات في استعلام PostgreSQL واحد — ولا يكشف أبداً لماذا تم رفض الوصول للعميل (حماية من التعداد).

وحدة التحكم الإدارية

اتصل بخادم zttp-admin من قائمة البوابة، أو سجل الدخول بحساب لديه دور security-admin.

توفر وحدة التحكم الإدارية:

يتم تسجيل جميع الإجراءات الإدارية في admin-actions.log داخل حجم التدقيق.

سجلات التدقيق وتسجيلات الجلسات

يتم تخزين جميع الجلسات في حجم Docker zttp-audit-logs (/var/log/zttp/audit/ داخل الحاوية).

العرض من وحدة التحكم الإدارية

1. سجل الدخول كـ security-admin
2. حدد عرض سجلات التدقيق
3. حدد خادماً من القائمة
4. حدد جلسة
5. اختر عرض السجل النصي (بدون ANSI، قابل للقراءة) أو تشغيل التسجيل (تشغيل في الوقت الفعلي)
6. اضغط Ctrl+C للرجوع

العرض من المضيف (خام)

# قائمة التسجيلات
sudo ls /var/lib/docker/volumes/zttp-audit-logs/_data/

# تشغيل تسجيل باستخدام ttyplay
sudo ttyplay /var/lib/docker/volumes/zttp-audit-logs/_data/<session-id>.ttyrec

# قراءة سجل الإجراءات الإدارية
sudo cat /var/lib/docker/volumes/zttp-audit-logs/_data/admin-actions.log

البناء من المصدر

المتطلبات: Go 1.25+، Docker (للترجمة المتقاطعة)

# بناء الوكيل + CLI للمنصة الحالية
make build

# ترجمة متقاطعة لـ CLI لجميع المنصات (Linux، macOS، Windows)
make release PROXY_ADDR=<proxy-ip>:2224

# تشغيل الاختبارات
make test

# تشغيل الوكيل محلياً (يتطلب تشغيل Postgres و Vault مسبقاً)
make run-proxy

مرجع Makefile

لقطات الشاشة والعرض التوضيحي

1. التثبيت

(انقر لتشغيل العرض التوضيحي)

2. تسجيل الدخول الآمن

(انقر لتشغيل العرض التوضيحي)

3. إضافة خادم (وحدة التحكم الإدارية)

(انقر لتشغيل العرض التوضيحي)

4. الاتصال بالخادم (البوابة)

(انقر لتشغيل العرض التوضيحي)

5. مفتاح الإيقاف (إخراج إداري)

(انقر لتشغيل العرض التوضيحي)

هيكل المشروع

zttp/
├── cmd/
│   ├── proxy/          # Proxy server entrypoint
│   └── zttp/           # CLI client entrypoint
├── db/
│   └── migrations/     # PostgreSQL schema migrations
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile.proxy
│   └── vault-seed.sh   # Seeds test SSH keys into Vault
├── dist/
│   ├── install.sh      # Linux/macOS installer script
│   └── install.ps1     # Windows installer script
├── internal/
│   ├── audit/          # Admin action logging
│   ├── auth/           # User authentication (bcrypt, lockout)
│   ├── cli/            # CLI client TUI and connect logic
│   ├── config/         # Environment-based configuration
│   ├── killswitch/     # gRPC kill-switch service
│   ├── proxy/          # SSH proxy, gateway TUI, admin TUI, bridge
│   ├── rbac/           # Role-based access control engine
│   ├── ratelimit/      # Per-IP rate limiting
│   ├── session/        # Session tracking and DB store
│   └── vault/          # HashiCorp Vault SSH key client
├── proto/              # gRPC protocol definitions
├── tools/
│   └── hashpw/         # CLI tool: generate bcrypt password hash
├── .env.example        # Configuration template
├── go.mod
└── Makefile

نموذج الأمان

المساهمة

1. انسخ المستودع (Fork)
2. أنشئ فرع ميزة: git checkout -b feat/your-feature
3. قم بإجراء تغييراتك، مع ضمان حصول كل ملف على التزام خاص به
4. شغّل الاختبارات: make test
5. افتح طلب دمج

يرجى عدم تضمين:

• .env أو أي ملف يحتوي على أسرار
• عناوين IP حقيقية أو أسماء مضيفين لخوادم الإنتاج
• ملفات ثنائية مترجمة (ملف zttp الثنائي في الجذر مدرج في .gitignore)

الترخيص

هذا المشروع ملكية خاصة. جميع الحقوق محفوظة.

بُني باستخدام Go و PostgreSQL و HashiCorp Vault و Docker.