trailofbits/gosentryसुरक्षा-केंद्रित Go टूलचेन, अत्याधुनिक फ़ज़िंग क्षमताओं पर केंद्रित।
# gosentry
[](https://github.com/trailofbits/gosentry/actions/workflows/go.yml)
gosentry Go टूलचेन का एक सुरक्षा-केंद्रित फोर्क है, जो Go कोडबेस पर अत्याधुनिक फज़िंग अभियानों के लिए कई सुविधाओं को एकीकृत करता है। यदि आप पहले `go test -fuzz` का उपयोग कर रहे थे, तो आपको इसके विकल्प के रूप में gosentry का उपयोग करना चाहिए। इसमें कई फज़िंग सुधार और बग डिटेक्टर शामिल हैं जो Go टूलचेन में मूल रूप से मौजूद नहीं हैं। नीचे TLDR; देखें। आप संबंधित ब्लॉग लेख [यहाँ](https://blog.trailofbits.com/2026/05/12/go-fuzzing-was-missing-half-the-toolkit.-we-forked-the-toolchain-to-fix-it./) भी पढ़ सकते हैं।
**TLDR (विशेषताएं और विकल्प)**:
- `struct` इनपुट को सीधे फज़ करें (कोई कस्टम पार्सर आवश्यक नहीं)। `f.Add(Input{N: 7, S: "hi"})` के साथ सीड जोड़ें, फिर `f.Fuzz(func(t *testing.T, in Input) { ... })`।
- पूर्णांक ओवरफ्लो पर पैनिक करें और अंकगणितीय समस्याओं का पता लगाएं
- पथ बाधाओं को हल करने जैसी अत्याधुनिक फज़िंग तकनीकों के लिए LibAFL के साथ फज़ करें
- बेकार म्यूटेशन से बचने के लिए ग्रामर से इनपुट उत्पन्न/म्यूटेट करें। म्यूटेशन वैध गणितीय संक्रियाएँ उत्पन्न करता है, जैसे `X + Y - Z` `X / U + Z - 14` बन सकता है, `X + Yè - Z` के बजाय
- चयनित फ़ंक्शनों पर पैनिक करें (जैसे क्रिटिकल एरर लॉगर) और कॉल होने पर क्रैश करें
- फज़र को हाल ही में बदली गई पंक्तियों और नए कवरेज पर केंद्रित करें, मुख्य रूप से नए कमिट्स को लक्षित करने के लिए
- फज़-टाइम पर डेटा रेस पकड़ें
- फज़-टाइम पर Go लीक पकड़ें
- फज़-टाइम पर टाइमआउट के साथ अटकी हुई एक्ज़ीक्यूशन पकड़ें
- एक CLI से फज़ कैंपेन कॉर्पस से HTML कवरेज रिपोर्ट उत्पन्न करें
## विषय-सूची
- [बिल्ड](#build)
- [फीचर 1: स्ट्रक्ट-अवेयर फज़िंग (इनपुट के रूप में स्ट्रक्ट फ़ज़ करें)](#feature-1-struct-aware-fuzzing-fuzz-structs-as-inputs)
- [फीचर 2: पूर्णांक ओवरफ्लो और ट्रंकेशन समस्याओं की पहचान](#feature-2-integer-overflow-and-truncation-issues-detection)
- [फीचर 3: चयनित फ़ंक्शनों पर पैनिक](#feature-3-panic-on-selected-functions)
- [फीचर 4: LibAFL अत्याधुनिक फज़िंग](#feature-4-libafl-state-of-the-art-fuzzing)
- [फीचर 5: Git-ब्लेम-उन्मुख फज़िंग (प्रयोगात्मक)](#feature-5-git-blame-oriented-fuzzing-experimental)
- [फीचर 6: फज़-टाइम पर रेस कंडीशन, goroutine लीक और हैंग का पता लगाएं](#feature-6-detect-race-conditions-goroutine-leaks-and-hangs-at-fuzz-time)
- [फीचर 7: ग्रामर-आधारित फज़िंग (Nautilus)](#feature-7-grammar-based-fuzzing-nautilus)
- [फीचर 8: कैंपेन से फज़िंग कवरेज रिपोर्ट उत्पन्न करें](#feature-8-generate-go-coverage-reports-from-fuzzing-campaign)
- [ट्राफियां](#trophies)
- [क्रेडिट्स](#credits)
## बिल्ड```bash
cd src && ./make.bash # Produces `../bin/go`. See `GOFLAGS` below.
```
> [!TIP]
> योगदानकर्ता दस्तावेज़: कोड मैप, अनुशंसित डेव लूप, CI एंट्रीपॉइंट और बेंचमार्क स्क्रिप्ट के लिए `docs/gosentry/index.md` पढ़ें।
> यह फोर्क `golang/go:master` से `master` में PRs खोलने और ऑटो-मर्ज करने के लिए Pull GitHub App का उपयोग करता है, जिससे हम Go टूलचेन के नवीनतम अपडेट से कभी पीछे नहीं रहते हैं।
## फ़ीचर 1: स्ट्रक्चर-जागरूक फ़ज़िंग (स्ट्रक्चर को इनपुट के रूप में फ़ज़ करें)
#### अवलोकन
Go का नेटिव फ़ज़िंग (`go test -fuzz=...`) फ़ज़ पैरामीटर के रूप में केवल स्केलर प्रकारों के एक छोटे समूह का समर्थन करता है (`[]byte`, `string`, संख्याएँ, ...)। gosentry में, आप उन स्केलरों से निर्मित **कंपोज़िट प्रकारों** को भी फ़ज़ कर सकते हैं: स्ट्रक्चर, ऐरे, स्लाइस और पॉइंटर्स।
यह तब उपयोगी है जब आपका कोड स्वाभाविक रूप से संरचित इनपुट लेता है और आप कॉर्पस को सीड और म्यूटेट करने के लिए कस्टम एन्कोडर/डिकोडर नहीं बनाना चाहते हैं।
उदाहरणों के लिए `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")
}
})
}
```
<details>
<summary><strong>struct seeds (<code>f.Add</code>) और struct फज़िंग कैसे काम करते हैं (गोंद की परत)</strong></summary>
Go का native fuzzer किसी `struct` मान को सीधे फज़ नहीं कर सकता (यह केवल scalar प्रकारों की छोटी सूची को mutate करना जानता है)। gosentry एक छोटी गोंद-परत जोड़ता है: जब आपका fuzz target composite प्रकारों (जैसे `Input`) का उपयोग करता है, gosentry पर्दे के पीछे एक ही `[]byte` फज़ करता है। हर निष्पादन पर, यह उन बाइट्स को आपके struct में **डीकोड** करता है (फ़ील्ड-दर-फ़ील्ड, slices/arrays/pointers के लिए पुनरावर्ती रूप से) और फिर डीकोड किए गए मान के साथ आपके `f.Fuzz` कॉलबैक को कॉल करता है। वही **एन्कोडिंग** seeds के लिए उपयोग होती है, इसलिए `f.Add(Input{...})` एक एन्कोडेड `[]byte` corpus entry बन जाता है जिसे fuzzer किसी भी अन्य seed की तरह पुनः उपयोग और mutate कर सकता है।
Fuzzers (LibAFL सहित) raw bytes mutate करते हैं, इसलिए हमें एक ऐसा decoder चाहिए जो **किसी भी** byte slice को "कुछ" struct मान में बदल सके और आगे बढ़ता रहे। JSON/`gob` अधिकांश रैंडम इनपुट अस्वीकार कर देंगे (कवरेज के लिए बुरा), और वे unexported फ़ील्ड्स को भी नहीं भरते, जबकि fuzzing अक्सर invariants को तोड़ने से लाभ उठाता है। यह custom format छोटा, तेज़, deterministic और malformed डेटा के प्रति सहिष्णु है।
अंदर से, यह gosentry का अपना simple binary format उपयोग करता है (`gob` नहीं, JSON नहीं)। कोड `src/testing/libafl.go` में स्थित है:
- एन्कोड: `libaflMarshalInputs` / `libaflAppendValue`
- डीकोड: `libaflUnmarshalArgs` / `libaflDecodeValue`
एन्कोडिंग नियम (high level):
- `bool`: 1 बाइट (`0` या `1`)
- Integers: little-endian बाइट्स (`int`/`uint` 8 बाइट्स होते हैं)
- Floats: little-endian में IEEE-754 बिट्स (`float32` = 4 बाइट्स, `float64` = 8 बाइट्स)
- `string`: `uvarint(len)` फिर raw string बाइट्स
- `[]byte`: `uvarint(len)` फिर raw बाइट्स
- अन्य slices: `uvarint(len)` फिर प्रत्येक एलिमेंट एन्कोड होता है
- Structs: फ़ील्ड्स घोषणा क्रम में एन्कोड होते हैं
- Pointers: 1 बाइट (`0` = nil, `1` = मौजूद) फिर pointed value
</details>
## फ़ीचर 2: पूर्णांक overflow और truncation समस्याओं का पता लगाना
#### अवलोकन
यह कार्य पहले विकसित [go-panikint](https://github.com/trailofbits/go-panikint) से प्रेरित है। यह पूर्णांक अंकगणितीय संक्रियाओं के लिए overflow/underflow का पता लगाना और (वैकल्पिक रूप से) पूर्णांक रूपांतरणों के लिए type truncation का पता लगाना जोड़ता है। जब overflow या truncation का पता चलता है, तो विस्तृत त्रुटि संदेश के साथ एक panic ट्रिगर होता है, जिसमें शामिल विशिष्ट संक्रिया प्रकार और पूर्णांक प्रकार शामिल होते हैं।
_अंकगणितीय संक्रियाएँ_: यह signed और unsigned दोनों प्रकार के पूर्णांकों के लिए जोड़ `+`, घटाव `-`, गुणा `*`, और भाग `/` को संभालती है। Signed पूर्णांकों के लिए, `int8`, `int16`, `int32` शामिल हैं। Unsigned पूर्णांकों के लिए, `uint8`, `uint16`, `uint32`, `uint64` शामिल हैं। भाग का मामला विशेष रूप से signed पूर्णांकों के लिए `MIN_INT / -1` overflow स्थिति का पता लगाता है। `int64` और `uintptr` की अंकगणितीय संक्रियाओं के लिए जाँच नहीं की जाती।
_प्रकार truncation का पता लगाना_: यह संभावित रूप से हानिपूर्ण (lossy) पूर्णांक प्रकार रूपांतरणों का पता लगाता है। सभी पूर्णांक प्रकारों को कवर करता है: `int8`, `int16`, `int32`, `int64`, `uint8`, `uint16`, `uint32`, `uint64`। `uintptr` को प्लेटफ़ॉर्म-निर्भर उपयोग के कारण बाहर रखा गया है। यह डिफ़ॉल्ट रूप से अक्षम है।
Overflow का पता लगाना डिफ़ॉल्ट रूप से सक्षम है। इसे अक्षम करने के लिए, अपने `./make.bash` से पहले `GOFLAGS='-gcflags=-overflowdetect=false'` जोड़ें। आप truncation issues checker को भी इसके साथ सक्षम कर सकते हैं: `-gcflags=-truncationdetect=true`
#### यह कैसे काम करता है
यह फ़ीचर कंपाइलर की SSA जनरेशन को पैच करता है ताकि पूर्णांक अंकगणितीय संक्रियाओं और पूर्णांक रूपांतरणों को अतिरिक्त runtime जाँचें मिलें, जो किसी bug का पता चलने पर विस्तृत त्रुटि संदेश के साथ panic करने के लिए runtime में कॉल करती हैं। जाँचें source-location-आधारित फ़िल्टरिंग का उपयोग करके लागू की जाती हैं, ताकि उपयोगकर्ता कोड इंस्ट्रूमेंट किया जाए, जबकि मानक पुस्तकालय फ़ाइलें और निर्भरताएँ (module cache और `vendor/`) छोड़ दी जाती हैं।
आप इससे संबंधित ब्लॉग पोस्ट [**यहाँ**](https://blog.trailofbits.com/2025/12/31/detect-gos-silent-arithmetic-bugs-with-go-panikint/) पढ़ सकते हैं।
#### गलत सकारात्मक (false positives) को दबाना
किसी विशेष रिपोर्ट को दबाने के लिए संक्रिया वाली ही पंक्ति में या ठीक उसके ऊपर वाली पंक्ति में एक मार्कर जोड़ें:
- Overflow/underflow: `overflow_false_positive`
- Truncation: `truncation_false_positive`
उदाहरण:```go
// overflow_false_positive
intentionalOverflow := a + b
// truncation_false_positive
x := uint8(big)
sum2 := a + b // overflow_false_positive
x2 := uint8(big) // truncation_false_positive
```
Sometimes this might not work, that's because Go is in-lining the function. If `// overflow_false_positive` isn't enough, add `//go:noinline` before the signature of your function.
## Feature 3: Panic on selected functions
When fuzzing targets, we may be interested in triggering a panic when certain functions are called. For example, some software may emit `log.error` messages instead of panicking, even though such conditions often indicate states that security researchers would want to detect during fuzzing.
However, these errors are usually handled internally (e.g., through retry or pause mechanisms, or by printing messages to logs), which makes them largely invisible to fuzzers. The objective of this feature is to address this issue.
#### How to use
Compile gosentry, then use the `--panic-on` flag.```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"
```
ऊपर दिया गया उदाहरण panic करेगा जब `(*Logger).Warning` या `(*Logger).Error` में से किसी को भी कॉल किया जाए (कॉमा-सेपरेटेड सूची)।
<details>
<summary><strong>चयनित फ़ंक्शंस पर panic सुविधा कैसे काम करती है</strong></summary>```text
┌───────────────────────────────────────────────────────────────────────────┐
│ 1) gosentry `go test` │
│ - parses + validates `-panic-on=...` against packages being built │
│ - forwards patterns to the compiler via `-panic-on-call=...` │
└───────────────┬───────────────────────────────────────────────────────────┘
v
┌───────────────────────────────────────────────────────────────────────────┐
│ 2) `cmd/compile` │
│ - prevents inlining of matching calls so the call stays visible │
│ - SSA pass inserts a call to `runtime.panicOnCall(...)` │
└───────────────┬───────────────────────────────────────────────────────────┘
v
┌───────────────────────────────────────────────────────────────────────────┐
│ 3) `runtime.panicOnCall` │
│ - panics with: "panic-on-call: func-name" │
└───────────────────────────────────────────────────────────────────────────┘
```
व्यवहार में, यह किसी भी मेल खाते कॉल साइट को फ़ज़र्स के लिए क्रैश/पैनिक जैसा व्यवहार कराता है (ध्यान दें: केवल स्टैटिक कॉल साइट्स को ही फँसाया जा सकता है)।
</details>
## फ़ीचर 4: LibAFL अत्याधुनिक फ़ज़िंग
LibAFL पारंपरिक Go फ़ज़र की तुलना में *कहीं* बेहतर प्रदर्शन करता है। फ़ज़िंग करते समय (`go test -fuzz=...`), gosentry **डिफ़ॉल्ट रूप से** [LibAFL](https://github.com/AFLplusplus/LibAFL) का उपयोग करता है (runner `golibafl/` में)।
स्थिरता नोट: LibAFL मोड में, gosentry `GODEBUG=updatemaxprocs=0` को बाध्य करता है (रनटाइम ऑटो GOMAXPROCS अपडेट को अक्षम करता है) ताकि एक आंतरायिक Linux CI क्रैश ("sync: inconsistent mutex state") से बचा जा सके। विवरण `misc/gosentry/USE_LIBAFL.md` में हैं।
LibAFL (डिफ़ॉल्ट) का उपयोग करते समय, आपको स्पष्ट रूप से चुनना होगा कि git-जागरूक शेड्यूलिंग सक्षम करनी है या नहीं: `--focus-on-new-code=true|false`। अधिक दस्तावेज़ीकरण [इस Markdown फ़ाइल में।](https://github.com/trailofbits/gosentry/blob/master/misc/gosentry/USE_LIBAFL.md)
आप LibAFL के लिए एक वैकल्पिक JSONC कॉन्फ़िग फ़ाइल भी पास कर सकते हैं (ग्रामर फ़ज़िंग विकल्पों सहित), देखें [यहाँ।](https://github.com/trailofbits/gosentry/blob/master/misc/gosentry/libafl.config.jsonc)
`"stop_all_fuzzers_on_panic": false` के साथ, LibAFL प्रत्येक क्रैश को सहेजता है और फ़ज़िंग जारी रखने के लिए अपने क्लाइंट को पुनः आरंभ करता है।```bash
./bin/go test -fuzz=FuzzHarness --focus-on-new-code=false --catch-races=false --catch-leaks=false --libafl-config=path/to/libafl.jsonc # optional --libafl-config
```
Use `-fuzztime=1m` का उपयोग करके LibAFL अभियान को एक मिनट के बाद रोकें।
LibAFL अभियान कॉर्पस से कवरेज रिपोर्ट निर्माण [Feature 8](#feature-8-generate-go-coverage-reports-from-fuzzing-campaign) में प्रलेखित है।
व्याकरण-आधारित फ़ज़िंग (Nautilus) [Feature 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 │
└───────────────────────────────────────────────────────────────────────────┘
```
`--use-libafl` मोड में, gosentry `libharness.a` बनाता है और Rust `golibafl` रनर libFuzzer एंट्रीपॉइंट्स के माध्यम से इसे इन-प्रोसेस चलाता है। ध्यान दें: `HARNESS_LIB` किसी भी हार्नेस आर्काइव नाम की ओर संकेत कर सकता है (उदाहरण के लिए `--catch-races` द्वारा उपयोग किया गया `libharness_race.a`).
</details>
<details>
<summary><strong>कवरेज इंस्ट्रूमेंटेशन कैसे काम करता है (LibAFL + Go टार्गेट)</strong></summary>
`--use-libafl` मोड में, gosentry कवरेज इंस्ट्रूमेंटेशन सक्षम के साथ Go हार्नेस को कंपाइल करता है। यह कोड में छोटे काउंटर जोड़ता है जो आपके प्रोग्राम के विभिन्न हिस्सों के चलने पर बदलते हैं। जब हार्नेस `golibafl` के अंदर शुरू होता है, Go रनटाइम इन काउंटरों को LibAFL को उजागर करता है। LibAFL प्रत्येक इनपुट के बाद उन्हें पढ़ता है ताकि देख सके कि कौन सा कोड चला, और अगले म्यूटेशनों को निर्देशित करने के लिए उस कवरेज का उपयोग करता है।
</details>
##### सीमाएँ
चलिए LibAFL उपयोग करने के पीछे की प्रेरणा के बारे में बात करते हैं। `go test -fuzz` के साथ फ़ज़िंग अत्याधुनिक फ़ज़िंग तकनीकों से _बहुत_ पीछे है। इसका एक अच्छा उदाहरण AFL++ का CMPLOG/Redqueen है। ये सुविधाएँ फ़ज़र्स को कुछ कंस्ट्रेंट्स को हल करने की अनुमति देती हैं। मान लीजिए निम्नलिखित स्निपेट```go
if input == "IMARANDOMSTRINGJUSTCMPLOGMEMAN" {
panic("this string is illegal")
}
```
SOTA fuzzers जैसे AFL++ या LibAFL उस स्थिति में panic को तुरंत ढूंढ लेंगे। हालाँकि, Go native fuzzer ऐसा नहीं करेगा। यह एक बड़ा अंतर है जो coverage exploration को **बहुत अधिक** सीमित करता है।
नीचे दिया गया बेंचमार्क उन सीमाओं को दर्शाता है। ध्यान दें कि उन बेंचमार्कों को [gosentry-bench-libafl रिपॉज़िटरी](https://github.com/kevin-valerio/gosentry-bench-libafl/tree/main) के माध्यम से **पुनरुत्पादित** और बेहतर किया जा सकता है।
##### बेंचमार्क 1:
नीचे दिया गया चार्ट LibAFL बनाम Go native fuzzer का उपयोग करके Google के [UUID](https://github.com/google/uuid) को फ़ज़िंग करते समय कवर की गई लाइनों की संख्या के विकास को दर्शाता है।
##### बेंचमार्क 2:
नीचे दिया गया चार्ट LibAFL बनाम Go native fuzzer का उपयोग करके [go-ethereum](https://github.com/ethereum/go-ethereum) को फ़ज़िंग करते समय कवर की गई लाइनों की संख्या के विकास को दर्शाता है।
#### उदाहरण
आप इसे `test/gosentry/examples/` में कुछ fuzzing harnesses पर आज़मा सकते हैं।```bash
cd test/gosentry/examples/reverse
../../../../bin/go test -fuzz=FuzzReverse --focus-on-new-code=false --catch-races=false --catch-leaks=false
```
Stop the fuzz campaign with Ctrl+C.
##### LibAFL आउटपुट निर्देशिका (अभियान पहचान / कॉर्पस पुन: उपयोग)
gosentry LibAFL के अभियान की स्थिति (कॉर्पस, क्रैश, आदि) को Go की फ़ज़ कैश रूट (मोटे तौर पर `$(go env GOCACHE)/fuzz`) के अंतर्गत संग्रहीत करता है, एक नियतात्मक निर्देशिका में जो **समान पैकेज + समान फ़ज़ टारगेट** (और समान प्रोजेक्ट रूट) से व्युत्पन्न होती है।
इसका अर्थ है कि समान फ़ज़ अभियान को रोकने (Ctrl+C) और पुनः प्रारंभ करने पर, डिफ़ॉल्ट रूप से पिछले LibAFL `queue/` कॉर्पस से जारी रहेगा।
पथ रन के अंत में मुद्रित होता है:```text
libafl output dir: /full/path/to/.../fuzz/<pkg import path>/libafl/<project>/<harness>
```
नोट्स:
- `<harness>` फ़ज़ टारगेट का नाम है जब `-fuzz` एक साधारण पहचानकर्ता हो जैसे `FuzzXxx` (या `^FuzzXxx$`), अन्यथा यह `pattern-<hash>` होता है।
---
[Read more](https://github.com/trailofbits/gosentry)