Contributing¶

Crucible welcomes contributions — new mutation strategies, target harnesses, bug reports, and documentation improvements.

Development Setup¶

git clone https://github.com/professor-moody/crucible.git
cd crucible
make build
make test

Requirements: Go 1.23+, clang (for harness builds)

Areas to Contribute¶

New Mutation Strategies¶

The mutation engine is the core innovation. New strategies that target unexplored parser code paths are highly valuable.

See the Adding Mutations guide for a step-by-step walkthrough.

Ideas for new strategies:

• Metadata with extremely deep nested arrays
• Tensor info with NaN/Inf in float16 dimension values
• Files that are valid GGUF v2 but claim to be v3
• Metadata keys with characters that confuse filesystem APIs
• Tensor data that is valid for one type but interpreted as another

New Target Harnesses¶

Every application that loads GGUF files is a potential target. Current targets with active harnesses:

• llama.cpp — primary target, GGUF parsing, RPC protocol, grammar engines, tokenizer, HTTP server API
• whisper.cpp — audio model loader and inference pipeline, shares ggml code paths
• stable-diffusion.cpp — multi-format model loader (GGUF, SafeTensors, Checkpoint)
• Ollama — vendored llama.cpp fork, Modelfile parser
• PyTorch / libtorch — TorchScript model deserialization
• TensorFlow Lite — FlatBuffer-based model loading
• Apple MLX — GGUF and SafeTensors loaders
• ONNX Runtime — ONNX model parsing (experimental)

Potential new targets:

• llama-cpp-python — Python bindings with custom GGUF loading
• LocalAI — Go-based local AI server
• koboldcpp — llama.cpp fork with custom extensions
• Candle — Rust ML framework with SafeTensors support
• Triton Inference Server — NVIDIA's production inference server

See the Writing Harnesses guide.

Documentation¶

• Fix typos or unclear explanations
• Add examples for API usage
• Improve the GGUF format specification
• Document new CVEs as they're discovered

Code Style¶

• Follow standard Go conventions (gofmt, go vet)
• Test new strategies with multiple RNG seeds
• Keep mutations targeted — 1-3 changes per file, not total corruption
• Use the provided RNG parameter for deterministic reproduction

Pull Request Process¶

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Run make test and make lint
5. Submit a PR with a clear description

Reporting Security Issues¶

If you discover a vulnerability in Crucible itself (not in a fuzzing target), please report it via GitHub Security Advisories.

If you discover a vulnerability in a fuzzing target using Crucible, follow the Responsible Disclosure workflow.