yawning_titan.networks.network#

Classes

`Network`	A Network that the NetworkInterface interacts with.
`NetworkLayout`	An enum class that maps to layout functions in networkx.drawing.layout.
`RandomEntryNodePreference`	Preference of hw the random entry nodes are placed.
`RandomHighValueNodePreference`	Preference of how the random high value nodes are placed.

yawning_titan.networks.network.choice(a, size=None, replace=True, p=None)#

Generates a random sample from a given 1-D array

New in version 1.7.0.

Note

New code should use the choice method of a default_rng() instance instead; please see the Quick Start.

Parameters:

a (1-D array-like or int) – If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if it were np.arange(a)
size (int or tuple of ints, optional) – Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
replace (boolean, optional) – Whether the sample is with or without replacement. Default is True, meaning that a value of a can be selected multiple times.
p (1-D array-like, optional) – The probabilities associated with each entry in a. If not given, the sample assumes a uniform distribution over all entries in a.

Returns:

samples – The generated random samples

Return type:

single item or ndarray

Raises:

ValueError – If a is an int and less than zero, if a or p are not 1-dimensional, if a is an array-like of size 0, if p is not a vector of probabilities, if a and p have different lengths, or if replace=False and the sample size is greater than the population size

See also

randint, shuffle, permutation

random.Generator.choice: which should be used in new code

Notes

Setting user-specified probabilities through p uses a more general but less efficient sampler than the default. The general sampler produces a different sample than the optimized sampler even if each element of p is 1 / len(a).

Sampling random rows from a 2-D array is not possible with this function, but is possible with Generator.choice through its axis keyword.

Examples

Generate a uniform random sample from np.arange(5) of size 3:

>>> np.random.choice(5, 3)
array([0, 3, 4]) # random
>>> #This is equivalent to np.random.randint(0,5,3)

Generate a non-uniform random sample from np.arange(5) of size 3:

>>> np.random.choice(5, 3, p=[0.1, 0, 0.3, 0.6, 0])
array([3, 3, 0]) # random

Generate a uniform random sample from np.arange(5) of size 3 without replacement:

>>> np.random.choice(5, 3, replace=False)
array([3,1,0]) # random
>>> #This is equivalent to np.random.permutation(np.arange(5))[:3]

Generate a non-uniform random sample from np.arange(5) of size 3 without replacement:

>>> np.random.choice(5, 3, replace=False, p=[0.1, 0, 0.3, 0.6, 0])
array([2, 3, 0]) # random

Any of the above can be repeated with an arbitrary array-like instead of just integers. For instance:

>>> aa_milne_arr = ['pooh', 'rabbit', 'piglet', 'Christopher']
>>> np.random.choice(aa_milne_arr, 5, p=[0.5, 0.1, 0.1, 0.3])
array(['pooh', 'pooh', 'pooh', 'Christopher', 'piglet'], # random
      dtype='<U11')

class yawning_titan.networks.network.NetworkLayout(value)[source]#

An enum class that maps to layout functions in networkx.drawing.layout.

See: https://networkx.org/documentation/stable/reference/drawing.html#module-networkx.drawing.layout

CIRCULAR = 'circular'#

KAMADA_KAWAI = 'kamada_kawai'#

PLANAR = 'planar'#

SHELL = 'shell'#

SPECTRAL = 'spectral'#

SPIRAL = 'spiral'#

SPRING = 'spring'#

as_layout_func()[source]#: Maps the NetworkLayout to a function in networkx.drawing.layout.

class yawning_titan.networks.network.RandomHighValueNodePreference(value)[source]#

Preference of how the random high value nodes are placed.

FURTHEST_AWAY_FROM_ENTRY = 'FURTHEST_AWAY_FROM_ENTRY'#: Prefer nodes furthest away from entry nodes.

NONE = 'NONE'#: No preference.

class yawning_titan.networks.network.RandomEntryNodePreference(value)[source]#

Preference of hw the random entry nodes are placed.

CENTRAL = 'CENTRAL'#: Prefer central nodes.

EDGE = 'EDGE'#: Prefer edge nodes.

NONE = 'NONE'#: No preference.

