Top-level package

Pure-Python CyberChef-compatible data transformations.

class pychef.BakeResult(result, type, progress, duration_ms, error=None)

Bases: object

Detailed result returned by Chef.bake_result().

Parameters:

  • result (str | bytes)

  • type (Literal['string', 'bytes'])

  • progress (int)

  • duration_ms (float)

  • error (Exception | None)

result: str | bytes
type: Literal['string', 'bytes']
progress: int
duration_ms: float
error: Exception | None
class pychef.Chef(*, operation_registry=registry)

Bases: object

Execute recipes with a small, synchronous Python API.

Parameters:

operation_registry (OperationRegistry)

bake(value, recipe, *, return_type=None)
Parameters:

  • value (str | bytes)

  • recipe (Sequence[RecipeStep | Mapping[str, Any] | str] | Recipe)

  • return_type (Literal['str', 'bytes'] | None)

Return type:

str | bytes

bake_result(value, recipe, *, return_type=None, raise_errors=True)
Parameters:

  • value (str | bytes)

  • recipe (Sequence[RecipeStep | Mapping[str, Any] | str] | Recipe)

  • return_type (Literal['str', 'bytes'] | None)

  • raise_errors (bool)

Return type:

BakeResult

class pychef.CompatibilityReport(target_version, target_commit, upstream_count, implemented, missing, unexpected)

Bases: object

A live comparison between the registry and the pinned upstream inventory.

Parameters:

  • target_version (str)

  • target_commit (str)

  • upstream_count (int)

  • implemented (tuple[str, ...])

  • missing (tuple[str, ...])

  • unexpected (tuple[str, ...])

target_version: str
target_commit: str
upstream_count: int
implemented: tuple[str, ...]
missing: tuple[str, ...]
unexpected: tuple[str, ...]
property complete: bool

Whether every pinned upstream operation is registered.

property coverage: float

Return operation-name coverage as a fraction between zero and one.

class pychef.Operation(name, function, category='')

Bases: object

Metadata and implementation for a registered operation.

Parameters:

  • name (str)

  • function (Callable[[str | bytes, Sequence[Any]], str | bytes])

  • category (str)

name: str
function: Callable[[str | bytes, Sequence[Any]], str | bytes]
category: str
run(value, args=())
Parameters:

  • value (str | bytes)

  • args (Sequence[Any])

Return type:

str | bytes

exception pychef.OperationError(operation, message)

Bases: PyChefError

Raised when an operation cannot transform its input.

Parameters:

  • operation (str)

  • message (str)

Return type:

None

class pychef.OperationRegistry

Bases: object

Case-sensitive registry matching CyberChef’s public operation names.

get(name)
Parameters:

name (str)

Return type:

Operation

names()
Return type:

tuple[str, …]

register(operation)
Parameters:

operation (Operation)

Return type:

None

class pychef.Pipeline(steps=(), *, operation_registry=registry, _stages=())

Bases: object

An immutable chain of transformations.

Each chaining method returns a new pipeline, so a configured instance can safely be reused for many inputs. CyberChef operations, ordinary Python callables, branches, and dictionary-producing packet parsers can be mixed.

Parameters:

  • steps (Iterable[PipelineStep])

  • operation_registry (OperationRegistry)

  • _stages (tuple[_Stage, ...])

aes_decrypt(key, *, mode='CBC', iv=None, padding='pkcs7', aad=b'', tag=None, key_format='raw', iv_format='raw', tag_format='raw')
Parameters:

  • key (str | bytes)

  • mode (str)

  • iv (str | bytes | None)

  • padding (str)

  • aad (str | bytes)

  • tag (str | bytes | None)

  • key_format (str)

  • iv_format (str)

  • tag_format (str)

Return type:

Pipeline

aes_encrypt(key, *, mode='CBC', iv=None, padding='pkcs7', aad=b'', key_format='raw', iv_format='raw', append_tag=True)
Parameters:

  • key (str | bytes)

  • mode (str)

  • iv (str | bytes | None)

  • padding (str)

  • aad (str | bytes)

  • key_format (str)

  • iv_format (str)

  • append_tag (bool)

