krill-fuzzer 0.1.2

Engine-agnostic HTTP workflow fuzzer core library

krill-fuzzer

Krill are tiny crustaceans that swarm the ocean in enormous numbers — individually insignificant, collectively they sustain whales. Each mutated test case is a single krill: small, fast, almost trivial — but hundreds of them per parameter can surface vulnerabilities no hand-written test suite would find.

Consume a recorded HTTP workflow and mutate each parameter with security-aware payloads against a running target.

Install

Requires Python 3.10+ and uv.

uv add krill-fuzzer

Record workflows with the companion krill-collector package.

Usage

from krill_fuzzer import fuzz, load_recording

# Load a recording produced by krill-collector
recording = load_recording("logicflow.json")

# Mutate each parameter, execute against the target, evaluate responses
findings = fuzz(recording, "http://target-app.local")

for f in findings:
    print(f"[{f.verdict.kind.value}] {f.mutation.parameter_name}={f.mutation.mutated_value!r}")
    print(f"  {f.mutation.reason} — {f.verdict.reason}")

API

recording ──▶ parse ──▶ mutate ──▶ fuzz
                         ├── execute  (HttpExecutor)
                         └── evaluate (BugOracle)

krill_fuzzer

Root package: one-call fuzzing, lifecycle control, HTTP primitives, and the exception hierarchy.

Symbol	Type	Description
fuzz(recording, url, config)	function	One-call fuzzing: parse → run → findings
Fuzzer(recording, url, config)	class	Lifecycle control: run(), results()
FuzzConfig	dataclass	Tuning knobs: oracle, collector, timeout, classify
Finding	dataclass	mutation + execution result + verdict
FuzzStatus	dataclass	Progress: total_cases, completed, findings
classify_parameters	function	Probe-based parameter classification
WorkflowInstance	dataclass	requests, step_order
HttpMethod / HttpRequest / HttpResponse / HttpExchange	HTTP primitives (from krill-core)
WorkflowRecording	dataclass	Recording input (from krill-core)
save_recording / load_recording	JSON persistence (from krill-core)
KrillError	Exception	Base for all krill errors
PersistenceError	Exception	Recording serialization failure
ExtractionError / ModelError / CodecError / ExecutionError / FuzzError	Exception	Fuzzer-stage failures

krill_fuzzer.parse · .mutate · .execute · .evaluate

Layer-2 sub-packages for custom pipelines: specification extraction (parse), mutation generation (mutate), sequential HTTP execution (execute), and bug oracles (evaluate).

Documentation

• Docs index — parse, mutate, schedule, execute, evaluate design/spec/impl docs.
• Concept — recording, Value Flow, mutation strategy/scheduler, gate, oracle.
• Agent-consumable documentation index at docs/llms.txt (llmstxt.org format).

Citation

If you use this project in academic work, please cite our paper. BibTeX (placeholder until the paper is released):

@misc{beluga_placeholder,
  title  = {{TODO: paper title — not yet released}},
  author = {{TODO: authors}},
  year   = {{TODO}},
  note   = {Paper not yet released. Citation entry will be updated on publication.}
}

License

GPL-2.0 — see LICENSE.