cyst.api.configuration.network

Provides configuration mechanisms to control creation of network topology and setting up networking. This includes:

Basic networking building blocks (cyst.api.configuration.network.elements)
Configuration of nodes within network (cyst.api.configuration.network.node)
Configuration of firewalls (cyst.api.configuration.network.firewall)
Configuration of routers (cyst.api.configuration.network.router)
Whole network configuration (cyst.api.configuration.network.network)

cyst.api.configuration.network.elements

class cyst.api.configuration.network.elements.PortConfig(ip: ~netaddr.ip.IPAddress, net: ~netaddr.ip.IPNetwork, index: int = -1, ref: str = <factory>, name: str = '__port', id: str = '')

Bases: ConfigItem

Configuration of a network port.

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.

Parameters:

ip (IPAddress) – The assigned IP address of the port.
net (IPNetwork) – The assigned network of the port. If used only for inter-router communication, ip/32 or ip/128 can be used.
index (int) – The index of the port. The index is used for unique addressing of a port within a node, especially for correctly setting routing tables. If left at the default value, it is assigned the next free index.

class cyst.api.configuration.network.elements.InterfaceConfig(ip: ~netaddr.ip.IPAddress, net: ~netaddr.ip.IPNetwork, index: int = -1, ref: str = <factory>, name: str = '__interface', id: str = '')

Bases: ConfigItem

Configuration of a network interface.

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

Parameters:

ip (IPAddress) – The assigned IP address of the interface.
net (IPNetwork) – The assigned network of the interface.
index (int) – The index of the interface. The index is used for unique addressing of an interface within a node. If left at the default value, it is assigned the next free index.

class cyst.api.configuration.network.elements.ConnectionConfig(src_ref: ~cyst.api.configuration.configuration.ConfigItem | str, src_port: int, dst_ref: ~cyst.api.configuration.configuration.ConfigItem | str, dst_port: int, ref: str = <factory>, name: str = '__connection', id: str = '')

Bases: ConfigItem

Configuration of a network connection.

Represents a connection between two network ports/interfaces. A connection will in future support setting of connection properties, such as delay or packet drops. While the supporting infrastructure is partially present in the code now, it is not propagated into the configuration a so, each connection has a unit speed (in terms of the simulation time) with zero drops.

Parameters:

src_ref (ConfigItem | str) – Connection source configuration or its ref.
src_port (int) – The index of a source port/interface.
dst_ref (ConfigItem | str) – Connection destination configuration or its ref.
dst_port (int) – The index of a destination port/interface.

class cyst.api.configuration.network.elements.RouteConfig(network: ~netaddr.ip.IPNetwork, port: int, metric: int = 100, ref: str = <factory>, name: str = '__route', id: str = '')

Bases: ConfigItem

Configuration of a network route.

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:

