kunglao-agent

kunglao-agent هو نظام هندسة عكسية مستقل. تسلّمه هدفًا والأسئلة التي تحتاج إلى إجابات لها؛ فيعمل على المسألة لساعات أو أيام من تلقاء نفسه — يخطط مساره الخاص، ويتعافى من موت العمال، ويستأنف بعد الأعطال — ولا يتقارب إلا عندما تُستمد كل إجابة من أدلة خام وتصمد أمام بوابات التحقق الميكانيكي.

English · Simplified Chinese

يُشحن حاليًا كإضافة لـ Claude Code — Claude Code هو الواجهة التي تتحدث إليها، وليس ما هو المنتج. المنتج هو الحلقة: يحلّل عمال متخصصون (التحليل الساكن أولًا)، ويعيد مُتحقّق مستقل اشتقاق كل حقيقة بشكل أعمى من الأدلة الخام، وتقرر بوابات ميكانيكية متى ينتهي العمل. المُخرَج هو قاعدة حقائق تكون فيها كل دعوى مُثبَّتة على مستوى البايت، ومُتحقَّق منها بشكل مستقل، ومفهرسة بالأدلة — فالثقة تُفرض بالآليات، لا بالعُرف.

لماذا kunglao-agent

أفق طويل بالتصميم. تمتد المهام دون إشراف عبر ساعات وأيام: نبضة قلب مجدولة تُبقي الحلقة حيّة، ويُوفَّق بين العمال الموتى وتُعاد دعاواهم إلى قائمة الانتظار، وتستأنف الأعطال من الحالة على القرص، وتتعافى الدعاوى المحظورة ذاتيًا. تقرأ الحكم عند التقارب — ولا تراقب كل خطوة. انظر الاستقلالية طويلة الأفق.
إجابات يمكنك الوثوق بها. لا تُصنَّف أي حقيقة كـ PROVEN حتى يعيد مُتحقّق مستقل اشتقاقها بشكل أعمى من الأثر الخام؛ وكل حقيقة تستشهد بأثر خام مفهرس بـ sha256 عبر evidence/_index.json.
الطيف الكامل للهندسة العكسية. ملفات Windows/Linux الأصلية، وAndroid APKs، والويب/JS، وتحليل البروتوكولات، ومحاكاة البرامج الثابتة، وتدابير مكافحة التحكم بالمخاطر — نظام واحد، لا أداة أحادية المجال.
اقتصاديات التحليل الساكن أولًا. مهمة تُغلق ساكنًا لا تلمس الأدوات الديناميكية أبدًا؛ وكل تصعيد مُعلَن ومحظور ومُدقَّق.
يعيد استخدام المعرفة بدل إعادة اشتقاقها. كتالوج متنامٍ من أدوات التحليل المسجّلة (مفككات تشفير، وخطوط تفكيك، واستعلامات رسوم بيانية) يعني أن النظام يمدّ يده إلى أدوات مُثبتة قبل كتابة سكربتات لمرة واحدة — وكل تشغيل يترك وراءه حقائق قابلة لإعادة الاستخدام، لا محادثة تتبخر.
يتعافى بدل أن يموت. موت العمال، وانقطاع API، والأعطال أحداث من الدرجة الأولى: تكتشفها الحلقة، وتأخذ لقطة لما أُنتج بالفعل، وتعيد الإرسال للاستمرار من حيث توقف العمل — لا من الصفر.
بيئتك، قواعدك. VMware، أو ssh، أو docker، أو adb، أو ساكن فقط — يقود النظام أي قناة تنفيذ تملكها بالفعل. لا شيء وضع متدهور؛ فمهمة لا تحتاج تنفيذًا لا تطلب VM أبدًا.

البدء السريع

يعمل kunglao-agent داخل Claude Code. من عيّنة على القرص إلى حكم:

1. تثبيت الإضافة

من أي مجلد، في Claude Code:``` /plugin marketplace add amd2g2zz/kunglao-agent /plugin install kunglao-agent@kunglao-agent

(بديل: `claude --plugin-dir /path/to/kunglao-agent` للتطوير.)

### 2. تهيئة مساحة عمل```
/kunglao-agent:init ~/cases/synth-dropper --type windows