class yawning_titan.networks.network.Network(set_random_entry_nodes=False, random_entry_node_preference=RandomEntryNodePreference.NONE, num_of_random_entry_nodes=0, set_random_high_value_nodes=False, random_high_value_node_preference=RandomHighValueNodePreference.NONE, num_of_random_high_value_nodes=0, set_random_vulnerabilities=False, node_vulnerability_lower_bound=0.01, node_vulnerability_upper_bound=1, doc_metadata=None, **kwargs)[source]#

A Network that the NetworkInterface interacts with.

Network extends networkx.Graph.

Example

The Network constructor.

Parameters:

set_random_entry_nodes – Whether entry nodes are set at random if not set in nodes. Default value of False.
random_entry_node_preference – The random entry node placement preference as an instance of yawning_titan.networks.network.RandomEntryNodePreference. Default value of RandomEntryNodePreference.NONE.
num_of_random_entry_nodes – The number of random entry nodes that will be attempted to be set.
set_random_high_value_nodes – Whether high value nodes are set at random if not set in nodes. Default value of False.
random_high_value_node_preference – The random high value node placement preference as an instance of yawning_titan.networks.network.RandomHighValueNodePreference. Default value of RandomHighValueNodePreference.NONE.
num_of_random_high_value_nodes – The number of random high value nodes that will be attempted to be set.
set_random_vulnerabilities – Whether node vulnerability scores are set at random.
node_vulnerability_lower_bound – The lower-bound of a nodes vulnerability score. Default value of 0.01.
node_vulnerability_upper_bound – The upper-bound of a nodes vulnerability score. Default value of 0.01.

__init__(set_random_entry_nodes=False, random_entry_node_preference=RandomEntryNodePreference.NONE, num_of_random_entry_nodes=0, set_random_high_value_nodes=False, random_high_value_node_preference=RandomHighValueNodePreference.NONE, num_of_random_high_value_nodes=0, set_random_vulnerabilities=False, node_vulnerability_lower_bound=0.01, node_vulnerability_upper_bound=1, doc_metadata=None, **kwargs)[source]#

The Network constructor.

Parameters:

set_random_entry_nodes – Whether entry nodes are set at random if not set in nodes. Default value of False.
random_entry_node_preference – The random entry node placement preference as an instance of yawning_titan.networks.network.RandomEntryNodePreference. Default value of RandomEntryNodePreference.NONE.
num_of_random_entry_nodes – The number of random entry nodes that will be attempted to be set.
set_random_high_value_nodes – Whether high value nodes are set at random if not set in nodes. Default value of False.
random_high_value_node_preference – The random high value node placement preference as an instance of yawning_titan.networks.network.RandomHighValueNodePreference. Default value of RandomHighValueNodePreference.NONE.
num_of_random_high_value_nodes – The number of random high value nodes that will be attempted to be set.
set_random_vulnerabilities – Whether node vulnerability scores are set at random.
node_vulnerability_lower_bound – The lower-bound of a nodes vulnerability score. Default value of 0.01.
node_vulnerability_upper_bound – The upper-bound of a nodes vulnerability score. Default value of 0.01.

set_random_entry_nodes#: If no entry nodes are added, set them at random. Default is False.

random_entry_node_preference#: The type of random entry node preference.

num_of_random_entry_nodes#: The number of random entry nodes to be generated.

set_random_high_value_nodes#: If no high value nodes are added, set them at random. Default is False.

random_high_value_node_preference#: The type of random high value node preference.

num_of_random_high_value_nodes#: The number of random high_value nodes to be generated.

set_random_vulnerabilities#: If True, random vulnerability is set for each node using the upper and lower bounds.

node_vulnerability_upper_bound#: A higher vulnerability means that a node is more vulnerable. Default value is 1.

property high_value_nodes#: A list of the high value nodes in the network.

property entry_nodes#: A list of the entry nodes in the network.

property deceptive_nodes#: A list of the deceptive nodes in the network.

property num_possible_high_value_nodes#

Maximum number of allowed high value nodes in the network.

Number of possible high value nodes calculated by seeing how many nodes there are minus the entry nodes, then only having 15% of the nodes left over to be high value nodes.

property node_vulnerability_lower_bound#: A lower vulnerability means that a node is less likely to be compromised. Default value is 0.

property doc_metadata#: The configs document metadata.

add_node(node_for_adding, **kwargs)[source]#

