Quipu

ورشة عمل مكتبية لكتابة قواعد YARA والتحقق من صحتها وتجميعها واختبارها.

يجمع Quipu (يُنطق "KEE-poo") مستكشف مشاريع، ومحررًا مدركًا لـ YARA، ومترجم YARA-X، ونتائج فحص مركّزة في تطبيق محلي واحد. وهو يضمّن كلاً من YARA-X وخادم لغته، لذا لا تحتاج إلى تثبيت YARA منفصل.

[!IMPORTANT] Quipu في مرحلة MVP. المنصة المدعومة مبدئيًا هي Linux 64-bit؛ وسيتبع ذلك دعم Windows و macOS.

الميزات

• افتح مجلدًا يحتوي على ملفات .yar و .yara كمساحة عمل، أو ابدأ بقاعدة مؤقتة.
• استكشف نقاط الدخول المستنتجة أو المُهيّأة، والتضمينات المتداخلة، والتضمينات الخارجية، ومشكلات المشروع.
• حرّر باستخدام تمييز الصياغة في Monaco، والإكمال، وتوثيق التمرير، وتشخيصات YARA-X المباشرة.
• جمّع مساحة عمل كاملة، ثم افحص نصًا مكتوبًا أو ملفًا محددًا.
• افحص القواعد المطابقة والأنماط والإزاحات وأطوال البايتات والبايتات المميّزة في عارض سداسي عشري.
• انتقل من التشخيصات والمطابقات مباشرةً إلى تعريفاتها المصدرية.
• استعد مجموعات القواعد المُجمّعة غير المتغيّرة من ذاكرة تخزين مؤقت محلية محدودة.
• اعمل من مجموعة من مشاريع الأمثلة الصغيرة والمكتفية ذاتيًا المضمّنة مع التطبيق.

تُعالَج القواعد وأهداف الفحص محليًا. لا يرسل Quipu محتوياتها إلى خدمة بعيدة.

التثبيت على Linux

تُنشر حزم Linux x86-64 على صفحة GitHub Releases:

Package	Best for	Install or run
AppImage	Portable use on supported distributions	chmod +x Quipu_*.AppImage && ./Quipu_*.AppImage
.deb	Ubuntu 22.04+ and Debian 12+	sudo apt install ./Quipu_*.deb
.rpm	Recent Fedora releases	sudo dnf install ./Quipu-*.rpm

تستخدم حزمتا .deb و .rpm وقت تشغيل WebKitGTK الخاص بالنظام. إذا تعذّر على توزيعتك تلبية هذه التبعية، فاستخدم AppImage.

حزم Quipu غير موقّعة حاليًا. يتضمن كل إصدار ملف SHA256SUMS؛ نزّله بجانب الحزم وتحقق من الملفات التي نزّلتها باستخدام:

sha256sum --ignore-missing --check SHA256SUMS

تكتشف المجاميع الاختبارية التلف العَرَضي لكنها ليست توقيعًا موثّقًا.

البدء السريع

1. شغّل Quipu واختر File → Open Example… → Basic text match.
2. استكشف text_indicators.yar في المحرر.
3. اختر Rules → Compile Workspace أو اضغط Ctrl+Shift+B.
4. افحص الهدف المُجهّز عبر Rules → Scan Target أو اضغط Ctrl+Shift+Enter.
5. وسّع مطابقة واخترها لفحص البايتات المميّزة.

الدليل الكامل مضمّن مع Quipu تحت Help → Documentation. مصدره متاح أيضًا في documentation/content.

مساحات العمل و quipu.toml

بدون تهيئة، يكتشف Quipu ملفات القواعد بشكل تكراري ويستنتج نقطة دخول من كل ملف غير مُضمّن بواسطة ملف آخر. أضف quipu.toml في جذر مساحة العمل عندما تحتاج إلى نقاط دخول صريحة، أو أدلة تضمين، أو استثناءات:

schema = 1
entrypoints = ["main.yar"]
include_dirs = ["rules", "../shared-rules"]
exclude = ["fixtures/**", "vendor/legacy/**"]

راجع Workspaces and projects للاطلاع على نموذج المشروع الكامل ومرجع البيان.

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

يستهدف Quipu حاليًا Linux x86-64. يتطلب البناء:

• Rust 1.93 أو أحدث
• Node.js 22.6 أو أحدث
• Zola 0.23
• Git
• المكتبات الأصلية التي تتطلبها Tauri و WebKitGTK

على Debian أو Ubuntu، ثبّت التبعيات الأصلية باستخدام:

sudo apt update
sudo apt install -y \
  build-essential \
  curl \
  file \
  libayatana-appindicator3-dev \
  libgtk-3-dev \
  librsvg2-dev \
  libssl-dev \
  libwebkit2gtk-4.1-dev \
  patchelf \
  rpm \
  wget

ثم ابنِ صيغ حزم Linux الثلاث:

git clone https://github.com/corelight/quipu.git
cd quipu/app
npm ci
npm run tauri -- build --bundles appimage,deb,rpm

تُكتب المخرجات أسفل app/src-tauri/target/release/bundle/. قد يستغرق البناء الأول وقتًا لأن Cargo يجمّع YARA-X وتبعياته من المصدر.

التطوير والاختبار

ثبّت التبعيات وابدأ تطبيق التطوير:

cd app
npm ci
npm run tauri -- dev

شغّل اختبارات الوحدة للواجهة الأمامية، وبناء الواجهة الأمامية للإنتاج، واختبارات Rust عبر:

cd app
npm test
npm run build

cd src-tauri
cargo test --locked

تتطلب مجموعة قبول القائمة الأصلية متطلبات إضافية لخادم عرض Linux. راجع test/README.md لإعدادها واستخدامها.

البنية

Quipu هو تطبيق Tauri بواجهة أمامية TypeScript خام وخلفية Rust:

• يحزم Vite الواجهة الأمامية ومحرر Monaco في webview التطبيق.
• يربط Tauri IPC واجهة المستخدم بخدمات مساحة العمل ونظام الملفات والتجميع والتخزين المؤقت والفحص في Rust.
• يعمل مترجم YARA-X وخادم اللغة داخل العملية.
• يبني Zola موقع توثيق دون اتصال مضمّنًا في التطبيق.

app/src/           TypeScript frontend
app/src-tauri/     Rust backend and desktop packaging
documentation/    Source for the bundled offline guide
examples/          Projects bundled with the application
test/ui/           Native-menu acceptance test harness

يُعرَّف إصدار التطبيق في app/package.json؛ يقرأ Tauri تلك القيمة عند تسمية الحزم والإبلاغ عن الإصدار قيد التشغيل.

القيود الحالية

• تُدعم حزم Linux x86-64 فقط مبدئيًا.
• يفحص Quipu ملفًا محددًا واحدًا أو مخزن نص واحد في كل مرة، وليس الأدلة أو الدفعات.
• تُنشأ القواعد الجديدة في جذر مساحة العمل. تُنفَّذ عمليات النقل والحذف خارج Quipu.
• يمكن تجميع قاعدة مؤقتة وفحصها، لكن لا يمكن حفظها أو تخزينها مؤقتًا.

المساهمة والأمان

المساهمات مرحّب بها. اقرأ CONTRIBUTING.md قبل فتح طلب سحب.

يُرجى عدم الإبلاغ عن ثغرات الأمان في مشكلة عامة. اتبع عملية الإبلاغ الخاصة في SECURITY.md.

شكر وتقدير

Quipu من بناء Corelight ويعمل بواسطة YARA-X، و Monaco Editor، و Tauri.

الترخيص

يُوزَّع Quipu تحت ترخيص BSD ثلاثي البنود. راجع LICENSE. الإشعارات الخاصة بالبرمجيات المدمجة من أطراف ثالثة موجودة في THIRD_PARTY_LICENSES.