Return type:

Pipeline

append(suffix)

Append a constant to each transformed output without coercing types.

Parameters:

suffix (str | bytes)

Return type:

Pipeline

apply(transform, *, name=None)

Append an arbitrary Python callable.

Parameters:

  • transform (Callable[[Any], Any])

  • name (str | None)

Return type:

Pipeline

bake(value)

Transform one value through every configured stage.

Parameters:

value (Any)

Return type:

Any

concat(*branches, separator=b'')

Run every branch on the current value and concatenate its outputs.

Parameters:

  • branches (Pipeline | Callable[[Any], Any])

  • separator (str | bytes)

Return type:

Pipeline

decode(encoding='UTF-8 (65001)')
Parameters:

encoding (str)

Return type:

Pipeline

digest(algorithm='sha256', *, output='hex')
Parameters:

  • algorithm (str)

  • output (str)

Return type:

Pipeline

encode(encoding='UTF-8 (65001)')
Parameters:

encoding (str)

Return type:

Pipeline

from_base64(alphabet='A-Za-z0-9+/=', strict=False)
Parameters:

  • alphabet (str)

  • strict (bool)

Return type:

Pipeline

from_hex(delimiter='Auto')
Parameters:

delimiter (str)

Return type:

Pipeline

from_pcap(*, max_packets=100_000, max_packet_size=16 * 1024 * 1024)
Parameters:

  • max_packets (int)

  • max_packet_size (int)

Return type:

Pipeline

hexdump(*, width=16, start=0)
Parameters:

  • width (int)

  • start (int)

Return type:

Pipeline

operation(operation, *args)

Append any registered CyberChef operation.

Parameters:

  • operation (str | RecipeStep | Mapping[str, Any])

  • args (Any)

Return type:

Pipeline

pack(bits=32, *, endian='little', signed=False)
Parameters:

  • bits (int)

  • endian (str)

  • signed (bool)

Return type:

Pipeline

parse_capture(*, max_packets=100_000, max_packet_size=16 * 1024 * 1024)
Parameters:

  • max_packets (int)

  • max_packet_size (int)

Return type:

Pipeline

parse_packet(*, link_type=1)
Parameters:

link_type (int)

Return type:

Pipeline

prepend(prefix)

Prepend a constant to each transformed output without coercing types.

Parameters:

prefix (str | bytes)

Return type:

Pipeline

property recipe: Recipe

Return this pipeline as a recipe if it only contains operations.

run(value)

Transform one value through every configured stage.

Parameters:

value (Any)

Return type:

Any

select(*path)

Select nested mapping keys, sequence indexes, or object attributes.

Parameters:

path (str | int)

Return type:

Pipeline

property steps: tuple[str, ...]

Return the human-readable names of all configured stages.

swap_endian(word_size=4, *, strict=True)
Parameters:

  • word_size (int)

  • strict (bool)

Return type:

Pipeline

then(operation, *args)

Append any registered CyberChef operation.

Parameters:

  • operation (str | RecipeStep | Mapping[str, Any])

  • args (Any)

Return type:

Pipeline

to_base64(alphabet='A-Za-z0-9+/=')
Parameters:

alphabet (str)

Return type:

Pipeline

to_hex(delimiter='None', bytes_per_line=0)
Parameters:

  • delimiter (str)

  • bytes_per_line (int)

Return type:

Pipeline

trace(value)

Run the pipeline and retain every intermediate input and output.

Parameters:

value (Any)

Return type:

tuple[PipelineTrace, …]

transform(value)

Transform one value through every configured stage.

Parameters:

value (Any)

Return type:

Any

transform_many(values)

Transform a finite iterable while retaining input order.

Parameters:

values (Iterable[Any])

Return type:

tuple[Any, …]

unpack(bits=32, *, endian='little', signed=False, offset=0)
Parameters:

  • bits (int)

  • endian (str)

  • signed (bool)

  • offset (int)

