Skip to content

Options

consortium.framework.options

The options framework provides a set of options classes, SingleValueOption, ListValueOption, ChoiceValueOption, ToggleableChoicesValueOption, and DictionaryValueOption that are used across the framework to define the parameters that different framework components accept as well as to perform validation on the arguments that are set on those options.

The options classes should be imported and used from this module.

Example 
from consortium.framework.options import (
    SingleValueOption,
    ListValueOption,
    ChoiceValueOption,
    ToggleableChoicesValueOption,
    DictionaryValueOption,
)

Additionally, the options framework provides a set of validating functions that can be used to validate option values.

Example 
from consortium.framework.options import validate_is_ip_address

ChoiceValueOption(name, available_values, description='', required=True, default_value=None)

Bases: BaseOption[Primitive]

An option whose value is a single choice from a fixed set of available values.

Each available choice is restricted to one of the primitive types str, int, float, or bool, and only one choice can be selected at a time.

Attributes:

Name Type Description
option_type OptionType

The type of the option.
name str

The human-readable name of the option. The name cannot be an empty string.
description str

A description of the option.
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.
default_value ValueType | None

The default value of the option. If None, the option has no default value.
available_values set[Primitive]

The set of available values that the user can choose from. The type of each choice is restricted to being a str, int, float, or bool.

Parameters:

Name Type Description Default
name str

The human-readable name of the option. The name cannot be an empty string.

 required
description str

A description of the option.

 ''
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.

 True
default_value Primitive | None

The default value of the option. If None, the option has no default value.

 None
available_values set[Primitive]

The set of available values that the user can choose from. The type of each choice is restricted to being a str, int, float, or bool.

 required
Setting up a ChoiceValueOption with string values. 
payload_format = ChoiceValueOption(
    name="payload_format",
    description="The output file format of the payload to compile to.",
    required=True,
    default_value="exe",
    available_values={"exe", "dll", "ps1"},
)
payload_format.validate_value("dll")
payload_format.validate_value("not_a_valid_format")  # Will raise `OptionValueValidationError`

option_type = OptionType.CHOICE_VALUE_OPTION class-attribute instance-attribute

The type of the option.

available_values = available_values instance-attribute

validate_value(value)

Validate that a candidate value is one of the option's available values.

Parameters:

Name Type Description Default
value Primitive

The value to validate.

 required

Raises:

Type Description
OptionValueValidationError

If the value is not one of the available values.

to_json()

Serialize the option and its available values to a JSON-compatible dictionary.

Returns:

Type Description
dict[str, JsonValue]

A dictionary containing the option's name, description, required flag,
dict[str, JsonValue]

default value, and available values.

DictionaryValueOption(name, description='', required=True, default_value=None, key_validating_regex=None, key_validating_function=None, value_type=None, value_validating_regex=None, value_validating_function=None, validating_function=None)

Bases: BaseOption[dict[str, Primitive]]

An option that holds a mapping of string keys to scalar values.

Keys are restricted to type str and values are restricted to one of the primitive types str, int, float, or bool.

Attributes:

Name Type Description
option_type OptionType

The type of the option.
name str

The human-readable name of the option. The name cannot be an empty string.
description str

A description of the option.
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.
default_value ValueType | None

The default value of the option. If None, the option has no default value.
key_validating_regex str | None

This parameter specifies a regex pattern that each of the keys in the dictionary, which can only be of type str, must match.
key_validating_function Callable[[str], None] | None

A function that accepts a single argument, the keys of the dictionary, and raises an exception, OptionValueValidationError, if the value is invalid. If None, no additional validation is performed.
value_type PrimitiveType | None

The type of the value in the dictionary that the option can accept. If None, the dictionary can have values of type str, int, float, or bool.
value_validating_regex str | None

This parameter specifies a regex pattern that each of the values in the dictionary must match.
value_validating_function Callable[[Primitive], None] | None

A function that accepts a single argument, the values of the dictionary, and raises an exception, OptionValueValidationError, if the value is invalid. If None, no additional validation is performed.
validating_function Callable[[dict[str, Primitive]], None] | None

A function that accepts a single argument, the entire dictionary value of the option, and raises an exception, OptionValueValidationError, if the value is invalid. If None, no additional validation is performed.

Parameters:

Name Type Description Default
name str

