fix: tighten python fuzzing examples

Author: berisher

README.md

@@ -198,23 +198,23 @@ same seed or fuzzer input.
 ### Integration with Atheris
 
 Use the `PickleMutator` class for structure-aware fuzzing:
+Pass generated pickle bytes to the parser you actually want to fuzz. Do not call
+`pickle.loads()` on generated data outside a sandbox.
 
 ```python
 import atheris
+import sys
 from pickle_fuzzer.fuzzer import PickleMutator
-import pickle
-
-mutator = PickleMutator(protocol=3)
 
 @atheris.instrument_func
 def test_one_input(data: bytes):
     # Generate a valid pickle from fuzzer input within the requested budget
-    pickle_bytes = mutator.mutate(data, max_size=10000)
-    
-    try:
-        pickle.loads(pickle_bytes)
-    except Exception:
-        pass  # Expected - looking for crashes
+    input_mutator = PickleMutator(protocol=3)
+    pickle_bytes = input_mutator.mutate(data, max_size=10000)
+
+    # Call the parser you actually want to fuzz with pickle_bytes here.
+    # For example: target.parse_pickle(pickle_bytes)
+    ...
 
 atheris.Setup(sys.argv, test_one_input)
 atheris.Fuzz()
@@ -275,6 +275,9 @@ For detailed fuzzing documentation, see [fuzz/README.md](fuzz/README.md).
 
 ### Fuzzing Custom Pickle Parsers
 
+Do not point these harnesses at `pickle.loads()` unless the unpickling step runs
+inside a sandbox you control.
+
 ```python
 #!/usr/bin/env python3
 import atheris
@@ -283,9 +286,9 @@ from pickle_fuzzer.fuzzer import fuzz_pickle_parser
 
 # Your custom pickle parser
 def my_pickle_parser(data: bytes):
-    # Your parsing logic here
-    import pickle
-    return pickle.loads(data)
+    # Replace this with the parser entrypoint you actually want to fuzz.
+    # Example: return my_project.parse_pickle(data)
+    ...
 
 if __name__ == "__main__":
     # Use structure-aware generation
@@ -300,21 +303,31 @@ if __name__ == "__main__":
 
 ```python
 import atheris
+import io
 import pickle
+import sys
 from pickle_fuzzer.fuzzer import PickleMutator
 
-class CustomUnpickler(pickle.Unpickler):
-    def find_class(self, module, name):
-        # Custom class resolution logic
-        return super().find_class(module, name)
+_ALLOWED_GLOBALS = {
+    # Add only the globals your target intentionally supports.
+}
 
-mutator = PickleMutator(protocol=3)
+
+class RestrictedUnpickler(pickle.Unpickler):
+    def find_class(self, module, name):
+        try:
+            return _ALLOWED_GLOBALS[(module, name)]
+        except KeyError as exc:
+            raise pickle.UnpicklingError(
+                f"global '{module}.{name}' is forbidden in this harness"
+            ) from exc
 
 @atheris.instrument_func
 def test_custom_unpickler(data: bytes):
-    pickle_bytes = mutator.mutate(data, max_size=10000)
+    input_mutator = PickleMutator(protocol=3)
+    pickle_bytes = input_mutator.mutate(data, max_size=10000)
     try:
-        CustomUnpickler(io.BytesIO(pickle_bytes)).load()
+        RestrictedUnpickler(io.BytesIO(pickle_bytes)).load()
     except Exception:
         pass
 

python/examples/harness.py

@@ -22,12 +22,11 @@
 
 with atheris.instrument_imports():
     import sys
-    import pickle
     # import your fuzz target
 
 
 def TestOneInput(data: bytes) -> None:
-    """Test Python's pickle.loads() with generated data."""
+    """Generate structured pickle data and pass it to your parser."""
     if not data:
         return
     proto = data[0] % 6
@@ -37,6 +36,8 @@ def TestOneInput(data: bytes) -> None:
     try:
         # call your fuzz target with pickle_bytes
         # e.g. target.parse(pickle_bytes)
+        _ = pickle_bytes
+        ...
     except Exception:
         ...
 

python/pickle_fuzzer/fuzzer.py

@@ -35,15 +35,14 @@ class PickleMutator:
         ```python
         import atheris
         from pickle_fuzzer.fuzzer import PickleMutator
-        
-        mutator = PickleMutator(protocol=4)
-        
+
         @atheris.instrument_func
         def fuzz_target(data):
-            pickle_bytes = mutator.mutate(data, max_size=10000)
+            input_mutator = PickleMutator(protocol=4)
+            pickle_bytes = input_mutator.mutate(data, max_size=10000)
             # test your pickle parser with pickle_bytes
             ...
-        
+
         atheris.Setup(sys.argv, fuzz_target)
         atheris.Fuzz()
         ```
@@ -124,8 +123,7 @@ def test_one_input(data: bytes) -> None:
             # Test the parser
             parser_func(pickle_bytes)
         except Exception:
-            print(f'Failed to parse pickle: {data}')
-            pass  # Expected - we're looking for crashes/hangs
+            pass  # Parser exceptions are expected; we're looking for crashes/hangs.
 
     atheris.Setup(sys.argv, test_one_input)
     atheris.Fuzz()

python/tests/test_fuzzer.py

@@ -15,7 +15,10 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import pickletools
+import py_compile
+from pathlib import Path
 
+import pickle_fuzzer.fuzzer as fuzz_module
 from pickle_fuzzer.fuzzer import PickleMutator
 
 
@@ -40,6 +43,9 @@ def test_pickle_mutator_fallback_stays_valid(monkeypatch):
     mutator = PickleMutator(protocol=4, seed=123)
 
     class FailingGenerator:
+        def reset(self):
+            return None
+
         def generate_from_bytes(self, *args, **kwargs):
             raise RuntimeError("boom")
 
@@ -49,3 +55,45 @@ def generate_from_bytes(self, *args, **kwargs):
 
     assert len(data) <= 32
     assert_whole_pickle_consumed(data)
+
+
+def test_pickle_mutator_reuse_matches_fresh_instance():
+    reused_mutator = PickleMutator(protocol=4, seed=123)
+    fresh_mutator = PickleMutator(protocol=4, seed=123)
+
+    first = reused_mutator.mutate(b"alpha", max_size=256)
+    second = reused_mutator.mutate(b"beta", max_size=256)
+    fresh_second = fresh_mutator.mutate(b"beta", max_size=256)
+
+    assert second == fresh_second
+    assert second != first
+    assert_whole_pickle_consumed(second)
+
+
+def test_fuzz_pickle_parser_swallows_parser_exceptions_without_logging(
+    monkeypatch, capsys
+):
+    captured = {}
+
+    monkeypatch.setattr(fuzz_module.atheris, "instrument_func", lambda func: func)
+    monkeypatch.setattr(
+        fuzz_module.atheris,
+        "Setup",
+        lambda _argv, func: captured.setdefault("callback", func),
+    )
+    monkeypatch.setattr(fuzz_module.atheris, "Fuzz", lambda: None)
+
+    def failing_parser(_data: bytes) -> None:
+        raise ValueError("boom")
+
+    fuzz_module.fuzz_pickle_parser(failing_parser, protocol=3, use_structure_aware=False)
+    captured["callback"](b"input")
+
+    output = capsys.readouterr()
+    assert output.out == ""
+    assert output.err == ""
+
+
+def test_example_harness_compiles():
+    harness_path = Path(__file__).resolve().parents[1] / "examples" / "harness.py"
+    py_compile.compile(str(harness_path), doraise=True)