yawning_titan.envs.generic.core.network_interface.NetworkInterface

class yawning_titan.envs.generic.core.network_interface.NetworkInterface(game_mode, network)

Bases: object

The primary interface between both red and blue agents and the underlying environment.

Initialise the Network Interface and initialises all the necessary components.

Parameters:

• game_mode – the GameMode that defines the abilities of the agents.

• network – the Network that defines the network within which the agents act.

Methods

add_deceptive_node	Add a deceptive node into the network.
attack_node	Attack a target node.
create_json_time_step	Create a dictionary that contains the current state of the environment and returns it.
get_all_isolation	Get a dictionary of the isolation status of all the nodes.
get_all_node_blue_view_compromised_states	Get a dictionary of compromised states.
get_all_node_compromised_states	Get a dictionary of compromised states.
get_all_node_positions	Get a dictionary of node positions.
get_all_vulnerabilities	Get a dictionary of vulnerability scores.
get_attributes_from_key	Take in a key and return a dictionary.
get_base_connected_nodes	Get all of the nodes connected to the given node in the base graph.
get_current_connected_nodes	Get all of the nodes currently connected to a target node.
get_current_graph_as_dict	Get the current networkx graph for the environment and convert it to a dict of dicts.
get_current_observation	Get the current observation of the environment.
get_midpoint	Get the midpoint between the position of two nodes.
get_number_unused_deceptive_nodes	Get the current number of unused deceptive nodes.
get_observation_size	Use base observation size calculator with feather switched off.
get_observation_size_base	Get the size of the observation space.
get_shortest_distances_to_target	Get a list of the shortest distances from each node to the target.
get_target_node	Get the node which is being targeted in the config.
get_total_num_nodes	Get the total number of nodes including any yet to be placed deceptive nodes.
initialise_deceptive_nodes	Create a separate list of :class: ~yawning_titan.networks.node.Node objects take represent deceptive nodes.
initialise_edge_map	Create a lookup that maps a unique integer key to an networkx edge (node pair).
isolate_node	Isolate a node (disable all of the nodes connections).
make_node_safe	Make the state for a given node safe.
reconnect_node	Re-enable any connections that may have previously been disabled.
reset	Reset the network back to its default state.
reset_stored_attacks	Reset the attacks list.
save_json	Save a given dictionary to a json file.
scan_node	Scan a target node to determine compromise based on the chance of discovery of compromise.
update_stored_attacks	Update this turns current attacks.

get_shortest_distances_to_target(nodes)

Get a list of the shortest distances from each node to the target.

get_target_node()

Get the node which is being targeted in the config.

Returns:

The target node if it exists

get_total_num_nodes()

Get the total number of nodes including any yet to be placed deceptive nodes.

Returns:

The number of nodes that there are including deceptive nodes that may not have been placed yet

get_midpoint(node1, node2)

Get the midpoint between the position of two nodes.

Parameters:

• node1 – the name of the first node to get the midpoint from

• node2 – the name of the second node to get the midpoint from

Returns:

The x and y coordinates of the midpoint between two nodes

get_current_connected_nodes(node)

Get all of the nodes currently connected to a target node.

Parameters:

node – The name of the node to get the current connections of

Returns:

A list of nodes

get_base_connected_nodes(node)

Get all of the nodes connected to the given node in the base graph.

Parameters:

node – The name of the node to get the current connections of

Returns:

A list of nodes

get_current_graph_as_dict()

Get the current networkx graph for the environment and convert it to a dict of dicts.

Returns:

The networkx graph as a dict of dicts

get_attributes_from_key(key, key_by_uuid=True)

Take in a key and return a dictionary.

The keys are the names of the nodes and the values are the attribute values that are stored for that node under the specified key

Parameters:

• key – The name of the attribute to extract

• key_by_uuid – Use the nodes uuid attribute as the key if True otherwise use the node object itself.

Returns:

A dictionary of attributes

get_all_vulnerabilities()

Get a dictionary of vulnerability scores.

get_all_isolation()

Get a dictionary of the isolation status of all the nodes.

get_all_node_compromised_states()

Get a dictionary of compromised states.

get_all_node_blue_view_compromised_states()

Get a dictionary of compromised states.

get_all_node_positions()

Get a dictionary of node positions.

get_number_unused_deceptive_nodes()

Get the current number of unused deceptive nodes.

get_current_observation()

Get the current observation of the environment.

The composition of the observation space is based on the configuration file used for the scenario.

Returns:

numpy array containing the above details

get_observation_size_base(with_feather)

Get the size of the observation space.

This is based on the game_mode that are turned on/off.

Returns:

The size of the observation space

get_observation_size()

Use base observation size calculator with feather switched off.

initialise_deceptive_nodes()

Create a separate list of :class: ~yawning_titan.networks.node.Node objects take represent deceptive nodes.

initialise_edge_map()

Create a lookup that maps a unique integer key to an networkx edge (node pair).

update_stored_attacks(attacking_nodes, target_nodes, success)

Update this turns current attacks.

This function collects all of the failed attacks and stores them for the blue agent to use in their action decision

Parameters:

• attacking_nodes – Nodes red has attacked from

• target_nodes – Nodes red is attacking

• success – If the attacks were a success or not

reset_stored_attacks()

Reset the attacks list.

This needs to be called every timestep to ensure that only the current attacks are contained.

reset()

Reset the network back to its default state.

add_deceptive_node(node1, node2)

Add a deceptive node into the network.

The deceptive node will sit between two actual nodes and act as a normal node in all regards other than the fact that it give more information when it is attacked

Parameters:

• node1 – Name of the first node to connect to the deceptive node

• node2 – Name of the second to connect to the deceptive node

Returns:

False if failed, the name of the new node if succeeded

isolate_node(node)

Isolate a node (disable all of the nodes connections).

Parameters:

node – the node to disable the connections of

reconnect_node(node)

Re-enable any connections that may have previously been disabled.

Parameters:

node – the node to re-enable

attack_node(node, skill=0.5, use_skill=False, use_vulnerability=False, guarantee=False)

Attack a target node.

Uses a random chance to succeed that is modified by the skill of the attack and the vulnerability of the node. Both the skill and the vulnerability can be toggled to either be used or not

Parameters:

• node – The name of the node to target

• skill – The skill of the attacker

• use_skill – A boolean value that is used to determine if skill is used in the calculation to check if the attack succeeds

• use_vulnerability – A boolean value that is used to determine if vulnerability is used in the calculation to check if the attack succeeds

• guarantee – If True then attack automatically succeeds

Returns:

A boolean value that represents if the attack succeeded or not

make_node_safe(node)

Make the state for a given node safe.

Parameters:

node – the node to make safe

scan_node(node)

Scan a target node to determine compromise based on the chance of discovery of compromise.

Parameters:

node – The node to be scanned

save_json(data_dict, ts)

Save a given dictionary to a json file.

Parameters:

• data_dict – Data to save to the json file

• ts – The current timestamp of the data

create_json_time_step()

Create a dictionary that contains the current state of the environment and returns it.

Returns:

A dictionary containing the node connections, states and vulnerability scores