cyst.api.configuration.logic

Provides configuration mechanisms to control aspects of simulation model’s logical component. This includes:

Authentization and authorization component (cyst.api.configuration.logic.access)
Data manipulation component (cyst.api.configuration.logic.data)
Exploit component (cyst.api.configuration.logic.exploit)

cyst.api.configuration.logic.access

class cyst.api.configuration.logic.access.AuthorizationConfig(identity: str, access_level: ~cyst.api.logic.access.AccessLevel, ref: str = <factory>, name: str = '__authorization', id: str = '')

Bases: ConfigItem

Configuration of a local authorization.

This configuration is used as a template to produce authorization tokens after successful authentication.

Parameters:

identity (str) – An identity, who this authorization relates to.
access_level (AccessLevel) – An access level of this particular authorization

class cyst.api.configuration.logic.access.FederatedAuthorizationConfig(identity: str, access_level: ~cyst.api.logic.access.AccessLevel, nodes: ~typing.List[str], services: ~typing.List[str], ref: str = <factory>, name: str = '__authorization', id: str = '')

Bases: ConfigItem

Configuration of a federated authorization.

Unlike local authorization a federated authorization can span multiple services and nodes.

This configuration is used as a template to produce authorization tokens after successful authentication.

Parameters:

identity (str) – An identity, who this authorization relates to.
access_level (AccessLevel) – An access level of this particular authorization
nodes (List[str]) – A list of node ids this authorization applies to.
services (List[str]) – A list of service ids this authorization applies to.

class cyst.api.configuration.logic.access.AuthorizationDomainType(*values)

Bases: IntEnum

Specification of an authorization domain type.

LOCAL:: Local domain (confined to one node and service)
FEDERATED:: Federated domain (can span multiple nodes and services)

class cyst.api.configuration.logic.access.AuthorizationDomainConfig(type: ~cyst.api.configuration.logic.access.AuthorizationDomainType, authorizations: ~typing.List[~cyst.api.configuration.logic.access.AuthorizationConfig | ~cyst.api.configuration.logic.access.FederatedAuthorizationConfig], ref: str = <factory>, name: str = '__authorization_domain', id: str = '')

Bases: ConfigItem

Configuration of an authorization domain.

An authorization domain represents a collection of authorizations, which can then be associated with access scheme.

Parameters:

type (AuthorizationDomainType) – A type of the domain.
authorizations (List[Union[AuthorizationConfig, FederatedAuthorizationConfig]]) – A list of authorization configurations

class cyst.api.configuration.logic.access.AuthenticationProviderConfig(provider_type: ~cyst.api.logic.access.AuthenticationProviderType, token_type: ~cyst.api.logic.access.AuthenticationTokenType, token_security: ~cyst.api.logic.access.AuthenticationTokenSecurity, ip: ~netaddr.ip.IPAddress | None = None, timeout: int = 0, ref: str = <factory>, name: str = '__authentication_provider', id: str = '')

Bases: ConfigItem

Configuration of an authentication provider

Authentication provider represents an authentication mechanism that can be employed in services via the access scheme mechanism.

Parameters:

provider_type (AuthenticationProviderType) – The type of authentication provider.
token_type (AuthenticationTokenType) – The type of tokens that are employed by this authentication provider.
token_security (AuthenticationTokenSecurity) – Security mechanism applied to stored tokens.
ip (Optional[IPAddress]) – An optional IP address, which is intended for remote or federated providers. It represents an IP address where this provider can be accessed.

class cyst.api.configuration.logic.access.AuthenticationTokenConfig(identity: str | None, providers: ~typing.List[str | ~cyst.api.configuration.logic.access.AuthenticationProviderConfig], ref: str = <factory>, name: str = '__authentication_token', id: str = '')

Bases: ConfigItem

Configuration of an authentication token.

The token represents a concrete piece of authentication. It can be tied to an identity (such as a combination of username and password), or it can be only the password, PIN, etc.

One token can belong to multiple authentication providers, as is the case with password sharing.

Parameters:

identity (str | None) – The identity of a user this token is tied to.
providers (List[str | AuthenticationProviderConfig]) – A list of authentication providers this token works on.

class cyst.api.configuration.logic.access.AccessSchemeConfig(authentication_providers: ~typing.List[str | ~cyst.api.configuration.logic.access.AuthenticationProviderConfig], authorization_domain: ~cyst.api.configuration.logic.access.AuthorizationDomainConfig | str, ref: str = <factory>, name: str = '__access_scheme', id: str = '')

Bases: ConfigItem

Configuration of an access scheme.

An access scheme is a combination of authentication providers, which use a supplied authorization domain. An access scheme provides means to describe multiple authentication scheme within one service or multi-factor authentication.

Example:

