module

Docs::A_GETTING_STARTED::DSL_GUIDE

Declarative DSL & Scoped Pipelines

Crowbar provides an expressive block-based DSL to pinpoint specific regions of data, attach weighted mutators, and calculate post-transform checksums or lengths.

Executive Summary & Key Topics

Topic Method / Anchor Description
Scopes, Matchers, and Fixup Hooks .topic_01_scopes_and_fixups Scoping byte ranges, regex captures, and repairing headers with fixups.
Deterministic Corpus Regression Gates (`Crowbar.corpus_gate`) .topic_02_corpus_gate Replaying crash reproducers and deterministic PRNG seeds inside `crystal spec` under a 60s watchdog budget.

Related Guides & Source References

  • src/crowbar/dsl/builder.cr
  • src/crowbar/selectors/base.cr

Class methods

topic_01_scopes_and_fixups

Scopes, Matchers, and Fixup Hooks: Scoping byte ranges, regex captures, and repairing headers with fixups.

Using Crowbar.define, you can isolate portions of an input payload:

Directive Syntax Description
`seed` `seed 1234_u64` Configures the deterministic PRNG
`pattern` `pattern :burst` Sets frequency (:once, :many, :burst)
`scope` `scope :header, bytes: 0...16` Constrains mutation to a byte range
`match` `match /"([^"]+)"/, group: 1` Targets regex match groups
`fixup` `fixup do \ buf\ ... end` Post-mutation callback for checksums

Working Examples

fuzzer = Crowbar.define do
  seed 0x1337_u64
  pattern :many

  # Scope 1: Protect and mutate header
  scope :header, bytes: 0...16 do
    weight 0.2
    mutate :byte_flip, :byte_swap
  end

  # Scope 2: Mutate payload
  scope :payload, bytes: 16.. do
    weight 0.8
    mutate :boundary_number, :unicode
  end

  # Fixup: recalculate payload length
  fixup do |buffer|
    next if buffer.size < 16
    len = (buffer.size - 16).to_u32
    IO::ByteFormat::BigEndian.encode(len, buffer[0, 4])
  end
end
Source
topic_02_corpus_gate

Deterministic Corpus Regression Gates (Crowbarcorpus_gate): Replaying crash reproducers and deterministic PRNG seeds inside crystal spec under a 60s watchdog budget.

Crowbar.corpus_gate wraps the Tier 1 Crowbar::Core::CorpusRunner engine in a declarative spec builder. It replays static crash reproducers (raw, Base64, hex, directories, or sessions) alongside deterministic PRNG-seeded mutations while enforcing a strict <= 60.seconds watchdog budget.

Working Examples

report = Crowbar.corpus_gate("Parser Regression Gate") do |gate|
  gate.watchdog_budget 60.seconds
  gate.seed 42_u64
  gate.iterations 25
  gate.preserve :json
  gate.expected_errors JSON::ParseException, ArgumentError

  gate.corpus %({"status": "ok"}), id: "baseline_json"
  gate.reproducer_base64 "eyJ0cmFwIjogdHJ1ZX0=", id: "repro_01"

  gate.execute do |buf|
    JSON.parse(buf.to_s)
  end
end
Source