cyst.api.network.elements

class cyst.api.network.elements.Route(net: ~netaddr.ip.IPNetwork, port: int, metric: int = 100, id: str = <factory>)

Bases: object

A route specifies which port should the traffic to specific network be routed through. Many routes can be specified for a node. If there is an overlap in network specification, than the resulting port is selected according to the route metrics (i.e., the lower the metric the higher the chance to be selected as the route). In case of a metric equality, the most specific network is selected.

Parameters:

• net (IPNetwork) – A network this route is related to.

• port (int) – A port/interface index, where to route traffic to the particular network.

• metric (int) – A route metric used for deciding which route to use in case of network overlap.

• id (str) – A unique identifier of the route. You very likely don’t need to set it and just let it autogenerate.

class cyst.api.network.elements.Port

Bases: ABC

A network port represents an abstraction of an ethernet port, with a given IP address and a given network. A network port does not support a default routing through a gateway and so it is used mostly for routers, which maintain their own routing tables based on the port indexes.

abstract property ip: IPAddress | None

Returns the IP address of the port.

Return type:

Optional[IPAddress]

abstract property mask: str | None

Returns the network mask of the port.

Return type:

Optional[str]

abstract property net: IPNetwork | None

Returns the network of the port.

Return type:

Optional[IPNetwork]

abstract property connection: Connection | None

Returns the connection of the port.

class cyst.api.network.elements.Interface

Bases: Port, ABC

A network interface represents an abstraction of an ethernet port, with a given IP address and a given network. The network interface automatically calculates the gateway and therefore enables a seamless networking.

abstract property gateway: IPAddress | None

Returns the IP address of the gateway.

Return type:

Optional[IPAddress]

class cyst.api.network.elements.Connection

Bases: ABC

Represents a connection between two network ports/interfaces. Connection supports setting of connection properties, such as delay or packet drops.

abstract property delay: int

Returns the delay of the connection in simulated time units.

Return type:

int

abstract property blocked: bool

Returns whether the connection is blocked or not.

Return type:

bool

abstract set_params(delay: int | None = None, blocked: bool | None = None) → None

Sets the connection parameters, such as delay and blocked.

Parameters:

• delay (int) – The delay of the connection in simulated time units.

• blocked (bool) – Whether the connection is blocked or not.

abstract evaluate(message: Message) → Tuple[int, Message]

Evaluates the message based on the connection properties. The properties are checked in this order:

1. The message is dropped: new response is formed from the message and delay is set to -1

2. The message is delayed: the original message is returned alongside connections’s delay

3. The message is passed through: the original message is returned alongside 0 delay

Parameters:

message (Message) – A message to evaluate.

Returns:

A tuple of delay and message.

cyst.api.network.firewall

class cyst.api.network.firewall.FirewallPolicy(value)

Bases: Enum

Represents a firewall policy, which dictates how network traffic is handled.

Possible values:

ALLOW:

The traffic is allowed to pass.

DENY:

The traffic is dropped.

class cyst.api.network.firewall.FirewallRule(src_net: IPNetwork, dst_net: IPNetwork, service: str, policy: FirewallPolicy)

Bases: object

Represents a firewall rule, which applies a firewall policy based on source and destination.

Parameters:

• src_net (IPNetwork) – A source network of a traffic.

• dst_net (IPNetwork) – A destination network of a traffic.

• service (str) – A name of the destination service.

• policy (FirewallPolicy) – A policy that should be applied.

class cyst.api.network.firewall.FirewallChainType(value)

Bases: Enum

A firewall chain represents a set of rules that are applied to a network traffic. The type depends on the direction of the traffic.

Possible values:

INPUT:

The traffic originates at the same node as the firewall.

OUTPUT:

The traffic is destined to the same node as the firewall.

FORWARD:

The traffic is passing through the same node as the firewall.

class cyst.api.network.firewall.Firewall

Bases: ABC

Firewall is represented as a collection of chains, with a default policy that is applied, unless specified otherwise.

abstract list_rules(chain: FirewallChainType | None = None) → List[Tuple[FirewallChainType, FirewallPolicy, List[FirewallRule]]]

List rules registered in the firewall.

Parameters:

chain (Optional[FirewallChainType]) – If specified, lists only rules associated with the given chain.

Returns:

A collection of rules with associated chain and the default policy.

abstract add_local_ip(ip: IPAddress) → None

