cyst.api.configuration.host

class cyst.api.configuration.host.service.ServiceParameter(*args, **kwargs)

Bases: Flags

Service parameter represents a domain of parametrization for passive services.

Values

ENABLE_SESSION:: A service can be a destination of a session, e.g., SSH or VPN tunnel, or HTTP server. Possible values: True|False
SESSION_ACCESS_LEVEL:: An access level of a session when it is established. This can be different from the service access level, e.g., SSH daemon has an elevated service access level, but its sessions are always limited. Possible values: the domain of cyst.api.logic.access.AccessLevel.

class cyst.api.configuration.host.service.ActiveServiceConfig(type: str, name: str, owner: str, access_level: ~cyst.api.logic.access.AccessLevel, configuration: ~typing.Dict[str, ~typing.Any] | None = None, id: str = '', ref: str = <factory>)

Bases: ConfigItem

A configuration for an Active service.

Parameters:

type (str) – A unique name of service type, with which it is registered into the system.
name (str) –
A unique name of service on a given node.

This name currently equals to a port identification, but in future releases a service will have a list of opened ports.
owner (str) –
An identity of the owner of the service.

This identity should exist on the node, but it is currently not enforced.
access_level (AccessLevel) – The access level of the service, i.e., the resources the service can access.
configuration (Optional[Dict[str, Any]]) –
A dictionary of any parameters configuring the behavior of the service.

The configuration is strictly service-dependent and there is no common configuration. For possible values consult service documentation.

class cyst.api.configuration.host.service.PassiveServiceConfig(name: str, owner: str, version: str, local: bool, access_level: ~cyst.api.logic.access.AccessLevel, authentication_providers: ~typing.List[~cyst.api.configuration.logic.access.AuthenticationProviderConfig | str | None] = <factory>, access_schemes: ~typing.List[~cyst.api.configuration.logic.access.AccessSchemeConfig] = <factory>, public_data: ~typing.List[~cyst.api.configuration.logic.data.DataConfig | str] = <factory>, private_data: ~typing.List[~cyst.api.configuration.logic.data.DataConfig | str] = <factory>, public_authorizations: ~typing.List[~cyst.api.configuration.logic.access.AuthorizationConfig | ~cyst.api.configuration.logic.access.AuthenticationTokenConfig | str] = <factory>, private_authorizations: ~typing.List[~cyst.api.configuration.logic.access.AuthorizationConfig | ~cyst.api.configuration.logic.access.AuthenticationTokenConfig | str] = <factory>, parameters: ~typing.List[~typing.Tuple[~cyst.api.configuration.host.service.ServiceParameter, ~typing.Any]] = <factory>, id: str = '', ref: str = <factory>)

Bases: ConfigItem

A configuration for a Passive service.

Any configuration parameter in the form Union[…Config, str] means that the parameter can be specified either inline, or can be referenced by its id. This enables a better structuring of a code.

Parameters:

name (str) –
A name of the passive service.

While the name can be anything, and it is not in any way enforced, this name is used to evaluate applicability of exploits, so two services susceptible to the same exploit should have the same name.

This name currently equals to a port identification, but in future releases a service will have a list of opened ports.
owner (str) –
An identity of the owner of the service.

This identity should exist on the node, but it is currently not enforced.
version (str) –
A version of the service.

The version specifier should follow semantic versioning scheme. Otherwise unintended consequences will occur. The version is also used to evaluate applicability of exploits.
local (bool) –
Availability of the service across the network.

If TRUE, the service does not have associated network port and can’t be accessed remotely. If FALSe, the service does have a network port with its name associated and can be accessed, provided the routing enables it.
access_level (AccessLevel) – The access level of the service. If the service is successfully compromised, then this will be the access level that the attacker will be able to use.

authentication_providers (List[Optional[Union[AuthenticationProviderConfig, str]]]) –

A set of authentication providers that the service uses.

Example:

local_password_auth = AuthenticationProviderConfig(
    provider_type=AuthenticationProviderType.LOCAL,
    token_type=AuthenticationTokenType.PASSWORD,
    token_security=AuthenticationTokenSecurity.SEALED,
    timeout=30
)

c = PassiveServiceConfig(
    ...
    authentication_providers=[local_password_auth("openssh_local_pwd_auth")],
    ...
)

access_schemes (List[AccessSchemeConfig]) –

A set of schemes for accessing the service.

An access scheme consists of authentication providers and authorization domains. For the complete logic behind authentication and authorization, see developer documentation.

Example:

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)
        ]
    )
)]

public_data (List[Union[DataConfig, str]]) – A set of data, that can be extracted from the service without authorization.
private_data (List[Union[DataConfig, str]]) – A set of data, that can be extracted from the service with authorization.
public_authorizations (List[Union[AuthorizationConfig, str]]) –
A set of authentications/authorizations that can be extracted from the service without authorization.

This function is DEPRECATED, because it does not conform to new authentication/authorization framework, but it is currently left here, because some tests still depend on it.
public_authorizations –
A set of authentications/authorizations that can be extracted from the service with authorization.

This function is DEPRECATED, because it does not conform to new authentication/authorization framework, but it is currently left here, because some tests still depend on it.
parameters (List[Tuple[ServiceParameter, Any]]) –
A set of parameters for the service.

The parameters can be chosen from the specific domain of ServiceParameter.

Example:
```
parameters=[
    (ServiceParameter.ENABLE_SESSION, True),
    (ServiceParameter.SESSION_ACCESS_LEVEL, AccessLevel.LIMITED)
],
```