kunglao-init يهيّئ مساحة العمل، ويكتب CLAUDE.md، ويفحص سلسلة الأدوات الخاصة بـ --type لديك، ويهيّئ .mcp.json. وهو يرفض رفضًا قاطعًا عند غياب أداة مطلوبة لنوعك — وتوجد إرشادات الإصلاح في كتلة الخطأ.

3. حدّد المهمة وابدأ التحليل```

/kunglao-agent:analysis ~/cases/synth-dropper

Goal: confirm this dropper's persistence mechanism and network endpoints; every conclusion must be reproducible from raw evidence. Verification: key findings count only if an independent verifier re-derives them blind and reaches the same answer. Constraints: static-first; never execute the sample on the host.

اكتب الموجز بحيث يستطيع مراجع مستقل الحكم على النتيجة: **هدف التحليل** (ما تحتاج إلى معرفته)، **منطق التحقق** (ما الذي يجعل الإجابة موثوقة — مثل "يجب أن تكون التوقيع قابلاً لإعادة الإنتاج من نفس المدخلات")، **القيود** (مثل "عدم التنفيذ على المضيف"). يتم تسجيل كل شيء في `task_spec.yaml`؛ ومن هناك تُدير الحلقة نفسها. لمعرفة كيف تتحول الطلبات الشائعة إلى عبارات جيدة الصياغة، راجع [كيفية صياغة المهمة](#how-to-state-the-task).

### 4. اقرأ المُخرَج```
claim-register.yaml   # every claim terminal, with verifier sign-off
facts/F<NNN>.md       # byte-anchored, reproducible, frontmatter contract
evidence/_index.json  # every fact → raw artifact (sha256 + path)
runs/                 # session audit trail

كيفية تحديد المهمة

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

"我要纯算" — "الخوارزمية الصافية فقط"

يعني عادةً: إعادة إنتاج دون اتصال لروتين التوقيع/التشفير الخاص بالتطبيق — أداة unidbg أو إعادة كتابة تعمل بلا جهاز وبلا تطبيق وقت التشغيل. ليس "تحليل التطبيق"؛ فالتطبيق ليس سوى المكان الذي توجد فيه الخوارزمية.```

Sample: the v7.2 APK; behavior: the signer producing the sign header on api.example.com/v2/* requests. Criterion: a standalone reproduction (unidbg or rewrite) replays every captured (input → sign) pair byte-exact — including the withheld pairs — with no device or app at run time. Attach: captures/sign-pairs.jsonl — 20 input/output pairs captured from a live session; 10 of them withheld from the analysis.

**مراسي Oracle على:** إعادة تشغيل مطابقة بايت ببايت على كل زوج، بما في ذلك الأزواج المحجوزة — وإعادة الإنتاج التي تعمل بشكل مستقل.

### "我要解密" — "أريد فك التشفير"

**عادةً يعني أحد هدفين مختلفين — حدّد أيهما:**

- **(أ) فك تشفير جسم واحد ملتقط** — إجابة لمرة واحدة حول هذه البيانات: "أنتج النص الصريح لملف الذاكرة المؤقت الملتقط هذا."
- **(ب) قدرة على فك التشفير** — الخوارزمية + استعادة المفتاح، قابلة لإعادة الاستخدام على البيانات التي تلتقطها غدًا.

جيد الصياغة (أ):```
> Sample: the v7.2 APK; behavior: the local config cache
>   files/.cfg/v2.dat is encrypted at rest.
> Criterion: produce the plaintext of the captured v2.dat and validate
>   it against what the app renders (field names and values match the
>   screenshot captured alongside).

حسن التكوين (ب):```

Sample: the v7.2 APK; behavior: request bodies on api.example.com/v2/* are encrypted with a static key. Criterion: identify the algorithm and the key, then run a canary round-trip — encrypt a known plaintext with the recovered key and match the ciphertext the device produced, byte for byte. Attach: captures/request-bodies.jsonl — ciphertext bodies captured from the device, with the requests that produced them.

**مراسي Oracle على:** (أ) النص العادي الذي يتحقق مقابل ما يعرضه التطبيق؛ (ب) الخوارزمية + المفتاح المحدد والرحلة ذهابًا وإيابًا للـ canary مطابقة بايت ببايت للنص المشفر المنتج من الجهاز. "لقد فك التشفير مرة واحدة" لا يحقق أيًّا منهما.

### "帮我分析这个协议" — "حلّل لي هذا البروتوكول"

**يعني عادةً:** استعادة تنسيق الإرسال — التأطير، ودلالات الحقول، وبرنامج ترميز/فك ترميز يمكنك تشغيله.```
> Sample: the Android chat app; behavior: the TCP protocol on
>   gateway.example.com:443, as captured in gateway-session.pcap.
> Criterion: a codec that round-trips every captured frame byte-exact,
>   and decodes the held-out frame to fields matching the observed app
>   behavior.
> Attach: captures/gateway-session.pcap — 40 frames, plus 1 held-out
>   frame kept out of the analysis.