PassiveServiceConfig(
    ...
    authentication_providers=[
        AuthenticationProviderConfig(
            provider_type=AuthenticationProviderType.LOCAL,
            token_type=AuthenticationTokenType.PASSWORD,
            token_security=AuthenticationTokenSecurity.SEALED,
            timeout=30,
            id="openssh_local_pwd_auth"
        )
    ],
    access_schemes=[AccessSchemeConfig(
        authentication_providers=["openssh_local_pwd_auth"],
        authorization_domain=AuthorizationDomainConfig(
            type=AuthorizationDomainType.LOCAL,
            authorizations=[
                AuthorizationConfig("user1", AccessLevel.LIMITED, id="ssh_auth_1"),
                AuthorizationConfig("user2", AccessLevel.LIMITED, id="ssh_auth_2"),
                AuthorizationConfig("root", AccessLevel.ELEVATED)
            ]
        )
    )],
    ...
)

Parameters:

authentication_providers (List[Union[AuthenticationProviderConfig, str]]) – A list of authentication providers or their ids.
authorization_domain (Union[AuthorizationDomainConfig, str]) – A domain from which authorization tokens are created after successful authentication.

cyst.api.configuration.logic.data

class cyst.api.configuration.logic.data.DataConfig(owner: str, description: str, path: str = '', ref: str = <factory>, name: str = '__data', id: str = '')

Bases: ConfigItem

Configuration of a data element.

This component is currently in a very rudimentary state and the future updates will among other things include the option to encrypt the data and add specific flags.

Parameters:

owner (str) – An identity of the owner of the data.
description (str) – A textual description of the data. Currently, the only mechanism to distinguish different data.
path (str) – A path to the data. If left as an empty string, the path is not considered.

cyst.api.configuration.logic.exploit

class cyst.api.configuration.logic.exploit.VulnerableServiceConfig(service: str, min_version: ~semver.version.Version | str, max_version: ~semver.version.Version | str = '0.0.0', ref: str = <factory>, name: str = '__vulnerable_service', id: str = '')

Bases: ConfigItem

Configuration of vulnerable service.

This represents a version range of an exploitable service and is used only by exploits and exploit evaluation mechanisms.

Parameters:

service (str) – A name of the service. It is an equivalent of PassiveService/PassiveServiceConfig name.
min_version (Union[VersionInfo, str]) – A minimum version of the service that is vulnerable. Even though the type supports any string, using anything else than string representation of a semantic version will lead to problems.
max_version (Union[VersionInfo, str]) – A maximum version of the service that is vulnerable. Even though the type supports any string, using anything else than string representation of a semantic version will lead to problems.

class cyst.api.configuration.logic.exploit.ExploitParameterConfig(type: ~cyst.api.logic.exploit.ExploitParameterType, value: str | None = None, immutable: bool = True, ref: str = <factory>, name: str = '__exploit_parameter', id: str = '')

Bases: ConfigItem

Configuration of exploit parameter.

Exploit parameter either represents a specification of an exploit, which can’t be modified by a user, but is taken into account by exploit evaluation mechanisms (e.g., if the impact is one user or all users), or provides a mean for a user to supply additional information necessary for full execution of the exploit (e.g., identity of a user to impersonate).

Example:

parameters=[
    ExploitParameterConfig(ExploitParameterType.IDENTITY, immutable=False),
    ExploitParameterConfig(ExploitParameterType.ENABLE_ELEVATED_ACCESS, "FALSE", immutable=True)
],

Parameters:

type (ExploitParameterType) – A type of the exploit parameter.
value (Optional[str]) – A value of the parameter.
immutable (bool) – A flag indicating, whether a user can change the value of the parameter.

class cyst.api.configuration.logic.exploit.ExploitConfig(services: ~typing.List[~cyst.api.configuration.logic.exploit.VulnerableServiceConfig | str], locality: ~cyst.api.logic.exploit.ExploitLocality, category: ~cyst.api.logic.exploit.ExploitCategory, parameters: ~typing.List[~cyst.api.configuration.logic.exploit.ExploitParameterConfig] | None = None, ref: str = <factory>, name: str = '__exploit', id: str = '')

Bases: ConfigItem

Configuration of a working exploit.

If a definition of exploit exists, then a services it refers to are vulnerable, as long as their version match. Patching the service and bumping a version over the max vulnerable version is the only countermeasure.

Example:

ExploitConfig(
    services=[
        VulnerableServiceConfig(
            name="bash",
            min_version="5.0.0",
            max_version="5.1.0"
        )
    ],
    locality=ExploitLocality.LOCAL,
    category=ExploitCategory.AUTH_MANIPULATION,
    parameters=[
        ExploitParameterConfig(
            type=ExploitParameterType.ENABLE_ELEVATED_ACCESS,
            value="TRUE",
            immutable=True
        )
    ],
    id="bash_root_exploit"
)

Parameters:

services (List[Union[VulnerableServiceConfig, str]]) – A list of services that are vulnerable to this exploit.
locality (ExploitLocality) – Determines if the exploit can be used locally or remotely.
category (ExploitCategory) – Determines the category of the exploit.
parameters (Optional[List[ExploitParameterConfig]]) – An optional list of exploit parameters.