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.
Files changed (78) hide show
  1. krill_fuzzer-0.1.2/PKG-INFO +98 -0
  2. krill_fuzzer-0.1.2/README.md +86 -0
  3. krill_fuzzer-0.1.2/pyproject.toml +22 -0
  4. krill_fuzzer-0.1.2/src/krill_fuzzer/__init__.py +121 -0
  5. krill_fuzzer-0.1.2/src/krill_fuzzer/_config.py +71 -0
  6. krill_fuzzer-0.1.2/src/krill_fuzzer/_errors.py +49 -0
  7. krill_fuzzer-0.1.2/src/krill_fuzzer/_fuzz.py +270 -0
  8. krill_fuzzer-0.1.2/src/krill_fuzzer/_http_headers.py +12 -0
  9. krill_fuzzer-0.1.2/src/krill_fuzzer/_json_path.py +97 -0
  10. krill_fuzzer-0.1.2/src/krill_fuzzer/_planning.py +268 -0
  11. krill_fuzzer-0.1.2/src/krill_fuzzer/_replay.py +117 -0
  12. krill_fuzzer-0.1.2/src/krill_fuzzer/_results.py +76 -0
  13. krill_fuzzer-0.1.2/src/krill_fuzzer/_tokens.py +37 -0
  14. krill_fuzzer-0.1.2/src/krill_fuzzer/_tomllib.py +17 -0
  15. krill_fuzzer-0.1.2/src/krill_fuzzer/_workflow_instance.py +16 -0
  16. krill_fuzzer-0.1.2/src/krill_fuzzer/classify/__init__.py +26 -0
  17. krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_environment.py +17 -0
  18. krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_instance.py +235 -0
  19. krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_instance_probe.py +145 -0
  20. krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_parameter.py +102 -0
  21. krill_fuzzer-0.1.2/src/krill_fuzzer/classify/_types.py +73 -0
  22. krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/__init__.py +27 -0
  23. krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_collector.py +56 -0
  24. krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_oracle.py +20 -0
  25. krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_status_code.py +33 -0
  26. krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_types.py +36 -0
  27. krill_fuzzer-0.1.2/src/krill_fuzzer/evaluate/_workflow_success.py +120 -0
  28. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/__init__.py +14 -0
  29. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_anomaly.py +52 -0
  30. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_config.py +41 -0
  31. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_context.py +285 -0
  32. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_executor.py +54 -0
  33. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_extract.py +219 -0
  34. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_inject.py +276 -0
  35. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_localhost_cookies.py +87 -0
  36. krill_fuzzer-0.1.2/src/krill_fuzzer/execute/_value_source.py +67 -0
  37. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/__init__.py +115 -0
  38. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_boundary.py +55 -0
  39. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_byte.py +106 -0
  40. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_case.py +158 -0
  41. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_composite.py +68 -0
  42. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_corpus.py +277 -0
  43. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_correlation.py +284 -0
  44. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_dictionary.py +112 -0
  45. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_origin.py +16 -0
  46. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_refinement.py +200 -0
  47. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_resources/name_mutations.toml +990 -0
  48. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_resources/type_mutations.toml +331 -0
  49. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_scheduler.py +150 -0
  50. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/__init__.py +72 -0
  51. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_predicate.py +123 -0
  52. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_registry.py +63 -0
  53. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_rule.py +133 -0
  54. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_slot_plan.py +75 -0
  55. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_select/_toml.py +241 -0
  56. krill_fuzzer-0.1.2/src/krill_fuzzer/mutate/_strategy.py +100 -0
  57. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/__init__.py +38 -0
  58. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/__init__.py +9 -0
  59. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_format.py +51 -0
  60. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_multipart.py +282 -0
  61. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_registry.py +43 -0
  62. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_body/_text.py +257 -0
  63. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_codec.py +102 -0
  64. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_csrf_fallback.py +65 -0
  65. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_dependencies.py +269 -0
  66. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_extract_as.py +86 -0
  67. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_extraction.py +211 -0
  68. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_locator.py +29 -0
  69. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_model.py +185 -0
  70. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_nested_strings.py +53 -0
  71. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_response_values.py +164 -0
  72. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_seed.py +90 -0
  73. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_substitution.py +92 -0
  74. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_template.py +191 -0
  75. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_types.py +300 -0
  76. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_validation.py +64 -0
  77. krill_fuzzer-0.1.2/src/krill_fuzzer/parse/_value_type.py +43 -0
  78. 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."""