_                                            _
    | | _____ _ __ _ __   __ _  __ _  ___ _ __ | |_
    | |/ / _ \ '__| '_ \ / _` |/ _` |/ _ \ '_ \| __|
    |   <  __/ |  | | | | (_| | (_| |  __/ | | | |_
    |_|\_\___|_|  |_| |_|\__,_|\__, |\___|_| |_|\__|
                                |___/

لماذا kernagent؟

• بلا واجهة بحكم التصميم — يعمل في CI/Docker؛ لا حاجة إلى واجهة IDA/Ghidra ولا إلى MCP
• أدلة لا حدس — كل إجابة تستشهد بالدوال والمراجع المتقاطعة والاستيرادات والسلاسل، ومقتطفات التفكيك
• حتمي ومحمول — نفس الملف الثنائي → نفس اللقطة → نفس التقرير؛ سهل المقارنة والأرشفة
• مستقل عن النموذج — يعمل مع أي نقطة نهاية LLM من نوع /v1/chat/completions (OpenAI وGemini وOllama وLM Studio وبوّابتك الخاصة)

🚀 بدء سريع

المتطلبات

• Docker (Engine أو Desktop) وGit
• نظام تشغيل 64-بت (x86_64 أو ARM64)
• 4 جيجابايت RAM (يُوصى بـ 8+ جيجابايت للعينات الكبيرة)
• الوصول إلى نقطة نهاية LLM (إنترنت أو بوابة محلية من نوع /v1/chat/completions مثل Ollama أو LM Studio)

التثبيت

اختر المسار الذي يناسب أدواتك. جميع الخيارات تُثبّت ~/.config/kernagent/config.env بحيث تهيّئ بيانات الاعتماد مرة واحدة فقط.

الخيار 1 — غلاف install.sh (Linux / macOS / WSL2)

bash <(curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/install.sh)

إذا كان الأمر أحادي السطر محظورًا:

curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/install.sh -o install.sh
bash install.sh

أو استنسخ المستودع أولًا:

git clone https://github.com/Karib0u/kernagent.git
cd kernagent
bash install.sh

يقوم سكربت التثبيت بما يلي (يمكنك تدقيقه بالكامل في scripts/):

1. يتحقق من أن Docker مثبّت وقيد التشغيل
2. يسحب الصورة الجاهزة ghcr.io/karib0u/kernagent:latest من GitHub Container Registry (بدون خطوة بناء)
3. يثبّت سكربتات الصدفة هذه في /usr/local/bin/:
   • kernagent — غلاف CLI الرئيسي (يثبّت الملفات الثنائية والإعداد تلقائيًا)
   • kernagent-config — محرر إعداد تفاعلي
   • kernagent-update — التحديث إلى أحدث إصدار/إصدار موسوم
   • kernagent-uninstall — إزالة جميع الملفات المثبتة
4. يحفظ معلومات الإصدار في ~/.config/kernagent/.version

جميع السكربتات عبارة عن كود شل بسيط يمكنك مراجعته في scripts/ قبل التشغيل. لا حاجة إلى sudo إلا إذا كان /usr/local/bin غير قابل للكتابة.

متقدم — تثبيت الإصدار على tag/commit محدد

لتثبيت إصدار معيّن من الغلاف والصورة، وجّه أداة التشغيل الأولي إلى سكربت موسوم ومرّر الوسم (tag):

KERNAGENT_INSTALL_URL="https://raw.githubusercontent.com/Karib0u/kernagent/vX.Y.Z/scripts/install.sh" \
  bash <(curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/install.sh) --tag vX.Y.Z

يمكنك أيضًا التثبيت على commit محدد باستبدال vX.Y.Z بـ SHA الخاص بالـ commit في الرابط الخام.

الخيار 2 — Docker Compose (Linux / macOS / Windows + Docker Desktop)

git clone https://github.com/Karib0u/kernagent.git
cd kernagent
mkdir -p ~/.config/kernagent
cp config.env.example ~/.config/kernagent/config.env

# Pull pre-built image (recommended)
docker compose pull

# Or build locally for development
docker compose build

docker compose run --rm kernagent --help

حلّل الملفات الثنائية بتثبيت دليلها تحت /data:

docker compose run --rm \
  -v /absolute/path/to/binaries:/data \
  kernagent summary /data/sample.exe

في Windows (PowerShell + Docker Desktop)، استخدم مسارات مطلقة بنمط Windows مثل C:\malware:/data.

الخيار 3 — Docker مباشر (أي نظام تشغيل يعمل عليه Docker)

اسحب الصورة الجاهزة (مُوصى به):

mkdir -p ~/.config/kernagent
curl -fsSL https://raw.githubusercontent.com/Karib0u/kernagent/main/config.env.example \
  -o ~/.config/kernagent/config.env

docker pull ghcr.io/karib0u/kernagent:latest
docker run --rm \
  -v /absolute/path/to/binaries:/data \
  -v ~/.config/kernagent/config.env:/config/config.env:ro \
  ghcr.io/karib0u/kernagent:latest summary /data/sample.exe

أو ابنِ الصورة محليًا:

git clone https://github.com/Karib0u/kernagent.git
cd kernagent
docker build -t kernagent:local .
docker run --rm \
  -v /absolute/path/to/binaries:/data \
  -v ~/.config/kernagent/config.env:/config/config.env:ro \
  kernagent:local summary /data/sample.exe

التحقق من التثبيت

الخيار 1 (الغلاف):

kernagent --help
kernagent --version

شغّله مباشرة:

kernagent summary /path/to/binary.exe
kernagent ask /path/to/binary.exe "What does this binary do?"
kernagent oneshot /path/to/binary.exe

الخياران 2 أو 3 (Docker Compose / Docker مباشر):

تحقق من ذلك بتشغيل أمر المساعدة:

# Docker Compose
docker compose run --rm kernagent --help

# Raw Docker
docker run --rm ghcr.io/karib0u/kernagent:latest --help

إلغاء التثبيت

الخيار 1 (الغلاف):

kernagent-uninstall

الخياران 2 أو 3 (Docker Compose / Docker مباشر):

فقط احذف المستنسخة وأزل الصور:

docker image rm ghcr.io/karib0u/kernagent:latest
# or
docker image rm kernagent:local

التحديث

الخيار 1 (الغلاف):

kernagent-update          # switch to latest
kernagent-update --check  # check only
kernagent-update --tag vX.Y.Z  # pin to specific version

الخياران 2 أو 3 (Docker Compose / Docker مباشر):

أعد تنفيذ docker compose pull أو docker pull ghcr.io/karib0u/kernagent:latest.

لقطات الشاشة

Summary — نظرة عامة تنفيذية مع أدلة مُستشهد بها

Ask — أسئلة وأجوبة مركّزة مع مراجع متقاطعة وشرائح تفكيك

الأوامر

أول تشغيل — إذا لم توجد لقطة <name>_archive/، يبنيها kernagent تلقائيًا قبل الإجابة

summary

نظرة عامة تنفيذية: الغرض، القدرات، الدوال/الاستيرادات/السلاسل الرئيسية، مع عناوين يمكن التحقق منها

kernagent summary /path/to/binary
# raw JSON (for automation)
kernagent summary /path/to/binary --json

ask

أسئلة وأجوبة تفاعلية عبر اللقطة باستخدام أدوات آمنة (البحث في الدوال/السلاسل/الاستيرادات، تتبّع مخطط الاستدعاءات، قراءة التفكيك، حلّ المراجع المتقاطعة)

kernagent ask /path/to/binary "Show suspected C2 logic and evidence."

oneshot

تقرير فرز حتمي لتحليل CI/التحليل بالدفعات. التصنيف: MALICIOUS | GRAYWARE | BENIGN | UNKNOWN

kernagent oneshot /path/to/binary
# raw JSON (for automation)
kernagent oneshot /path/to/binary --json

تجاوزات عامة (لأي أمر):

# verbosity and per-run model/API overrides
kernagent -v --model gpt-4o \
  --base-url https://api.openai.com/v1 \
  --api-key sk-... \
  summary /path/to/binary

كيف يعمل (نظرة عامة في 20 ثانية)

1. استخراج مرة واحدة — بناء لقطة ثابتة باستخدام Ghidra/PyGhidra؛ تضيف قواعد CAPA تلميحات حول القدرات
2. أدوات للقراءة فقط — وكيل محدود النطاق (أو نصوصك البرمجية) يتنقل عبر اللقطة بأمان
3. إجابات مُستشهد بها — تشير النتائج دائمًا إلى أدلة ملموسة (عناوين EA وأسماء وسلاسل وواجهات برمجة API)

هيكل اللقطة (جزء منه)

<name>_archive/
├─ meta.json
├─ functions.jsonl
├─ strings.jsonl
├─ imports_exports.json
├─ callgraph.jsonl
├─ capa_summary.json
└─ decomp/*.c

إعداد النموذج

أنشئه مرة واحدة (خارج المستودع). المسار السريع:

kernagent-config

أو حرّر الملف يدويًا:

mkdir -p ~/.config/kernagent
cp config.env.example ~/.config/kernagent/config.env
$EDITOR ~/.config/kernagent/config.env

تجاوز عبر متغيرات البيئة:

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1   # or your gateway
export OPENAI_MODEL=gpt-4o                        # or your local model

أي نقطة نهاية متوافقة مع /v1/chat/completions تعمل.

مقارنات (باختصار)

• إضافات MCP/IDE — تحتاج إلى مفكّك قيد التشغيل ومشروعًا، وغالبًا ما تكون مرتبطة بواجهة رسومية
• kernagent — يعمل بدون واجهة ويُنتج لقطة محمولة يمكنك تحليلها في أي مكان، بما في ذلك البيئات المعزولة عن الشبكة

ضمانات التصميم

• قراءة فقط
• تحليل ثابت فقط
• حتمي
• قابل للتدقيق

المساهمة

نرحب بطلبات السحب (Pull Requests)

الترخيص

Apache 2.0 — انظر LICENSE