### Install Boofuzz from Source with Pip

Source: https://github.com/jtpereyda/boofuzz/blob/master/INSTALL.rst

Install Boofuzz directly from its source directory using pip. Use the -e option for editable installs.

```bash
$ pip install .
```

```bash
$ pip install -e .
```

```bash
$ pip install -e .[dev]
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/install.md

Sets up a Python virtual environment for boofuzz installation. Activate the environment before proceeding with package installations.

```bash
mkdir boofuzz && cd boofuzz
python3 -m venv env
```

```bash
source env/bin/activate
```

```batch
env\Scripts\activate.bat
```

--------------------------------

### Start Python HTTP Server

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/quickstart.md

Start a simple HTTP server using Python's built-in module. This is useful for testing HTTP fuzzing scripts.

```bash
$ python3 -m http.server

```

--------------------------------

### Process Monitor Setup with ProcessMonitor

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Initialize ProcessMonitor to detect crashes and restart target processes. The boofuzz-pm daemon must be started on the target host before running this code.

```python
from boofuzz import *

# Start daemon on target host first:

```

--------------------------------

### Install boofuzz with Poetry Extras

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/install.md

Installs boofuzz with additional dependency groups like 'dev' or 'docs' using Poetry.

```bash
$ poetry install --extras "dev"
```

```bash
$ poetry install -E docs
```

```bash
$ poetry install --all-extras
```

--------------------------------

### Install Boofuzz with Poetry

Source: https://github.com/jtpereyda/boofuzz/blob/master/INSTALL.rst

Install Boofuzz and its dependencies using Poetry within the source directory. This command also installs extra dependencies if specified.

```bash
$ poetry install
```

```bash
$ poetry install --extras "dev"
```

```bash
$ poetry install -E docs
```

```bash
$ poetry install --all-extras
```

--------------------------------

### Install boofuzz from Source with Pip

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/install.md

Installs boofuzz directly from the local source code using pip. This is useful for development or when installing a specific version.

```bash
$ pip install .
```

--------------------------------

### Upgrade Pip and Setuptools

Source: https://github.com/jtpereyda/boofuzz/blob/master/INSTALL.rst

Ensure you have the latest versions of pip and setuptools installed within your activated virtual environment.

```bash
(env) $ pip install -U pip setuptools
```

--------------------------------

### post_start_target Method

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/monitors.md

Called after a target is started or restarted.

```APIDOC
## post_start_target(target=None, fuzz_data_logger=None, session=None)

Called after a target is started or restarted.
```

--------------------------------

### Install boofuzz with Poetry

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/install.md

Installs boofuzz using Poetry, which automatically manages virtual environments and dependencies. This command installs the package in editable mode.

```bash
$ poetry install
```

--------------------------------

### Create and Activate Virtual Environment (Bash)

Source: https://github.com/jtpereyda/boofuzz/blob/master/INSTALL.rst

Create a directory for Boofuzz and set up a Python virtual environment using venv. Activate the environment before proceeding with installations.

```bash
mkdir boofuzz && cd boofuzz
python3 -m venv env
```

```bash
source env/bin/activate
```

--------------------------------

### Install Boofuzz via Pip

Source: https://github.com/jtpereyda/boofuzz/blob/master/INSTALL.rst

Install the Boofuzz package using pip after activating your virtual environment.

```bash
(env) $ pip install boofuzz
```

--------------------------------

### Instantiate Target with SocketConnection

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/source/Target.md

Example of creating a Target instance using a SocketConnection. Ensure the SocketConnection is properly configured with host and port.

```python
tcp_target = Target(SocketConnection(host=’127.0.0.1’, port=17971))
```

--------------------------------

### example_test_case_callback

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/source/Session.md

Example call signature for callback methods used with connect() or register_post_test_case_callback().

```APIDOC
## example_test_case_callback(target, fuzz_data_logger, session, test_case_context, *args, **kwargs)