مراسي Oracle على: إعادة ترميز وفك ترميز كل إطار ملتقط بايت-بايت بدقة، وفك ترميز الإطار المحتفظ به إلى حقول تطابق سلوك التطبيق الملاحظ.

"这个 sign 在哪算的" — "أين يُحسب هذا التوقيع؟"

يعني عادةً: موقع مع دليل. تسمية نقطة في الكود أمر سهل؛ الإجابة لا تكون مفيدة إلا مع دليل على أن هذه النقطة هي النقطة المقصودة.```

Sample: the v7.2 APK; behavior: the sign header attached to every request. Criterion: name the class/method (or native function) where sign is computed, and hook that point to reproduce the captured sign values from the same inputs. Attach: captures/sign-session.jsonl — captured sign values with their request inputs.

**مراسي Oracle على:** فئة/دالة/دالة أصلية مُسمّاة، بالإضافة إلى hook عند تلك النقطة يعيد إنتاج القيم المُلتقطة.

### ما تشترك فيه هذه الأمور

- **سمِّ العينة والسلوك** — أي معامل، أو مدخل، أو تدفق — وليس الفئة. "我要纯算" فئة؛ أما "الموقّع الذي ينتج ترويسة `sign` على api.example.com/v2/*" فهو هدف.
- **النجاح يجب أن يكون بيانات.** أرفق أزواج المدخلات/المخرجات المُلتقطة؛ فالأزواج المحجوزة هي ما يجعل التحقق صادقًا — إذ لا يمكن لإعادة الإنتاج أن تُفرط في التخصيص لبيانات لم يرها قط.
- **يُشتق الـ oracle من الحالة النهائية التي حددتها.** عبارة غامضة، تحقق غامض، تحليل منحرف.
- **القيود تغيّر الخطة.** ثابت فقط؟ جهاز متاح؟ أي قناة؟ اذكر ذلك مسبقًا — فهو يحدد المسار قبل بدء العمل (انظر [أحضر بيئتك الخاصة](#bring-your-own-environment)).

## الأوامر الفرعية

| الأمر | استخدمه عندما | ما يفعله |
|---|---|---|
| `/kunglao-agent:init <workspace> [--type windows\|linux\|android\|web\|macos] [--lane malware\|algorithm\|protocol\|web\|data\|app]` | بدء مهمة، أولًا | يهيّئ مساحة العمل، ويفحص سلسلة الأدوات الخاصة بالنوع، ويكتب `CLAUDE.md` و`.mcp.json`؛ يرفض بشكل صارم مع إرشادات إصلاح عند غياب أداة مطلوبة |
| `/kunglao-agent:analysis <workspace>` (الاسم المستعار `analyze`) | بعد init — حدد المهمة وابدأ | يجمع هدفك / منطق التحقق / القيود مرة واحدة، ثم يشغّل حلقة التقارب: دورات إرسال / تحقق حتى التقرير |
| `/kunglao-agent:resume <workspace>` | بعد انهيار، أو إعادة تشغيل، أو أي "أين كنت؟" | موجز نقطة توقف للقراءة فقط (الحالة الصحية، الادعاءات المفتوحة، العمال قيد التنفيذ، الجدول الزمني للانهيار) بالإضافة إلى الإجراء التالي من آلة الحالة |
| `/kunglao-agent:upgrade <workspace> [--dry-run]` | بعد تحديث إضافة، على مساحة عمل أقدم (أو عندما تقول رسالة الترقية إن الطابع متأخر) | يهاجر هيكل مساحة العمل (الـ hooks، القوالب، مفردات الأحداث) إلى إصدار الإضافة الحالي؛ `--dry-run` يعرض معاينة؛ لا تُمس بيانات المستخدم (الادعاءات، الحقائق، الأدلة) أبدًا — انحراف البايتات يرفض مع RC=4 |
| `/kunglao-agent:help` | أي شيء آخر | يطبع قائمة الاستخدام |

الترتيب المعتاد: `init` ينشئ مساحة العمل → `analysis` يحدد المهمة ويبدأ → (`resume` إذا انحرف أي شيء) → اقرأ التقرير عند التقارب → `upgrade` لمساحات العمل القديمة بعد تحديثات الإضافة.

## كيف تبدو الجولة

*شكل المهمة — ما تكتبه، وما يعود إليك، وأين تنظر.* مثال اصطناعي: dropper صغير لنظام Windows يهبط في `~/cases/synth-dropper`:```bash
/kunglao-agent:init ~/cases/synth-dropper --type windows   # probes Ghidra, VM reachability
/kunglao-agent:analysis ~/cases/synth-dropper
> "What does this binary do, and where does it phone home?"

