> [!TIP]
> وثائق المساهمين: اقرأ `docs/gosentry/index.md` للحصول على خريطة الكود، وحلقة التطوير الموصى بها، ونقاط دخول CI، وسكربتات القياس.
> يستخدم هذا الفرع تطبيق Pull GitHub لفتح ودمج PRs تلقائيًا من `golang/go:master` إلى `master`، مما يضمن ألا نتخلف أبدًا عن أحدث تحديثات سلسلة أدوات Go.

## الميزة 1: الاختبار التلقائي المبني على البنى (fuzz structs كمدخلات)

#### نظرة عامة

الاختبار التلقائي الأصلي في Go (`go test -fuzz=...`) يدعم فقط مجموعة صغيرة من الأنواع العددية كوسائط للاختبار التلقائي (`[]byte`, `string`, أرقام, ...). في gosentry، يمكنك أيضًا اختبار **الأنواع المركبة** المبنية من تلك الأنواع العددية: البنى (structs)، المصفوفات، الشرائح، والمؤشرات.
هذا مفيد عندما يتلقى الكود الخاص بك مدخلات منظمة بشكل طبيعي ولا تريد بناء مُرمِّز/مُفكِّك ترميز مخصص فقط لتزويد المجموعة (corpus) وتغييرها.
انظر `test/gosentry/examples/multiargs` و `test/gosentry/examples/composite` للحصول على أمثلة.

#### مثال بسيط```go
type Input struct {
	Data []byte
	S    string
	N    int
	OK   bool
}

func FuzzStructInput(f *testing.F) {
	// Seed the initial corpus with a Go struct (gosentry feature).
	f.Add(Input{Data: []byte("A"), S: "B", N: 7, OK: true})

	f.Fuzz(func(t *testing.T, in Input) {
		if in.OK && in.N == 1337 && in.S == "BOOMMOOB" && bytes.Equal(in.Data, []byte("A")) {
			t.Fatalf("boom")
		}
	})
}

أحيانًا قد لا يعمل هذا، والسبب أن Go تقوم بتضمين الدالة (inlining). إذا لم يكن `// overflow_false_positive` كافيًا، أضف `//go:noinline` قبل توقيع الدالة الخاصة بك.

## الميزة 3: التسبب في panic عند استدعاء دوال محددة

عند فحص الأهداف باستخدام fuzzing، قد نكون مهتمين بتفعيل panic عند استدعاء دوال معينة. على سبيل المثال، قد تصدر بعض البرامج رسائل `log.error` بدلاً من التسبب في panic، على الرغم من أن هذه الحالات غالبًا ما تشير إلى حالات يريد باحثو الأمان اكتشافها أثناء fuzzing.
ومع ذلك، عادةً ما يتم التعامل مع هذه الأخطاء داخليًا (على سبيل المثال، عبر آليات إعادة المحاولة أو الإيقاف المؤقت، أو عبر طباعة الرسائل في السجلات)، مما يجعلها غير مرئية إلى حد كبير لأدوات fuzzing. الهدف من هذه الميزة هو معالجة هذه المشكلة.

#### طريقة الاستخدام

قم بتجميع gosentry، ثم استخدم الخيار `--panic-on`.```bash
./bin/go test -fuzz=FuzzHarness --use-libafl --focus-on-new-code=false --catch-races=false --catch-leaks=false --panic-on="test_go_panicon.(*Logger).Warning,test_go_panicon.(*Logger).Error"

استخدم `-fuzztime=1m` لإيقاف حملة LibAFL بعد دقيقة واحدة.

توليد تقرير التغطية من مجموعة حملة LibAFL موثق في [الميزة 8](#feature-8-generate-go-coverage-reports-from-fuzzing-campaign).

التضمين القائم على القواعد (Nautilus) موثق في [الميزة 7](#feature-7-grammar-based-fuzzing-nautilus).

<details>
<summary><strong>كيف يتم ربط Go مع LibAFL معًا</strong></summary>```text
┌───────────────────────────────────────────────────────────────────────────┐
│ 1) gosentry `go test`                                                      │
│    - captures  `testing.F.Fuzz(...)` callback                             │
│    - generates  extra source file: `_libaflmain.go`                       │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 2) Generated bridge: `_libaflmain.go`                                     │
│    - provides libFuzzer-style C ABI entrypoints:                          │
│        LLVMFuzzerInitialize                                               │
│        LLVMFuzzerTestOneInput                                             │
│    - adapts bytes -> Go types -> calls the captured fuzz callback         │
└───────────────┬───────────────────────────────────────────────────────────┘ 
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 3) `libharness.a` (static archive on disk) contains:                      │
│      - compiled objects for all test package (+ dependencies)             │
│      - generated `_testmain.go` + `_libaflmain.go`                        │
│      - LLVMFuzzerInitialize                                               │
│      - LLVMFuzzerTestOneInput                                             │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 4) `golibafl/` (Rust + LibAFL)                                            │
│    env: HARNESS_LIB=/path/to/libharness.a                                 │
│    fuzz loop: mutate input -> LLVMFuzzerTestOneInput(data) -> observe     │
└───────────────────────────────────────────────────────────────────────────┘