The human-readable name of the option. The name cannot be an empty string.

 required
description str

A description of the option.

 ''
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.

 True
default_value dict[str, Primitive] | None

The default value of the option. If None, the option has no default value.

 None
key_validating_regex str | None

This parameter specifies a regex pattern that each of the keys in the dictionary, which can only be of type str, must match.

 None
key_validating_function Callable[[str], None] | None

A function that accepts a single argument, the keys of the dictionary, and raises an exception, OptionValueValidationError, if the value is invalid. If None, no additional validation is performed.

 None
value_type PrimitiveType | None

The type of the value in the dictionary that the option can accept. If None, the dictionary can have values of type str, int, float, or bool.

 None
value_validating_regex str | None

This parameter specifies a regex pattern that each of the values in the dictionary must match.

 None
value_validating_function Callable[[Primitive], None] | None

A function that accepts a single argument, the values of the dictionary, and raises an exception, OptionValueValidationError, if the value is invalid. If None, no additional validation is performed.

 None
validating_function Callable[[dict[str, Primitive]], None] | None

A function that accepts a single argument, the entire dictionary value of the option, and raises an exception, OptionValueValidationError, if the value is invalid. If None, no additional validation is performed.

 None
Example 
extra_headers = DictionaryValueOption(
    name="extra_headers",
    description=(
        "Extra headers to include in the HTTP request made by the agent when "
        "checking in with the listener."
    ),
    required=False,
    default_value={"User-Agent": "Mozilla/5.0"},
    value_type=str,
)

option_type = OptionType.DICTIONARY_VALUE_OPTION class-attribute instance-attribute

The type of the option.

key_validating_regex = key_validating_regex instance-attribute

key_validating_function = key_validating_function instance-attribute

value_type = value_type instance-attribute

value_validating_regex = value_validating_regex instance-attribute

value_validating_function = value_validating_function instance-attribute

validating_function = validating_function instance-attribute

validate_value(value)

Validate a candidate dictionary value against this option's constraints.

Checks that the value is a dictionary, then validates each key against the key type, key regex, and key validating function, and each value against the value type, value regex, and value validating function, before running any whole-dictionary validating function.

Parameters:

Name Type Description Default
value dict[str, Primitive]

The dictionary value to validate.

 required

Raises:

Type Description
OptionValueValidationError

If the value, any key, or any value violates a configured constraint.

to_json()

Serialize the option and its constraints to a JSON-compatible dictionary.

Returns:

Type Description
dict[str, JsonValue]

A dictionary containing the option's name, description, required flag,
dict[str, JsonValue]

default value, and every configured key and value constraint.

ListValueOption(name, description='', required=True, default_value=None, allow_duplicates=True, value_type=None, minimum_length=None, maximum_length=None, greater_than=None, less_than=None, greater_than_or_equal_to=None, less_than_or_equal_to=None, minimum_elements=None, maximum_elements=None, validating_regex=None, validating_function=None)

Bases: BaseOption[list[Primitive]]

An option that holds a list of scalar values.

Each element is restricted to one of the primitive types str, int, float, or bool, and the elements may be either homogeneous or heterogeneous.

Attributes:

Name Type Description
option_type OptionType

The type of the option.
name str

The human-readable name of the option. The name cannot be an empty string.
description str

A description of the option.
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.
default_value ValueType | None

The default value of the option. If None, the option has no default value.
value_type PrimitiveType | None

The type of the elements that the option can accept for the list value. If None, the list's data type is heterogeneous and each element can be any of str, int, float, or bool otherwise its data type is homogeneous and the data type of its elements can only be one of str, int, float, or bool.
minimum_length int | None

If value_type is of type str, this parameter specifies the minimum max_length of each string element that the option can accept. If None, there is no minimum max_length.
maximum_length int | None

If value_type is of type str, this parameter specifies the maximum max_length of each string element that the option can accept. If None, there is no maximum max_length.
greater_than int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be greater than this value.
less_than int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be less than this value.
greater_than_or_equal_to int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be greater than or equal to this value.
less_than_or_equal_to int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be less than or equal to this value.
minimum_elements int | None

The minimum number of elements that the option can hold. If None, there is no minimum number of elements.
maximum_elements int | None

The maximum number of elements that the option can hold. If None, there is no maximum number of elements.
validating_regex str | None

