Metadata-Version: 2.3
Name: krill-fuzzer
Version: 0.1.3
Summary: Engine-agnostic HTTP workflow fuzzer core library
Author: anonymous
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: krill-core>=0.1.0,<0.2.0
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: requests>=2.32
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/).

```bash
uv add krill-fuzzer
```

Record workflows with the companion [krill-collector](../krill-collector/README.md) package.

## Usage

```python
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](docs/index.md) — parse, mutate, schedule, execute, evaluate design/spec/impl docs.
- [Concept](docs/concept.md) — recording, Value Flow, mutation strategy/scheduler, gate, oracle.
- Agent-consumable documentation index at [`docs/llms.txt`](../../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):

```bibtex
@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](../../LICENSE).
