smallworld.state

class smallworld.state.Stateful

An abstract class whose subclasses represent system state that can be applied to/loaded from an emulator.

abstractmethod extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

abstractmethod apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

class smallworld.state.Value

An abstract class whose subclasses all have a tuple of content, type, and label. Content is the value which must be convertable into bytes. The type is a ctype reprensenting the type of content. Label is a string that is a human label for the object. Any or all are optional.

abstractmethod get_size() → int

Get the size of this value.

Returns:

The number of bytes this value should occupy in memory.

get_content() → ValueContent

Get the content of this value.

Returns:

The content of this value.

set_content(content: ValueContent) → None

Set the content of this value.

Parameters:

content – The content to which the value will be set.

get_type() → Any | None

Get the type of this value.

Returns:

The type of this value.

set_type(type: Any | None) → None

Set the type of this value.

Parameters:

type – The type value to set.

get_label() → str | None

Get the label of this value.

Returns:

The label of this value.

set_label(label: str | None) → None

Set the label of this value.

Parameters:

type – The label value to set.

get() → ValueContent

A helper to get the content of this value.

Returns:

The content of this value.

set(content: ValueContent) → None

A helper to set the content of this value.

Parameters:

content – The content value to set.

to_symbolic(byteorder: Byteorder) → BV | None

Convert this value into a symbolic expression

For an unlabeled value, this will be a bit vector symbol containing the label. Otherwise, it will be a bit vector value containing the contents.

Parameters:

byteorder – The byte order to use in the conversion.

Returns:

Symbolic expression object, or None if both content and label are None

abstractmethod to_bytes() → bytes

Convert this value into a byte string.

Returns:

Bytes for this value.

classmethod from_ctypes(ctype: CTypesAny, label: str)

Load from an existing ctypes value.

Arguements:

ctype: The data in ctype form.

Reutrns:

The value constructed from ctypes data.

class smallworld.state.IntegerValue(integer: int, size: int, label: str | None, byteorder: Byteorder, signed: bool = True)

An integer value.

This is useful for using python integers, but passing them to emulators that care about things like width. The type is derived based on the size.

Parameters:

• size – The size of the integer. Must be 1, 2, 4, 8

• label – An optional metadata label

get_size() → int

Get the size of this value.

Returns:

The number of bytes this value should occupy in memory.

to_bytes() → bytes

Convert this value into a byte string.

Returns:

Bytes for this value.

classmethod from_ctypes(ctype: CTypesAny, label: str)

Load from an existing ctypes value.

Arguements:

ctype: The data in ctype form.

Reutrns:

The value constructed from ctypes data.

get() → ValueContent

A helper to get the content of this value.

Returns:

The content of this value.

get_content() → ValueContent

Get the content of this value.

Returns:

The content of this value.

get_label() → str | None

Get the label of this value.

Returns:

The label of this value.

get_type() → Any | None

Get the type of this value.

Returns:

The type of this value.

set(content: ValueContent) → None

A helper to set the content of this value.

Parameters:

content – The content value to set.

set_content(content: ValueContent) → None

Set the content of this value.

Parameters:

content – The content to which the value will be set.

set_label(label: str | None) → None

Set the label of this value.

Parameters:

type – The label value to set.

set_type(type: Any | None) → None

Set the type of this value.

Parameters:

type – The type value to set.

to_symbolic(byteorder: Byteorder) → BV | None

Convert this value into a symbolic expression

For an unlabeled value, this will be a bit vector symbol containing the label. Otherwise, it will be a bit vector value containing the contents.

Parameters:

byteorder – The byte order to use in the conversion.

Returns:

Symbolic expression object, or None if both content and label are None

class smallworld.state.BytesValue(content: bytes | bytearray, label: str | None)

A bytes value.

This is for representing a python bytes or bytearray as a value.

Parameters:

label – An optional metadata label

get_size() → int

Get the size of this value.

Returns:

The number of bytes this value should occupy in memory.

to_bytes() → bytes

Convert this value into a byte string.

Returns:

Bytes for this value.

classmethod from_ctypes(ctype: CTypesAny, label: str)

Load from an existing ctypes value.

Arguements:

ctype: The data in ctype form.

Reutrns:

The value constructed from ctypes data.

get() → ValueContent

A helper to get the content of this value.

Returns:

The content of this value.

get_content() → ValueContent

Get the content of this value.

Returns:

The content of this value.