If value_type is of type str, this parameter specifies a regex pattern that each element of the option must match.
validating_function Callable[[Primitive], None] | None

A function that accepts a single argument, the value of the option, and raises an exception, OptionValueValidationError if the value is invalid. If None, no additional validation is performed.

Parameters:

Name Type Description Default
name str

The human-readable name of the option. The name cannot be an empty string.

 required
description str

A description of the option.

 ''
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.

 True
default_value list[Primitive] | None

The default value of the option. If None, the option has no default value.

 None
value_type PrimitiveType | None

The type of the elements that the option can accept for the list value. If None, the list's data type is heterogeneous and each element can be any of str, int, float, or bool otherwise its data type is homogeneous and the data type of its elements can only be one of str, int, float, or bool.

 None
minimum_length int | None

If value_type is of type str, this parameter specifies the minimum max_length of each string element that the option can accept. If None, there is no minimum max_length.

 None
maximum_length int | None

If value_type is of type str, this parameter specifies the maximum max_length of each string element that the option can accept. If None, there is no maximum max_length.

 None
greater_than int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be greater than this value.

 None
less_than int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be less than this value.

 None
greater_than_or_equal_to int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be greater than or equal to this value.

 None
less_than_or_equal_to int | float | None

If value_type is of type int or float, the numeric value of each element of the option must be less than or equal to this value.

 None
minimum_elements int | None

The minimum number of elements that the option can hold. If None, there is no minimum number of elements.

 None
maximum_elements int | None

The maximum number of elements that the option can hold. If None, there is no maximum number of elements.

 None
validating_regex str | None

If value_type is of type str, this parameter specifies a regex pattern that each element of the option must match.

 None
validating_function Callable[[Primitive], None] | None

A function that accepts a single argument, the value of the option, and raises an exception, OptionValueValidationError if the value is invalid. If None, no additional validation is performed.

 None
Setting up a ListValueOption with a homogeneous data type. 
backup_hosts = ListValueOption(
    name="backup_hosts",
    description=(
        "The list of hosts as IPV4 addresses to attempt to connect to in "
        "case the main host is unreachable."
    ),
    required=True,
    default_value=["1.1.1.1", "2.2.2.2"],
    value_type=str,
    minimum_length=1,
    validating_regex=r"^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$",
)
backup_hosts.set_option_value(["1.1.1.1", "2.2.2.2", "3.3.3.3"])  # A list of values is passed in to the option.
backup_hosts.set_option_value(["not_an_ip_address", "2.2.2.2", "3.3.3.3"])  # Will raise `OptionValueValidationError`

option_type = OptionType.LIST_VALUE_OPTION class-attribute instance-attribute

allow_duplicates = allow_duplicates instance-attribute

value_type = value_type instance-attribute

minimum_length = minimum_length instance-attribute

maximum_length = maximum_length instance-attribute

greater_than = greater_than instance-attribute

less_than = less_than instance-attribute

greater_than_or_equal_to = greater_than_or_equal_to instance-attribute

less_than_or_equal_to = less_than_or_equal_to instance-attribute

minimum_elements = minimum_elements instance-attribute

maximum_elements = maximum_elements instance-attribute

validating_regex = validating_regex instance-attribute

validating_function = validating_function instance-attribute

validate_value(value)

Validate a candidate list value against this option's constraints.

Checks that the value is a list, applies any element duplication and list length constraints, then validates each element's data type along with any configured numeric range, string length, regex, and custom validating function constraints.

Parameters:

Name Type Description Default
value list[Primitive]

The list value to validate.

 required

Raises:

Type Description
OptionValueValidationError

If the value or any of its elements violates a configured constraint.

to_json()

Serialize the option and its constraints to a JSON-compatible dictionary.

Returns:

Type Description
dict[str, JsonValue]

A dictionary containing the option's name, description, required flag,
dict[str, JsonValue]

default value, and every configured constraint.

OptionType

Bases: StrEnum

Identifies the different types of options that can be created.

Every option object exposes an option_type class attribute set to one of the variants of this enum.

Attributes:

Name Type Description
SINGLE_VALUE_OPTION

This type of option can only hold a single value at once. The type of this value is restricted to being a str, int, float, or bool.
LIST_VALUE_OPTION