Return type:

Pipeline

xor(key, *, key_format='raw')
Parameters:

  • key (str | bytes)

  • key_format (str)

Return type:

Pipeline

class pychef.PipelineTrace(name, input, output)

Bases: object

The input and output captured for one pipeline stage.

Parameters:

  • name (str)

  • input (Any)

  • output (Any)

name: str
input: Any
output: Any
exception pychef.PyChefError

Bases: Exception

Base class for all public PyChef errors.

class pychef.Recipe(config)

Bases: object

A validated sequence of data transformation operations.

Parameters:

config (RecipeConfig)

execute(value, *, operation_registry=registry)
Parameters:
Return type:

tuple[str | bytes, int]

exception pychef.RecipeError

Bases: PyChefError

Raised when a recipe configuration is malformed.

class pychef.RecipeStep(op, args=(), disabled=False, breakpoint=False)

Bases: object

One immutable CyberChef-compatible recipe step.

Parameters:

  • op (str)

  • args (tuple[Any, ...])

  • disabled (bool)

  • breakpoint (bool)

op: str
args: tuple[Any, ...]
disabled: bool
breakpoint: bool
exception pychef.UnknownOperationError

Bases: PyChefError, LookupError

Raised when a recipe names an operation that is not registered.

pychef.aes_decrypt(value, key, *, mode='CBC', iv=None, padding='pkcs7', aad=b'', tag=None, key_format='raw', iv_format='raw', tag_format='raw')

Decrypt AES bytes; GCM reads an appended tag when tag is omitted.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • key (str | bytes | bytearray | memoryview)

  • mode (str)

  • iv (str | bytes | bytearray | memoryview | None)

  • padding (str)

  • aad (str | bytes | bytearray | memoryview)

  • tag (str | bytes | bytearray | memoryview | None)

  • key_format (str)

  • iv_format (str)

  • tag_format (str)

Return type:

bytes

pychef.aes_encrypt(value, key, *, mode='CBC', iv=None, padding='pkcs7', aad=b'', key_format='raw', iv_format='raw', append_tag=True)

Encrypt bytes with AES; GCM appends its tag by default.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • key (str | bytes | bytearray | memoryview)

  • mode (str)

  • iv (str | bytes | bytearray | memoryview | None)

  • padding (str)

  • aad (str | bytes | bytearray | memoryview)

  • key_format (str)

  • iv_format (str)

  • append_tag (bool)

Return type:

bytes

pychef.aes_gcm_decrypt(value, key, *, iv, tag, aad=b'', key_format='raw', iv_format='raw', tag_format='raw')

Authenticate and decrypt an AES-GCM ciphertext.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • key (str | bytes | bytearray | memoryview)

  • iv (str | bytes | bytearray | memoryview)

  • tag (str | bytes | bytearray | memoryview)

  • aad (str | bytes | bytearray | memoryview)

  • key_format (str)

  • iv_format (str)

  • tag_format (str)

Return type:

bytes

pychef.aes_gcm_encrypt(value, key, *, iv, aad=b'', key_format='raw', iv_format='raw')

Encrypt with AES-GCM and return (ciphertext, 16-byte tag).

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • key (str | bytes | bytearray | memoryview)

  • iv (str | bytes | bytearray | memoryview)

  • aad (str | bytes | bytearray | memoryview)

  • key_format (str)

  • iv_format (str)

Return type:

tuple[bytes, bytes]

pychef.bake(value, recipe, *, return_type=None)

Bake value with recipe and return the transformed value.

Parameters:

  • value (str | bytes)

  • recipe (Sequence[RecipeStep | Mapping[str, Any] | str] | Recipe)

  • return_type (Literal['str', 'bytes'] | None)

Return type:

str | bytes

pychef.chunks(value, size, *, drop_incomplete=False)

Split bytes or text into fixed-size chunks while preserving its type.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • size (int)

  • drop_incomplete (bool)

Return type:

tuple[Any, …]

pychef.compatibility_report()

Compare the current registry with CyberChef 11.3.0.