get_label() → str | None

Get the label of this value.

Returns:

The label of this value.

get_type() → Any | None

Get the type of this value.

Returns:

The type of this value.

set(content: ValueContent) → None

A helper to set the content of this value.

Parameters:

content – The content value to set.

set_content(content: ValueContent) → None

Set the content of this value.

Parameters:

content – The content to which the value will be set.

set_label(label: str | None) → None

Set the label of this value.

Parameters:

type – The label value to set.

set_type(type: Any | None) → None

Set the type of this value.

Parameters:

type – The type value to set.

to_symbolic(byteorder: Byteorder) → BV | None

Convert this value into a symbolic expression

For an unlabeled value, this will be a bit vector symbol containing the label. Otherwise, it will be a bit vector value containing the contents.

Parameters:

byteorder – The byte order to use in the conversion.

Returns:

Symbolic expression object, or None if both content and label are None

class smallworld.state.SymbolicValue(size: int, bv: BV | None, type: Any | None, label: str | None)

A symbolic value

This value is expressed as a bitvector expression, compatible with angr’s internal state representation. If used with a concrete emulator, it defaults to zeroes.

Parameters:

• size – The size of the region

• bv – Optional bitvector value

• type – Optional typedef information

• label – An optional metadata label

get_size() → int

Get the size of this value.

Returns:

The number of bytes this value should occupy in memory.

to_bytes()

Convert this value into a byte string.

Returns:

Bytes for this value.

classmethod from_ctypes(ctype: CTypesAny, label: str)

Load from an existing ctypes value.

Arguements:

ctype: The data in ctype form.

Reutrns:

The value constructed from ctypes data.

get() → ValueContent

A helper to get the content of this value.

Returns:

The content of this value.

get_content() → ValueContent

Get the content of this value.

Returns:

The content of this value.

get_label() → str | None

Get the label of this value.

Returns:

The label of this value.

get_type() → Any | None

Get the type of this value.

Returns:

The type of this value.

set(content: ValueContent) → None

A helper to set the content of this value.

Parameters:

content – The content value to set.

set_content(content: ValueContent) → None

Set the content of this value.

Parameters:

content – The content to which the value will be set.

set_label(label: str | None) → None

Set the label of this value.

Parameters:

type – The label value to set.

set_type(type: Any | None) → None

Set the type of this value.

Parameters:

type – The type value to set.

to_symbolic(byteorder: Byteorder) → BV | None

Convert this value into a symbolic expression

For an unlabeled value, this will be a bit vector symbol containing the label. Otherwise, it will be a bit vector value containing the contents.

Parameters:

byteorder – The byte order to use in the conversion.

Returns:

Symbolic expression object, or None if both content and label are None

class smallworld.state.Register(name: str, size: int = 4)

An individual register.

Parameters:

• name – The canonical name of the register.

• size – The size (in bytes) of the register.

name: str

Canonical name.

size

Register size in bytes.

byteorder: Byteorder | None

Register platform byteorder. Assigned by CPU constructor.

set_content(content: ValueContent)

Set the content of this value.

Parameters:

content – The content to which the value will be set.

get_size() → int

Get the size of this value.

Returns:

The number of bytes this value should occupy in memory.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

to_bytes() → bytes

Convert this value into a byte string.

Returns:

Bytes for this value.

classmethod from_ctypes(ctype: CTypesAny, label: str)

Load from an existing ctypes value.

Arguements:

ctype: The data in ctype form.

Reutrns:

The value constructed from ctypes data.

get() → ValueContent

A helper to get the content of this value.

Returns:

The content of this value.

get_content() → ValueContent

Get the content of this value.

Returns:

The content of this value.

get_label() → str | None

Get the label of this value.

Returns:

The label of this value.

get_type() → Any | None

Get the type of this value.

Returns:

The type of this value.

set(content: ValueContent) → None

A helper to set the content of this value.

Parameters:

content – The content value to set.

set_label(label: str | None) → None

Set the label of this value.

Parameters:

type – The label value to set.

set_type(type: Any | None) → None

Set the type of this value.

Parameters:

type – The type value to set.

to_symbolic(byteorder: Byteorder) → BV | None

Convert this value into a symbolic expression

For an unlabeled value, this will be a bit vector symbol containing the label. Otherwise, it will be a bit vector value containing the contents.

Parameters:

byteorder – The byte order to use in the conversion.

Returns:

Symbolic expression object, or None if both content and label are None