This type of option can hold multiple values at once. The type of each element in the list is restricted to being a str, int, float, or bool. The type of the elements may be either heterogeneous or homogeneous.
CHOICE_VALUE_OPTION

This type of option presents a set of choices that the user can select from. The type of each choice is restricted to being a str, int, float, or bool. Only one choice can be selected at a time.
TOGGLEABLE_CHOICES_VALUE_OPTION

This type of option presents a set of choices that the user can select from. The type of each choice is restricted to being only a str which maps to a bool. Multiple choices can be selected at a time and their values are restricted to toggling the value of the bool.
DICTIONARY_VALUE_OPTION

This type of option can hold multiple key-value pairs at once. The type of the key is restricted to being only a str. The type of the value is restricted to being a str, int, float, or bool. The type of the values may be either heterogeneous or homogeneous.

SINGLE_VALUE_OPTION = 'SINGLE_VALUE_OPTION' class-attribute instance-attribute

This type of option can only hold a single value at once. The type of this value is restricted to being a str, int, float, or bool.

LIST_VALUE_OPTION = 'LIST_VALUE_OPTION' class-attribute instance-attribute

This type of option can hold multiple values at once. The type of each element in the list is restricted to being a str, int, float, or bool. The type of the elements may be either heterogeneous or homogeneous.

CHOICE_VALUE_OPTION = 'CHOICE_VALUE_OPTION' class-attribute instance-attribute

This type of option presents a set of choices that the user can select from. The type of each choice is restricted to being a str, int, float, or bool. Only one choice can be selected at a time.

TOGGLEABLE_CHOICES_VALUE_OPTION = 'TOGGLEABLE_CHOICES_VALUE_OPTION' class-attribute instance-attribute

This type of option presents a set of choices that the user can select from. The type of each choice is restricted to being only a str. Multiple choices can be selected at a time.

DICTIONARY_VALUE_OPTION = 'DICTIONARY_VALUE_OPTION' class-attribute instance-attribute