من هناك تُدير الحلقة نفسها — يتكيّف المسار مع ما تتبيّن عليه العيّنة. يمكنك أن تبتعد (انظر الاستقلالية طويلة الأمد). عندما تتقارب، اقرأ المُخرَج أدناه.

السيناريوهات

مساران إضافيان من البداية إلى النهاية — اختر المسار المطابق لهدفك (بالنسبة لملف Windows PE / Linux ELF عادي، الحالة المُنجزة أعلاه هي المسار).

Android APK — ما يكتبه المستخدم، وما يستقرّ وأين

```bash /kunglao-agent:init ~/cases/sample.apk --type android /kunglao-agent:analysis ~/cases/sample.apk > "Does this APK load code dynamically or fight debugging? If so, where is > the hidden logic and what does it do?" ``` - **يستقر في:** `bins/` (ملف APK)، `facts/` (مخطط الفئات، جرد ملفات `.so` الأصلية)، `evidence/` (عمليات الالتقاط، التفريغات). - **شكل الإنجاز:** كل سؤال مدعوم بأدلة قابلة لإعادة الإنتاج. - **المسار يتكيّف.** بعض ملفات APK تُغلق بعمل DEX ثابت بحت؛ وأخرى تحتاج إلى تصحيح على الجهاز — الحلقة تقرر بناءً على ما تكون عليه العينة فعليًا.

Web / JS — فك الحزمة → إزالة التشويش → إعادة تشغيل المعاملات الموقّعة

```bash /kunglao-agent:init ~/cases/example-site.com --type web /kunglao-agent:analysis ~/cases/example-site.com > "how is the XHR request signed, and where does the nonce come from?" ``` - **يستقر في:** `evidence/` (عمليات الالتقاط، الكود المُزال التمويه)، `facts/` (مفتاح التوقيع، اشتقاق nonce). - **ملاحظة:** `web` هدف في مرحلة بيتا — عتبة سلسلة الأدوات خفيفة عن قصد؛ القدرة المفقودة تظهر عندما تحتاجها الحلقة فعلاً، لا عند التهيئة.

ما الذي تحصل عليه

سجل ادعاءات وقاعدة حقائق تكون الثقة فيه ميكانيكية، لا عُرفية:

تقارب موثّق — يتطلب PROVEN توقيع مطابقة تامة من مُدقّق أعمى مستقل؛ ويتطلب CONVERGED الإجابة على كل سؤال أساسي بدليل بايتي، وصفر ادعاءات يتيمة، وعدم الدوران.
سلامة الأدلة — كل حقيقة تُتتبَّع عبر evidence/_index.json إلى أثر خام (التقاط / تتبع / تفريغ / ملف ثنائي). الملخصات المشتقة مستبعدة بحكم التصميم.
الصانع-المدقق — العامل (الصانع) يكتب الحقائق؛ ومدقق redteam (المدقق) يعيد اشتقاقها بشكل أعمى. وكلاء مختلفون، دائماً.

لا يصل أي ادعاء إلى PROVEN بمجرد كلام صاحبه: يجب على مدقق مستقل إعادة اشتقاقه بشكل أعمى، ويجب اجتياز مجموعة من البوابات الميكانيكية. يوجد تصميم البوابات الكامل في docs/design/loop-engineering.md.

بعد التشغيل، تجيب الملفات عن أسئلة مختلفة:

مثال على حقيقة:```yaml id: F061 status: VERIFIED-BY-W01-static-byte-recheck claim_id: C-401 provenance:

{role: sample, path: bins/}
{role: capture_log, path: runs/c329-inner-pe.bin} # via evidence/_index.json reproduce: python -c "import struct; ..." # runs against the cited artifact verifier_sign_off: {verifier: kunglao-redteam, verdict: CONFIRMED}

## الاستقلالية طويلة المدى

المهام الحقيقية ليست محادثة مدتها عشرون دقيقة. يبقى kunglao-agent على المشكلة دون أن يوجّهه إنسان في كل خطوة:

- **يعمل لساعات أو أيام، دون إشراف** — تُبقي نبضة مجدولة الحلقة تعمل بين زياراتك، وتُعلَّم الحلقة المتوقفة بدلاً من أن تموت بصمت.
- **يتعافى من الفشل** — يُستبدل العمال الميتون أو العالقون وتُعاد أسئلتهم إلى قائمة الانتظار؛ العمل المحظور يتعافى ذاتياً بدلاً من أن يظل خامداً.
- **ينجو من الأعطال وإعادة التشغيل** — يعيد `/kunglao-agent:resume <workspace>` بناء ما كانت عليه الأمور من الحالة على القرص ويسمّي الإجراء التالي.
- **يتذكر على القرص، لا في المحادثة** — المطالبات والحقائق والأدلة وسجل تدقيق كامل تعيش في مساحة العمل، فيمكن لأي جلسة أن تستأنف المهمة.

تعطيه هدفاً والأسئلة؛ فيعمل على المشكلة لساعات أو أيام، ويتعافى من الإخفاقات، وتقرأ الحكم عندما يتقارب.

## الحصول على نتائج جيدة

- **زوّده بأهداف يمكن الوصول إليها بشكل ساكن.** الحلقة ساكنة أولاً: ملف APK غير المحزوم، أو حزمة غير مموّهة، أو ملف ثنائي غير مجرّد يتقارب أسرع بكثير من واحد يفرض عملاً ديناميكياً.
- **جهّز المسار الديناميكي قبل أن تحتاجه.** إذا كانت أسئلتك الأساسية ستتطلب تنفيذاً، فاختر قناة أولاً (انظر [أحضر بيئتك الخاصة](#bring-your-own-environment)) — يرفض init بشكل صارم مهمة ديناميكية على `local`.
- **التمييز بين "يعمل" و"عالق"** — الإدخالات الجديدة في `runs/` تعني أن الحلقة حية؛ نبضة ميتة أو القرار نفسه يتكرر دون حقائق جديدة يعني أنها ليست كذلك — يشخّص `/kunglao-agent:resume <workspace>` ويسمّي الخطوة التالية.

## سلسلة الأدوات حسب الهدف

يحدد `--type` الذي تختاره عند init أي أدوات من فئة HARD يجب تثبيتها. الإرشادات مطوية — وسّع هدفك. **جميع الأنواع تتطلب خادمي MCP:** `ghidra` (`claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe`) و`sequential-thinking` (`claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking`).

<details>
<summary><strong>windows (PE32+ x86-64)</strong> — ملفات Windows الثنائية الأصلية</summary>

| الفئة | الأداة | التثبيت |
|---|---|---|
| HARD | `pefile` (Python) | `pip install pefile` |
| HARD | `die` (Detect It Easy) | متغير بيئة `KUNGLAO_DIE` أو على PATH — [ntinfo.com](https://ntinfo.com) |
| HARD | `floss` (FLARE FLOSS) | حسب [flare-floss docs](https://github.com/mandiant/flare-floss) |
| HARD | Ghidra أو IDA | أحدهما؛ انظر [Internals](#internals) |
| HARD (T2/T3) | VMware + vmr-shell، أو قناة ssh/docker | انظر [أحضر بيئتك الخاصة](#bring-your-own-environment) |
| HARD (T2/T3) | `frida-server` (مُعاد تسميته، منفذ مخصص) | ملف ثنائي على الجهاز/الآلة الافتراضية، المنفذ الافتراضي 1337 |

يستخدم Windows T3 الديناميكي أيضاً MCP الخاص بـ `x64dbg`؛ `volatility` (تحليل الذاكرة الجنائي) وIDA-Pro MCP اختياريان — انظر بيان MCP تحت [Internals](#internals).

</details>

<details>
<summary><strong>linux (ELF)</strong> — ملفات Linux الثنائية الأصلية / البرامج الثابتة / صور الذاكرة</summary>

| الفئة | الأداة | التثبيت |
|---|---|---|
| HARD | `file`، `readelf`، `objdump` | حزمة `binutils` |
| HARD | Ghidra أو IDA | أحدهما |
| HARD (T2/T3) | VMware + vmr-shell، أو مستوى تحكم ssh/docker | انظر [أحضر بيئتك الخاصة](#bring-your-own-environment) |
| HARD (T2/T3) | `frida-server` (مُعاد تسميته، منفذ مخصص) | ملف ثنائي على الجهاز، المنفذ 1337 |
| WARN | `gdbserver` (على PATH في المضيف)، `strace`، `ltrace` | إضافات اختيارية |

يمكّن `ssh-mcp` مستوى تحكم ssh للمضيفين البعيدين / السحابيين / docker.

</details>

<details>
<summary><strong>android (APK / DEX / native .so)</strong> — أصعب نوع أهداف، وأكثر عناصر HARD</summary>

| الفئة | الأداة | التثبيت |
|---|---|---|
| HARD | `aapt` أو `aapt2` (أو `unzip` كبديل) | Android SDK build-tools |
| HARD | `jadx` (DEX → Java decompiler) | [skylot/jadx](https://github.com/skylot/jadx) |
| HARD | `apktool` (APK resource decode/rebuild) | [iBotPeaches/Apktool](https://github.com/iBotPeaches/Apktool) |
| HARD | `gitnexus` (post-decompile graph) | `npm i -g gitnexus` |
| HARD | Ghidra أو IDA | فقط إذا كان APK يحتوي على `.so` أصلي |
| HARD | `adb` + **جهاز مُروّت** مع `ro.debuggable=1` | platform-tools + frida مخصص على الجهاز |
| HARD | `frida-server` (مُعاد تسميته، منفذ مخصص 1337) | ملف ثنائي على الجهاز |
| HARD | `android_server` (IDA remote debugging) | ملف ثنائي على الجهاز، المنفذ 23946 |
| WARN | `apkid` | `pip install apkid` |
| WARN | `baksmali` | من [smali releases](https://github.com/baksmali/smali/releases) |

</details>

<details>
<summary><strong>web &amp; macos (beta)</strong> — سلاسل أدوات بسيطة، بلا عناصر HARD بحكم التصميم</summary>

| الفئة | الأداة | التثبيت |
|---|---|---|
| WARN | `camoufox-reverse` MCP (web) | Firefox مضاد للكشف لاعتراض / تتبع / التقاط الشبكة |
| WARN | `docker` (القناة الافتراضية للويب) | Docker Desktop، أو عيّن `KUNGLAO_CHANNEL=ssh` صراحةً |
| WARN | `lipo`، `otool`، `nm`، `codesign`، `xattr` (macOS) | Xcode Command Line Tools |
| WARN | `ghidra` MCP (macOS) | موصى به — انظر البيان تحت [Internals](#internals) |

كلاهما هدفان في مرحلة بيتا: تظهر القدرات المفقودة عندما تحتاجها الحلقة فعلاً، لا عند init. يستخدم العمل الديناميكي على macOS قناة `ssh` (إلى مضيف Mac)؛ لمسار تصحيح المتصفح الاختياري x64dbg، ثبّت سلسلة أدوات Windows أعلاه.

</details>

مصدر بيان واحد لكل ما سبق — افحصه في أي وقت: `python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos>` (exit 1 = HARD مفقود).

## أحضر بيئتك الخاصة

يحتاج التصحيح الديناميكي إلى مستوى تحكم في التنفيذ يستطيع الوكيل تشغيله. يختار `KUNGLAO_CHANNEL` واحدة من خمس قنوات من الدرجة الأولى — استخدم ما تملكه بيئتك بالفعل؛ لا شيء منها وضع متدهور:

| القناة | ما تشغّله | المتطلبات المسبقة |
|---|---|---|
| `vmr` (افتراضي) | آلة VMware الافتراضية، **أي نظام ضيف** — سير عمل snapshot/revert هو قيمتها التي لا تُعوَّض | مهارة vmr-shell؛ `KUNGLAO_VM_HOST` + المنفذان 9876/1337 |
| `ssh` | أي جهاز يمكن الوصول إليه عبر ssh: عتاد فعلي، آلة سحابية، Mac، مضيف docker بعيد | مصادقة بالمفتاح — يشغّل الفحص `ssh ... true` حقيقياً بـ BatchMode |
| `docker` | خادم docker محلي أو بعيد — `docker exec` مكافئ لأي مسار تحكم | `docker version` يعمل؛ `KUNGLAO_DOCKER_CONTAINER` اختياري |
| `adb` | محاكي Android أو جهاز حقيقي | يُظهره `adb devices`؛ `adb forward tcp:1337 tcp:1337` لـ frida |
| `local` | **تحليل ساكن فقط على المضيف** | لا شيء — انظر الخط الأحمر |

> **الخط الأحمر لـ `local`:** local للعمل **الساكن** فقط — لا تنفّذ أو تصحّح أو تحقن العينة على المضيف أبداً. أي متطلب ديناميكي يبدّل `KUNGLAO_CHANNEL` إلى `vmr`/`ssh`/`docker`/`adb`؛ يرفض init بشكل صارم مهمة ديناميكية على `local`.

تُشغَّل فحوصات القنوات للمهام الديناميكية فقط (المهام الساكنة فقط تتخطاها). يمر تنفيذ قناة `ssh` عبر مستوى تحكم **ssh-mcp** (`npm i -g ssh-mcp`)؛ وssh عبر CLI العادي هو البديل. لـ docker البعيد عبر ssh، عيّن `KUNGLAO_DOCKER_CONTAINER`.

## الإعدادات

أربعة متغيرات تغطي معظم الإعدادات:

| المتغير | الافتراضي | المعنى |
|---|---|---|
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | غير معيّن | يجب أن يبقى غير معيّن أو `0` — القيم الصادقة توجّه الإرسالات عبر قناة الفريق وتُرفض |
| `KUNGLAO_CHANNEL` | `vmr` | مستوى تحكم التنفيذ الديناميكي: `vmr` \| `ssh` \| `docker` \| `adb` \| `local` — انظر [أحضر بيئتك الخاصة](#bring-your-own-environment) |
| `KUNGLAO_VM_HOST` | غير معيّن | الآلة الافتراضية/المضيف للتحليل الديناميكي (vmr-shell :9876، Frida :1337) |
| `GHIDRA_HOME` | غير معيّن | جذر تثبيت Ghidra (يجب أن يحتوي على `support/analyzeHeadless.bat`) |

نادراً ما تُحتاج: `KUNGLAO_DOCKER_CONTAINER` (هدف تنفيذ docker لقناتي `ssh`/`docker`)، `KUNGLAO_FRIDA_PORT` (الافتراضي 1337)، `KUNGLAO_DIE` (مسار DIE، يعود إلى PATH)، `KUNGLAO_CLAUDE_JSON` (تجاوز اختباري لسجل MCP على مستوى المستخدم).

## السلامة

- لا تُنفَّذ العينات على المضيف أبداً — يفرض ذلك خطاف `block_malware_exec`؛ العمل الديناميكي يعمل على الآلة الافتراضية/الحاوية/الجهاز فقط ويتطلب تصريحاً لكل جلسة.
- تسلسل الحقيقة الأساسية: الأثر الخام > الأداة المحلية > الصندوق الرملي > استخبارات التهديدات (CTI فرضية قابلة للتكذيب، وليست حقيقة أبداً).
- صانع-مدقق: لا يتحقق العامل من نفسه أبداً؛ ولا يقرأ المدقق استنتاج الصانع أبداً.
- لا تُلتزم الملفات الثنائية والإعدادات والخطافات أبداً؛ وتُستبعد الأسرار من مساحات العمل والمستودع.

## التطوير

المساهمات مرحّب بها. سير العمل: تفرّع من `dev`، فرع واحد لكل تغيير، وPR عائد إلى `dev`.```bash
git worktree add .worktrees/<name> -b <name> dev
uv sync --locked
uv run python -m pytest -q
gh pr create --base dev