class smallworld.state.RegisterAlias(name: str, reference: Register, size: int = 4, offset: int = 0)

An alias to a partial register.

Parameters:

• name – The cannonical name of the register.

• reference – A register which this alias references.

• size – The size (in bytes) of the register.

• offset – The offset from the start of the register that this alias references.

reference: Register

The register referenced by this alias.

offset: int

‘The offset into the referenced register.

get_content() → ValueContent

Get the content of this value.

Returns:

The content of this value.

set_content(content: ValueContent) → None

Set the content of this value.

Parameters:

content – The content to which the value will be set.

get_type() → Any | None

Get the type of this value.

Returns:

The type of this value.

set_type(type: Any | None) → None

Set the type of this value.

Parameters:

type – The type value to set.

get_label() → str | None

Get the label of this value.

Returns:

The label of this value.

set_label(label: str | None) → None

Set the label of this value.

Parameters:

type – The label value to set.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

classmethod from_ctypes(ctype: CTypesAny, label: str)

Load from an existing ctypes value.

Arguements:

ctype: The data in ctype form.

Reutrns:

The value constructed from ctypes data.

get() → ValueContent

A helper to get the content of this value.

Returns:

The content of this value.

get_size() → int

Get the size of this value.

Returns:

The number of bytes this value should occupy in memory.

set(content: ValueContent) → None

A helper to set the content of this value.

Parameters:

content – The content value to set.

to_bytes() → bytes

Convert this value into a byte string.

Returns:

Bytes for this value.

to_symbolic(byteorder: Byteorder) → BV | None

Convert this value into a symbolic expression

For an unlabeled value, this will be a bit vector symbol containing the label. Otherwise, it will be a bit vector value containing the contents.

Parameters:

byteorder – The byte order to use in the conversion.

Returns:

Symbolic expression object, or None if both content and label are None

name: str

Canonical name.

byteorder: Byteorder | None

Register platform byteorder. Assigned by CPU constructor.

size

Register size in bytes.

class smallworld.state.FixedRegister(name, size=4, value=0)

A Register that holds a fixed value, and should not be set.

A number of ISAs have registers hard-wired to zero. It would be nice for the harness author to not have to remember to set it each time.

Parameters:

• name – Name of the register

• size – Size of the register in bytes

• value – Fixed value of the register

set_content(value: Any | None)

Set the content of this value.

Parameters:

content – The content to which the value will be set.

get_label() → str | None

Get the label of this value.

Returns:

The label of this value.

set_label(label: str | None) → None

Set the label of this value.

Parameters:

type – The label value to set.

get_type() → Any | None

Get the type of this value.

Returns:

The type of this value.

set_type(type: Any | None) → None

Set the type of this value.

Parameters:

type – The type value to set.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

classmethod from_ctypes(ctype: CTypesAny, label: str)

Load from an existing ctypes value.

Arguements:

ctype: The data in ctype form.

Reutrns:

The value constructed from ctypes data.

get() → ValueContent

A helper to get the content of this value.

Returns:

The content of this value.

get_content() → ValueContent

Get the content of this value.

Returns:

The content of this value.

get_size() → int

Get the size of this value.

Returns:

The number of bytes this value should occupy in memory.

set(content: ValueContent) → None

A helper to set the content of this value.

Parameters:

content – The content value to set.

to_bytes() → bytes

Convert this value into a byte string.

Returns:

Bytes for this value.

to_symbolic(byteorder: Byteorder) → BV | None

Convert this value into a symbolic expression

For an unlabeled value, this will be a bit vector symbol containing the label. Otherwise, it will be a bit vector value containing the contents.

Parameters:

byteorder – The byte order to use in the conversion.

Returns:

Symbolic expression object, or None if both content and label are None

name: str

Canonical name.

byteorder: Byteorder | None

Register platform byteorder. Assigned by CPU constructor.

size

Register size in bytes.

class smallworld.state.Machine

A container for all state needed to begin or resume emulation or analysis), including CPU with register values, code, raw memory or even stack and heap memory.

Machines have exit points which are instruction addresses that when hit by an emulator will cause it to stop before any side effects of that instruction are applied. Similarly, machines have bounds which are address ranges. When an address outside of the range is hit by the emulator that will cause it to stop before any side effects are applied. Note that the start of the range is included in the range, but the end is not.

add_exit_point(address: int)

Add an exit point to the machine.

Parameters:

