Host

Bases: Entity

This class simulates the internals of a host, including files, processes and interfaces. The methods are used to change the state of the host.

The Host class contains all the relevant data for a host along with the relevant methods for modifying that data. It is instantiated by the State object when the scenario is loaded and can be found in Simulator/Host.py.

The methods in the Host class are mostly about modifying data. This is where most of the low-level work of CybORG is done as the Action objects call these methods, usually through the State object. An exception to this is the get_ephemeral port method, which generates a random port, which is particularly important when a new session is created. This is usually due to red activity, where an exploit creates a new shell, which needs to listen on a new port.

Attributes:

Name	Type	Description
`original_services`	`Dict[str, Dict[str,[bool, int]]`	Services present on the host at the beginning of the scenario. Needed for the Restore action.
`os_type`	`OperatingSystemType`	Differentiates between Windows and Linux hosts.
`distribution`	`OperatingSystemDistribution`	Differentiates between Linux Distributions and Windows generations (XP,7,8,10 etc.).
`version`	`OperatingSystemVersion`	Differentiates between Operating System versions. e.g. Windows XP Service Pack 1, Ubuntu 18.04.
`kernel`	`OperatingSystemKernelVersion`	Represents the kernel of the operating system.
`patches`	`List[OperatingSystemPatch]`	A list of patches applied to the operating system.
`hostname`	`str`	The name of the host.
`architecture`	`dict`
`respond_to_ping`	`bool`
`host_type`	`str`
`users`	`List[User]`
`files`	`List[File]`
`original_files`	`List[File]`
`sessions`	`Dict[Session]`
`original_sessions`	`Dict[Session]`
`default_process_info`	`List[Process]`
`processes`	`List[Process]`
`original_processes`	`List[Process]`
`interfaces`	`List[Interface]`
`ephemeral_ports`	`List[int]`
`services`	`Dict[str, Dict[str,[bool, int]]`

Functions

init

__init__(np_random, system_info: dict, hostname: str = None, users: List[User] = None, files: List[File] = None, sessions: Dict[str, List[int]] = None, processes: List[Process] = None, interfaces: List[Interface] = None, info: dict = None, services: dict = None, respond_to_ping: bool = True, starting_position: bool = np.array([0.0, 0.0]), host_type: bool = 'host', confidentiality_value: str = None, availability_value: str = None)

Instantiates the class

Hosts have an large __init__ function because they contain most of the data inside specified in the image and scenario files. This includes operating system information, interfaces, users, groups, files, processes, sessions and services. Each of these is it's own custom datatype.

Parameters:

Name	Type	Description	Default
`np_random`	`numpy random generator`		required
`system_info`	`dict`		required
`hostname`	`str`		`None`
`users`	`Dict[str, User]`		`None`
`files`	`List[File]`		`None`
`sessions`	`Dict[str, Session]`	dictionary of agent names and session objects	`None`
`processes`	`List[Process]`		`None`
`interfaces`	`List[Interface]`		`None`
`info`	`dict`		`None`
`services`	`dict`		`None`
`respond_to_ping`	`bool`		`True`
`starting_position`	`np.array`		`np.array([0.0, 0.0])`
`host_type`	`str`		`'host'`

add_service

add_service(service_name: str, service: Service) -> Service

Adds a service to the host, and starts it

add_user

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

Creates and returns a new user object.

Returns:

Name	Type	Description
`new_user`	`User`	new user object

create_backup

create_backup()

Creates a backup of the host by filling original class attributes with current class details

get_ephemeral_port

get_ephemeral_port()

Getter for the host's ephemeral port

Returns:

Name	Type	Description
`port`	`int`	a random value between 49152 and 60000 based on the environment seed

get_file

get_file(name: str, path: str = None)

Get file by filename

get_impact_count

get_impact_count()

Getter for impact count

get_interface

get_interface(name = None, cidr = None, ip_address = None, subnet_name = None)

Get an interface with a selected name, subnet, or ip_address

get_process

get_process(pid)

Get process by pid

get_restore_count

get_restore_count()

Getter for restore count

get_state

get_state()

Getter for observation dictionary.

Return

observation : Dict[str, _]

get_user

get_user(username)

Get user object by username

is_using_port

is_using_port(port: int) -> bool

Convenience method for checking if a host is using a port

restore

restore()

Restores the host by filling current class details from 'original' class attributes

start_service

start_service(service_name: str)

Starts a stopped service, no effect if service already started

stop_service

stop_service(service_name: str)

Stops a started service, no effect if service already stopped