> [!TIP]
> 기여자 문서:  `docs/gosentry/index.md`를 읽고 코드 맵, 권장 개발 루프, CI 진입점 및 벤치마크 스크립트를 확인하세요.
> 이 포크는 Pull GitHub App을 사용하여 `golang/go:master`에서 `master`로 PR을 열고 자동 병합하므로 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")
		}
	})
}

때로는 이것이 작동하지 않을 수 있는데, 그 이유는 Go가 함수를 인라인 처리하기 때문입니다. `// overflow_false_positive`만으로 충분하지 않다면 함수 시그니처 앞에 `//go:noinline`을 추가하세요.

## 기능 3: 선택된 함수에서 패닉 발생

퍼징 대상에서 특정 함수가 호출될 때 패닉을 유발하는 것에 관심이 있을 수 있습니다. 예를 들어, 일부 소프트웨어는 패닉을 일으키는 대신 `log.error` 메시지를 출력할 수 있는데, 이러한 조건은 종종 보안 연구자들이 퍼징 중에 탐지하고자 하는 상태를 나타냅니다.
그러나 이러한 오류는 일반적으로 내부적으로 처리되므로(예: 재시도 또는 일시 중지 메커니즘을 통해, 또는 로그에 메시지를 출력하여) 퍼저가 거의 인식하지 못합니다. 이 기능의 목적은 이 문제를 해결하는 것입니다.

#### 사용 방법

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`을 사용하면 1분 후에 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     │
└───────────────────────────────────────────────────────────────────────────┘

SOTA 퍼저(AFL++ 또는 LibAFL 등)는 그 경우 패닉을 즉시 발견할 것입니다. 하지만 Go 네이티브 퍼저는 그렇지 않습니다. 이는 커버리지 탐색을 **크게** 제한하는 거대한 격차입니다.

아래 벤치마크는 이러한 한계를 보여줍니다. 해당 벤치마크는 [gosentry-bench-libafl 저장소](https://github.com/kevin-valerio/gosentry-bench-libafl/tree/main)를 통해 **재현**하고 개선할 수 있습니다.

##### 벤치마크 1:

아래 차트는 LibAFL과 Go 네이티브 퍼저를 사용하여 Google의 [UUID](https://github.com/google/uuid)를 퍼징하는 동안 커버된 라인 수의 변화를 보여줍니다.
![BENCH1](https://assets.kitploit.com/production/public/readmes/41918/7b1ea005996846c9ee4d7c0d42fee26731050d10b6b21d59c551e4b1b956923e.png "BENCH1")

##### 벤치마크 2:

아래 차트는 LibAFL과 Go 네이티브 퍼저를 사용하여 [go-ethereum](https://github.com/ethereum/go-ethereum)을 퍼징하는 동안 커버된 라인 수의 변화를 보여줍니다.
![BENCH2](https://assets.kitploit.com/production/public/readmes/41918/61aab8540ab8d339307854de6737a405056c3c8ad83a822df40f74e362b93021.png "BENCH2")



#### 예제
`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`가 `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)의 이전 작업을 기반으로 합니다. 모든 기술적 세부 사항은 해당 문서에 정리되어 있습니다.

#### 사용 방법

`--focus-on-new-code=true`로 git-aware 스케줄링을 활성화하세요:```bash
./bin/go test -fuzz=FuzzHarness --use-libafl --focus-on-new-code=true --catch-races=false --catch-leaks=false