address – The address to exit on

get_exit_points() → Set[int]

Gets the set of exit points for a machine.

Returns:

The set of exit point addresses.

add_bound(start: int, end: int)

Adds a bound to the machine

Parameters:

• start – the start address of the bound (included in the bound)

• end – the end address of the bound (excluded in the bound)

get_bounds() → List[Tuple[int, int]]

Gets a list of bounds for the machine.

Returns:

The list of bounds.

add_constraint(expr: Bool) → None

Add a constraint to the environment

A constraint is an expression that some emulators can use to limit the possible values of unbound variables. They will only consider execution states where all constraints can evaluate to True.

Constraints must be Boolean expressions; the easiest form is the equality or inequality of two bitvector expressions.

You can get the variable representing a labeled Value via its to_symbolic() method. Note that Values with both a label and content already have a constraint binding the label’s variable to the content.

Parameters:

expr – The constraint expression to add

get_constraints() → List[Bool]

Retrieve all constraints applied to this machine.

Returns:

A list of constraint expressions

apply(emulator: Emulator) → None

Apply state to an emulator.

Parameters:

emulator – The emulator to which state should applied.

extract(emulator: Emulator) → None

Load state from an emulator.

Parameters:

emulator – The emulator from which to load

emulate(emulator: Emulator) → Machine

Emulate this machine with the given emulator.

Parameters:

emulator – An emulator instance on which this machine state should run.

Returns:

The final system state after emulation.

add(item)

Add an element.

analyze(analysis: Analysis) → None

Run the given analysis on this machine.

Parameters:

analysis – The analysis to run.

clear()

This is slow (creates N new iterators!) but effective.

discard(item)

Remove an element. Do not raise an exception if absent.

isdisjoint(other)

Return True if two sets have a null intersection.

pop()

Return the popped value. Raise KeyError if empty.

remove(value)

Remove an element. If not a member, raise a KeyError.

step(emulator: Emulator) → Generator[Machine, None, None]

This is a generator that single steps the machine each time it is called.

Yields:

A new machine that is the previous one single stepped forward.

fuzz(emulator: Emulator, input_callback: Callable, crash_callback: Callable | None = None, always_validate: bool = False, iterations: int = 1) → None

Fuzz the machine using unicornafl.

Parameters:

• emulator – Currently, must be the unicorn emulator

• input_callback – A callback that applies an input to a machine

• input_file_path – The path of the input file AFL will mutate. If not given, we assume argv[1].

• crash_callback – An optional callback that is given the unicorn state and can decide whether or not to record it as a crash. (See unicornafl documentation for more info)

• always_validate – Whether to run the crash_callback on every run or only when unicorn returns an error.

• iterations – The number of iterations to run before forking a new child

Returns:

Bytes for this value with the given byteorder.

fuzz_with_file(emulator: Emulator, input_callback: Callable, input_file_path: str, crash_callback: Callable | None = None, always_validate: bool = False, iterations: int = 1) → None

Fuzz the machine using unicornafl.

Parameters:

• emulator – Currently, must be the unicorn emulator

• input_callback – A callback that applies an input to a machine

• input_file_path – The path of the input file AFL will mutate. If not given, we assume argv[1].

• crash_callback – An optional callback that is given the unicorn state and can decide whether or not to record it as a crash. (See unicornafl documentation for more info)

• always_validate – Whether to run the crash_callback on every run or only when unicorn returns an error.

• iterations – The number of iterations to run before forking a new child

Returns:

Bytes for this value with the given byteorder.

get_cpus()

Gets a list of CPU attached to this machine.

Returns:

A list of objects that subclass CPU attached to this machin.

get_platforms()

Gets a set of platforms for the CPU (s) attached to this machine.

Returns:

A set of platforms for the CPU (s) attached to this machin.

get_cpu()

Gets the CPU attached to this machine. Throws an exception if the machine has more than one.

Raises:

ConfigurationError – if the machine has more than one CPU

Returns:

The CPU attached to this machine.

get_platform()

Gets the platform of the CPU (s) attached to this machine. Throws an exception if the machine has more than one.

Raises:

ConfigurationError – if the machine has more than one platform

Returns:

The platform for the CPU (s) attached to this machine.

read_memory(address: int, size: int) → bytes | None

Read bytes out of memory if available.

Parameters:

• address – start address of read.

• size – number of bytes to read.

Returns:

the bytes read, or None if unavailable.