cyst.api.logic.access

class cyst.api.logic.access.AccessLevel(*values)

Bases: IntEnum

Access level represents in a simplified manner privileges of user, services, etc.

Possible values:

NONE:: No explicit access granted. This can either mean no access or guest-level access if available.
LIMITED:: A user-level access.
ELEVATED:: A root/superuser/administrator-level access

class cyst.api.logic.access.AuthenticationTokenType(*values)

Bases: IntEnum

A type of authentication token.

Possible values:

NONE:: A sentinel value indicating misconfigured authentication token.
PASSWORD:: A password-type auhentication token. Something that can be stored, shared, stolen, etc.
BIOMETRIC:: A token that is bound to a user and cannot be appropriated unless the user is made to comply.
DEVICE:: A physical token. Can be stolen by a human actor, but cannot be wholly manipulated by an agent.

class cyst.api.logic.access.AuthenticationTokenSecurity(*values)

Bases: IntEnum

A security precautions on the authentication token.

Possible values:

OPEN:: There are no safeguards on the token. E.g, a plaintext password or any biometric.
SEALED:: The token is hashed or encrypted for storage. E.g., /etc/shadow
HIDDEN:: The token is never exposed. E.g., stored inside TPM.

class cyst.api.logic.access.AuthenticationProviderType(*values)

Bases: IntEnum

A type of service providing an authentication.

Possible values:

LOCAL:: A service provides authentication for the node it resides on.
PROXY:: A service provides authentication through another service residing on a remote node. E.g., openID.
REMOTE:: A service provides authentication for another service on a remote node. E.g., sms or email codes.

class cyst.api.logic.access.AuthenticationToken

Bases: ABC

Authentication token represents a unit of information that can be used in one phase of authentication exchange to attempt to gain an authorization. It can be anything from PIN to biometrics.

abstract property type: AuthenticationTokenType

Returns a type of the token

Return type:: AuthenticationTokenType

abstract property security: AuthenticationTokenSecurity

Returns a security measures of the token.

Return type:: AuthenticationTokenSecurity

abstract property identity: str

Returns or sets the identity of the token, i.e., who is associated with the token and which authorization would be gained if authenticated successfully.

Getter:: Returns the identity.
Setter:: Sets the identity. The token must enable setting the identity, otherwise False is returned.
Type:: str

abstractmethod copy() → AuthenticationToken | None

Creates a copy of the token.

Return type:: AuthenticationToken

abstract property content: Data | None

Returns the data associated with the token. These data are mostly present with SEALED tokens, as they contained hashed/encrypted values that can be cracked before the token can be used.

Return type:: Optional[Data]

class cyst.api.logic.access.AuthenticationTarget

Bases: ABC

An authentication target represents on factor of an authentication scheme. It is a “pointer” to an existing service, with information about which tokens are accepted.

abstract property address: IPAddress | None

An IP address of the target. The address need not be present in case of local services.

Return type:: Optional[IPAddress]

abstract property service: str

A name of the service.

Return type:: str

abstract property tokens: List[AuthenticationTokenType]

A list of token types that the service is accepting.

Return type:: List[AuthenticationTokenType]

class cyst.api.logic.access.Authorization

Bases: ABC

Authorization represents a set of permissions that are in effect for the given combination of identity, services and nodes. Aside from identity, authorization does not enable inspecting the services and nodes it is working on. This information must be inferred from other channels.

abstract property identity: str | None

The identity of the owner of this authorization. TODO: That Optional[] is suspicious.

Return type:: Optional[str]

abstract property access_level: AccessLevel

The access level this authorization enables.

Return type:: AccessLevel

abstract property expiration: int

A number of simulated time units this authorization will be effective from the time it was created. If the value is -1, then the authorization never expires.

:rtype:int

abstract property token: UUID

A unique data token. This token can be used to compare and discern two or more authorizations.

Return type:: uuid.UUID

class cyst.api.logic.access.AuthenticationProvider

Bases: ABC