الوثيقة المرجعية الكاملة هي python -m pytest -q (انظر .github/workflows/release-check.yml).

توجد وثائق التصميم في docs/ و specs/. انظر License.

Internals

MCP supply (the full manifest)

مصدر الحقيقة الوحيد: scripts/mcp_probe.py؛ يقوم kunglao-init بإنشاء ملف .mcp.json لمساحة العمل عند غيابه (--no-mcp يتخطاه؛ لا يتم استبدال ملف موجود أبدًا). الفحص: python scripts/mcp_probe.py <ws> --type <windows|linux|android|web|macos> — رمز الخروج 1 = HARD مفقود، 2 = WARN مفقود فقط.

Workspace layout

مساحة عمل واحدة لكل engagement لعينة:

``` / ├── bins/ # the sample (gitignored) ├── task_spec.yaml # primary_questions / scope / constraints / success_criteria ├── claim-register.yaml # claims C-NN with status (OPEN/PROVEN/STAMP/...) ├── claim_deps.yaml # claim DAG ├── facts/ # byte-anchored facts F-NNN.md + _INDEX.md ├── evidence/ # raw artifacts + _index.json (eid → path + sha256) ├── runs/ # worker-status, plans, ledgers, .heartbeat.json ├── blockers/ # failure-attribution records per claim └── CLAUDE.md # workspace rules, generated by kunglao-init ``` يتم ربط خطافات kunglao على مستوى مساحة العمل؛ لا تتم الكتابة أبدًا في ملف `~/.claude/settings.json` العام الخاص بك.

