Skip to content

Contributing

Contributions are welcome for mutation engines, target-faithful harnesses, execution services, correctness gates, documentation, and fixes.

Development setup

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

The Go packages require Go 1.23 or newer. Native harnesses also require the target source and a matching compiler/sanitizer toolchain.

Before changing code

  • Read the package tests and the public contract it implements.
  • Write a negative control that fails under the behavior being corrected.
  • Preserve unrelated work in a dirty tree.
  • Treat pkg/triage compatibility surfaces carefully; prefer additive wrappers over changes that would rewrite historical oracles.
  • Do not turn UNKNOWN, skipped work, or a missing integration into success.

Mutation engines

New mutations should name a source-derived invariant and include:

  • deterministic on-wire assertions;
  • an unrelated-field control;
  • serialization behavior;
  • custom-mutator linkage verification; and
  • a target experiment before any reach or yield claim.

See Adding Mutations.

Harnesses

A new harness must document the target commit, entry point, build flags, fault interception, limits, control input, and how far it proceeds beyond parsing. Add lifecycle, failure-to-start, timeout, and known-positive tests where possible.

See Writing Harnesses.

Documentation and generated artifacts

Do not hand-type counts that the repository can derive. Update the structured source or generator, then regenerate the public artifact. Public documentation must distinguish:

  • artifact admission from text evidence and process facts;
  • Exact, Stable, and legacy identities;
  • observed primitive from proposed impact;
  • submitted from assigner CWE/CVSS; and
  • tested commit from affected-version claims.

Run:

python3 tools/docs/generate_public_site.py --check
go run ./tools/cveviz --check
python3 tools/docs/audit_public_docs.py \
  --binary ./crucible --generator ./crucible-gen
mkdocs build --strict

Pull requests

  1. Keep commits reviewable and separate generated output from unrelated code.
  2. Add tests that fail under the previous or intentionally broken behavior.
  3. Run gofmt, go vet, and the relevant package tests.
  4. Run make gates where local evidence and stock integrations are available.
  5. State which gates were incomplete; do not report an incomplete run as green.

Security reports

Report vulnerabilities in Crucible itself through the repository's current private security reporting channel. Findings in fuzz targets belong to the affected project or an appropriate coordinator and remain operator-submitted. See Responsible Disclosure.