Authentication provider is a service that enables evaluation of authentication information. Depending on its type, it can authenticate only against itself (as a service), or can serve as an authenticator for other services.

abstract property type: AuthenticationProviderType

The type of the provider.

Return type:: AuthenticationProviderType

abstract property target: AuthenticationTarget

An authentication target of this provider, i.e., the description of this provider in the form usable within the authentication framework.

Return type:: AuthenticationTarget

abstractmethod token_is_registered(token: AuthenticationToken) → bool

Checks whether the supplied authentication token is registered in this provider.

Parameters:: token (AuthenticationToken) – The token to check.
Returns:: True if token is registered, false otherwise.

class cyst.api.logic.access.AccessScheme

Bases: ABC

The access scheme represents the highest level of authentication/authorization framework. The scheme is a set of authentication factors (i.e., authentication providers) with associated authorizations. A scheme is linked to a service and describes the steps an outside actor must undertake to get access to its resources.

abstract property factors: List[Tuple[AuthenticationProvider, int]]

Returns a list of authentication factors in form of authentication providers. For each factor it includes a time in simulated units that an actor has, before the authentication process is terminated.

Return type:: List[Tuple[AuthenticationProvider, int]]:

abstract property identities: List[str]

Returns a list of identities that are registered with the access scheme.

Return type:: List[str]

abstract property authorizations: List[Authorization]

Returns a list of authorization templates that are associated with the scheme. These are not actual authorizations. TODO: Are they? I am really not sure.

Return type:: List[Authorization]

cyst.api.logic.action

class cyst.api.logic.action.ActionParameterDomainType(*values)

Bases: Enum

Specifies a type of the action parameter domain.

Possible values:

ANY:: The parameters can take any values. If possible avoid this domain, as it does not enable sampling of values, thus being less useful for automated processing and learning.
RANGE:: The parameters belong to a certain numeric range, e.g., port numbers.
OPTIONS:: The parameters are a collection of values to choose from.

class cyst.api.logic.action.ActionParameterDomain

Bases: Sequence

Specifies a domain of action parameters.

abstract property type: ActionParameterDomainType

Returns a type of the action parameter domain.

Return type:: ActionParameterDomainType

abstract property range_min: int

Returns a minimal value of the range, if the domain is of RANGE type. Otherwise the value is undefined.

Return type:: int

abstract property range_max: int

Returns a maximal value of the range, if the domain is of RANGE type. Otherwise the value is undefined.

Return type:: int

abstract property range_step: int

Returns a gap between two values in a range. E.g., a range [1,3,5,7] has a step = 2.

Return type:: int

abstract property options: List[Any]

Returns a list of possible values in the domain, if the type of the domain is OPTIONS. Otherwise and empty list.

Return type:: List[Any]

abstractmethod validate(value: Any) → bool

Checks, whether a value belongs into a domain.

Parameters:: value (Any) – A value to check.

abstract property default: Any

A value from the domain that is considered a default one.

Type:: return

class cyst.api.logic.action.ActionParameterType(*values)

Bases: Enum

Specifies a type of action parameters.

Possible values:

NONE:: Type not specified, or outside the current domain of parameter types. This should be used only after due consideration, as it is better to expand this domain than to use NONE. It may interfere with the learning process.
IDENTITY:: The parameter is an identity of a user in the system.
IDENTIFIER:: The parameter is some kind of identifier.
DURATION:: The parameter represents a time duration in simulated time units.
TOKEN:: The parameter is an instance of a token object, such as cyst.api.logic.access.AuthenticationToken.
DATA:: Added as a temporary solution for actions and communication that carries actual data not encoded into the message structure. Given the complicated definition of parameters and factual uselessness of fitting data into a domain that can be sampled, this will likely be replaced by a more top-level solution.

class cyst.api.logic.action.ActionParameter(type: ActionParameterType, name: str, domain: ActionParameterDomain | None = None, value: Any | None = None)

Bases: object