Return type:

CompatibilityReport

pychef.cyclic(length, *, alphabet=b'abcdefghijklmnopqrstuvwxyz', n=4)

Generate a deterministic de Bruijn pattern for offset discovery.

Parameters:

  • length (int)

  • alphabet (bytes)

  • n (int)

Return type:

bytes

pychef.cyclic_find(subsequence, *, alphabet=b'abcdefghijklmnopqrstuvwxyz', n=4, endian='little')

Return a pattern offset or -1 when the subsequence is absent.

Parameters:

  • subsequence (int | str | bytes | bytearray | memoryview)

  • alphabet (bytes)

  • n (int)

  • endian (str)

Return type:

int

pychef.decode_bytes(value, *, format='raw')

Decode an explicitly formatted value to bytes.

Supported formats are raw/utf8, hex, base64, and latin1. Bytes in raw mode are returned without a copy where possible.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • format (str)

Return type:

bytes

pychef.digest(value, *, algorithm='sha256', output='hex')

Calculate any hash provided by hashlib with a predictable output.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • algorithm (str)

  • output (str)

Return type:

bytes | str

pychef.digests(value, algorithms=('md5', 'sha1', 'sha256', 'sha512'))

Calculate several hexadecimal hashes in one call.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • algorithms (Iterable[str])

Return type:

dict[str, str]

pychef.encode_bytes(value, *, format='raw')

Encode bytes as raw bytes, UTF-8 text, hex, base64, or Latin-1.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • format (str)

Return type:

bytes | str

pychef.flat(*values, word_size=32, endian='little', signed=False, encoding='utf-8')

Flatten integers, byte strings, text, and nested sequences to bytes.

Parameters:

  • values (Any)

  • word_size (int)

  • endian (str)

  • signed (bool)

  • encoding (str)

Return type:

bytes

pychef.hexdump(value, *, width=16, start=0)

Return a compact offset/hex/ASCII dump suitable for terminals.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • width (int)

  • start (int)

Return type:

str

pychef.json_safe(value)

Recursively convert packet bytes to hexadecimal JSON-friendly objects.

Parameters:

value (Any)

Return type:

Any

pychef.list_operations()

Return every registered operation name in stable alphabetical order.

Return type:

tuple[str, …]

pychef.md5(value)
Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

str

pychef.p8(value, *, signed=False)
Parameters:

  • value (int)

  • signed (bool)

Return type:

bytes

pychef.p16(value, *, endian='little', signed=False)
Parameters:

  • value (int)

  • endian (str)

  • signed (bool)

Return type:

bytes

pychef.p16be(value, *, signed=False)
Parameters:

  • value (int)

  • signed (bool)

Return type:

bytes

pychef.p16le(value, *, signed=False)
Parameters:

  • value (int)

  • signed (bool)

Return type:

bytes

pychef.p32(value, *, endian='little', signed=False)
Parameters:

  • value (int)

  • endian (str)

  • signed (bool)

Return type:

bytes

pychef.p32be(value, *, signed=False)
Parameters:

  • value (int)

  • signed (bool)

Return type:

bytes

pychef.p32le(value, *, signed=False)
Parameters:

  • value (int)

  • signed (bool)

Return type:

bytes

pychef.p64(value, *, endian='little', signed=False)
Parameters:

  • value (int)

  • endian (str)

  • signed (bool)

Return type:

bytes

pychef.p64be(value, *, signed=False)
Parameters:

  • value (int)

  • signed (bool)

Return type:

bytes

pychef.p64le(value, *, signed=False)
Parameters:

  • value (int)

  • signed (bool)

Return type:

bytes

pychef.pack(value, bits=32, *, endian='little', signed=False)

Pack one integer with an explicit width and byte order.

Parameters:

  • value (int)

  • bits (int)

  • endian (str)

  • signed (bool)

Return type:

bytes

pychef.packet_json(value, *, indent=2)

Serialize decoded packet/capture data without losing byte lengths.

Parameters:

  • value (Any)

  • indent (int | None)

Return type:

str