### Description
Example call signature for methods given to [`connect()`](#boofuzz.Session.connect) or [`register_post_test_case_callback()`](#boofuzz.Session.register_post_test_case_callback)

### Parameters
#### Path Parameters
* **target** (*Target*) – Target with sock-like interface.
* **fuzz_data_logger** (*ifuzz_logger.IFuzzLogger*) – Allows logging of test checks and passes/failures. Provided with a test case and test step already opened.
* **session** (*Session*) – Session object calling post_send. Useful properties include last_send and last_recv.
* **test_case_context** (*ProtocolSession*) – Context for test case-scoped data. [`ProtocolSession`](../user/other-modules.md#boofuzz.ProtocolSession) `session_variables` values are generally set within a callback and referenced in elements via default values of type [`ProtocolSessionReference`](../user/other-modules.md#boofuzz.ProtocolSessionReference).
* **args** – Implementations should include *args and **kwargs for forward-compatibility.
* **kwargs** – Implementations should include *args and **kwargs for forward-compatibility.
```

--------------------------------

### Install boofuzz with Development Dependencies

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/install.md

Installs boofuzz from source in editable mode along with development tools and dependencies, such as unit test libraries.

```bash
$ pip install -e .[dev]
```

--------------------------------

### Install boofuzz from Source in Editable Mode

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/install.md

Installs boofuzz from source in editable mode using pip. Changes to the source code will be reflected immediately without reinstallation.

```bash
$ pip install -e .
```

--------------------------------

### UDPSocketConnection: Basic UDP Fuzzing

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Basic UDP fuzzing example, demonstrated with a TFTP request.

```python
from boofuzz import *

# Basic UDP fuzzing (TFTP example)
session = Session(
    target=Target(connection=UDPSocketConnection("127.0.0.1", 69))
)

s_initialize("RRQ")
s_static("\x00\x01")
s_string("filename", name="fname")
s_static("\x00")
s_string("netascii", name="mode")
s_static("\x00")

session.connect(s_get("RRQ"))
session.fuzz()
```

--------------------------------

### Static API: s_checksum, s_size, s_repeat, s_update

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Demonstrates helper functions for adding structural primitives. Includes examples for checksums, size fields, repeating data, and updating primitive values at runtime.

```python
from boofuzz import *

s_initialize("structured-packet")
with s_block("header"):
    s_byte(0x01, name="version")
    s_byte(0x00, name="flags")
    s_size("body", length=2, endian=BIG_ENDIAN, name="body-len")

with s_block("body"):
    s_string("payload data", name="data")
    s_repeat("data", min_reps=1, max_reps=50, step=5, name="data-repeat")

s_checksum("body", algorithm="md5", length=16, name="body-md5")

# Update a primitive's default value at runtime
s_update("version", 0x02)
```

--------------------------------

### Start Fuzzing Session

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/quickstart.md

Initiate the fuzzing process using the session.fuzz() method. This will begin sending generated data to the target based on the defined protocol graph.

```python
session.fuzz()

```

--------------------------------

### Define HTTP Request with Boofuzz Primitives

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/protocol-definition.md

Example demonstrating the creation of an HTTP request using boofuzz's Request, Block, Group, Delim, String, and Static primitives. This structure defines the components and their default values for fuzzing.

```python
req = Request("HTTP-Request",children=(
    Block("Request-Line", children=(
        Group("Method", values= ["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE"]),
        Delim("space-1", " "),
        String("URI", "/index.html"),
        Delim("space-2", " "),
        String("HTTP-Version", "HTTP/1.1"),
        Static("CRLF", "\r\n"),
    )),
    Block("Host-Line", children=(
        String("Host-Key", "Host:"),
        Delim("space", " "),
        String("Host-Value", "example.com"),
        Static("CRLF", "\r\n"),
    )),
    Static("CRLF", "\r\n"),
))
```

--------------------------------

### Configure ProcessMonitor for Remote Target

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Sets up a ProcessMonitor to track a remote target process. Specify start commands, process name, and output capture options.

```python
procmon = ProcessMonitor("192.168.1.100", 26002)
procmon.set_options(
    start_commands=[["./vulnerable_server", "--port", "9999"]],
    stop_commands=[],
    proc_name="vulnerable_server",
    capture_output=True,
)

session = Session(
    target=Target(
        connection=TCPSocketConnection("192.168.1.100", 9999),
        monitors=[procmon],
    ),
    sleep_time=1,
    crash_threshold_request=5,
)

s_initialize("probe")
s_string("PING", name="cmd")
s_static("\r\n")
session.connect(s_get("probe"))
session.fuzz()
```

--------------------------------

### Configure NetworkMonitor for Traffic Capture

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Sets up a NetworkMonitor to capture network traffic. Requires starting the boofuzz-netmon daemon separately and specifying the capture device and filter.

```python
from boofuzz import *

# Start daemon first:
#   python -m boofuzz.utils.network_monitor --device eth0
netmon = NetworkMonitor("127.0.0.1", 26001)
netmon.set_options(
    filter="tcp port 21",
    log_path="/tmp/pcaps",
)

session = Session(
    target=Target(
        connection=TCPSocketConnection("127.0.0.1", 21),
        monitors=[netmon],
    )
)
```

--------------------------------

### TCPSocketConnection: Client-side Fuzzing

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Example of configuring TCPSocketConnection for client-side fuzzing with custom timeouts.

```python
from boofuzz import *

# Client-side fuzzing (default)
session = Session(
    target=Target(connection=TCPSocketConnection(
        host="192.168.1.100",
        port=21,
        send_timeout=10.0,
        recv_timeout=10.0,
    ))
)
```

--------------------------------

### UDPSocketConnection: UDP with Reply Reception

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Example of UDP fuzzing with reply reception, requiring the `bind` parameter to be set.

```python
# UDP with reply reception (bind required)
session2 = Session(
    target=Target(connection=UDPSocketConnection(
        host="255.255.255.255",
        port=67,
        bind=("0.0.0.0", 68),
        broadcast=True,
    ))
)
```

--------------------------------

### Mirror Primitive Example

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Demonstrates the Mirror primitive, which mirrors the rendered value of another primitive. Useful for length-correlated fields or repeated values.

```python
from boofuzz import *

req = Request("mirrored", children=(
    String(name="original", default_value="hello"),
    Static(name="sep", default_value="|"),
    Mirror(name="copy", primitive_name="original", request=None),
))
# Sends: "hello|hello" — copy always tracks mutations of "original"
```

--------------------------------

### Create a Boofuzz CLI Entry Point with Click

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Integrate a custom fuzzer with the boofuzz CLI using `main_helper` and `click`. This provides standard options like `--target` and `--tui` automatically.

```python
# simple_fuzzer.py
from boofuzz import *
import boofuzz
import click

@click.command()
@click.pass_context
def my_fuzzer(ctx):
    session = ctx.obj.session

    req = Request("hello", children=(
        String(name="data", default_value="HELLO"),
        Static(name="end", default_value="\r\n"),
    ))
    session.connect(req)

if __name__ == "__main__":
    boofuzz.main_helper(click_command=my_fuzzer)
```

--------------------------------

### open_test_step(description)

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/logging.md

Open a test step - e.g., “Fuzzing”, “Pre-fuzz”, “Response Check.”

```APIDOC
## open_test_step(description)

### Description
Open a test step - e.g., “Fuzzing”, “Pre-fuzz”, “Response Check.”

### Parameters
#### Path Parameters
* **description** - Required - Description of fuzzing step.

### Returns
None
```

--------------------------------

### Fuzzable.name

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/protocol-definition.md

Gets the element name, which should be unique for each instance.

```APIDOC
## *property* name

### Description
Element name, should be unique for each instance.

### Return type
str
```

--------------------------------

### open()

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/connections.md

Opens connection to the target. Make sure to call close!

```APIDOC
## open()

### Description
Opens connection to the target. Make sure to call close!

### Returns
None
```

--------------------------------

### Block Manipulation Functions

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/static-protocol-definition.md

Functions for opening, starting, and closing blocks within a request.

```APIDOC
## boofuzz.s_block(name=None, group=None, encoder=None, dep=None, dep_value=None, dep_values=None, dep_compare='==')

### Description
Open a new block under the current request. The returned instance supports the “with” interface so it will be automatically closed for you.

### Parameters
* **name** (*str* *,* *optional*) – Name of block being opened
* **group** (*str* *,* *optional*) – (Optional, def=None) Name of group to associate this block with
* **encoder** (*Function Pointer* *,* *optional*) – (Optional, def=None) Optional pointer to a function to pass rendered data to prior to return
* **dep** (*str* *,* *optional*) – (Optional, def=None) Optional primitive whose specific value this block is dependant on
* **dep_value** (*bytes* *,* *optional*) – (Optional, def=None) Value that field “dep” must contain for block to be rendered
* **dep_values** (*List* *of* *bytes* *,* *optional*) – (Optional, def=None) Values that field “dep” may contain for block to be rendered
* **dep_compare** (*str* *,* *optional*) – (Optional, def=”==”) Comparison method to use on dependency (==, !=, >, >=, <, <=)
```

```APIDOC
## boofuzz.s_block_start(name=None, *args, **kwargs)

### Description
Open a new block under the current request. This routine always returns an instance so you can make your fuzzer pretty with indenting.

:note Prefer using s_block to this function directly
:see s_block
```

```APIDOC
## boofuzz.s_block_end(name=None)

### Description
Close the last opened block. Optionally specify the name of the block being closed (purely for aesthetic purposes).

### Parameters
* **name** (*str*) – (Optional, def=None) Name of block to closed.
```

--------------------------------

### Static API: s_initialize, s_get, s_switch

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Illustrates global request management functions for legacy SPIKE-style protocol definition. Use s_get to retrieve named requests for connect().

```python
from boofuzz import *

# Define multiple requests
s_initialize("greeting")
s_string("HELLO", name="cmd")
s_delim(" ")
s_string("world", name="arg")
s_static("\r\n")

s_initialize("farewell")
s_string("BYE", name="cmd")
s_static("\r\n")

session = Session(target=Target(connection=TCPSocketConnection("127.0.0.1", 7)))
# Use s_get to retrieve named requests for connect()
session.connect(s_get("greeting"))
session.connect(s_get("greeting"), s_get("farewell"))
session.fuzz()

# Inspect mutation count for a request
s_switch("greeting")
print("Mutations:", s_num_mutations())  # e.g. Mutations: 1440
```

--------------------------------

### Configure Proxy for Pip

Source: https://github.com/jtpereyda/boofuzz/blob/master/INSTALL.rst

Set the HTTPS_PROXY environment variable to configure pip for installations when behind a proxy.

```bash
$ set HTTPS_PROXY=http://your.proxy.com:port
```

--------------------------------

### server_init

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/source/Session.md

Initializes session variables, web interface, and other components. This method is called internally by the fuzz() method.

```APIDOC
## server_init()

### Description
Initializes session variables, web interface, and other components. This method is called internally by the fuzz() method.
```

--------------------------------

### Fuzzable.qualified_name

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/protocol-definition.md

Gets the dot-delimited name representing the request name and the element's path within the request.

```APIDOC
## *property* qualified_name

### Description
Dot-delimited name that describes the request name and the path to the element within the request.

Example: “request1.block1.block2.node1”
```

--------------------------------

### TCPSocketConnection: Server-side Fuzzing

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Example of configuring TCPSocketConnection for server-side fuzzing, where Boofuzz listens on a specified port.

```python
# Server-side fuzzing: boofuzz listens on port 4444
session_server = Session(
    target=Target(connection=TCPSocketConnection(
        host="0.0.0.0",
        port=4444,
        server=True,
    ))
)
```

--------------------------------

### CLI Equivalent for Serving Test Run Results

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Command-line interface command to serve previous boofuzz test run results, specifying a custom UI port.

```bash
# CLI equivalent:
boo open boofuzz-results/run-2024-01-15T12-00-00+00-00.db --ui-port 8080
```

--------------------------------

### Instantiate SocketConnection for TCP

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/connections.md

Use this to create a TCP connection to a target host and port. Ensure the host and port are correctly specified.

```python
tcp_connection = SocketConnection(host='127.0.0.1', port=17971)
```

--------------------------------

### Get and Print Request Mutations

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/static-protocol-definition.md

Retrieve a specific request by name and print the number of mutations it can undergo. This is useful for inspecting request properties.

```python
req = s_get("HTTP BASIC")
print(req.num_mutations())
```

--------------------------------

### Creating Custom Blocks/Primitives

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/protocol-definition.md

Guidance on how to create your own custom blocks or primitives by inheriting from Fuzzable or FuzzableBlock and overriding specific methods.

```APIDOC
## Making Your Own Block/Primitive

To make your own block/primitive:

1. Create an object that inherits from [`Fuzzable`](#boofuzz.Fuzzable) or [`FuzzableBlock`](#boofuzz.FuzzableBlock)
2. Override [`mutations`](#boofuzz.Fuzzable.mutations) and/or [`encode`](#boofuzz.Fuzzable.encode).
3. Optional: Create an accompanying static primitive function. See boofuzz’s __init__.py file for examples.
4. ???
5. Profit!

If your block depends on references to other blocks, the way a checksum or length field depends on other parts of the message, see the [`Size`](#boofuzz.Size) source code for an example of how to avoid recursion issues, and Be Careful. :)
```

--------------------------------

### Run Tests with Tox

Source: https://github.com/jtpereyda/boofuzz/blob/master/CONTRIBUTING.rst

Execute the test suite using tox. This command verifies that all tests pass and ensures code quality.

```bash
tox
```

--------------------------------

### Serial Port Fuzzing with Silence-Based Boundary

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Use SerialConnection for fuzzing serial protocols. This example configures a silence-based message boundary detection with a 0.5-second timeout.

```python
from boofuzz import *

# Silence-based boundary: recv returns once wire is quiet 0.5 s
session = Session(
    target=Target(connection=SerialConnection(
        port="/dev/ttyUSB0",
        baudrate=115200,
        timeout=10,
        message_separator_time=0.5,
    ))
)
```

--------------------------------

### Instantiate SocketConnection for Raw Layer 2 with Destination and Protocol

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/connections.md

Configure a raw Layer 2 connection with a specific Layer 2 destination address (e.g., MAC address) and Ethernet protocol.

```python
raw_layer_2 = (host='lo', proto='raw-l2',
               l2_dst='\xFF\xFF\xFF\xFF\xFF\xFF', ethernet_proto=socket_connection.ETH_P_IP)
```

--------------------------------

### Define HTTP Request with Object-Oriented Style

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Defines an HTTP GET request using Boofuzz's object-oriented primitives. Requires importing necessary classes from boofuzz.

```python
from boofuzz import *

http_req = Request("HTTP-GET", children=(
    Block("request-line", children=(
        Group(name="method", values=["GET", "HEAD", "POST", "PUT", "DELETE"]),
        Delim(name="sp1", default_value=" "),
        String(name="uri", default_value="/index.html"),
        Delim(name="sp2", default_value=" "),
        Static(name="version", default_value="HTTP/1.1"),
        Static(name="crlf1", default_value="\r\n"),
    )),
    Block("host-header", children=(
        Static(name="key", default_value="Host: "),
        String(name="value", default_value="example.com"),
        Static(name="crlf2", default_value="\r\n"),
    )),
    Static(name="end", default_value="\r\n"),
))

session = Session(target=Target(connection=TCPSocketConnection("127.0.0.1", 80)))
session.connect(http_req)
session.fuzz()
```

--------------------------------

### Initialize Boofuzz Session with TCP Connection

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/quickstart.md

Create a Session object, passing a Target with a TCPSocketConnection to specify the host and port to fuzz.

```python
session = Session(
    target=Target(
        connection=TCPSocketConnection("127.0.0.1", 8021)))

```

--------------------------------

### open_test_case(test_case_id, name, index, *args, **kwargs)

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/logging.md

Open a test case - i.e., a fuzzing mutation.

```APIDOC
## open_test_case(test_case_id, name, index, *args, **kwargs)

### Description
Open a test case - i.e., a fuzzing mutation.

### Parameters
#### Path Parameters
* **test_case_id** - Required - Test case name/number. Should be unique.
* **name** (str) - Required - Human readable and unique name for test case.
* **index** (int) - Required - Numeric index for test case

### Returns
None
```

--------------------------------

### Fuzz Single Test Case by Mutant Index (Deprecated)

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/source/Session.md

Deprecated method to fuzz a test case using its mutant index. The recommended approach is to set the Session's start and end indices to the same value.

```python
sess.fuzz_single_case(mutant_index=5)
```

--------------------------------

### Static API - s_initialize, s_get, s_switch

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Global functions for managing requests in a legacy SPIKE-style protocol definition. These functions allow creating, retrieving, and switching between named requests.

```APIDOC
## Static API — s_initialize / s_get / s_switch

Global request management functions for the legacy SPIKE-style protocol definition.

`s_initialize(name)` — create a new named request and make it current.
`s_get(name)` — retrieve a request by name (also sets it as current).
`s_switch(name)` — switch the current request context without returning it.

```python
from boofuzz import *

# Define multiple requests
s_initialize("greeting")
s_string("HELLO", name="cmd")
s_delim(" ")
s_string("world", name="arg")
s_static("\r\n")

s_initialize("farewell")
s_string("BYE", name="cmd")
s_static("\r\n")

session = Session(target=Target(connection=TCPSocketConnection("127.0.0.1", 7)))
# Use s_get to retrieve named requests for connect()
session.connect(s_get("greeting"))
session.connect(s_get("greeting"), s_get("farewell"))
session.fuzz()

# Inspect mutation count for a request
s_switch("greeting")
print("Mutations:", s_num_mutations())  # e.g. Mutations: 1440
```
```

--------------------------------

### Activate Virtual Environment (Windows Batch)

Source: https://github.com/jtpereyda/boofuzz/blob/master/INSTALL.rst

Activate the Python virtual environment on Windows using the provided batch script.

```batch
> env\Scripts\activate.bat
```

--------------------------------

### Boofuzz Session Configuration and Fuzzing

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Configure a boofuzz Session with target connection, logging, fuzzing parameters, and callbacks. Defines a simple FTP-like protocol graph using Request objects and initiates the fuzzing campaign.

```python
from boofuzz import *

def check_response(target, fuzz_data_logger, session, *args, **kwargs):
    """Post-test-case callback: receive and validate response."""
    try:
        response = target.recv(1024)
        if not response:
            fuzz_data_logger.log_fail("No response received")
        else:
            fuzz_data_logger.log_pass(f"Got {len(response)} bytes")
    except Exception as e:
        fuzz_data_logger.log_error(str(e))

session = Session(
    target=Target(connection=TCPSocketConnection("127.0.0.1", 8021)),
    sleep_time=0.1,
    fuzz_loggers=[FuzzLoggerText()],
    index_start=1,           # start from first test case
    index_end=500,           # stop after 500 test cases
    crash_threshold_request=12,
    crash_threshold_element=3,
    receive_data_after_fuzz=True,
    ignore_connection_reset=True,
    post_test_case_callbacks=[check_response],
    web_port=26000,          # web UI at http://localhost:26000
    db_filename="results/ftp-run.db",
)

# Build protocol graph
user = Request("user", children=(
    String(name="cmd", default_value="USER"),
    Delim(name="sp", default_value=" "),
    String(name="val", default_value="anonymous"),
    Static(name="end", default_value="\r\n"),
))
passw = Request("pass", children=(
    String(name="cmd", default_value="PASS"),
    Delim(name="sp", default_value=" "),
    String(name="val", default_value="secret"),
    Static(name="end", default_value="\r\n"),
))

session.connect(user)           # user is sent first
session.connect(user, passw)    # passw is fuzzed after user succeeds

session.fuzz()                  # run the campaign
# Results saved to results/ftp-run.db; re-open later with:
# boo open results/ftp-run.db
```

--------------------------------

### Size Primitive for Length Prefixes

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Illustrates the Size primitive for automatically computing and rendering the byte length of a block. Supports various output formats and transformations. Requires boofuzz imports.

```python
from boofuzz import *

s_initialize("length-prefixed")
with s_block("payload"):
    s_string("hello world", name="data")

# 4-byte little-endian binary size of "payload" placed before it
s_size("payload", length=4, endian=LITTLE_ENDIAN, name="len", output_format="binary")

# ASCII decimal size with +4 offset (to include the size field itself)
# s_size("payload", length=4, output_format="ascii", inclusive=True, name="len2")

# Object-oriented equivalent with math transform
req = Request("tlv", children=(
    Size(name="length", block_name="value", length=2,
         endian=BIG_ENDIAN, math=lambda x: x + 4),
    Block(name="value", children=(
        String(name="content", default_value="ABCD"),
    )),
))
```

--------------------------------

### Instantiate SocketConnection for UDP

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/connections.md

Create a UDP connection to a target host and port. This is suitable for connectionless communication.

```python
udp_connection = SocketConnection(host='127.0.0.1', port=17971, proto='udp')
```

--------------------------------

### Instantiate SocketConnection for Raw Layer 3

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/connections.md

Create a raw Layer 3 connection for sending network protocol packets (e.g., IP packets). Specify the network interface as the host.

```python
raw_layer_3 = (host='lo', proto='raw-l3')
```

--------------------------------

### log_info(description)

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/logging.md

Catch-all method for logging test information.

```APIDOC
## log_info(description)

### Description
Catch-all method for logging test information.

### Parameters
#### Path Parameters
* **description** (str) - Required - Information.

### Returns
None
```

--------------------------------

### Instantiate SocketConnection for Raw Layer 2

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/connections.md

Establish a raw Layer 2 connection, typically used for sending Ethernet frames. Specify the network interface as the host.

```python
raw_layer_2 = (host='lo', proto='raw-l2')
```

--------------------------------

### Static API: s_block, s_block_start, s_block_end

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Shows how to open and close named blocks within the current request. The `with s_block(...)` context manager is preferred for automatic closure.

```python
from boofuzz import *

s_initialize("http-body")
with s_block("request-line"):
    s_group("method", ["GET", "POST", "DELETE"])
    s_delim(" ", name="sp1")
    s_string("/api/v1/users", name="uri")
    s_delim(" ", name="sp2")
    s_string("HTTP/1.1", name="version")
    s_static("\r\n")

with s_block("content"):
    s_string("body content here", name="body")

# Size field referencing the "content" block
s_size("content", length=4, output_format="ascii", name="content-length")

# Manual open/close alternative
s_block_start("manual-block")
s_string("data", name="d")
s_block_end("manual-block")
```

--------------------------------

### Configure CallbackMonitor for Custom Events

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Integrates custom Python functions as monitors for pre-send, post-send, and restart events. Define callback functions and pass them to the Session constructor.

```python
from boofuzz import *

def pre_send(target, fuzz_data_logger, session, *args, **kwargs):
    fuzz_data_logger.log_info("About to fuzz...")

def post_send(target, fuzz_data_logger, session, *args, **kwargs):
    response = target.recv(1024)
    if b"ERROR" in response:
        raise BoofuzzFailure("Target returned ERROR")

def on_restart(target, fuzz_data_logger, session, *args, **kwargs):
    import time, subprocess
    subprocess.Popen(["./server"])
    time.sleep(2)

session = Session(
    target=Target(connection=TCPSocketConnection("127.0.0.1", 9999)),
    pre_send_callbacks=[pre_send],
    post_test_case_callbacks=[post_send],
    restart_callbacks=[on_restart],
)
```

--------------------------------

### info

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/connections.md

Return description of connection info.

```APIDOC
## info

### Description
Return description of connection info.

E.g., “127.0.0.1:2121”

### Returns
Connection info descrption
* **Return type:**
  str
```

--------------------------------

### Configure Session with TCPSocketConnection

Source: https://context7.com/jtpereyda/boofuzz/llms.txt

Explicitly configure a Session with a TCPSocketConnection target.

```python
session2 = Session(
    target=Target(connection=TCPSocketConnection("127.0.0.1", 21)),
    fuzz_loggers=[
        FuzzLoggerCurses(
            web_port=26000,
            window_height=40,
            window_width=160,
            auto_scroll=True,
        )
    ],
)
```

--------------------------------

### pre_send Method

Source: https://github.com/jtpereyda/boofuzz/blob/master/docs/user/monitors.md

Executes all supplied pre-send callbacks. Exceptions are caught, logged, and discarded.

```APIDOC
## pre_send(target=None, fuzz_data_logger=None, session=None)

This method iterates over all supplied pre send callbacks and executes them. Their return values are discarded, exceptions are catched and logged, but otherwise discarded.
```