الترخيص

مرخّص بشكل مزدوج: AGPL-3.0 للاستخدام الشخصي والأكاديمي والداخلي (مجاني — راجع LICENSE)؛ ويلزم ترخيص تجاري للاستخدام التجاري مغلق المصدر أو القائم على SaaS — راجع LICENSE-commercial.md.

Claude Code	حيث يعمل kunglao-agent	وفق وثائق Anthropic
Python 3.10+ (Python 2 غير مدعوم)	تحمل الإضافة بيئة مثبّتة عبر `uv`؛ لا تلمسها أنت	على النظام أو مُدارة بـ `uv`
`uv`	مُحلّل بيئة مُقفَل	`pip install uv` أو astral.sh/uv
Ghidra أو IDA	مجموعة تحليل ساكن واحدة للتفكيك	انظر سلسلة الأدوات حسب الهدف

هل انتهى؟	رمز خروج الحلقة — `CONVERGED` (0) يعني أن كل سؤال أساسي له إجابة موثّقة؛ حالة كل ادعاء في `claim-register.yaml`
ماذا وجد؟	`facts/F<NNN>.md` — حقيقة واحدة مثبتة بالبايت لكل ملف، مرتبطة بالادعاءات عبر `claim-register.yaml`
كيف أعيد إنتاجه؟	`evidence/_index.json` — حقيقة → أثر خام (مسار + sha256)؛ كل حقيقة تحمل أمر `reproduce:`
ماذا حدث بالضبط؟	`runs/` — السجل لحظة بلحظة وحالة العامل