pychef.parse_arp_packet(value)
Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

dict[str, Any]

pychef.parse_capture(value, *, max_packets=100_000, max_packet_size=16 * 1024 * 1024)

Auto-detect and decode PCAP or PCAPNG bytes.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • max_packets (int)

  • max_packet_size (int)

Return type:

dict[str, Any]

pychef.parse_dns_message(value)

Decode a DNS wire message, including compressed names and common records.

Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

dict[str, Any]

pychef.parse_ethernet_frame(value)

Decode Ethernet II/802.1Q and recursively decode network layers.

Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

dict[str, Any]

pychef.parse_icmp_message(value, *, ipv6=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • ipv6 (bool)

Return type:

dict[str, Any]

pychef.parse_ipv4_packet(value)

Decode IPv4 and recursively decode its first-fragment transport payload.

Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

dict[str, Any]

pychef.parse_ipv6_packet(value)

Decode IPv6, common extension headers, and its transport payload.

Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

dict[str, Any]

pychef.parse_packet(value, *, link_type=1)

Decode one captured packet for a common libpcap link-layer type.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • link_type (int)

Return type:

dict[str, Any]

pychef.parse_pcap(value, *, max_packets=100_000, max_packet_size=16 * 1024 * 1024)

Decode a classic PCAP capture and every supported packet layer.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • max_packets (int)

  • max_packet_size (int)

Return type:

dict[str, Any]

pychef.parse_pcapng(value, *, max_packets=100_000, max_packet_size=16 * 1024 * 1024)

Decode PCAPNG sections, interfaces, enhanced/simple packet blocks.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • max_packets (int)

  • max_packet_size (int)

Return type:

dict[str, Any]

pychef.parse_tcp_segment(value)

Decode a TCP segment and common options/application payloads.

Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

dict[str, Any]

pychef.parse_udp_datagram(value)

Decode a UDP datagram and common application payloads.

Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

dict[str, Any]

pychef.read_capture(path, *, max_file_size=512 * 1024 * 1024, max_packets=100_000, max_packet_size=16 * 1024 * 1024)

Read and parse a capture file with an explicit file-size limit.

Parameters:

  • path (str | PathLike[str])

  • max_file_size (int)

  • max_packets (int)

  • max_packet_size (int)

Return type:

dict[str, Any]

pychef.rol(value, amount, bits=32)

Rotate an integer left inside a fixed-width word.

Parameters:

  • value (int)

  • amount (int)

  • bits (int)

Return type:

int

pychef.ror(value, amount, bits=32)

Rotate an integer right inside a fixed-width word.

Parameters:

  • value (int)

  • amount (int)

  • bits (int)

Return type:

int

pychef.sha1(value)
Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

str

pychef.sha256(value)
Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

str

pychef.sha512(value)
Parameters:

value (str | bytes | bytearray | memoryview)

Return type:

str

pychef.swap_endian(value, word_size=4, *, strict=True)

Reverse the byte order independently in each fixed-width word.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • word_size (int)

  • strict (bool)

Return type:

bytes

pychef.u8(value, *, offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u16(value, *, endian='little', offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • endian (str)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u16be(value, *, offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u16le(value, *, offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u32(value, *, endian='little', offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • endian (str)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u32be(value, *, offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u32le(value, *, offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u64(value, *, endian='little', offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • endian (str)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u64be(value, *, offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.u64le(value, *, offset=0, signed=False)
Parameters:

  • value (str | bytes | bytearray | memoryview)

  • offset (int)

  • signed (bool)

Return type:

int

pychef.unpack(value, bits=32, *, endian='little', signed=False, offset=0)

Unpack one integer at offset and reject truncated input.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • bits (int)

  • endian (str)

  • signed (bool)

  • offset (int)

Return type:

int

pychef.xor_bytes(value, key, *, repeat=True)

XOR a byte string with a key, repeating the key by default.

Parameters:

  • value (str | bytes | bytearray | memoryview)

  • key (str | bytes | bytearray | memoryview)

  • repeat (bool)

Return type:

bytes