Action parameter represents a mechanism to further specify details of actions. An action can have an arbitrary number of parameters.

Parameters:

type (ActionParameterType) – The type of the parameter.
name (str) – A name of the parameter, which is unique within an action.
domain (Optional[ActionParameterDomain]) – A domain of the parameter. If not specified, it is the same as adding a domain of type ANY.
value (Optional[Any]) – A default value of the parameter.

class cyst.api.logic.action.ActionType(*values)

Bases: Enum

Specifies the type of the action. The type governs, how the action is being evaluated during a simulation.

Possible values:

COMPONENT:: Component actions can only be expressed within the simulation as a part of another actions. They do not have their own semantics expressed through a behavioral model. They are primarily used to provide parametrized description of action elements, such as network flows. The intended recipient for these type of actions are metadata providers, but behavioral models can also use them to fine-tune evaluation of higher-level actions.
DIRECT:: Direct actions are expressed through a behavioral model. A direct action is always evaluated in the context of the target it reached.
COMPOSITE:: Composite actions enable specification of higher-order actions. A composite action is defined by a flow of other actions - composite or direct. Semantics of composite actions are defined through its constituent actions, which get processed and evaluated in a given flow. A composite action is evaluated in the context of its source.

Added in version 0.6.0.

class cyst.api.logic.action.ActionDescription(id: str, type: ActionType, description: str, parameters: List[ActionParameter], platform: None | PlatformSpecification | List[PlatformSpecification] = None)

Bases: object

A description of an action in the form that is used for registering into the system.

Parameters:

id (str) – A name of the action. The combination of name and execution environment must be unique across all behavioral models, so it is advisable to use own namespace for each model.
type (ActionType) – A type of the action.
description (str) – A textual description of the action.
parameters (List[ActionParameter]) – A list of action parameters.
platform (Union[None, PlatformSpecification, List[PlatformSpecification]]) – The platform, where the action is valid. One or more platforms can be specified. If none is provided, the default CYST simulation is assumed.

Changed in version 0.6.0: Removed action tokens until a new action meta-model is polished. Added type and platform specification.

class cyst.api.logic.action.Action

Bases: ABC

An action represent an activity that an actor within simulation can do. Usage of actions is mostly the domain of active services. An action does not carry any semantics by itself. The semantics is provided by interpreters / behavioral models. One action can therefore have different impact depending on the model chosen.

abstract property id: str

A unique identifier of the action within simulation. The identifier is expected to be a serialization of a position in hierarchy, separated by a colon. E.g., “aif:privilege_escalation:root_privilege_escalation”.

Return type:: str

abstract property description: str

A textual description of the action.

Return type:: str

abstract property fragments: List[str]

The list of fragments of the id (i.e., what is left after removing the colons). E.g, [“aif”, “privilege_escalation”, “root_privilege escalation”].

Return type:: List[str]

abstract property namespace: str

Currently a shorthand for fragments()[0], but that can change in the future, as the namespace can span multiple fragments.

Return type:: str

abstract property exploit: Exploit | None

Returns an exploit currently associated with the action.

Return type:: Optional[Exploit]

abstractmethod set_exploit(exploit: Exploit | None) → None

Sets an exploit associated with the action. TODO: Why the hell is this not a setter of the exploit property?

Parameters:: exploit (Optional[Exploit]) – The exploit to use. If None is passed as a value, removes the exploit from the action.

abstract property parameters: Dict[str, ActionParameter]

Returns a collection of action parameters.

Return type:: Dict[str, ActionParameter]

abstractmethod add_parameters(*params: ActionParameter) → None

Adds one or more parameters to the action. If a parameter of the same name is present, it gets overwritten.

Parameters:: params (ActionParameter) – One or more action parameters.

abstract property components: List[Action]

Returns a list of actions that constitute components of this action.

Return type:: List[Action]

Added in version 0.6.0.

abstractmethod add_components(*components: Action) → None

Adds one or more component actions to the actions. The system validates, whether an action has ActionType equal to COMPONENT. If not, an exception is thrown.