This type of option can hold multiple key-value pairs at once. The type of the key is restricted to being only a str. The type of the value is restricted to being a str, int, float, or `bool. The type of the values may be either heterogeneous or homogeneous.

SingleValueOption(name, description='', required=True, default_value=None, value_type=None, minimum_length=None, maximum_length=None, greater_than=None, less_than=None, greater_than_or_equal_to=None, less_than_or_equal_to=None, validating_regex=None, validating_function=None)

Bases: BaseOption

An option that holds a single scalar value.

The value is restricted to one of the primitive types str, int, float, or bool.

Attributes:

Name Type Description
option_type OptionType

The type of the option.
name str

The human-readable name of the option. The name cannot be an empty string.
description str

A description of the option.
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.
default_value ValueType | None

The default value of the option. If None, the option has no default value.
value_type PrimitiveType | None

The type of the value that the option can accept. If None, the option can accept values of type str, int, float, or bool.
minimum_length int | None

If value_type is of type str, this parameter specifies the minimum max_length of the string value that the option can accept. If None, there is no minimum max_length.
maximum_length int | None

If value_type is of type str, this parameter specifies the maximum max_length of the string value that the option can accept. If None, there is no maximum max_length.
greater_than int | float | None

If value_type is of type int or float, the numeric value of the option must be greater than this value.
less_than int | float | None

If value_type is of type int or float, the numeric value of the option must be less than this value.
greater_than_or_equal_to int | float | None

If value_type is of type int or float, the numeric value of the option must be greater than or equal to this value.
less_than_or_equal_to int | float | None

If value_type is of type int or float, the numeric value of the option must be less than or equal to this value.
validating_regex str | None

If value_type is of type str, this parameter specifies a regex pattern that the string value must match.
validating_function Callable[[Primitive], None] | None

A function that accepts a single argument, the value of the option, and raises an exception, OptionValueValidationError, if the value is invalid. If None, no additional validation is performed.
Setting up a SingleValueOption with numeric value constraints 
local_port = SingleValueOption(
    name="local_port",
    description="The port that the server listens on.",
    required=True,
    default_value=8080,
    value_type=int,
    greater_than=1024,
    less_than=65536,
)
local_port.set_option_value(80)  # Will raise `OptionValueValidationError`
local_port.set_option_value(65535)
Setting up a SingleValueOption with string value constraints 
local_host = SingleValueOption(
    name="local_host",
    description="The local host as an IPV4 address that the server listens on.",
    required=True,
    default_value="127.0.0.1",
    value_type=str,
    validating_regex=r"^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$",
)
local_host.set_option_value("0.0.0.0")
local_host.set_option_value("not_an_ip_address")  # Will raise `OptionValueValidationError`

option_type = OptionType.SINGLE_VALUE_OPTION class-attribute instance-attribute

value_type = value_type instance-attribute

minimum_length = minimum_length instance-attribute

maximum_length = maximum_length instance-attribute

greater_than = greater_than instance-attribute

less_than = less_than instance-attribute

greater_than_or_equal_to = greater_than_or_equal_to instance-attribute

less_than_or_equal_to = less_than_or_equal_to instance-attribute

validating_regex = validating_regex instance-attribute

validating_function = validating_function instance-attribute

validate_value(value)

Validate a candidate value against this option's constraints.

Checks the value's data type followed by any configured numeric range, string length, regex, and custom validating function constraints.

Parameters:

Name Type Description Default
value Primitive

The value to validate.

 required

Raises:

Type Description
OptionValueValidationError

If the value violates any configured constraint.

to_json()

Serialize the option and its constraints to a JSON-compatible dictionary.

Returns:

Type Description
dict[str, JsonValue]

A dictionary containing the option's name, description, required flag,
dict[str, JsonValue]

default value, value type, and every configured constraint.

ToggleableChoicesValueOption(name, available_values, description='', required=True, default_value=None)

Bases: BaseOption[dict[str, bool]]

An option whose value toggles each of a set of string choices on or off.

Each toggleable choice is restricted to type str, and multiple choices can be toggled on at the same time. The value is a dictionary mapping each available value to a boolean indicating whether that choice is toggled on or off.

Attributes:

Name Type Description
option_type OptionType

The type of the option.
name str

The human-readable name of the option. The name cannot be an empty string.
description str

A description of the option.
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.
default_value ValueType | None

The default value of the option. If None, the option has no default value.
available_values set[str]

The set of available values that the user can toggle on or off. The type of each choice is restricted to being a str.

Parameters:

Name Type Description Default
name str

The human-readable name of the option. The name cannot be an empty string.

 required
description str

A description of the option.

 ''
required bool

Whether the option is required or not. If True, the option must have a value set before it can be retrieved. If False, the option can be retrieved without a value being set.

 True
default_value dict[str, bool] | None

The default value of the option. If None, the option has no default value.

 None
available_values set[str]

The set of available values that the user can toggle on or off. The type of each choice is restricted to being a str.

 required

option_type = OptionType.TOGGLEABLE_CHOICES_VALUE_OPTION class-attribute instance-attribute

available_values = available_values instance-attribute

validate_value(value)

Validate a candidate toggle mapping against this option's available values.

Checks that the value is a dictionary whose keys are all available values and whose values are all booleans.

Parameters:

Name Type Description Default
value dict[str, bool]

The toggle mapping to validate.

 required

Raises:

Type Description
OptionValueValidationError

If the value is not a dictionary, contains an unknown key, or maps a key to a non-boolean value.

to_json()

Serialize the option and its available values to a JSON-compatible dictionary.

Returns:

Type Description
dict[str, JsonValue]

A dictionary containing the option's name, description, required flag,
dict[str, JsonValue]

default value, and available values.

validate_is_cidr(value)

Validate that the value is a valid CIDR subnet.

validate_is_datetime(value)

Validate that the value is a valid datetime string in ISO 8601 format.

validate_is_directory_and_exists(value)

Validate that the value is a valid filesystem path to a directory that exists.

validate_is_file_and_exists(value)

Validate that the value is a valid filesystem path to a file that exists.

validate_is_filesystem_path_and_exists(value)

Validate that the value is a valid filesystem path that exists.

validate_is_http_url(value)

Validate that the value is a valid HTTP or HTTPS URL.

validate_is_ip_address(value)

Validate that the value is a valid IP address.

validate_is_url(value)

Validate that the value is a valid URL with a defined scheme and network location.

validate_is_url_path(value)

Validate that the value is a valid URL endpoint path.

validate_is_uuid4(value)

Validate that the value is a valid, hyphenated UUID4 string.

Non-hyphenated UUID4 strings are considered invalid.