أدوات التضمين المتطورة (SOTA) مثل AFL++ أو LibAFL كانت ستكتشف الانهيار (panic) فورًا في تلك الحالة. لكن أداة التضمين الأصلية للغة Go لن تفعل ذلك. تلك فجوة هائلة تعيق استكشاف التغطية **بكثير**.

المعيار أدناه يُظهر هذه الحدود. لاحظ أن هذه المعايير يمكن **إعادة إنتاجها** وتحسينها عبر [مستودع gosentry-bench-libafl](https://github.com/kevin-valerio/gosentry-bench-libafl/tree/main).

##### المعيار 1:

الرسم البياني أدناه يوضح تطور عدد الأسطر المغطاة أثناء التضمين (Fuzzing) لمكتبة [UUID](https://github.com/google/uuid) الخاصة بجوجل باستخدام LibAFL مقابل أداة التضمين الأصلية للغة Go.
![BENCH1](https://assets.kitploit.com/production/public/readmes/41918/7b1ea005996846c9ee4d7c0d42fee26731050d10b6b21d59c551e4b1b956923e.png "BENCH1")

##### المعيار 2:

الرسم البياني أدناه يوضح تطور عدد الأسطر المغطاة أثناء التضمين (Fuzzing) لمشروع [go-ethereum](https://github.com/ethereum/go-ethereum) باستخدام LibAFL مقابل أداة التضمين الأصلية للغة Go.
![BENCH2](https://assets.kitploit.com/production/public/readmes/41918/61aab8540ab8d339307854de6737a405056c3c8ad83a822df40f74e362b93021.png "BENCH2")



#### مثال
يمكنك اختباره على بعض أحزمة التضمين (fuzzing harnesses) في المسار `test/gosentry/examples/`.```bash
cd test/gosentry/examples/reverse
../../../../bin/go test -fuzz=FuzzReverse --focus-on-new-code=false --catch-races=false --catch-leaks=false

ملاحظات:
- `<harness>` هو اسم هدف الـ fuzz عندما يكون `-fuzz` معرّفًا بسيطًا مثل `FuzzXxx` (أو `^FuzzXxx$`)، وإلا فإنه يكون `pattern-<hash>`.
- توليد التغطية (`--generate-coverage`) يستخدم نفس القاعدة للعثور على مجموعة `queue/` الصحيحة، لذا يجب تشغيله من نفس الحزمة مع نفس `-fuzz=...`.

## الميزة 5: التضمين الموجَّه بـ Git-blame (تجريبي)

#### نظرة عامة

التضمين الموجَّه بالتغطية ممتاز في استكشاف مسارات جديدة، لكنه يعامل جميع الأكواد المغطاة على أنها مثيرة للاهتمام بنفس القدر. عند تضمين قواعد أكواد كبيرة، قد ترغب في تحيز أداة التضمين نحو الأكواد المعدلة مؤخرًا، حيث من المرجح أن تُدخل الانحدارات والعلل. في وضع LibAFL، يمكن لـ gosentry استخدام `git blame` لتفضيل المدخلات التي تنفذ أسطرًا تغيرت مؤخرًا (مع الإبقاء على توجيه التغطية كإشارة أساسية).

يستند هذا العمل إلى عمل سابق من [LibAFL-git-aware](https://github.com/kevin-valerio/LibAFL-git-aware). جميع التفاصيل التقنية المعمقة موثقة هناك.

#### طريقة الاستخدام

فعّل الجدولة الموجَّهة بـ git باستخدام `--focus-on-new-code=true`:```bash
./bin/go test -fuzz=FuzzHarness --use-libafl --focus-on-new-code=true --catch-races=false --catch-leaks=false

</details>

## الميزة 6: اكتشاف حالات السباق، وتسريبات الغوروتين، والتعليق (انتهاء المهلة) أثناء وقت التضمين

##### اكتشاف التعليقات المؤكدة (انتهاء مهلة LibAFL)

عند التضمين باستخدام LibAFL، يمكن أن ينتهي تنفيذ الـ harness **بمهلة** (على سبيل المثال بسبب طريق مسدود / غوروتينات عالقة في الانتظار، أو مسار بطيء للغاية).

لتقليل النتائج الإيجابية الخاطئة، يتعامل gosentry مع انتهاء المهلة كمرشح للتعليق ويؤكده بإعادة تشغيل المدخلات التي انتهت مدتها عدة مرات مع مهلة أكبر. عند تأكيد التعليق، يكتب gosentry المدخلات إلى `<libafl output dir>/hangs/` ويوقف حملة التضمين (يتعامل معها كخلل/انهيار).

قبل الخروج، يحاول `golibafl` تصغير المدخلات المتسببة في الانهيار/التعليق (أفضل جهد؛ يتم تحديد التعليقات بحوالي 60 ثانية إجمالاً).

ملاحظة: يتم أيضًا تشغيل تأكيد التعليق أثناء استيراد/توليد المجموعة الأولية، لذا يمكن اكتشاف الأهداف التي تنتهي مهلتها على كل مدخل بشكل حتمي.

يتم تكوين هذا عبر `--libafl-config`:
- `catch_hangs` (الافتراضي: `true`)
- `hang_timeout_ms` (الافتراضي: `10000`)
- `hang_confirm_runs` (الافتراضي: `3`)

##### اكتشاف حالات السباق (`--catch-races`)

يمكن لـ gosentry تشغيل حلقة إعادة تشغيل منفصلة `-race` تراقب دليل LibAFL `queue/` وتعيد تشغيل البذور المكتشفة حديثًا مع `GORACE=halt_on_error=1`.

تقوم حلقة إعادة التشغيل ببناء أرشيف harness منفصل `-race` لإعادة التشغيل فقط (بدون أدوات قياس تغطية التضمين).

عند اكتشاف حالة سباق أثناء إعادة التشغيل، يطبع gosentry تقرير كاشف السباق الكامل قبل ملخص `catch-races:` وأمر إعادة الإنتاج.

ملاحظة: يكتشف كاشف السباق في Go حالات السباق **داخل تنفيذ harness واحد فقط** (سباقات بين غوروتينات في نفس العملية تصل إلى نفس الذاكرة دون مزامنة صحيحة). سيفوّت `--catch-races` السباقات إذا لم تؤدِ البذرة إلى تحفيز التزامن المتسابق، كما أنه لا يكتشف السباقات عبر العمليات.

<details>
<summary><strong>كيف تعمل وضعية كشف السباق</strong></summary>

يبدأ هذا الوضع مراقبًا صغيرًا داخل `go test` (نفس العملية الأب)، ويعمل طوال حملة التضمين بأكملها.

- متى: قبل بدء عملية التضمين الرئيسية في LibAFL، يبني gosentry أداة إعادة التشغيل + المُشغّل.
- المراقبة: قبل بدء التضمين، تلتقط gosentry لقطة للمحتويات الأولية لدليل `<libafl output dir>/queue/` في مجموعة `seen`. ثم يقوم غوروتين باستطلاع `<libafl output dir>/queue/` كل ~1 ثانية ويعيد فقط تشغيل البذور المنشأة حديثًا (يتخطى ملفات dotfiles و `*.metadata`).```text
Legend: output/... = <libafl output dir>/...

┌───────────────────────────────────────────────────────────────────────────┐
│ 1) Main LibAFL fuzzing run                                                 │
│    - `golibafl` writes new seeds to `output/queue/`                        │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 2) `--catch-races` sidecar setup                                           │
│    - builds replay harness: `libharness_race.a` (`go test -race ...`)      │
│    - builds replay runner: `golibafl-race` (linked against race harness)   │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 3) Replay loop                                                             │
│    - polls `output/queue/` for new seeds                                   │
│    - runs: `GORACE=halt_on_error=1 golibafl-race run --input <seed>`       │
│      (2 workers × 3 repeats per seed)                                      │
└───────────────┬───────────────────────────────────────────────────────────┘
                v
┌───────────────────────────────────────────────────────────────────────────┐
│ 4) On "DATA RACE"                                                          │
│    - prints the race detector report                                       │
│    - copies seed to `output/races/`                                        │
│    - stops the fuzz campaign (treat as bug/crash)                          │
└───────────────────────────────────────────────────────────────────────────┘