initial commit

Author: frystile

.gitignore

@@ -0,0 +1,23 @@
+# Allow docker files
+!Dockerfile
+
+/.cache
+
+.idea/
+.vscode/
+.clangd
+.antlr/
+
+# Develop IDE
+.vs/
+
+# fuzzing example
+example/corpus/
+example/cov*
+example/crash*
+example/go-fuzz.a
+example/go-fuzz.h
+example/fuzz
+example/result.html
+example/result.txt
+example/result_func.txt

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Notice to external contributors
+
+## General info
+
+Hello! In order for us (YANDEX LLC) to accept patches and other contributions from you, you will have to adopt our Contributor License Agreement (the “CLA”). The current version of the CLA you may find here:
+
+1. https://yandex.ru/legal/cla/?lang=en (in English) and
+2. https://yandex.ru/legal/cla/?lang=ru (in Russian).
+
+By adopting the CLA, you state the following:
+
+- You obviously wish and are willingly licensing your contributions to us for our open source projects under the terms of the CLA,
+- You have read the terms and conditions of the CLA and agree with them in full,
+- You are legally able to provide and license your contributions as stated,
+- We may use your contributions for our open source projects and for any other our project too,
+- We rely on your assurances concerning the rights of third parties in relation to your contributions.
+
+If you agree with these principles, please read and adopt our CLA. By providing us your contributions, you hereby declare that you have read and adopted our CLA, and we may freely merge your contributions with our corresponding open source project and use it in further in accordance with terms and conditions of the CLA.
+
+## Other questions
+
+If you have any questions, please write us at [email protected].

README.md