Parameters:: components (Action) – One or more component Actions.

Added in version 0.6.0.

abstractmethod copy() → Action

Returns a copy of the action. This is useful for keeping copies of action with different parameters or exploits.

Return type:: Action

cyst.api.logic.data

class cyst.api.logic.data.Data

Bases: ABC

This class represents an arbitrary data.

Warning

This is currently very underdeveloped and will be overhauled in the near future.

abstract property id: str

An identifier of the data that is unique within one service, but preferably across simulation.

Return type:: str

abstract property owner: str

The identity of a user, to whom the data belongs.

Return type:: str

abstract property description: str

A textual description of the data. Currently, it also serves as a way to store contents of the data, even though true contents of the data will never be a part of the simulation.

Return type:: str

abstract property path: str

The path to a data.

Return type:: str

cyst.api.logic.exploit

class cyst.api.logic.exploit.ExploitCategory(*values)

Bases: Enum

Exploit category represents the high-level taxonomy of exploit effects.

Possible values:

NONE:: Either the category was not selected or is not one of the other possible values. This category should be used sparsely and after due consideration.
AUTH_MANIPULATION:: The exploit is used to affect authentications or authorizations, such as privilege escalation or user manipulation.
DATA_MANIPULATION:: The exploit is used to affect data, mostly through giving access to said data.
CODE_EXECUTION:: The exploit enables execution of arbitrary code in the context of the action, so the result can be an opened session, new malware instance, etc.

class cyst.api.logic.exploit.ExploitLocality(*values)

Bases: Enum

The area of effect of the exploit, i.e., whether it can be used remotely, or whether only locally. Note that having a session opened to a remote machine counts as having a local access to the machine.

Possible values:

NONE:: Misconfiguration sentinel. No exploit should have this locality.
LOCAL:: Exploit usable only locally.
REMOTE:: Exploit usable over network.

class cyst.api.logic.exploit.ExploitParameterType(*values)

Bases: Enum

Exploits support further parametrization. The parametrization works in a key-value manner, but unlike with actions, there is no domain specification of values, so they are all strings. This will likely change in the future. But at least keys (aka. parameter types have an explicit domain).

Some parameters are mutable, i.e., able to be changed by the users, and some are immutable, which mostly describe in more details the effect of the exploit.

Possible mutable values:

NONE:: Misconfiguration sentinel. No exploit parameter should have this type.
IDENTITY:: The parameter should contain a name of a user within a simulation.
ADDRESS:: The parameter should contain an IP address.
SERVICE:: The parameter should contain a service name.

Possible immutable values:

IMPACT_IDENTITY:: A successful exploitation will provide authorization for a selected few identities, or for all. Values: (ENUMERATED, ALL).
IMPACT_NODE:: A successful exploitation will provide authorization for a selected few nodes, or for all. Values: (ENUMERATED, ALL).
IMPACT_SERVICE:: A successful exploitation will provide authorization for a selected few services, or for all. Values: (ENUMERATED, ALL).
ENABLE_ELEVATED_ACCESS:: An exploit enables to get root access. Values: (TRUE, FALSE).

class cyst.api.logic.exploit.ExploitParameter(exploit_type: ExploitParameterType, value: str = '', immutable: bool = False)

Bases: ABC

A representation of exploit parameter.

Parameters:

exploit_type (ExploitParameterType) – A type of the exploit parameter. TODO: Rename to include parameter.
value (str) – A value of the exploit parameter.
immutable (bool) – An immutability of the exploit parameter.

abstract property type: ExploitParameterType

Returns a type of the exploit parameter.

Return type:: ExploitParameterType

abstract property value: str

Returns a value of the exploit parameter.

Return type:: str

abstractmethod set_value(val: str) → None

Sets the value of the parameter, provided it is mutable one.

Parameters:: val (str) – A new value.

class cyst.api.logic.exploit.VulnerableService

Bases: ABC

