CybORG.CybORG

Bases: CybORGLogger

The main interface for the Cyber Operations Research Gym.

The primary purpose of this class is to provide a unified interface for the CybORG simulation and emulation environments. The user chooses which of these modes to run when instantiating the class and CybORG initialises the appropriate environment controller.

This class also provides the external facing API for reinforcement learning agents, before passing these commands to the environment controller. The API is intended to closely resemble that of OpenAI Gym, but is also inspired by PettingZoo for MultiAgent aspects.

Attributes:

Name	Type	Description
scenario_generator	ScenarioGenerator	ScenarioGenerator object that creates scenarios.
environment	str	The environment to use. CybORG currently only supports 'sim' (default='sim').
env_config	dict	Configuration keyword arguments for environment controller (See relevant Controller class for details), (default=None).
agents	dict	Defines the agent that selects the default action to be performed if the external agent does not pick an action If None agents will be loaded from description in scenario file (default=None).

Attributes

active_agents property

active_agents: list

Returns all active agents.

An active agent must have an active shell.

Returns:

Name	Type	Description
agents	List[str]	List of names of all active agents.

agents property

agents: list

Returns all external-facing agents.

Returns:

Name	Type	Description
Agents	List[str]	List of names of all external-facing agents.

unwrapped property

unwrapped

Returns CybORG without any wrappers.

Returns:

Name	Type	Description
cyborg	CybORG	The CybORG main class.

Functions

__init__

__init__(scenario_generator: ScenarioGenerator, agents: dict = None, seed: Union[int, CustomGenerator] = None)

Instantiates the CybORG class.

Parameters:

Name	Type	Description	Default
scenario_generator	ScenarioGenerator	ScenarioGenerator object that creates scenarios.	required
agents	dict	Defines the agent that selects the default action to be performed if the external agent does not pick an action If None agents will be loaded from description in scenario file (default=None).	None
seed	Union[int, CustomGenerator]	optional seed for random number generator	None

close

close(**kwargs)

Shuts down CybORG.

Designed for the emulator.

Parameters:

Name	Type	Description	Default
**kwargs		Keyword Arguments to pass to the environment_controller.	{}

get_action_space

get_action_space(agent: str)

Returns the most recent action space for the specified agent.

Action spaces may change dynamically as the scenario progresses.

Parameters:

Name	Type	Description	Default
agent	str	Name of the agent to get action space for.	required

Returns:

Type	Description
dict	The action space of the specified agent.

get_agent_ids

get_agent_ids()

Returns the ids for the agents.

Returns:

Name	Type	Description
agent_ids	List[str]	List of agent ids.

get_agent_state

get_agent_state(agent_name) -> dict

Get the initial observation of the specified agent.

Parameters:

Name	Type	Description	Default
agent_name	str	The agent to get the initial observation for. Set as 'True' to get the true-state.	required

Returns:

Type	Description
dict	The initial observation of the specified agent.

get_attr

get_attr(attribute: str) -> Any

Returns the specified attribute if present.

Intended to give wrappers access to the base CybORG class.

Parameters:

Name	Type	Description	Default
attribute	str	Name of the requested attribute.	required

Returns:

Type	Description
Any	The requested attribute.

get_cidr_map

get_cidr_map()

Returns a mapping of hostnames to subnet cidrs for the current scenario.

Returns:

Type	Description
cidr_map	The ip_map indexed by hostname.

get_ip_map

get_ip_map()

Returns a mapping of hostnames to ip addresses for the current scenario.

Returns:

Type	Description
ip_map	The ip_map indexed by hostname.

get_last_action

get_last_action(agent: str)

Returns the last executed action for the specified agent.

Parameters:

Name	Type	Description	Default
agent	str	Name of the agent to get last action for.	required

Returns:

Type	Description
Action	The last action of the specified agent.

get_message_space

get_message_space(agent: str) -> gym.Space

Returns an OpenAI Gym Space that contains possible values for messages.

Parameters:

Name	Type	Description	Default
agent	str	The agent whose message space is being returned.	required

Returns:

Name	Type	Description
message_space	gym.Space	The message space being returned.

get_observation

get_observation(agent: str) -> dict

Get the last observation for an agent.

Parameters:

Name	Type	Description	Default
agent	str	Name of the agent to get observation for.	required

Returns:

Type	Description
Observation	The agent's last observation.

get_observation_space

get_observation_space(agent: str)

Returns the most recent observation for the specified agent.

Parameters:

Name	Type	Description	Default
agent	str	Name of the agent to get observation space for.	required

Returns:

Type	Description
dict	The observation of the specified agent.

get_reward_breakdown

get_reward_breakdown(agent: str)

Returns a dictionary mapping hosts to the rewards they contribute to the overall total.

Parameters:

Name	Type	Description	Default
agent	str	The agent to see the reward breakdown for.	required

Returns:

Name	Type	Description
rewards	dict	The rewards indexed by hostname.

get_rewards

get_rewards()

Returns the rewards for each agent at the last executed step.

Returns:

Name	Type	Description
rewards	dict	The rewards indexed by team name.

get_true_state

get_true_state(info: dict) -> dict

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		required

Returns:

Type	Description
Results	The information requested.

parallel_step

parallel_step(actions: dict = None, messages: dict = None, skip_valid_action_check: bool = False) -> Tuple[dict, dict, dict, dict]

Performs a step in CybORG accepting multiple external agent inputs.

Used by multiagent scenarios such as CAGE Challenge 3 and CAGE Challenge 4. Actions conceptually occur simultaneously, but in reality occur sequentially according to priority order.

Parameters
----------
actions: dict
    the actions to perform
skip_valid_action_check: bool
    a flag to diable the valid action check
Returns
-------
tuple
    the result of agent performing the action

reset

reset(agent: str = None, seed: int = None) -> Results

Resets CybORG and gets initial observation and action-space for the specified agent.

Note

This method is a critical part of the OpenAI Gym API.

Parameters:

Name	Type	Description	Default
agent	str	The agent to get the initial observation for. If None will return the initial true-state (default=None).	None

Returns:

Type	Description
Results	The initial observation and actions of an agent.

set_seed

set_seed(seed: int)

Creates an np_random object to seed all internal CybORG randomisations.

Parameters:

Name	Type	Description	Default
seed	int	The seed to pass to the np_random object	required

start

start(steps: int, log_file: int = None, verbose: int = False) -> bool

Start CybORG and run for a specified number of steps.

Parameters:

Name	Type	Description	Default
steps	int	the number of steps to run for	required
log_file		a file to write results to (default=None)	None

Returns:

Type	Description
bool	whether goal was reached or not

step

step(agent: str = None, action: str = None, messages: dict = None, skip_valid_action_check: bool = False) -> Results

Performs a step in CybORG for the given agent. Enables compatibility with older versions of CybORG including CAGE Challenge 1 and CAGE Challenge 2

Parameters:

Name	Type	Description	Default
agent	str	the agent to perform step for (default=None)	None
action		the action to perform	None
skip_valid_action_check	bool	a flag to diable the valid action check	False

Returns:

Type	Description
Results	the result of agent performing the action