@@ -0,0 +1,85 @@
+## Mutator  
+
+This is a go-protobuf-mutator library for random value mutations. (See also [libprotobuf-mutator](https://github.com/google/libprotobuf-mutator))
+
+### Supported Types  
+- ProtoMessage  
+- Bool  
+- Float64  
+- Float32  
+- Uint32  
+- Uint64  
+- Int32  
+- Int64  
+- String  
+- Bytes  
+
+### Dependencies for libfuzzer
+- Go 1.21+
+- Protocol Buffers compiler (`protoc`)
+- libprotobuf-dev
+- clang (for libFuzzer integration)
+- libprotobuf-mutator (v1.1)
+
+### Basic Usage
+```go  
+message := NewProtoMessage()  
+mutator := mutator.New(int64(seed), maxSize)  
+if err := mutator.MutateProto(message); err != nil {  
+    fmt.Printf("Failed to mutate message: %+v", err)  
+}  
+```
+
+### Implementation Examples
+
+For complete reference implementations:
+
+| Feature               | Location                          | Documentation                       |
+|-----------------------|-----------------------------------|-------------------------------------|
+| libFuzzer Integration | [`example/cmd/libfuzzer.go`](./example/cmd/libfuzzer.go) | [README](./example/README.md) |
+| Coverage Tracking     | [`example/cmd/coverage.go`](./example/cmd/coverage.go) | Code comments            |
+
+**Pro Tip**: The libFuzzer example includes:
+- Custom mutator setup
+- Seed corpus generation
+- Crash reproduction workflow
+- Performance benchmarking
+
+### Integration with libFuzzer  
+Add `--tag libfuzzer` to build commands when using libFuzzer.  
+
+#### Example Code  
+```go  
+// #include <stdint.h>
+import "C"
+
+//export LLVMFuzzerTestOneInput
+func LLVMFuzzerTestOneInput(data *C.char, size C.size_t) C.int {
+    gdata := unsafe.Slice((*byte)(unsafe.Pointer(data)), size)
+    message := NewProtoMessage(gdata)
+    Fuzz(message)
+    return 0
+}
+
+//export LLVMFuzzerCustomMutator
+func LLVMFuzzerCustomMutator(data *C.char, size C.size_t, maxSize C.size_t, seed C.uint) C.size_t {
+    gdata := unsafe.Slice((*byte)(unsafe.Pointer(data)), size)
+    message := NewProtoMessage(gdata)
+
+    mutator := mutator.New(int64(seed), int(maxSize-size))
+    if err := mutator.MutateProto(message); err != nil {
+        return 0
+    }
+
+    gdata = unsafe.Slice((*byte)(unsafe.Pointer(data)), maxSize)
+    newSize := StoreMessage(gdata, message)
+    return C.size_t(newSize)
+}
+```  
+
+#### Build Commands  
+```sh
+go build -tags libfuzzer -buildmode c-archive -o fuzz.a ./cmd/fuzzing
+clang++ -o fuzz fuzz.a -fsanitize=fuzzer
+./fuzz ./corpus
+```

SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+We're extremely grateful for security researchers and users who report vulnerabilities they discovered in mutator. All reports are thoroughly investigated.
+
+To report a potential vulnerability in mutator please email details to [[email protected]](mailto:[email protected]).
+
+### When Should I Report a Vulnerability?
+
+- You think you discovered a potential security vulnerability in mutator
+- You are unsure how a vulnerability affects mutator
+
+## Security Vulnerability Response
+
+Each report is acknowledged and analyzed by mutator maintainers within 5 working days.
+We will keep the reporter informed about the issue progress.
+
+## Public Disclosure Timing
+
+A public disclosure date is negotiated by mutator maintainers and the bug submitter. We prefer to fully disclose the bug as soon as possible once a mitigation is available for mutator users. It is reasonable to delay disclosure when the bug or the fix is not yet fully understood, the solution is not well-tested, or for vendor coordination. The timeframe for disclosure is from immediate (especially if it's already publicly known) to 90 days. For a vulnerability with a straightforward mitigation, we expect report date to disclosure date to be on the order of 7 days.

base.go

@@ -0,0 +1,82 @@
+package mutator
+
+import (
+	"encoding/binary"
+	"math/rand"
+	"unsafe"
+)
+
+var nativeEndian binary.ByteOrder
+
+func init() {
+	buf := [2]byte{}
+	*(*uint16)(unsafe.Pointer(&buf[0])) = uint16(0xABCD)
+
+	switch buf {
+	case [2]byte{0xCD, 0xAB}:
+		nativeEndian = binary.LittleEndian
+	case [2]byte{0xAB, 0xCD}:
+		nativeEndian = binary.BigEndian
+	default:
+		panic("Could not determine native endian.")
+	}
+}
+
+// Return random integer from [0, count)
+func getRandomRange(src *rand.Rand, count int) int {
+	// validate count
+	// because rand panics if count <= 0
+	if count <= 0 {
+		return 0
+	}
+	return src.Intn(count)
+}
+
+func MutateInt64(src *rand.Rand, value *int64) error {
+	return mutateValue(src, value)
+}
+
+func MutateInt32(src *rand.Rand, value *int32) error {
+	return mutateValue(src, value)
+}
+
+func MutateUint64(src *rand.Rand, value *uint64) error {
+	return mutateValue(src, value)
+}
+
+func MutateUint32(src *rand.Rand, value *uint32) error {
+	return mutateValue(src, value)
+}
+
+func MutateFloat32(src *rand.Rand, value *float32) error {
+	return mutateValue(src, value)
+}
+
+func MutateFloat64(src *rand.Rand, value *float64) error {
+	return mutateValue(src, value)
+}
+
+func MutateBool(src *rand.Rand, value *bool) error {
+	return mutateValue(src, value)
+}
+
+// Return random bool value
+func GetRandomBool(src *rand.Rand) bool {
+	return GetRandomBoolN(src, 2)
+}
+
+// Return true with probability about 1-of-n.
+func GetRandomBoolN(src *rand.Rand, n int) bool {
+	val := getRandomRange(src, n)
+	return val == 0
+}
+
+// Flips random bit in the buffer.
+func flipBit(src *rand.Rand, size int, data []byte) {
+	if len(data) == 0 {
+		return
+	}
+	bit := getRandomRange(src, size*8)
+
+	data[bit/8] ^= (1 << (bit % 8))
+}

common.go

@@ -0,0 +1,60 @@
+//go:build !libfuzzer
+
+package mutator
+
+import (
+	"bytes"
+	"encoding/binary"
+	"math/rand"
+	"reflect"
+)
+
+// flipBitValue flips random bit in the value.
+func mutateValue(src *rand.Rand, value any) error {
+	data := make([]byte, 0, reflect.TypeOf(value).Size())
+	buf := bytes.NewBuffer(data)
+	if err := binary.Write(buf, nativeEndian, value); err != nil {
+		return err
+	}
+	flipBit(src, buf.Len(), buf.Bytes())
+	return binary.Read(buf, nativeEndian, value)
+}
+
+func MutateString(src *rand.Rand, str string, maxSize int) (string, error) {
+	value, err := MutateBytes(src, []byte(str), maxSize)
+	if err != nil {
+		return "", err
+	}
+	if err := FixUTF8(value, src); err != nil {
+		return "", err
+	}
+	return string(value), nil
+}
+
+func MutateBytes(src *rand.Rand, value []byte, maxSize int) ([]byte, error) {
+	result := make([]byte, len(value))
+	copy(result, value)
+
+	for len(result) > 0 && GetRandomBool(src) {
+		index := getRandomRange(src, len(result))
+		result = append(result[:index], result[index+1:]...)
+	}
+
+	for len(result) < maxSize && GetRandomBool(src) {
+		index := getRandomRange(src, len(result)+1)
+		result = append(result, byte(getRandomRange(src, 1<<8)))
+		result[index], result[len(result)-1] = result[len(result)-1], result[index]
+	}
+
+	if !bytes.Equal(result, value) {
+		return result, nil
+	}
+
+	if len(result) == 0 {
+		result = append(result, byte(getRandomRange(src, 1<<8)))
+		return result, nil
+	}
+
+	flipBit(src, len(result), result)
+	return result, nil
+}

common_test.go

@@ -0,0 +1,69 @@
+//go:build !libfuzzer
+
+package mutator
+
+import (
+	"math/rand"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestFlipBitValue(t *testing.T) {
+	src := rand.New(rand.NewSource(time.Now().Unix()))
+
+	var (
+		valueInt32   = int32(32)
+		valueInt64   = int64(64)
+		valueUint32  = uint32(32)
+		valueUint64  = uint64(64)
+		valueFloat32 = float32(32)
+		valueFloat64 = float64(64)
+		valueBool    = true
+	)
+
+	tests := []struct {
+		name  string
+		value any
+	}{
+		{
+			"int32",
+			&valueInt32,
+		},
+		{
+			"int64",
+			&valueInt64,
+		},
+		{
+			"uint32",
+			&valueUint32,
+		},
+		{
+			"uint64",
+			&valueUint64,
+		},
+		{
+			"float32",
+			&valueFloat32,
+		},
+		{
+			"float64",
+			&valueFloat64,
+		},
+		{
+			"bool",
+			&valueBool,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			for run := 0; run < 10000; run++ {
+				value := reflect.ValueOf(tt.value)
+				require.NoError(t, mutateValue(src, tt.value))
+				require.NotEqualValues(t, value, tt.value)
+			}
+		})
+	}
+}