A specification of a service and its version that are vulnerable for the purpose of exploit description.

abstract property id: str

Returns the name of the service.

Return type:: str

abstract property min_version: Version

Returns the minimal affected version.

Return type:: VersionInfo

abstract property max_version: Version

Returns the maximal affected version.

Return type:: VersionInfo

class cyst.api.logic.exploit.Exploit

Bases: ABC

A description of a working exploit.

abstract property id: str

Returns the unique identification of the exploit.

Return type:: str

abstract property services: Dict[str, VulnerableService]

Returns the collection of services that are affected by this exploit.

Return type:: Dict[str, VulnerableService]:

abstract property locality: ExploitLocality

Returns the locality of the exploit.

Return type:: ExploitLocality

abstract property category: ExploitCategory

Returns the category of the exploit.

Return type:: ExploitCategory

abstract property parameters: Dict[ExploitParameterType, ExploitParameter]

Returns the collection of exploit parameters.

Return type:: Dict[ExploitParameterType, ExploitParameter]

cyst.api.logic.metadata

class cyst.api.logic.metadata.Event(id: str)

Bases: object

Event represents an identification of a phenomenon within a message. Typically it can be some alert from an IDS, which the mechanisms downstream can act upon.

Parameters:: id (str) – An identifier of the event.

class cyst.api.logic.metadata.TCPFlags(*args, **kwargs)

Bases: Flags

TCP protocol flags. Can be used separately or combined together by means of the OR operator. Example:

f1 = TCPFlags.R
f2 = TCPFlags.S | TCPFlags.A

Possible values:

S:: SYN
A:: ACK
R:: RESET
P:: PUSH
U:: UPDATE
F:: FIN

class cyst.api.logic.metadata.Protocol(*values)

Bases: Enum

A communication protocol used in the messages.

Possible values:

UDP:: UDP Protocol.
TCP:: TCP Protocol.
ICMP:: ICMP Protocol.

class cyst.api.logic.metadata.FlowDirection(*values)

Bases: Enum

Direction of the flow.

Possible values:

REQUEST:: The flow was create from a message of the request type.
RESPONSE:: The flow was created from a message of the response type.

class cyst.api.logic.metadata.Flow(id: str, direction: FlowDirection, packet_count: int, duration: int, flags: TCPFlags, protocol: Protocol)

Bases: object

Flow (in network terminology) represents an aggregation of packets. However, because the simulation engine is not modelling the communication at the packet level, but rather a flow-level, the flow describes one message. It adds statistical and L2/L3 layer information on top of abstract message description.

Parameters:

id (str) – Identifier of the flow. It is the same as the ID of the message it was created from. TODO: There is a discrepancy, as the message id is int. What the hell is the purpose of Flow id?
direction (FlowDirection) – A direction of the flow.
packet_count (int) – A number of packets aggregated into the flow.
duration (int) – A number of simulated time units it took for the flow to realize.
flags (TCPFlags) – A set of TCP flags.
protocol (Protocol) – A protocol type.

Bases: object

Metadata represents information that could be observed if one took a look at the packets that were exchanged between message source and destination. Metadata are supplied to messages by metadata providers. For more info see cyst.api.environment.metadata_provider.MetadataProvider. Because of the reliance on providers, not all metadata need to be specified.

Parameters:

src_ip (Optional[IPAddress]) – A source IP of the message. Does not necessarily have to be the same as message source IP, as the provider can put there anything it thinks is the source (e.g., seeing through the proxy or NAT).
dst_ip (Optional[IPAddress]) – A destination IP of the message. Does not necessarily have to be the same as message destination IP, as the provider can put there anything it thinks is the ultimate destination.
dst_service (Optional[str]) – A destination service of the message. Does not necessarily have to be the same as message destination service, as the provider can put there anything it thinks is the ultimate destination (e.g., final result of port knocking, understanding port forwarding).
event (Optional[str]) – A recognized event.
flows (Optional[List[Flow]]) – A list of flows associated with the message.