منصوبے کے بارے میں

# Zentra CLI Zentra ایک اوپن سورس، AI سے چلنے والا ایپلیکیشن سیکیورٹی CLI ہے جو ڈویلپرز کے لیے ڈیزائن کیا گیا ہے۔ یہ فریم ورک تجزیہ، خطرے کی ماڈلنگ، جامد تجزیہ (SAST)، سپلائی چین، API، اور انفراسٹرکچر-بطور-کوڈ (IaC) اسکینرز کا استعمال کرتے ہوئے کوڈ بیسز میں سیکیورٹی خطرات کو اسکین کرتا ہے۔ یہ انٹرایکٹو ٹرمینل انٹرفیس کے ساتھ مقامی طور پر یا CI پائپ لائنز میں ہیڈ لیس چل سکتا ہے۔ بائنری کا نام `zentra` ہے۔ ## خصوصیات - **ہیڈ لیس CI موڈ** GitHub Actions اور GitLab مرج ریکویسٹ پائپ لائنز کے لیے۔ - **LLM سے تعاون یافتہ اسکینر آرکیسٹریشن** Anthropic، OpenAI-مطابق، Claude CLI، اور تجرباتی Codex CLI فراہم کنندگان کے ساتھ۔ - **متحرک براؤزر پینٹیسٹ موڈ** مجاز اہداف کے لیے۔ - **متعدد آؤٹ پٹ فارمیٹس**: مارک ڈاؤن، JSON، SARIF، اور اسٹائل شدہ HTML `.zentra/` کے تحت۔ - **آرام پر خفیہ کردہ اسناد اسٹوریج** (ونڈوز پر DPAPI، یونکس پر `0600` فائلیں)۔ ## انسٹالیشن ### فوری انسٹال (تجویز کردہ) کوئی Rust ٹول چین، ریپوزٹری کلون، یا بلڈ مرحلہ درکار نہیں۔ ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.sh | sh ``` ونڈوز پاور شیل کے لیے: ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.ps1 | iex" ``` بعد میں ایک نیا ٹرمینل ونڈو کھولیں تاکہ `zentra` دستیاب ہو۔ دستی طور پر انسٹال کرنے کے لیے، [Releases صفحہ](https://github.com/johannus22/zentra/releases) سے ایک بلڈ ڈاؤن لوڈ کریں۔ > **لینکس نوٹ:** بائنری OS کی چابی کی انگوٹھی تک رسائی کے لیے رن ٹائم پر `libdbus` سے منسلک ہوتی ہے۔ کم سے کم یا ہیڈ لیس امیجز پر، اسے پہلے انسٹال کریں (`sudo apt-get install -y libdbus-1-3` یا اس کے مساوی)۔ متبادل طور پر، خفیہ کردہ فائل پر مبنی اسناد اسٹور استعمال کرنے کے لیے `ZENTRA_NO_OS_KEYCHAIN=1` سیٹ کریں۔ ### سورس سے انسٹال کریں مقامی طور پر بلڈ اور چلائیں: ```bash cargo build ``` ریپوزٹری چیک آؤٹ سے بائنری انسٹال کریں: ```bash cargo install --path . ``` ## استعمال TUI فراہم کنندگان کو ترتیب دینے، اسکین شروع کرنے، اور نتائج کا جائزہ لینے کے لیے بنیادی مقامی تجربہ ہے۔ مرکزی مینو جامد ایپلیکیشن سیکیورٹی ٹیسٹنگ (SAST)، متحرک ایپلیکیشن سیکیورٹی ٹیسٹنگ (DAST)، اور متفرق اقدامات کو گروپ کرتا ہے۔ ### اسکین کمانڈز صرف ایک اسکینر فیملی چلائیں: ```bash zentra scan --only sast zentra scan --only supply-chain zentra scan --only api zentra scan --only iac ``` ہر اسکینر کو سیاق و سباق سے چیک شدہ ریپوزٹری پیک دینے کے لیے `--pack` استعمال کریں۔ اسکین کی حالت بڑھتی ہوئی رنز کے لیے `.zentra/checkpoint.json` پر محفوظ ہوتی ہے۔ SAST 50 تک ReAct فراہم کنندہ راؤنڈ استعمال کر سکتا ہے؛ دوسرے اسکینرز 30 تک استعمال کرتے ہیں۔ مقامی `zentra scan` رنز میں ایک مستقل پڑھنے کے لیے صرف چیٹ پین شامل ہوتا ہے۔ چیٹ پابند، سرخ کردہ اسکین اور ریپوزٹری سوالات کا جواب پڑھنے کے لیے صرف پروفائل (`list_files`, `read_file`, `grep_code`, اور پابند Git کمانڈز) کے ساتھ دیتا ہے۔ یہ ٹائپ شدہ فوکس/دوبارہ چلانے یا کمزوری کے زمرے کے اقدامات تجویز کر سکتا ہے، لیکن نہ تو ماڈل آؤٹ پٹ اور نہ ہی ٹول کال مقامی تصدیق کے بغیر ان میں سے کسی کو لاگو کر سکتی ہے۔ تصدیق شدہ اقدامات چیک پوائنٹ میں محفوظ ہوتے ہیں اور صرف اگلے اسکین پر لاگو ہوتے ہیں۔ چیٹ `zentra ci` یا دیگر ہیڈ لیس اسکین راستوں میں دستیاب نہیں ہے۔ ### CI سیکیورٹی اسکیننگ Zentra میں ایک وقف شدہ CI کمانڈ شامل ہے: ```bash zentra ci ``` `zentra ci` `zentra scan` کا عرف نہیں ہے۔ یہ GitHub Actions یا GitLab CI کا پتہ لگاتا ہے، تصدیق کرتا ہے کہ جاب PR/MR پائپ لائن میں چلتی ہے، بغیر TUI کے فوکسڈ سیکیورٹی اسکینرز چلاتا ہے، CI آرٹیفیکٹس لکھتا ہے، اور صرف ناکامی کی حد سے اوپر یا اس کے برابر نتائج یا اسکینر/سسٹم کی ناکامیوں کے لیے ناکام ہوتا ہے۔ ڈیفالٹ طور پر، `zentra ci` کسی بھی **Critical یا High** تلاش پر PR/MR کو بلاک کرتا ہے۔ Medium، Low، اور Info نتائج رپورٹ ہوتے ہیں لیکن جاب کو ناکام نہیں بناتے۔ #### ناکامی کی حد `ZENTRA_CI_FAIL_THRESHOLD` ماحولیاتی متغیر سیٹ کریں (`critical`, `high`, `medium`, `low`, `info` میں سے ایک) یا پالیسی کو برقرار رکھنے کے لیے `.zentra/config.json` میں `fail_threshold` فیلڈ استعمال کریں۔ مثال GitHub Actions جاب: ```yaml - name: Run Zentra CI env: ZENTRA_API_KEY: ${{ secrets.ZENTRA_API_KEY }} ZENTRA_PROVIDER_MODEL: ${{ vars.ZENTRA_PROVIDER_MODEL }} ZENTRA_CI_FAIL_THRESHOLD: critical run: zentra ci ``` #### GitLab CI GitLab CI ورک فلو push-to-`staging` پائپ لائنز کے لیے دوسری جاب بھیجتا ہے۔ یہ مکمل ریپوزٹری اسکین چلاتا ہے، پائپ لائن کو کبھی ناکام نہیں بناتا، اور `security` اور `zentra-triage` لیبلز کے ساتھ ایک GitLab مسئلہ فائل یا اپ ڈیٹ کرتا ہے۔ ماسک شدہ CI/CD متغیر کے طور پر `api` اسکوپ والا ذاتی رسائی ٹوکن استعمال کریں۔ CI آرٹیفیکٹس `.zentra/ci-report.md`, `.zentra/ci-report.json`, اور `.zentra/ci-report.html` پر رہتے ہیں۔ #### CI ماحولیاتی متغیرات | متغیر | مطلوبہ | نوٹس | |----------|----------|-------| | `ZENTRA_API_KEY` | ہاں | خفیہ — LLM فراہم کنندہ API کلید | | `ZENTRA_PROVIDER_BASE_URL` | ہاں | خفیہ یا متغیر — مثلاً، `https://api.anthropic.com` | | `ZENTRA_PROVIDER_MODEL` | ہاں | متغیر — مثلاً، `claude-sonnet-5` | | `ZENTRA_PROVIDER_KIND` | نہیں | ڈیفالٹ `openai_compat` ہے | | `ZENTRA_PROVIDER_REASONING_EFFORT` | نہیں | OpenAI-مطابق فراہم کنندگان کو منتقل ہوتا ہے | | `ZENTRA_PROVIDER_CONTEXT_WINDOW` | نہیں | فراہم کنندہ کے ڈیفالٹ سیاق و سباق ونڈو کو اوور رائیڈ کرتا ہے | | `ZENTRA_CI_FAIL_THRESHOLD` | نہیں | کم از کم شدت جو PR کو بلاک کرتی ہے | اگر `ZENTRA_API_KEY`, `ZENTRA_PROVIDER_BASE_URL`, یا `ZENTRA_PROVIDER_MODEL` میں سے کوئی بھی سیٹ نہیں ہے، تو `zentra ci` `~/.zentra/config.toml` میں `zentra config setup` کے ساتھ ترتیب کردہ پروفائل پر واپس آتا ہے۔ ### CI ورک فلو تیار کریں ```bash zentra init --ci github # GitHub Actions ورک فلو بنائیں zentra init --ci gitlab # GitLab CI جاب بنائیں ``` ### پینٹیسٹ موڈ Zentra میں لائیو ویب اہداف کے لیے ایک مجاز متحرک پینٹیسٹ موڈ شامل ہے: ```bash zentra pentest --url https://target.example --authorized \ --allow-host target.example \ --allow-host api.target.example ``` `--authorized` جھنڈا مطلوبہ ہے، لہذا ایک حادثاتی اسکین بند ہو جاتا ہے۔ صرف اس موڈ کو ان سسٹمز کے خلاف چلائیں جن کے آپ مالک ہیں یا جن کی جانچ کرنے کی واضح اجازت ہے۔ راستوں کو خارج کرنے کے لیے `--exclude-path` اور ڈومین اور اس کے تمام ذیلی ڈومینز کی اجازت دینے کے لیے `--scope-domain` استعمال کریں۔ پینٹیسٹ موڈ اپنے الگ تھلگ ٹول چین کے لیے `zentra/pentest-sandbox:0.1.0` Docker امیج استعمال کرتا ہے۔ کسٹم امیجز کے لیے `ZENTRA_SANDBOX_IMAGE` اور `ZENTRA_SANDBOX_VERSION` سیٹ کریں۔ ایک پینٹیسٹ رن تین سینڈ باکس ایجنٹس (Recon, Exploit, Validator) استعمال کرتا ہے اور CVSS v3.1 بیس ویکٹرز کے ساتھ رپورٹیں تیار کرتا ہے۔ آؤٹ پٹ ڈائریکٹریز: - ایک ابتدائی پروجیکٹ کے اندر: `./.zentra/pentest/<host>/<run-id>/` - باہر: `<Documents>/Zentra/pentest/<host>/<run-id>/` (یا ترتیب شدہ `output_dir`) ### دیگر کمانڈز ```bash zentra init # .zentra/config.json بنائیں zentra scan --only sast # ایک اسکینر فیملی چلائیں zentra ci # ہیڈ لیس PR/MR CI اسکین zentra ci --refresh-architecture zentra ci --full --report-only # اسٹیجنگ پائپ لائن کو بلاک کیے بغیر مکمل اسکین zentra security verify-audit [session] ``` ## سیکیورٹی نوٹس - Zentra فراہم کنندہ اسناد کو پروجیکٹ ڈائریکٹری سے باہر ایک خفیہ کردہ خفیہ اسٹور میں محفوظ کرتا ہے۔ DPAPI ونڈوز پر ڈیٹا-انکرپشن کلید کی حفاظت کرتا ہے؛ یونکس پابندی والی فائل کی اجازتیں اور دستیاب کی رنگ بیک اینڈ استعمال کرتا ہے۔ - فائل ٹولز پاتھ ٹراورسل کو روکتے ہیں اور فائل ریڈز کو محدود کرتے ہیں۔ - انٹرایکٹو چیٹ ایک علیحدہ پابند، پڑھنے کے لیے صرف ٹول پروفائل استعمال کرتا ہے۔ - ڈیفالٹ سیکیورٹی لفافہ ایک چھیڑ چھاڑ سے واضح آڈٹ چین ریکارڈ کرتا ہے، ٹول کالز کو گیٹ کرتا ہے، اور ناقابل اعتماد ٹول آؤٹ پٹ کو نشان زد کرتا ہے۔ رسپانس بائنڈنگ اور انجیکشن پر ایبورٹ نافذ کرنے کے لیے `ZENTRA_SECURITY=hardened` سیٹ کریں؛ صرف قابل اعتماد مقامی ترقی کے لیے `ZENTRA_SECURITY=off` استعمال کریں۔ - آڈٹ چین کی تصدیق کریں `zentra security verify-audit [session]` کے ساتھ۔ - Git تاریخ اور انحصار آڈٹ ٹولز مطلوبہ بائنریز یا تاریخ دستیاب نہ ہونے پر آہستہ سے ناکام ہو جاتے ہیں۔ ## پروجیکٹ ڈھانچہ - `.zentra/config.json` — پروجیکٹ کنفیگریشن - `.zentra/checkpoint.json` — بڑھتی ہوئی رنز کے لیے اسکین کی حالت - `.zentra/reports/findings.html` — HTML رپورٹس - `.zentra/architecture.md` — فریم ورک تجزیہ آؤٹ پٹ CI سیاق و سباق کے طور پر استعمال ہوتا ہے خفیہ یا اسکین کی حالت کو ورژن کنٹرول میں کمٹ نہ کریں۔