State

Bases: CybORGLogger

Simulates the Network State.

This class contains all the data for the simulated network, including ips, subnets, hosts and sessions. The methods mostly modify the network state, but tend to delegate most of the work to the Host class.

Attributes:

Name	Type	Description
np_random	numpy.random._generator.Generator	Used to resolve all random events inside CybORG.
scenario	Scenario	Object used to create initial State from Scenario Object.
subnet_name_to_cidr	Dict[str, IPv4Network]	Dictionary mapping subnet name to matching cidr address.
ip_addresses	Dict[IPv4Address, str]	Dictionary mapping ip address to corresponding hostname.
hostname_ip_map	Dict[str, IPv4Address]	Dictionary mapping hostname to corresponding ip address.
hostname_subnet_map	Dict[str, SUBNET]	Dictionary mapping hostname to corresponding subnet Enum object.
hosts	Dict[str, Host]	Dictionary mapping hostname to matching Host object.
sessions	Dict[str, Dict[int, Session]]	Dictionary mapping agent name to dictionary containing its corresponding sessions. Sessions objects are indexed by session ids, which are integers.
subnets	Dict[IPv4Network, Subnet]	Dictionary mapping ip address to corresponding subnet.
link_diagram	networkx.classes.graph.Graph	NetworkX graph representing which hosts can directly communicate with each other. Used for routing actions between hosts.
connected_components	List[Set[str]]	List of sets of hostnames representing hosts that are all connected together. Used to identify which hosts have no route between them.
sessions_count	Dict[str, int]	Dictionary mapping agent name to the number of sessions it controls across the network.
mission_phase	int	Integer representing the current mission phase.
original_time	datetime.datetime	Time fixed at Jan 1 2020. Unused, but intended to timestamp backup of Restored host.
time	datetime.datetime	Simulated current time. Unused, but intended for timestamping purposes.
operational_firewall	bool	Boolean represeting whether the Operational Server in Scenario 2 has a firewall protecting it. Unused in later scenarios.
blocks	Dict[str:List[str]]	Dictionary mapping hostames to a list of hostnames they will block actions from.

Functions

__init__

__init__(scenario: Scenario, np_random: RandomNumberGenerator)

Instantiates State class.

Parameters:

Name	Type	Description	Default
scenario	Scenario	Object used to create initial State from Scenario Object.	required
np_random	RandomNumberGenerator	Used to resolve all random events inside CybORG.	required

add_file

add_file(host: str, name: str, path: str, user: str = None, user_permissions: str = None, group: str = None, group_permissions: int = None, default_permissions: int = None)

Adds a file to the specified host.

This is based on Linux file permissions.

Parameters:

Name	Type	Description	Default
host	str	The name of the host to add the file to.	required
name	str	The name of the file to add.	required
path	str	The path of the file on the target host.	required
user	str	The user who owns the file.	None
user_permissions	str	The file permissions of the file owner.	None
group	str	The group the file belongs to.	None
group_permissions	int	The file permissions of the file group.	None
default_permissions	int	The file permissions for default users.	None

Returns:

Name	Type	Description
file	File	The file to be added to the host.

add_session

add_session(session: Session)

Adds a session to the specified host.

Sessions with usernames 'root' or 'SYSTEM' are considered privileged. If process is none then a PID will be created randomly. If the session is a sandbox, then the PrivilegeEscalate action will not work on this host. Created only when exploiting an deceptive service.

add_user

add_user(host: str = None, username: str = None, password: str = None, password_hash_type: str = None)

Adds a user to the specified host.

Parameters:

Name	Type	Description	Default
host	str	The name of the host having the user added.	None
username	str	The name of the user to be added.	None
password	str	The password of the user to be added.	None
password_hash_type	str	The hashing algorithm to be used on the password.	None

Returns:

Name	Type	Description
user	User	The user to be added to the host.

check_next_phase_on_update_step

check_next_phase_on_update_step(step: int)

Updates the State step count and mission phase number.

Parameters:

Name	Type	Description	Default
step	int	The current step count	required

Returns:

Name	Type	Description
change	bool	True if mission phased changed otherwise False

dist staticmethod

dist(pos_a: float, pos_b: float)

Computes the Eulcidian distance between two points.

Intended for use with DroneSwarmScenarioGenerator to compute distance between drones.

Parameters:

Name	Type	Description	Default
pos_a	float	Position of first drone.	required
pos_b	float	Position of second drone.	required

Returns:

Name	Type	Description
distance	int	The distance between the two points provided.

get_session_from_pid

get_session_from_pid(hostname: str, pid: int)

Searches the target host for a session with the specified PID.

Returns None, None if not found.

Parameters:

Name	Type	Description	Default
hostname	str	The name of the host to search.	required
pid	int	The process id to search for.	required

Returns:

Name	Type	Description
agent	str	Name of the agent owning the found session.
session_index	int	The Session id of the found session.

get_subnet_containing_ip_address

get_subnet_containing_ip_address(ip_address: IPv4Address) -> Subnet

Returns the subnet containing the specified ip address.

Parameters:

Name	Type	Description	Default
ip_address	IPv4Address	The ip address to find the subnet for.	required

Returns:

Name	Type	Description
subnet	Subnet	The subnet containing the specified ip address.

get_true_state

get_true_state(info: dict) -> Observation

Create's a dictionary containing the requested information from the state.

Intended to be used for debugging and evaluation purposes. Agents should not have visibility of the unfiltered state. Info dictionary should have hostnames as keys. Each host is passed a dictionary whose keys define the subcomponents to pull out and whose values specify which attributes. For example: {'HostnameA': {'Interfaces':'ip_address','Services':'Femitter'}, 'HostnameB': {'Interfaces':'All', 'Files': 'All', 'Sessions':'All'}, 'HostnameC': {'User info': 'All', 'System info': 'All'} }

Parameters:

Name	Type	Description	Default
info	dict	Dictionary used to filter out information.	required

Returns:

Name	Type	Description
true_obs	dict	Dictionary containing the requested information from the state.

reboot_host

reboot_host(hostname)

Unused. Used by deprecated action.

remove_process

remove_process(hostname: str, pid: int)

Removes a process from the specified host.

Parameters:

Name	Type	Description	Default
hostname	str	The name of the host having the process removed.	required
pid	int	The process id of the process to be removed.	required

set_np_random

set_np_random(np_random)

Sets up the np_random object at the beginning of the scenario.

Parameters:

Name	Type	Description	Default
np_random		The random number genetator to resolve CybORG's internal events.	required

start_service

start_service(hostname: str, service_name: str)

Starts the target service on the specified host.

Parameters:

Name	Type	Description	Default
hostname	str	The name of the host to start the service on.	required
service_name	str	The name of the service to start.	required

stop_service

stop_service(hostname: str, service_name: str)

Stops the target service on the specified host.

Parameters:

Name	Type	Description	Default
hostname	str	The name of the host to stop the service on.	required
service_name	str	The name of the service to stop.	required

update_data_links

update_data_links()

Updates the links between drones.

Intended for use with DroneSwarmScenarioGenerator. Drones which are too far apart will have their data links dropped. Drones that come into range will establish datalinks.