`ghidra`	HARD	required, all types	decompilation / static analysis	`claude mcp add ghidra -- <path>/bridge-mcp-ghidra.exe`
`sequential-thinking`	HARD	required, all types	structured reasoning	`claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking`
`x64dbg`	HARD	Windows T3 dynamic	dynamic debugging (VM remote)	`claude mcp add x64dbg -- x64dbg-automate-mcp`
`volatility`	WARN	Windows T3	memory forensics	`claude mcp add volatility -- python <path>/volatility_mcp_server.py`
`ida-pro-vm`	WARN	when IDA chosen	remote IDA analysis	`claude mcp add --transport http ida-pro-vm <ida-mcp-url>`
`gitnexus`	HARD	Android graph building	post-decompile knowledge graph	`claude mcp add gitnexus -- gitnexus mcp`
`virustotal`	WARN	CTI	threat intel (family-attribution hypotheses)	`claude mcp add virustotal -- npx -y @burtthecoder/mcp-virustotal`
`ssh-mcp`	WARN	channel	ssh execution control plane	`claude mcp add ssh-mcp -- ssh-mcp`
`camoufox-reverse`	WARN	web (beta)	browser JS reversing (hooks / trace / network capture)	`claude mcp add camoufox-reverse -- python -m camoufox_reverse_mcp`

الأكثر شعبية

kunglao-agent

kunglao-agent

لماذا kunglao-agent

البدء السريع

1. تثبيت الإضافة

3. حدّد المهمة وابدأ التحليل```

كيفية تحديد المهمة

"我要纯算" — "الخوارزمية الصافية فقط"

"这个 sign 在哪算的" — "أين يُحسب هذا التوقيع؟"

السيناريوهات

ما الذي تحصل عليه

Internals

الترخيص