network (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.

class cyst.api.configuration.network.elements.SessionConfig(src_service: str, dst_service: str, waypoints: ~typing.List[str], reverse: bool = False, ref: str = <factory>, name: str = '__session', id: str = '')

Bases: ConfigItem

Configuration of a session.

A session represents a virtual connection between two endpoint services that is ignoring the routing limitations imposed by routers and firewalls en route.

Parameters:

src_service (str) – A service that the session originates from.
dst_service (str) – A service that the session terminates at.
waypoints (List[str]) – A list of node IDs through which the session is established.
reverse (bool) – The direction of construction of the session. If reverse is set, then session is originating from the destination service. This can matter, because the session creation should honor the router configuration and the reverse shell can be the only one that can be established. But, for example, the CYST simulation engine tries to construct the session in both ways to see if anything works, so this parameter may be inconsequential.

cyst.api.configuration.network.node

class cyst.api.configuration.network.node.NodeConfig(active_services: ~typing.List[~cyst.api.configuration.host.service.ActiveServiceConfig | str], passive_services: ~typing.List[~cyst.api.configuration.host.service.PassiveServiceConfig | str], traffic_processors: ~typing.List[~cyst.api.configuration.network.firewall.FirewallConfig | ~cyst.api.configuration.host.service.ActiveServiceConfig | str], shell: str, interfaces: ~typing.List[~cyst.api.configuration.network.elements.InterfaceConfig | str], ref: str = <factory>, name: str = '__node', id: str = '')

Bases: ConfigItem

Configuration for a network node

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.

Parameters:

active_services (List[Union[ActiveServiceConfig, str]]) – A list of active services running on the node.
passive_services (List[Union[PassiveServiceConfig, str]]) – A list of passive services running on the node.
traffic_processors (Optional[List[Union[FirewallConfig, ActiveServiceConfig, str]]]) – A list of either active services that are acting as traffic processors, or at most one firewall.
shell (str) – A name of a passive service that is designated as a shell. Properties of the shell service determine the impact of some exploits, e.g., when related to access rights. Technically, any name could be selected as a shell, because the system currently does not check whether the service exists or not.
interfaces (List[Union[InterfaceConfig, str]]) – A list of interfaces on the node.

cyst.api.configuration.network.firewall

TODO: Firewall configuration should be moved into host configuration

class cyst.api.configuration.network.firewall.FirewallChainConfig(type: ~cyst.api.network.firewall.FirewallChainType, policy: ~cyst.api.network.firewall.FirewallPolicy, rules: ~typing.List[~cyst.api.network.firewall.FirewallRule], ref: str = <factory>, name: str = '__firewall_chain', id: str = '')

Bases: ConfigItem

Configuration of firewall chain.

A firewall chain represents a set of rules that are applied to a network traffic.

Parameters:

type (FirewallChainType) – A type of traffic this chain applies to.
policy (FirewallPolicy) – A default policy applied to a traffic, which does not satisfy any rule.
rules (List[FirewallRule]) – A set of rules governing what happens with a network traffic.

class cyst.api.configuration.network.firewall.FirewallConfig(default_policy: ~cyst.api.network.firewall.FirewallPolicy, chains: ~typing.List[~cyst.api.configuration.network.firewall.FirewallChainConfig], ref: str = <factory>, name: str = '__firewall', id: str = '')

Bases: ConfigItem

Configuration of a firewall.

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

Parameters:

default_policy (FirewallPolicy) – A default policy applied to a traffic, which is not handled by a chain with its own policy.
chains (List[FirewallChainConfig]) – A list of firewall chain configurations.

cyst.api.configuration.network.router

class cyst.api.configuration.network.router.RouterConfig(interfaces: ~typing.List[~cyst.api.configuration.network.elements.InterfaceConfig | str], traffic_processors: ~typing.List[~cyst.api.configuration.network.firewall.FirewallConfig | ~cyst.api.configuration.host.service.ActiveServiceConfig | str], routing_table: ~typing.List[~cyst.api.configuration.network.elements.RouteConfig] = <factory>, ref: str = <factory>, name: str = '__router', id: str = '')

Bases: ConfigItem

Configuration of a network router

Router models an active network device that forwards messages over the network according to rules. At the conceptual level it conflates the concept of switch and router to one device.

Currently, a router is implemented as a special type of node, with distinct code paths, in the future it is expected that a router would be implemented as an active service on a node. This will enable better logical separation between its routing, firewalling, and IDS/IPS activities. It will also be more fit for SDN modelling.

Parameters:

interfaces (List[Union[InterfaceConfig, str]]) – A list of network interfaces.
traffic_processors (Optional[List[Union[FirewallConfig, ActiveServiceConfig, str]]]) – A list of either active services that are acting as traffic processors, or at most one firewall. Firewall is used as a mechanism for router to do inter-network routing, by means of a FORWARD chain.
routing_table (List[RouteConfig]) – A routing configuration for inter-router communication. Routing to end devices is arranged automatically when creating connections between end devices and the router. Networks are inferred from interface configurations.
firewall (Optional[FirewallConfig]) – A configuration of firewall rules.

cyst.api.configuration.network.network

class cyst.api.configuration.network.network.NetworkConfig(nodes: ~typing.List[~cyst.api.configuration.network.node.NodeConfig | ~cyst.api.configuration.network.router.RouterConfig | str], connections: ~typing.List[~cyst.api.configuration.network.elements.ConnectionConfig | str], ref: str = <factory>, name: str = '__network', id: str = '')

Bases: ConfigItem

Configuration of a network.

A network is a collection of nodes linked by connections. The configuration enables creation of unconnected subnets, but to make any use of it, there needs to be added a set of actions, which enable setting up/tearing down of connections.

Parameters:

nodes (List[Union[NodeConfig, RouterConfig, str]]) – A collection of nodes and routers that constitute the vertices of network topology.
connections (List[Union[ConnectionConfig, str]]) – A collection of connections that constitute the edges of network topology.