Add a node to the network.

Extend the add_node method of the superclass.

if the node_for_adding is a special node then check that there are no intersections between hvn and entry_node’s.

remove_node(n)[source]#

Remove a node from the network.

Extend the remove_node method of the superclass.

add_edge(u_of_edge, v_of_edge, **kwargs)[source]#

Add an edge between 2 nodes in the network.

Extend the add_edge method of the superclass.

remove_edge(u, v)[source]#

Remove an edge between 2 nodes in the network.

Extend the remove_edge method of the superclass.

reset()[source]#

Resets the network.

This is done by calling:

reset_random_entry_nodes()
reset_random_high_value_nodes
reset_random_vulnerabilities()

show(verbose=False)[source]#

Show details of all Nodes in the Network.

Parameters:: verbose – If True, all Node attributes are shown, otherwise just the uuid is shown.

get_nodes(filter_true_compromised=False, filter_blue_view_compromised=False, filter_true_safe=False, filter_blue_view_safe=False, filter_isolated=False, filter_non_isolated=False, filter_deceptive=False, filter_non_deceptive=False, key_by_name=False, as_list=False)[source]#

Get all of the nodes from the network and apply a filter(s) to extract a specific subset of the nodes.

Parameters:

filter_true_compromised – Filter so only nodes that are compromised remain
filter_blue_view_compromised – Filter so only nodes that blue can see are compromised remain
filter_true_safe – Filter so only nodes that are safe remain
filter_blue_view_safe – Filter so only nodes that blue can see are safe remain
filter_isolated – Filter so only isolated nodes remain
filter_non_isolated – Filter so only connected nodes remain
filter_deceptive – Filter so only deceptive nodes remain
filter_non_deceptive – Filter so only non-deceptive nodes remain

Returns:

A list of nodes

get_node_from_uuid(uuid)[source]#: Return the first node that has a given uuid.

get_node_from_name(name)[source]#: Return the first node that has a given name.

set_from_dict(config_dict, remove_existing_edges=False, remove_existing_nodes=False, clear_special_nodes=True)[source]#

Set the values of existing network attributes from those contained in a dictionary.

Parameters:

config_dict – A dictionary of network attribute name value pairs
remove_existing_edges – Whether to remove existing edges
remove_existing_nodes – Whether to remove existing nodes

clear_special_nodes()[source]#: Remove all special node designations.

set_node_positions(network_layout=NetworkLayout.SPRING)[source]#

Sets the Node positions of the current Network.

Parameters:: network_layout – A member of NetworkLayout. Default is NetworkLayout.SPRING.

add_nodes_from_dict(nodes_dict, remove_existing=False)[source]#

Add nodes to the graph with properties defined from a dictionary.

Parameters:

nodes_dict – a dictionary of node uuids to properties
remove_existing – a boolean to indicate whether to remove existing nodes

add_edges_from_dict(edges_dict, remove_existing=False)[source]#

Add edges to the graph with properties defined from a dictionary.

Parameters:

edges_dict – a dictionary of edge uuids to properties
remove_existing – a boolean to indicate whether to remove existing edges

reset_random_entry_nodes()[source]#

Set the entry nodes.

If no entry nodes supplied then the first node in the network is chosen as the initial node.

reset_random_high_value_nodes()[source]#

Sets up the high value nodes (HVNs) to be used by the training environment.

If HVNs are supplied in the Network, they are used. However, if they are not supplied, the following logic is applied:

If game_mode.game_rules.lose_when_high_value_node_lost is True:
An acceptable amount (math.ceil((len(current_graph.nodes) - len(entry_nodes) + 1) * 0.15) of HVNs are defined from a list of potential HVSn at random after steps are taken to ensure that HVNs are not entry nodes.

Otherwise:
HVNs are set to an empty list.

reset_random_vulnerabilities()[source]#: Regenerate random vulnerabilities for every node in the network.

to_dict(json_serializable=False)[source]#: Represent the Network as a dictionary.

to_adj_matrix_and_positions()[source]#: Represent the network by its adjacency matrix and a dictionary of node names to positions.

classmethod create(network_dict)[source]#

Create an instance on :class: Network from a dictionary.

Parameters:: network_dict – a dictionary describing a Network
Returns:: An instance of :class: Network.