krill-fuzzer 0.1.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- krill_fuzzer-0.1.2/PKG-INFO +98 -0
- krill_fuzzer-0.1.2/README.md +86 -0
- krill_fuzzer-0.1.2/pyproject.toml +22 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/__init__.py +121 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_config.py +71 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_errors.py +49 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_fuzz.py +270 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_http_headers.py +12 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_json_path.py +97 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_planning.py +268 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_replay.py +117 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_results.py +76 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_tokens.py +37 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_tomllib.py +17 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/_workflow_instance.py +16 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/classify/__init__.py +26 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_environment.py +17 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_instance.py +235 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_instance_probe.py +145 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_parameter.py +102 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_types.py +73 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/__init__.py +27 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_collector.py +56 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_oracle.py +20 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_status_code.py +33 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_types.py +36 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_workflow_success.py +120 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/__init__.py +14 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_anomaly.py +52 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_config.py +41 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_context.py +285 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_executor.py +54 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_extract.py +219 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_inject.py +276 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_localhost_cookies.py +87 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_value_source.py +67 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/__init__.py +115 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_boundary.py +55 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_byte.py +106 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_case.py +158 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_composite.py +68 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_corpus.py +277 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_correlation.py +284 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_dictionary.py +112 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_origin.py +16 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_refinement.py +200 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_resources/name_mutations.toml +990 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_resources/type_mutations.toml +331 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_scheduler.py +150 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/__init__.py +72 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_predicate.py +123 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_registry.py +63 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_rule.py +133 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_slot_plan.py +75 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_toml.py +241 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_strategy.py +100 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/__init__.py +38 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/__init__.py +9 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_format.py +51 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_multipart.py +282 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_registry.py +43 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_text.py +257 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_codec.py +102 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_csrf_fallback.py +65 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_dependencies.py +269 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_extract_as.py +86 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_extraction.py +211 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_locator.py +29 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_model.py +185 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_nested_strings.py +53 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_response_values.py +164 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_seed.py +90 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_substitution.py +92 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_template.py +191 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_types.py +300 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_validation.py +64 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_value_type.py +43 -0
- krill_fuzzer-0.1.2/src/krill_fuzzer/py.typed +0 -0
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: krill-fuzzer
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: Engine-agnostic HTTP workflow fuzzer core library
|
|
5
|
+
Author: anonymous
|
|
6
|
+
Requires-Dist: krill-core>=0.1.0,<0.2.0
|
|
7
|
+
Requires-Dist: beautifulsoup4>=4.14.3
|
|
8
|
+
Requires-Dist: requests>=2.32
|
|
9
|
+
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
|
|
13
|
+
# krill-fuzzer
|
|
14
|
+
|
|
15
|
+
> 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.
|
|
16
|
+
|
|
17
|
+
Consume a recorded HTTP workflow and mutate each parameter with security-aware payloads against a running target.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
uv add krill-fuzzer
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Record workflows with the companion [krill-collector](../krill-collector/README.md) package.
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
from krill_fuzzer import fuzz, load_recording
|
|
33
|
+
|
|
34
|
+
# Load a recording produced by krill-collector
|
|
35
|
+
recording = load_recording("logicflow.json")
|
|
36
|
+
|
|
37
|
+
# Mutate each parameter, execute against the target, evaluate responses
|
|
38
|
+
findings = fuzz(recording, "http://target-app.local")
|
|
39
|
+
|
|
40
|
+
for f in findings:
|
|
41
|
+
print(f"[{f.verdict.kind.value}] {f.mutation.parameter_name}={f.mutation.mutated_value!r}")
|
|
42
|
+
print(f" {f.mutation.reason} — {f.verdict.reason}")
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## API
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
recording ──▶ parse ──▶ mutate ──▶ fuzz
|
|
49
|
+
├── execute (HttpExecutor)
|
|
50
|
+
└── evaluate (BugOracle)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### `krill_fuzzer`
|
|
54
|
+
|
|
55
|
+
Root package: one-call fuzzing, lifecycle control, HTTP primitives, and the exception hierarchy.
|
|
56
|
+
|
|
57
|
+
| Symbol | Type | Description |
|
|
58
|
+
|--------|------|-------------|
|
|
59
|
+
| `fuzz(recording, url, config)` | function | One-call fuzzing: parse → run → findings |
|
|
60
|
+
| `Fuzzer(recording, url, config)` | class | Lifecycle control: `run()`, `results()` |
|
|
61
|
+
| `FuzzConfig` | dataclass | Tuning knobs: oracle, collector, timeout, classify |
|
|
62
|
+
| `Finding` | dataclass | mutation + execution result + verdict |
|
|
63
|
+
| `FuzzStatus` | dataclass | Progress: total_cases, completed, findings |
|
|
64
|
+
| `classify_parameters` | function | Probe-based parameter classification |
|
|
65
|
+
| `WorkflowInstance` | dataclass | requests, step_order |
|
|
66
|
+
| `HttpMethod` / `HttpRequest` / `HttpResponse` / `HttpExchange` | HTTP primitives (from `krill-core`) |
|
|
67
|
+
| `WorkflowRecording` | dataclass | Recording input (from `krill-core`) |
|
|
68
|
+
| `save_recording` / `load_recording` | JSON persistence (from `krill-core`) |
|
|
69
|
+
| `KrillError` | Exception | Base for all krill errors |
|
|
70
|
+
| `PersistenceError` | Exception | Recording serialization failure |
|
|
71
|
+
| `ExtractionError` / `ModelError` / `CodecError` / `ExecutionError` / `FuzzError` | Exception | Fuzzer-stage failures |
|
|
72
|
+
|
|
73
|
+
### `krill_fuzzer.parse` · `.mutate` · `.execute` · `.evaluate`
|
|
74
|
+
|
|
75
|
+
Layer-2 sub-packages for custom pipelines: specification extraction (`parse`), mutation generation (`mutate`), sequential HTTP execution (`execute`), and bug oracles (`evaluate`).
|
|
76
|
+
|
|
77
|
+
## Documentation
|
|
78
|
+
|
|
79
|
+
- [Docs index](docs/index.md) — parse, mutate, schedule, execute, evaluate design/spec/impl docs.
|
|
80
|
+
- [Concept](docs/concept.md) — recording, Value Flow, mutation strategy/scheduler, gate, oracle.
|
|
81
|
+
- Agent-consumable documentation index at [`docs/llms.txt`](../../docs/llms.txt) (llmstxt.org format).
|
|
82
|
+
|
|
83
|
+
## Citation
|
|
84
|
+
|
|
85
|
+
If you use this project in academic work, please cite our paper. BibTeX (placeholder until the paper is released):
|
|
86
|
+
|
|
87
|
+
```bibtex
|
|
88
|
+
@misc{beluga_placeholder,
|
|
89
|
+
title = {{TODO: paper title — not yet released}},
|
|
90
|
+
author = {{TODO: authors}},
|
|
91
|
+
year = {{TODO}},
|
|
92
|
+
note = {Paper not yet released. Citation entry will be updated on publication.}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
GPL-2.0 — see [LICENSE](../../LICENSE).
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# krill-fuzzer
|
|
2
|
+
|
|
3
|
+
> 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.
|
|
4
|
+
|
|
5
|
+
Consume a recorded HTTP workflow and mutate each parameter with security-aware payloads against a running target.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv add krill-fuzzer
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Record workflows with the companion [krill-collector](../krill-collector/README.md) package.
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from krill_fuzzer import fuzz, load_recording
|
|
21
|
+
|
|
22
|
+
# Load a recording produced by krill-collector
|
|
23
|
+
recording = load_recording("logicflow.json")
|
|
24
|
+
|
|
25
|
+
# Mutate each parameter, execute against the target, evaluate responses
|
|
26
|
+
findings = fuzz(recording, "http://target-app.local")
|
|
27
|
+
|
|
28
|
+
for f in findings:
|
|
29
|
+
print(f"[{f.verdict.kind.value}] {f.mutation.parameter_name}={f.mutation.mutated_value!r}")
|
|
30
|
+
print(f" {f.mutation.reason} — {f.verdict.reason}")
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## API
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
recording ──▶ parse ──▶ mutate ──▶ fuzz
|
|
37
|
+
├── execute (HttpExecutor)
|
|
38
|
+
└── evaluate (BugOracle)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### `krill_fuzzer`
|
|
42
|
+
|
|
43
|
+
Root package: one-call fuzzing, lifecycle control, HTTP primitives, and the exception hierarchy.
|
|
44
|
+
|
|
45
|
+
| Symbol | Type | Description |
|
|
46
|
+
|--------|------|-------------|
|
|
47
|
+
| `fuzz(recording, url, config)` | function | One-call fuzzing: parse → run → findings |
|
|
48
|
+
| `Fuzzer(recording, url, config)` | class | Lifecycle control: `run()`, `results()` |
|
|
49
|
+
| `FuzzConfig` | dataclass | Tuning knobs: oracle, collector, timeout, classify |
|
|
50
|
+
| `Finding` | dataclass | mutation + execution result + verdict |
|
|
51
|
+
| `FuzzStatus` | dataclass | Progress: total_cases, completed, findings |
|
|
52
|
+
| `classify_parameters` | function | Probe-based parameter classification |
|
|
53
|
+
| `WorkflowInstance` | dataclass | requests, step_order |
|
|
54
|
+
| `HttpMethod` / `HttpRequest` / `HttpResponse` / `HttpExchange` | HTTP primitives (from `krill-core`) |
|
|
55
|
+
| `WorkflowRecording` | dataclass | Recording input (from `krill-core`) |
|
|
56
|
+
| `save_recording` / `load_recording` | JSON persistence (from `krill-core`) |
|
|
57
|
+
| `KrillError` | Exception | Base for all krill errors |
|
|
58
|
+
| `PersistenceError` | Exception | Recording serialization failure |
|
|
59
|
+
| `ExtractionError` / `ModelError` / `CodecError` / `ExecutionError` / `FuzzError` | Exception | Fuzzer-stage failures |
|
|
60
|
+
|
|
61
|
+
### `krill_fuzzer.parse` · `.mutate` · `.execute` · `.evaluate`
|
|
62
|
+
|
|
63
|
+
Layer-2 sub-packages for custom pipelines: specification extraction (`parse`), mutation generation (`mutate`), sequential HTTP execution (`execute`), and bug oracles (`evaluate`).
|
|
64
|
+
|
|
65
|
+
## Documentation
|
|
66
|
+
|
|
67
|
+
- [Docs index](docs/index.md) — parse, mutate, schedule, execute, evaluate design/spec/impl docs.
|
|
68
|
+
- [Concept](docs/concept.md) — recording, Value Flow, mutation strategy/scheduler, gate, oracle.
|
|
69
|
+
- Agent-consumable documentation index at [`docs/llms.txt`](../../docs/llms.txt) (llmstxt.org format).
|
|
70
|
+
|
|
71
|
+
## Citation
|
|
72
|
+
|
|
73
|
+
If you use this project in academic work, please cite our paper. BibTeX (placeholder until the paper is released):
|
|
74
|
+
|
|
75
|
+
```bibtex
|
|
76
|
+
@misc{beluga_placeholder,
|
|
77
|
+
title = {{TODO: paper title — not yet released}},
|
|
78
|
+
author = {{TODO: authors}},
|
|
79
|
+
year = {{TODO}},
|
|
80
|
+
note = {Paper not yet released. Citation entry will be updated on publication.}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## License
|
|
85
|
+
|
|
86
|
+
GPL-2.0 — see [LICENSE](../../LICENSE).
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "krill-fuzzer"
|
|
3
|
+
version = "0.1.2"
|
|
4
|
+
description = "Engine-agnostic HTTP workflow fuzzer core library"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [
|
|
7
|
+
{ name = "anonymous" }
|
|
8
|
+
]
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
dependencies = [
|
|
11
|
+
"krill-core>=0.1.0,<0.2.0",
|
|
12
|
+
"beautifulsoup4>=4.14.3",
|
|
13
|
+
"requests>=2.32",
|
|
14
|
+
"tomli>=2.0; python_version < '3.11'",
|
|
15
|
+
]
|
|
16
|
+
|
|
17
|
+
[tool.uv.sources]
|
|
18
|
+
krill-core = { workspace = true }
|
|
19
|
+
|
|
20
|
+
[build-system]
|
|
21
|
+
requires = ["uv_build>=0.11.26,<0.12"]
|
|
22
|
+
build-backend = "uv_build"
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
"""krill-fuzzer — Black-box HTTP workflow fuzzer.
|
|
2
|
+
|
|
3
|
+
Progressive API:
|
|
4
|
+
Layer 0: krill_fuzzer.fuzz(recording, url) → list[Finding]
|
|
5
|
+
Layer 1: krill_fuzzer.Fuzzer(recording, url, config=FuzzConfig(...)).run()
|
|
6
|
+
Layer 2: krill_fuzzer.parse / .mutate / .execute / .evaluate sub-packages
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from collections.abc import Callable
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
|
|
14
|
+
from krill_core import (
|
|
15
|
+
HttpExchange,
|
|
16
|
+
HttpMethod,
|
|
17
|
+
HttpRequest,
|
|
18
|
+
HttpResponse,
|
|
19
|
+
KrillError,
|
|
20
|
+
PersistenceError,
|
|
21
|
+
WorkflowRecording,
|
|
22
|
+
load_recording,
|
|
23
|
+
save_recording,
|
|
24
|
+
)
|
|
25
|
+
from krill_fuzzer._config import (
|
|
26
|
+
EvaluationConfig,
|
|
27
|
+
ExecutionConfig,
|
|
28
|
+
FuzzConfig,
|
|
29
|
+
MutationConfig,
|
|
30
|
+
)
|
|
31
|
+
from krill_fuzzer._errors import (
|
|
32
|
+
CodecError,
|
|
33
|
+
ExecutionError,
|
|
34
|
+
ExtractionError,
|
|
35
|
+
FuzzError,
|
|
36
|
+
ModelError,
|
|
37
|
+
SelectionError,
|
|
38
|
+
)
|
|
39
|
+
from krill_fuzzer._fuzz import Fuzzer
|
|
40
|
+
from krill_fuzzer._replay import ReplayResult, StepResponse, replay
|
|
41
|
+
from krill_fuzzer._results import CaseError, Finding, FuzzStatus, WorkflowFailure
|
|
42
|
+
from krill_fuzzer._workflow_instance import WorkflowInstance
|
|
43
|
+
from krill_fuzzer.classify import (
|
|
44
|
+
InstanceClassification,
|
|
45
|
+
InstancePair,
|
|
46
|
+
InstanceRelation,
|
|
47
|
+
InstanceStrategy,
|
|
48
|
+
classify_parameters,
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def fuzz(
|
|
53
|
+
recording: str | Path | object,
|
|
54
|
+
target_url: str,
|
|
55
|
+
*,
|
|
56
|
+
config: FuzzConfig | None = None,
|
|
57
|
+
on_status: Callable[[FuzzStatus], None] | None = None,
|
|
58
|
+
) -> list[Finding]:
|
|
59
|
+
"""Fuzz an HTTP workflow recording against a target URL.
|
|
60
|
+
|
|
61
|
+
Args:
|
|
62
|
+
recording: Path to requests.json, or a WorkflowRecording object.
|
|
63
|
+
target_url: Base URL of the running target application.
|
|
64
|
+
config: FuzzConfig tuning knobs (oracle, collector, timeout, ...);
|
|
65
|
+
omitted → defaults.
|
|
66
|
+
on_status: Progress callback.
|
|
67
|
+
|
|
68
|
+
Returns:
|
|
69
|
+
List of findings (mutations the oracle judged FAIL). Execution failures
|
|
70
|
+
are recorded separately; use the Fuzzer API directly to access them.
|
|
71
|
+
"""
|
|
72
|
+
fuzzer = Fuzzer(recording, target_url, config)
|
|
73
|
+
fuzzer.run(on_status=on_status)
|
|
74
|
+
return fuzzer.results()
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
__all__ = [
|
|
78
|
+
# Layer 0: one-call API
|
|
79
|
+
"fuzz",
|
|
80
|
+
# Layer 1: lifecycle control
|
|
81
|
+
"Fuzzer",
|
|
82
|
+
"FuzzConfig",
|
|
83
|
+
"MutationConfig",
|
|
84
|
+
"EvaluationConfig",
|
|
85
|
+
"ExecutionConfig",
|
|
86
|
+
"Finding",
|
|
87
|
+
"CaseError",
|
|
88
|
+
"WorkflowFailure",
|
|
89
|
+
"FuzzStatus",
|
|
90
|
+
# Layer 2: custom pipeline utility
|
|
91
|
+
"classify_parameters",
|
|
92
|
+
# Errors (base + persistence re-exported from krill_core)
|
|
93
|
+
"KrillError",
|
|
94
|
+
"PersistenceError",
|
|
95
|
+
"ExtractionError",
|
|
96
|
+
"ModelError",
|
|
97
|
+
"CodecError",
|
|
98
|
+
"ExecutionError",
|
|
99
|
+
"FuzzError",
|
|
100
|
+
"SelectionError",
|
|
101
|
+
# HTTP primitives (from krill_core)
|
|
102
|
+
"HttpMethod",
|
|
103
|
+
"HttpRequest",
|
|
104
|
+
"HttpResponse",
|
|
105
|
+
"HttpExchange",
|
|
106
|
+
"WorkflowInstance",
|
|
107
|
+
# Recording model (from krill_core)
|
|
108
|
+
"WorkflowRecording",
|
|
109
|
+
# Instance classification
|
|
110
|
+
"InstanceClassification",
|
|
111
|
+
"InstancePair",
|
|
112
|
+
"InstanceRelation",
|
|
113
|
+
"InstanceStrategy",
|
|
114
|
+
# Replay
|
|
115
|
+
"ReplayResult",
|
|
116
|
+
"StepResponse",
|
|
117
|
+
"replay",
|
|
118
|
+
# Persistence (from krill_core)
|
|
119
|
+
"save_recording",
|
|
120
|
+
"load_recording",
|
|
121
|
+
]
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
"""FuzzConfig — immutable Fuzzer tuning knobs, grouped by concern.
|
|
2
|
+
|
|
3
|
+
The flat bundle is decomposed into three cohesive sub-configs — mutation,
|
|
4
|
+
evaluation, execution — so each concern changes for one reason. Every field
|
|
5
|
+
defaults, so a Layer 0/1 caller may omit the whole bundle.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
|
|
12
|
+
from krill_fuzzer.evaluate import (
|
|
13
|
+
AcceptAll,
|
|
14
|
+
BugOracle,
|
|
15
|
+
ExecutionCollector,
|
|
16
|
+
SuccessCriterion,
|
|
17
|
+
)
|
|
18
|
+
from krill_fuzzer.mutate import (
|
|
19
|
+
DEFAULT_RULES,
|
|
20
|
+
MutationScheduler,
|
|
21
|
+
MutationStrategy,
|
|
22
|
+
MutatorRegistry,
|
|
23
|
+
Rule,
|
|
24
|
+
SeedScorer,
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class MutationConfig:
|
|
30
|
+
"""How fuzzable slots become candidate values — targeting and generation."""
|
|
31
|
+
|
|
32
|
+
rules: tuple[Rule, ...] = DEFAULT_RULES
|
|
33
|
+
registry: MutatorRegistry = field(default_factory=MutatorRegistry)
|
|
34
|
+
strategy: MutationStrategy | None = None
|
|
35
|
+
byte_mutation_ratio: float = 0.0
|
|
36
|
+
|
|
37
|
+
def __post_init__(self) -> None:
|
|
38
|
+
if not 0.0 <= self.byte_mutation_ratio <= 1.0:
|
|
39
|
+
raise ValueError(
|
|
40
|
+
f"byte_mutation_ratio must be in [0, 1], got {self.byte_mutation_ratio}"
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
@dataclass(frozen=True)
|
|
45
|
+
class EvaluationConfig:
|
|
46
|
+
"""How an executed case is gated and judged."""
|
|
47
|
+
|
|
48
|
+
oracle: BugOracle | None = None
|
|
49
|
+
collector: ExecutionCollector | None = None
|
|
50
|
+
success_criterion: SuccessCriterion = field(default_factory=AcceptAll)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
@dataclass(frozen=True)
|
|
54
|
+
class ExecutionConfig:
|
|
55
|
+
"""How the campaign loop runs and explores — toggles and feedback machinery."""
|
|
56
|
+
|
|
57
|
+
scheduler: MutationScheduler | None = None
|
|
58
|
+
seed_scorer: SeedScorer | None = None
|
|
59
|
+
timeout_seconds: float = 10.0
|
|
60
|
+
classify: bool = True
|
|
61
|
+
refine_instances: bool = False
|
|
62
|
+
reseed_findings: bool = False
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
@dataclass(frozen=True)
|
|
66
|
+
class FuzzConfig:
|
|
67
|
+
"""Immutable Fuzzer tuning knobs, separate from runtime state."""
|
|
68
|
+
|
|
69
|
+
mutation: MutationConfig = field(default_factory=MutationConfig)
|
|
70
|
+
evaluation: EvaluationConfig = field(default_factory=EvaluationConfig)
|
|
71
|
+
execution: ExecutionConfig = field(default_factory=ExecutionConfig)
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"""Fuzzer exception types — extending the shared KrillError base."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from krill_core import KrillError
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class ExtractionError(KrillError):
|
|
9
|
+
"""Specification extraction failure."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class ModelError(KrillError):
|
|
13
|
+
"""Workflow model validation failure."""
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class CodecError(KrillError):
|
|
17
|
+
"""Byte encode/decode failure."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class SelectionError(KrillError):
|
|
21
|
+
"""Invalid slot-resolution rule list.
|
|
22
|
+
|
|
23
|
+
Raised when a rule list has no trailing catch-all, a SEED or BIND rule
|
|
24
|
+
names mutators, or a rule references an unregistered mutator.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class ExecutionError(KrillError):
|
|
29
|
+
"""HTTP execution failure against target server.
|
|
30
|
+
|
|
31
|
+
Attributes:
|
|
32
|
+
step_index: Zero-based index of the workflow step where the failure occurred.
|
|
33
|
+
__cause__: Original exception that triggered this error, if any.
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
def __init__(
|
|
37
|
+
self,
|
|
38
|
+
message: str,
|
|
39
|
+
step_index: int,
|
|
40
|
+
cause: Exception | None = None,
|
|
41
|
+
) -> None:
|
|
42
|
+
super().__init__(message)
|
|
43
|
+
self.step_index = step_index
|
|
44
|
+
if cause is not None:
|
|
45
|
+
self.__cause__ = cause
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class FuzzError(KrillError):
|
|
49
|
+
"""Fuzzer lifecycle failure."""
|