API reference

cyst.api.configuration

class cyst.api.configuration.configuration.ConfigItem

A superclass of a configuration items.

Most of the configuration items have an instantiated counterpart produced by the platform. To tie these two object classes together, the configuration item has three identification properties: ref, name, and id.

Parameters:

  • ref (str) – A unique identification of a given configuration item. This parameter is primarily used for referencing this configuration from other configurations, usually when a configuration of a particular item is shared among multiple other configuration items. Unless there is a good reason to set it explicitly, it is best to let it be autogenerated. By default, UUIDs are used.

  • name (str) – An identifier of the object produced from the configuration item. It should be unique among siblings within the same parent. As with the ref parameters, it is best to let it be autogenerated, as the system will try to come up with a memorable name. In case of name clash among siblings, a suffix is added to the name to distinguish different objects. Note that the name is often not accessible through CYST API, except for service names that are currently used for message routing and exploit evaluation.

  • id (str) – An identifier of the object that is unique within the whole simulation. Unless you have a very good reason, you should let it be autogenerated. The id is automatically constructed with the dot notation to express the parent-child hierarchy. Note that the id is generally not accessible through CYST API, as it is considered an implementation detail that is used for management of simulation components.

class cyst.api.configuration.configuration.ConfigParameter(*args, **kwargs)

ConfigParameter serves as a placeholder, that will be replaced by a concrete value when configuration pass happens.

Usage example:
...
PassiveServiceConfig(
    name="bash",
    owner="root",
    version=ConfigParameter("my-custom-version"),
    access_level=ConfigParameter("my-custom-access_level"),
    local=True,
)
...
Parameters:

id (str) – An identifier of the parameter. Must be unique within the configuration.

class cyst.api.configuration.configuration.ConfigParameterValueType(*values)

Configuration parameter can be replaced with a concrete value in the configuration pass in three different ways. However, in any case, the developer behind the parametrization is responsible for providing values of the correct type. This is not validated, until a configuration pass happens and in case of wrong value type, it will just die painfully.

VALUE:

A specific value is provided.

REF:

An existing configuration item with a given ref will be used. If multiple config parameters resolve to the same ref, then a one instance of the same configuration item will be present in multiple places. This can be desired in some cases, but more often it is not. So, beware!

REF_COPY:

A copy of an existing configuration item will be used, with autogenerated identifiers. Thus, more instances of the same type can be created. This is usually the right choice.

class cyst.api.configuration.configuration.ConfigParameterSingle(name: str, value_type: ConfigParameterValueType, description: str, default: Any, parameter_id: str)

This represents a single configurable parameter.

Parameters:

  • name (str) – The name is an identification of a configurable parameter. It must be unique among other configuration parameters.

  • value_type (ConfigParameterValueType) – The type of configuration parameter, i.e. what type of value will be there after substitution.

  • description (str) – Additional information about the purpose of the configuration parameter. Most useful for user-facing interfaces.

  • default (Any) – A default value of the parameter. This value will be used if there is no user-provided parametrization.

  • parameter_id (str) – An id of a parameter placeholder, which should be replaced by the value of this parameter.

class cyst.api.configuration.configuration.ConfigParameterGroupType(*values)

When a group of parameters is used, this specifies, how its elements can be selected.

ONE:

Only one element of the group can be selected.

ANY:

0..N elements of the group can be selected.

class cyst.api.configuration.configuration.ConfigParameterGroupEntry(description: str, value: Any, parameter_id: str)

A single choice from the parametrization group. Unlike the single configuration parameter, the group entry directly specifies the value. If you require the user to specify something within the group entry, do it two-step like this:

Example

attacker_service = ActiveServiceConfig(
    type=ConfigParameter("attacker_type"),
    name="attacker",
    owner="attacker",
    access_level=AccessLevel.LIMITED,
    ref="attacker_service_ref"
)

...

parametrization = ConfigParametrization([
    ConfigParameterGroup(
        name="Attacker position",
        group_type=ConfigParameterGroupType.ONE,
        value_type=ConfigParameterValueType.REF,
        description="The node, where the attacker starts at.",
        default="attacker_location_1",
        options=[
            ConfigParameterGroupEntry(
                parameter_id="attacker_location_1",
                value="attacker_service_ref",
                description="Node 1"
            ),
            ConfigParameterGroupEntry(
                parameter_id="attacker_location_2",
                value="attacker_service_ref",
                description="Node 2"
            )
        ]
    )
])

This way, you will enable the user to specify both the position of the attacker from the group and its type.

Parameters:

  • description (str) – Additional information about the purpose of the configuration parameter. Most useful for user-facing interfaces.

  • value (Any) – The concrete value that will be used if chosen.

  • parameter_id (str) – An id of a parameter placeholder, which should be replaced by the value of this parameter.

class cyst.api.configuration.configuration.ConfigParameterGroup(parameter_id: str, name: str, group_type: ConfigParameterGroupType, value_type: ConfigParameterValueType, description: str, default: list[str], options: List[ConfigParameterGroupEntry])

Config parameter group represents a choice of zero or more options that a user can make.

Parameters:

  • name (str) – The name is an identification of the group. It must be unique among other configuration parameters.

  • group_type (ConfigParameterGroupType) – Specifies a selection method for group entries.

  • value_type (ConfigParameterValueType) – Specifies the type of configuration parameter, i.e. what type of value will be there after substitution.

  • description (str) – Provides additional information about the purpose of the group of parameters. Most useful for user-facing interfaces.

  • default (str) – A parameter_id of the entry that is used if the user does not specify anything.

  • options (List[ConfigParameterGroupEntry]) – A list of configuration entries to select from.

class cyst.api.configuration.configuration.ConfigParametrization(parameters: ~typing.List[~cyst.api.configuration.configuration.ConfigParameterSingle | ~cyst.api.configuration.configuration.ConfigParameterGroup], ref: str = <factory>)

A top-level object covering all the parametrization in a given configuration.

Parameters:

parameters (List[Union[ConfigParameterSingle, ConfigParameterGroup]]) – A list of configuration parameters and groups.

cyst.api.environment

cyst.api.host

cyst.api.logic

cyst.api.network

cyst.api.utils

While there is some code inside, utils are only rarely used and most of the code should go away.