Observation

Class that holds the observation data for the environment at a step in the episode

Attributes:

Name	Type	Description
data	Dict[str, _]	dictionary of agent observation data
raw	str

Attributes

action_succeeded property

action_succeeded: bool

Check the success of the action that the observation 'observes'

success property

success

Success of the action that the observation 'observes'

Functions

__init__

__init__(success: Union[bool, CyEnums.TernaryEnum] = CyEnums.TernaryEnum.UNKNOWN, msg: str = None)

Parameters:

Name	Type	Description	Default
success	Union[bool, CyEnums.TernaryEnum]	success of the action in the observation	CyEnums.TernaryEnum.UNKNOWN
msg	str	the message, if any, communicated by the agents	None

add_action_obs_pair

add_action_obs_pair(action, obs)

Adds an Action-Observation pair to this observation.

This can be used to send back observations of multiple actions, in a single observation.

Parameters:

Name	Type	Description	Default
action	Action	the action	required
obs	Observation	the observation	required

add_file_info

add_file_info(hostid: str = None, path: str = None, name: str = None, vendor: str = None, version: str = None, file_type: str = None, user: str = None, user_permissions: int = None, group: str = None, group_permissions: int = None, default_permissions: int = None, last_modified_time: datetime = None, signed: bool = None, density: float = None, **kwargs: float)

Add new file information to a specific host in the observation.

Parameters:

Name	Type	Description	Default
hostid	str		None
path	str		None
name	str		None
vendor	str		None
version	str		None
file_type	str		None
user	str		None
user_permissions	int		None
group	str		None
group_permissions	int		None
default_permissions	int		None
last_modified_time	datetime		None
signed	bool		None
density	float		None

add_interface_info

add_interface_info(hostid: str = None, interface_name: str = None, ip_address: Union[str, IPv4Address] = None, subnet: Union[str, IPv4Network] = None, Subnet: Union[str, IPv4Network] = None, blocked_ips: list = None, network_connections: list = None, **kwargs: list)

Add new interface information to a specifc host in the observation.

Parameters:

Name	Type	Description	Default
hostid	str		None
interface_name	str		None
ip_address	Union[str, IPv4Address]		None
subnet	Union[str, IPv4Network]		None
blocked_ips	list		None

add_process

add_process(hostid: str = None, pid: int = None, PID: int = None, parent_pid: int = None, process_name: str = None, program_name: str = None, service_name: str = None, username: str = None, path: str = None, local_port: int = None, remote_port: int = None, local_address: Union[str, IPv4Address] = None, remote_address: Union[str, IPv4Address] = None, app_protocol: str = None, transport_protocol: str = None, status: str = None, Status: str = None, process_type: str = None, process_version: str = None, vulnerability: str = None, properties: Optional[list[str]] = None, **kwargs: Optional[list[str]])

Adds a new process to a host in the observation.

Parameters:

Name	Type	Description	Default
hostid	str		None
pid	int		None
parent_pid	int		None
process_name	str		None
program_name	str		None
service_name	str		None
username	str		None
path	str		None
local_port	int		None
remote_port	int		None
local_address	Union[str, IPv4Address]		None
remote_address	Union[str, IPv4Address]		None
app_protocol	str		None
transport_protocol	str		None
status	str		None
process_type	str		None
process_version	str		None
vulnerability	str		None
properties	Optional[list[str]]		None

add_raw_obs

add_raw_obs(raw_obs)

Replaces the current raw observation with a new raw observation.

Parameters:

Name	Type	Description	Default
raw_obs			required

add_session_info

add_session_info(hostid: str = None, username: str = None, session_id: int = None, agent: str = None, timeout: int = None, pid: int = None, session_type: str = None, **kwargs: str)

Add new session information to specific host in observation.

Parameters:

Name	Type	Description	Default
hostid	str		None
username	str		None
session_id	int		None
agent	str		None
timeout	int		None
pid	int		None
session_type	str		None

add_system_info

add_system_info(hostid: str = None, hostname: str = None, os_type: str = None, os_distribution: str = None, os_version: str = None, os_kernel: str = None, os_patches: list = None, architecture: str = None, local_time: datetime = None, position: tuple = None, **kwargs: tuple)

And new system information to a specific host in the observation.

Parameters:

Name	Type	Description	Default
hostid	str		None
hostname	str		None
os_type	str		None
os_distribution	str		None
os_version	str		None
os_kernel	str		None
os_patches	list		None
architecture	str		None
local_time	datetime		None
position	tuple		None

add_user_info

add_user_info(hostid: str = None, group_name: str = None, gid: int = None, username: str = None, uid: int = None, password: str = None, password_hash: str = None, password_hash_type: str = None, logged_in: bool = None, key_path: str = None, Groups: list = None, **kwargs: list)

Add user information to a host in the observation.

Parameters:

Name	Type	Description	Default
hostid	str		None
group_name	str		None
gid	int		None
username	str		None
uid	int		None
password	str		None
password_hash	str		None
password_hash_type	str		None
logged_in	bool		None
key_path	str		None

combine_obs

combine_obs(obs)

Combines this Observation with another Observation

Parameters:

Name	Type	Description	Default
obs	Observation	the other observation	required

copy

copy()

Creates a copy of the observation.

Returns:

Name	Type	Description
obs_copy	Observation	copy of the current observation

filter_addresses

filter_addresses(ips: Union[list[str], list[IPv4Address]] = None, cidrs: Union[list[str], list[IPv4Network]] = None, include_localhost: bool = True)

Filter observation, in place, to include only certain addresses

This function will remove any observation information for addresses not in the list, and will remove all observations of Hosts which have had atleast one address observed but where none of the observed addresses are in the list.

Parameters:

Name	Type	Description	Default
ips	list[str] or list[IPv4Address]	the ip addresses to keep, if None does not filter IP addresses (default=None)	None
cidrs	list[str] or list[IPv4Network]	the cidr addresses to keep, if None does not filter Cidr addresses (default=None)	None
include_localhost	bool	If True and ips is not None, will include localhost address ('127.0.0.1') in IP addresses to keep (default=True)	True

get_agent_sessions

get_agent_sessions(agent: str) -> list

Get list of info for each agent session in observation

Parameters:

Name	Type	Description	Default
agent	str	the agent to get session info for	required

Returns:

Type	Description
list(dict)	list of session info

get_dict

get_dict()

Returns the data of the observation

get_nested_obs

get_nested_obs()

Returns any nested action, observation pairs

Returns:

Type	Description
list((Action, Observation))	any nested observations

get_sessions

get_sessions() -> list

Get list of info for each session in observation

Returns:

Type	Description
list(dict)	list of session info

has_multiple_obs

has_multiple_obs() -> bool

Returns whether Observation contains multiple nested observation

Returns:

Type	Description
bool	True if Observation has nested observations

set_success

set_success(success: Union[bool, CyEnums.TernaryEnum])

Sets the success value of the data dictionary

Parameters:

Name	Type	Description	Default
success	Union[bool, CyEnums.TrinaryEnum]		required