0
# Core Fuzzing Functions
1

2
Essential functions for setting up and running the Atheris fuzzer. These functions provide the fundamental fuzzing capabilities including configuration, execution control, and input mutation.
3

4
## Capabilities
5

6
### Setup and Configuration
7

8
Configure the fuzzer with your test function and options before starting the fuzzing process.
9

10
```python { .api }
11
def Setup(args, test_one_input, **kwargs):
12
    """
13
    Configure the fuzzer with test function and options.
14
    
15
    Args:
16
        args (list): Command-line arguments, typically sys.argv. This list may be
17
                    modified in-place to remove arguments consumed by the fuzzer.
18
        test_one_input (callable): Your fuzzer's entry point function. Must accept
19
                                  a single bytes argument and perform the testing.
20
        **kwargs: Optional keyword arguments:
21
            internal_libfuzzer (bool, optional): Controls libfuzzer mode:
22
                                               - None: Auto-detect (default)
23
                                               - True: Use internal libfuzzer
24
                                               - False: Use external libfuzzer
25
            custom_mutator (callable, optional): Custom mutation function with signature:
26
                                               (data: bytes, max_size: int, seed: int) -> bytes
27
            custom_crossover (callable, optional): Custom crossover function with signature:
28
                                                 (data1: bytes, data2: bytes, max_out_size: int, seed: int) -> bytes
29
    
30
    Returns:
31
        list: Remaining command-line arguments after fuzzer argument consumption
32
    """
33
```
34

35
**Usage Example:**
36

37
```python
38
import atheris
39
import sys
40

41
def TestOneInput(data):
42
    # Your fuzzing logic here
43
    some_function_to_test(data)
44

45
# Basic setup
46
atheris.Setup(sys.argv, TestOneInput)
47

48
# Setup with custom mutator
49
def custom_mutator(data, max_size, seed):
50
    # Custom mutation logic
51
    return mutated_data
52

53
atheris.Setup(sys.argv, TestOneInput, custom_mutator=custom_mutator)
54
```
55

56
### Fuzzing Execution
57

58
Start and control the fuzzing process.
59

60
```python { .api }
61
def Fuzz():
62
    """
63
    Start the fuzzing loop. Must call Setup() first.
64
    
65
    This function takes control of the program and does not return under normal
66
    circumstances. The fuzzer will run until one of these conditions:
67
    - A crash is found (uncaught exception in test_one_input)
68
    - Run limits are reached (via command-line flags)
69
    - External termination (SIGINT, SIGTERM, etc.)
70
    - libFuzzer exits due to other conditions
71
    
72
    Raises:
73
        RuntimeError: If Setup() was not called first
74
    """
75
```
76

77
**Usage Example:**
78

79
```python
80
# Must call Setup() before Fuzz()
81
atheris.Setup(sys.argv, TestOneInput)
82

83
# Start fuzzing - this call does not return
84
atheris.Fuzz()
85

86
# Code after this point will not be reached
87
print("This will never be printed")
88
```
89

90
### Input Mutation
91

92
Access libFuzzer's built-in mutation capabilities for custom mutators.
93

94
```python { .api }
95
def Mutate(data, max_size):
96
    """
97
    Mutate input data using libFuzzer's built-in mutator.
98
    
99
    This function provides access to the same mutation algorithms that libFuzzer
100
    uses internally. Useful for implementing custom mutators that combine
101
    domain-specific mutations with libFuzzer's general-purpose mutations.
102
    
103
    Args:
104
        data (bytes): Input data to mutate. Can be empty bytes.
105
        max_size (int): Maximum size of the mutated output in bytes.
106
                       The actual output may be smaller than this limit.
107
    
108
    Returns:
109
        bytes: Mutated data. The length will be <= max_size.
110
    """
111
```
112

113
**Usage Example:**
114

115
```python
116
def CustomMutator(data, max_size, seed):
117
    # Use libFuzzer's built-in mutation as a base
118
    mutated = atheris.Mutate(data, max_size)
119
    
120
    # Apply domain-specific mutations
121
    if len(mutated) > 4:
122
        # Example: occasionally corrupt a magic header
123
        if seed % 10 == 0:
124
            mutated = b"CORRUPT" + mutated[4:]
125
    
126
    return mutated
127

128
atheris.Setup(sys.argv, TestOneInput, custom_mutator=CustomMutator)
129
atheris.Fuzz()
130
```
131

132
### Command-Line Integration
133

134
Atheris processes command-line arguments to configure fuzzing behavior. Common options include:
135

136
- `-atheris_runs=N`: Limit fuzzing to N executions
137
- `-max_len=N`: Maximum input length
138
- `-timeout=N`: Timeout in seconds for each execution
139
- `-dict=file`: Use dictionary file for mutations
140
- `-jobs=N`: Number of parallel fuzzing jobs
141
- `-workers=N`: Number of simultaneous worker processes
142

143
**Usage Example:**
144

145
```python
146
import sys
147
import atheris
148

149
def TestOneInput(data):
150
    target_function(data)
151

152
# sys.argv might contain: ['fuzzer.py', '-atheris_runs=1000', '-max_len=100']
153
remaining_args = atheris.Setup(sys.argv, TestOneInput)
154
print(f"Remaining arguments: {remaining_args}")
155

156
atheris.Fuzz()
157
```
158

159
### Error Handling
160

161
Atheris reports failures when the test function throws uncaught exceptions:
162

163
```python
164
def TestOneInput(data):
165
    try:
166
        risky_function(data)
167
    except ExpectedException:
168
        # Expected exceptions should be caught - they don't indicate bugs
169
        pass
170
    # Uncaught exceptions will be reported as crashes by Atheris
171
```
172

173
For debugging, you can limit runs and examine specific inputs:
174

175
```python
176
# Run fuzzer for limited iterations to debug
177
# Command: python fuzzer.py -atheris_runs=10
178

179
def TestOneInput(data):
180
    print(f"Testing with {len(data)} bytes: {data[:10]}...")
181
    target_function(data)
182
```