Add an IP address that is considered local for the purpose of determining the chain of processed traffic.

Parameters:

ip (IPAddress) – The IP address to add.

abstract remove_local_ip(ip: IPAddress) → None

Remove an IP address that is considered local for the purpose of determining the chain of processed traffic.

Parameters:

ip (IPAddress) – The IP address to remove.

abstract add_rule(chain: FirewallChainType, rule: FirewallRule) → None

Adds a rule to a given chain.

Parameters:

• chain (FirewallChainType) – The chain to apply the rule to.

• rule (FirewallRule) – The rule to add.

abstract remove_rule(chain: FirewallChainType, index: int) → None

Removes a rule from a given chain.

Parameters:

• chain (FirewallChainType) – The chain to remove the rule from.

• index (int) – An index of the rule within the chain.

abstract set_default_policy(chain: FirewallChainType, policy: FirewallPolicy) → None

Sets a default policy for a given chain.

Parameters:

• chain (FirewallChainType) – The chain to set default policy at.

• policy (FirewallPolicy) – The default policy to set.

abstract get_default_policy(chain: FirewallChainType) → FirewallPolicy

Gets the default policy for a given chain.

Parameters:

chain (FirewallChainType) – The chain to get the policy from.

Returns:

The default policy.

abstract evaluate(src_ip: IPAddress, dst_ip: IPAddress, dst_service: str) → Tuple[bool, int]

Evaluates, whether a traffic with given source and destination will pass through or not, according to the rules.

Parameters:

• src_ip (IPAddress) – The source IP of the traffic.

• dst_ip (IPAddress) – The destination IP of the traffic.

• dst_service (str) – The destination service of the traffic.

Returns:

A tuple indicating if the traffic should pass and how long the processing took.

cyst.api.network.node

class cyst.api.network.node.Node

Bases: ABC

A network node is a main building block of simulation topology. It is modelled as a collection of services and a set of network interfaces.

abstract property type: str

Returns the type of the node. Currently, only two types are supported - “node” and “router”.

Return type:

str

abstract property services: Dict[str, Service]

Returns a collection of service instances, which are present at the node.

Return type:

Dict[str, Service]

abstract property shell: Service | None

Returns a designated shell service (if there is one).

Return type:

Optional[Service]

abstract property interfaces: List[Interface]

Returns network interfaces of the node.

Return type:

List[Interface]

abstract property ips: List[IPAddress]

Returns a list of IP addresses, which are set across all interfaces of the node.

Return type:

List[IPAddress]

abstract gateway(ip: str | IPAddress = '') → Tuple[IPAddress, int] | None

Calculates, which gateway would be used by the node, if a message was sent to a given destination IP address. The gateway is selected according to the routing rules.

Parameters:

ip (Union[str, IPAddress]) – The destination IP address.

Returns:

A gateway IP address together with port index (if one is found).

Return type:

Optional[Tuple[IPAddress, int]]

cyst.api.network.session

class cyst.api.network.session.Session

Bases: ABC

A session represents a virtual connection between two nodes in the infrastructure. The session ignores the routing limitations imposed by router configuration.

abstract property owner: str

Returns the owner of the session. This method is being slowly phased away.

Return type:

str

abstract property id: str

Returns a unique identifier of the session.

Return type:

str

abstract property parent: Session | None

Returns the parent session of this session (if there is one). Sessions can be chained together and a message traverses this chain sequentially.

Return type:

Optional[Session]

abstract property path: List[Tuple[IPAddress | None, IPAddress | None]]

Returns a path trough the infrastructure, on which the session lies. The path is modelled as a set of “hops”, i.e., tuples of IP addresses representing a source and destination of one connection. Note that a destination of preceding hop does not have to be the same as the source of the next hop. These can often differ, especially when a session is crossing between different networks.

Return type:

List[Tuple[Optional[IPAddress], Optional[IPAddress]]]

abstract property end: Tuple[IPAddress, str]

Returns the ultimate destination of the session. The result includes both the IP address of the node, and the service the session is linked to.

Return type:

Tuple[IPAddress, str]

abstract property start: Tuple[IPAddress, str]

Returns the start of the session. If the session has a parent, then a start of the parent is returned. The result includes both the IP address of the node, and the service the session is linked to.

Return type:

Tuple[IPAddress, str]

abstract property enabled: bool

Returns whether the session is enabled. Messages can’t be send in disabled sessions.

Return type:

bool