Game Components

AIDojoCoordinator.game_components

Action(action_type, parameters=dict()) dataclass

Immutable dataclass representing an Action.

Attributes:

Name	Type	Description
action_type	ActionType	The type of action.
parameters	Dict[str, Any]	Parameters for the action.

as_dict property

Return a dictionary representation of the Action.

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: The action as a dictionary.

type property

Return the action type.

Returns:

Name	Type	Description
ActionType	ActionType	The action type.

__eq__(other)

Check equality with another Action object.

Parameters:

Name	Type	Description	Default
other	object	Another Action object.	required

Returns:

Name	Type	Description
bool	bool	True if equal, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def __eq__(self, other: object) -> bool:
    """
    Check equality with another Action object.

    Args:
        other (object): Another Action object.

    Returns:
        bool: True if equal, False otherwise.
    """
    if not isinstance(other, Action):
        return NotImplemented
    return (
        self.action_type == other.action_type and
        self.parameters == other.parameters
    )

__hash__()

Compute the hash of the Action.

Returns:

Name	Type	Description
int	int	The hash value.

Source code in AIDojoCoordinator/game_components.py

def __hash__(self) -> int:
    """
    Compute the hash of the Action.

    Returns:
        int: The hash value.
    """
    # Convert parameters to a sorted tuple of key-value pairs for consistency
    sorted_params = tuple(sorted((k, hash(v)) for k, v in self.parameters.items()))
    return hash((self.action_type, sorted_params))

__repr__()

Return the string representation of the Action.

Returns:

Name	Type	Description
str	str	The action as a string.

Source code in AIDojoCoordinator/game_components.py

def __repr__(self) -> str:
    """
    Return the string representation of the Action.

    Returns:
        str: The action as a string.
    """
    return f"Action <{self.action_type}|{self.parameters}>"

__str__()

Return the string representation of the Action.

Returns:

Name	Type	Description
str	str	The action as a string.

Source code in AIDojoCoordinator/game_components.py

def __str__(self) -> str:
    """
    Return the string representation of the Action.

    Returns:
        str: The action as a string.
    """
    return f"Action <{self.action_type}|{self.parameters}>"

from_dict(data_dict) classmethod

Create an Action from a dictionary.

Parameters:

Name	Type	Description	Default
data_dict	Dict[str, Any]	The action as a dictionary.	required

Returns:

Name	Type	Description
Action	Action	The created Action object.

Raises:

Type	Description
ValueError	If an unsupported parameter is encountered.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_dict(cls, data_dict: Dict[str, Any]) -> "Action":
    """
    Create an Action from a dictionary.

    Args:
        data_dict (Dict[str, Any]): The action as a dictionary.

    Returns:
        Action: The created Action object.

    Raises:
        ValueError: If an unsupported parameter is encountered.
    """
    action_type = ActionType.from_string(data_dict["action_type"])
    params = {}
    for k, v in data_dict["parameters"].items():
        match k:
            case "source_host" | "target_host" | "blocked_host":
                params[k] = IP.from_dict(v)
            case "target_network":
                params[k] = Network.from_dict(v)
            case "target_service":
                params[k] = Service.from_dict(v)
            case "data":
                params[k] = Data.from_dict(v)
            case "agent_info":
                params[k] = AgentInfo.from_dict(v)
            case "request_trajectory":
                params[k] = ast.literal_eval(v)
            case _:
                raise ValueError(f"Unsupported value in {k}: {v}")
    return cls(action_type=action_type, parameters=params)

from_json(json_string) classmethod

Create an Action from a JSON string.

Parameters:

Name	Type	Description	Default
json_string	str	The JSON string representation.	required

Returns:

Name	Type	Description
Action	Action	The created Action object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_json(cls, json_string: str) -> "Action":
    """
    Create an Action from a JSON string.

    Args:
        json_string (str): The JSON string representation.

    Returns:
        Action: The created Action object.
    """
    data_dict = json.loads(json_string)
    return cls.from_dict(data_dict)

to_json()

Serialize the Action to a JSON string.

Returns:

Name	Type	Description
str	str	The JSON string representation.

Source code in AIDojoCoordinator/game_components.py

def to_json(self) -> str:
    """
    Serialize the Action to a JSON string.

    Returns:
        str: The JSON string representation.
    """
    return json.dumps(self.as_dict)

ActionType

Bases: Enum

Enum representing possible action types in the NetSecGame.

__eq__(other)

Compare ActionType with another ActionType or string.

Parameters:

Name	Type	Description	Default
other	ActionType or str	The object to compare.	required

Returns:

Name	Type	Description
bool	bool	True if equal, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def __eq__(self, other)->bool:
    """
    Compare ActionType with another ActionType or string.

    Args:
        other (ActionType or str): The object to compare.

    Returns:
        bool: True if equal, False otherwise.
    """
    # Compare with another ActionType
    if isinstance(other, ActionType):
        return self.value == other.value
    # Compare with a string
    elif isinstance(other, str):
       return self.value == other.replace("ActionType.", "")
    return False

__hash__()

Compute the hash of the ActionType.

Returns:

Name	Type	Description
int	int	The hash value.

Source code in AIDojoCoordinator/game_components.py

def __hash__(self)->int:
    """
    Compute the hash of the ActionType.

    Returns:
        int: The hash value.
    """
    # Use the hash of the value for consistent behavior
    return hash(self.value)

from_string(name) classmethod

Convert a string to an ActionType enum. Strips 'ActionType.' if present.

Parameters:

Name	Type	Description	Default
name	str	The string representation.	required

Returns:

Name	Type	Description
ActionType	ActionType	The corresponding ActionType.

Raises:

Type	Description
ValueError	If the string does not match any ActionType.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_string(cls, name)->"ActionType":
    """
    Convert a string to an ActionType enum. Strips 'ActionType.' if present.

    Args:
        name (str): The string representation.

    Returns:
        ActionType: The corresponding ActionType.

    Raises:
        ValueError: If the string does not match any ActionType.
    """
    if name.startswith("ActionType."):
        name = name.split("ActionType.")[1]
    try:
        return cls[name]
    except KeyError:
        raise ValueError(f"Invalid ActionType: {name}")

to_string()

Convert the ActionType enum to string.

Returns:

Name	Type	Description
str	str	The string representation.

Source code in AIDojoCoordinator/game_components.py

def to_string(self)->str:
    """
    Convert the ActionType enum to string.

    Returns:
        str: The string representation.
    """
    return self.value

AgentInfo(name, role) dataclass

Represents agent information.

Attributes:

Name	Type	Description
name	str	Name of the agent.
role	str	Role of the agent.

__repr__()

Return the string representation of the AgentInfo.

Returns:

Name	Type	Description
str	str	The agent info as a string.

Source code in AIDojoCoordinator/game_components.py

def __repr__(self)->str:
    """
    Return the string representation of the AgentInfo.

    Returns:
        str: The agent info as a string.
    """
    return f"{self.name}({self.role})"

from_dict(data) classmethod

Build the AgentInfo object from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary with agent info attributes.	required

Returns:

Name	Type	Description
AgentInfo	AgentInfo	The created AgentInfo object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_dict(cls, data: dict)->"AgentInfo":
    """
    Build the AgentInfo object from a dictionary.

    Args:
        data (dict): Dictionary with agent info attributes.

    Returns:
        AgentInfo: The created AgentInfo object.
    """
    return cls(**data)

AgentStatus

Bases: Enum

Enum representing possible agent statuses.

__eq__(other)

Compare AgentStatus with another AgentStatus or string.

Parameters:

Name	Type	Description	Default
other	AgentStatus or str	The object to compare.	required

Returns:

Name	Type	Description
bool	bool	True if equal, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def __eq__(self, other)->bool:
    """
    Compare AgentStatus with another AgentStatus or string.

    Args:
        other (AgentStatus or str): The object to compare.

    Returns:
        bool: True if equal, False otherwise.
    """
    # Compare with another ActionType
    if isinstance(other, AgentStatus):
        return self.value == other.value
    # Compare with a string
    elif isinstance(other, str):
       return self.value == other.replace("AgentStatus.", "")
    return False

__hash__()

Compute the hash of the AgentStatus.

Returns:

Name	Type	Description
int	int	The hash value.

Source code in AIDojoCoordinator/game_components.py

def __hash__(self)->int:
    """
    Compute the hash of the AgentStatus.

    Returns:
        int: The hash value.
    """
    # Use the hash of the value for consistent behavior
    return hash(self.value)

from_string(name) classmethod

Convert a string to an AgentStatus enum.

Parameters:

Name	Type	Description	Default
name	str	The string representation.	required

Returns:

Name	Type	Description
AgentStatus	AgentStatus	The corresponding AgentStatus.

Raises:

Type	Description
ValueError	If the string does not match any AgentStatus.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_string(cls, name)->"AgentStatus":
    """
    Convert a string to an AgentStatus enum.

    Args:
        name (str): The string representation.

    Returns:
        AgentStatus: The corresponding AgentStatus.

    Raises:
        ValueError: If the string does not match any AgentStatus.
    """
    if name.startswith("AgentStatus."):
        name = name.split("AgentStatus.")[1]
    try:
        return cls[name]
    except KeyError:
        raise ValueError(f"Invalid AgentStatus: {name}")

to_string()

Convert the AgentStatus enum to string.

Returns:

Name	Type	Description
str	str	The string representation.

Source code in AIDojoCoordinator/game_components.py

def to_string(self)->str:
    """
    Convert the AgentStatus enum to string.

    Returns:
        str: The string representation.
    """
    return self.value

Data(owner, id, size=0, type='', content=str()) dataclass

Represents a data object in the NetSecGame.

Attributes:

Name	Type	Description
owner	str	Owner of the data.
id	str	Identifier of the data.
size	int	Size of the data. Default = 0
type	str	Type of the data. Default = ""
content	str	Content of the data. Default = ""

__hash__()

Compute the hash of the Data object.

Returns:

Name	Type	Description
int	int	The hash value.

Source code in AIDojoCoordinator/game_components.py

def __hash__(self) -> int:
    """
    Compute the hash of the Data object.

    Returns:
        int: The hash value.
    """
    return hash((self.owner, self.id, self.type))

from_dict(data) classmethod

Build the Data object from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary with data attributes.	required

Returns:

Name	Type	Description
Data	Data	The created Data object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_dict(cls, data: dict)->"Data":
    """
    Build the Data object from a dictionary.

    Args:
        data (dict): Dictionary with data attributes.

    Returns:
        Data: The created Data object.
    """
    return cls(**data)

GameState(controlled_hosts=set(), known_hosts=set(), known_services=dict(), known_data=dict(), known_networks=set(), known_blocks=dict()) dataclass

Represents the state of the game.

Attributes:

Name	Type	Description
controlled_hosts	set	Controlled hosts.
known_hosts	set	Known hosts.
known_services	dict	Known services.
known_data	dict	Known data.
known_networks	set	Known networks.
known_blocks	dict	Known blocks.

as_dict property

Return the dictionary representation of the GameState.

Returns:

Name	Type	Description
dict	dict	The game state as a dictionary.

as_graph property

Build a graph representation of the game state.

Returns:

Name	Type	Description
tuple	tuple	(node_features, controlled, edges, node_index_map)

__str__()

Return the string representation of the GameState.

Returns:

Name	Type	Description
str	str	The game state as a string.

Source code in AIDojoCoordinator/game_components.py

def __str__(self) -> str:
    """
    Return the string representation of the GameState.

    Returns:
        str: The game state as a string.
    """
    return f"State<nets:{self.known_networks}; known:{self.known_hosts}; owned:{self.controlled_hosts}; services:{self.known_services}; data:{self.known_data}; blocks:{self.known_blocks}>"    

as_json()

Return the JSON representation of the GameState.

Returns:

Name	Type	Description
str	str	The JSON string.

Source code in AIDojoCoordinator/game_components.py

def as_json(self) -> str:
    """
    Return the JSON representation of the GameState.

    Returns:
        str: The JSON string.
    """
    ret_dict = self.as_dict
    return json.dumps(ret_dict)

from_dict(data_dict) classmethod

Create a GameState from a dictionary.

Parameters:

Name	Type	Description	Default
data_dict	dict	The game state as a dictionary.	required

Returns:

Name	Type	Description
GameState	GameState	The created GameState object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_dict(cls, data_dict:dict)->"GameState":
    """
    Create a GameState from a dictionary.

    Args:
        data_dict (dict): The game state as a dictionary.

    Returns:
        GameState: The created GameState object.
    """
    if "known_blocks" in data_dict:
        known_blocks = {IP(target_host):{IP(blocked_host["ip"]) for blocked_host in blocked_hosts} for target_host, blocked_hosts in data_dict["known_blocks"].items()}
    else:
        known_blocks = {}
    state = GameState(
        known_networks = {Network(x["ip"], x["mask"]) for x in data_dict["known_networks"]},
        known_hosts = {IP(x["ip"]) for x in data_dict["known_hosts"]},
        controlled_hosts = {IP(x["ip"]) for x in data_dict["controlled_hosts"]},
        known_services = {IP(k):{Service(s["name"], s["type"], s["version"], s["is_local"])
            for s in services} for k,services in data_dict["known_services"].items()},  
        known_data = {IP(k):{Data(v["owner"], v["id"], v["size"], v["type"], v["content"]) for v in values} for k,values in data_dict["known_data"].items()},
        known_blocks = known_blocks
            )
    return state

from_json(json_string) classmethod

Create a GameState from a JSON string.

Parameters:

Name	Type	Description	Default
json_string	str	The JSON string.	required

Returns:

Name	Type	Description
GameState	GameState	The created GameState object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_json(cls, json_string)->"GameState":
    """
    Create a GameState from a JSON string.

    Args:
        json_string (str): The JSON string.

    Returns:
        GameState: The created GameState object.
    """
    json_data = json.loads(json_string)
    state = GameState(
        known_networks = {Network(x["ip"], x["mask"]) for x in json_data["known_networks"]},
        known_hosts = {IP(x["ip"]) for x in json_data["known_hosts"]},
        controlled_hosts = {IP(x["ip"]) for x in json_data["controlled_hosts"]},
        known_services = {IP(k):{Service(s["name"], s["type"], s["version"], s["is_local"])
            for s in services} for k,services in json_data["known_services"].items()},  
        known_data = {IP(k):{Data(v["owner"], v["id"], v["size"], v["type"], v["content"]) for v in values} for k,values in json_data["known_data"].items()},
        known_blocks = {IP(target_host):{IP(blocked_host) for blocked_host in blocked_hosts} for target_host, blocked_hosts in json_data["known_blocks"].items()}
        )
    return state

GameStatus

Bases: Enum

Enum representing possible game statuses.

__repr__()

Return the string representation of the GameStatus.

Returns:

Name	Type	Description
str	str	The game status as a string.

Source code in AIDojoCoordinator/game_components.py

def __repr__(self) -> str:
    """
    Return the string representation of the GameStatus.

    Returns:
        str: The game status as a string.
    """
    return str(self)

from_string(string) classmethod

Convert a string to a GameStatus enum.

Parameters:

Name	Type	Description	Default
string	str	The string representation.	required

Returns:

Name	Type	Description
GameStatus	GameStatus	The corresponding GameStatus.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_string(cls, string:str)->"GameStatus":
    """
    Convert a string to a GameStatus enum.

    Args:
        string (str): The string representation.

    Returns:
        GameStatus: The corresponding GameStatus.
    """
    match string:
        case "GameStatus.OK":
            return GameStatus.OK
        case "GameStatus.CREATED":
            return GameStatus.CREATED
        case "GameStatus.BAD_REQUEST":
            return GameStatus.BAD_REQUEST
        case "GameStatus.FORBIDDEN":
            return GameStatus.FORBIDDEN
        case "GameStatus.RESET_DONE":
            return GameStatus.RESET_DONE

IP(ip) dataclass

Immutable object representing an IPv4 address in the NetSecGame.

Attributes:

Name	Type	Description
ip	str	The IP address in dot-decimal notation.

__eq__(other)

Check equality with another IP object.

Parameters:

Name	Type	Description	Default
other	IP	Another IP object.	required

Returns:

Name	Type	Description
is_equal	bool	True if equal, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def __eq__(self, other)->bool:
    """
    Check equality with another IP object.

    Args:
        other (IP): Another IP object.

    Returns:
        is_equal: True if equal, False otherwise.
    """
    if not isinstance(other, IP):
        return NotImplemented
    return self.ip == other.ip

__hash__()

Compute the hash of the IP.

Returns:

Name	Type	Description
hash	int	The hash value.

Source code in AIDojoCoordinator/game_components.py

def __hash__(self)->int:
    """
    Compute the hash of the IP.

    Returns:
        hash: The hash value.
    """
    return hash(self.ip)

__post_init__()

Verify if the provided IP is valid.

Raises:

Type	Description
ValueError	If the IP address is invalid.

Source code in AIDojoCoordinator/game_components.py

def __post_init__(self):
    """
    Verify if the provided IP is valid.

    Raises:
        ValueError: If the IP address is invalid.
    """
    try:
        ipaddress.ip_address(self.ip)
    except ValueError:
        raise ValueError(f"Invalid IP address provided: {self.ip}")

__repr__()

Return the string representation of the IP.

Returns:

Name	Type	Description
str	str	The IP address.

Source code in AIDojoCoordinator/game_components.py

def __repr__(self)->str:
    """
    Return the string representation of the IP.

    Returns:
        str: The IP address.
    """
    return self.ip

from_dict(data) classmethod

Build the IP object from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary with IP attributes.	required

Returns:

Name	Type	Description
IP	IP	The created IP object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_dict(cls, data: dict)->"IP":
    """
    Build the IP object from a dictionary representation.

    Args:
        data (dict): Dictionary with IP attributes.

    Returns:
        IP: The created IP object.
    """
    return cls(**data)

is_private()

Check if the IP address is private. Uses ipaddress module.

Returns:

Name	Type	Description
is_private	bool	True if the IP is private, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def is_private(self)->bool:
    """
    Check if the IP address is private. Uses ipaddress module.

    Returns:
        is_private: True if the IP is private, False otherwise.
    """
    try:
        return ipaddress.IPv4Network(self.ip).is_private
    except ipaddress.AddressValueError:
        # The IP is a string 
        # In the concepts, 'external' is the string used for external hosts.
        if self.ip != 'external':
            return True
        return False

Network(ip, mask) dataclass

Immutable object representing an IPv4 network in the NetSecGame.

Attributes:

Name	Type	Description
ip	str	IP address of the network.
mask	int	CIDR mask of the network.

__gt__(other)

Greater-than comparison for networks.

Parameters:

Name	Type	Description	Default
other	Network	Another network.	required

Returns:

Name	Type	Description
bool	bool	True if self > other, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def __gt__(self, other)->bool:
    """
    Greater-than comparison for networks.

    Args:
        other (Network): Another network.

    Returns:
        bool: True if self > other, False otherwise.
    """
    try:
        return netaddr.IPNetwork(str(self)) > netaddr.IPNetwork(str(other))
    except netaddr.core.AddrFormatError:
        return str(self.ip) > str(other.ip)

__le__(other)

Less-than-or-equal comparison for networks.

Parameters:

Name	Type	Description	Default
other	Network	Another network.	required

Returns:

Name	Type	Description
bool	bool	True if self <= other, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def __le__(self, other)->bool:
    """
    Less-than-or-equal comparison for networks.

    Args:
        other (Network): Another network.

    Returns:
        bool: True if self <= other, False otherwise.
    """
    try:
        return netaddr.IPNetwork(str(self)) <= netaddr.IPNetwork(str(other))
    except netaddr.core.AddrFormatError:
        return str(self.ip) <= str(other.ip)

__lt__(other)

Less-than comparison for networks.

Parameters:

Name	Type	Description	Default
other	Network	Another network.	required

Returns:

Name	Type	Description
bool	bool	True if self < other, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def __lt__(self, other)->bool:
    """
    Less-than comparison for networks.

    Args:
        other (Network): Another network.

    Returns:
        bool: True if self < other, False otherwise.
    """
    try:
        return netaddr.IPNetwork(str(self)) < netaddr.IPNetwork(str(other))
    except netaddr.core.AddrFormatError:
        return str(self.ip) < str(other.ip)

__repr__()

Return the string representation of the network.

Returns:

Name	Type	Description
str	str	The network in CIDR notation.

Source code in AIDojoCoordinator/game_components.py

def __repr__(self)->str:
    """
    Return the string representation of the network.

    Returns:
        str: The network in CIDR notation.
    """
    return f"{self.ip}/{self.mask}"

__str__()

Return the string representation of the network.

Returns:

Name	Type	Description
str	str	The network in CIDR notation.

Source code in AIDojoCoordinator/game_components.py

def __str__(self)->str:
    """
    Return the string representation of the network.

    Returns:
        str: The network in CIDR notation.
    """
    return f"{self.ip}/{self.mask}"

from_dict(data) classmethod

Build the Network object from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary with network attributes.	required

Returns:

Name	Type	Description
Network	Network	The created Network object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_dict(cls, data: dict)->"Network":
    """
    Build the Network object from a dictionary.

    Args:
        data (dict): Dictionary with network attributes.

    Returns:
        Network: The created Network object.
    """
    return cls(**data)

is_private()

Check if the network is private. Uses ipaddress module.

Returns:

Name	Type	Description
bool	bool	True if the network is private, False otherwise.

Source code in AIDojoCoordinator/game_components.py

def is_private(self)->bool:
    """
    Check if the network is private. Uses ipaddress module.

    Returns:
        bool: True if the network is private, False otherwise.
    """
    try:
        return ipaddress.IPv4Network(f'{self.ip}/{self.mask}',strict=False).is_private
    except ipaddress.AddressValueError:
        # If we are dealing with strings, assume they are local networks
        return True

ProtocolConfig() dataclass

Configuration for protocol constants.

Attributes:

Name	Type	Description
END_OF_MESSAGE	bytes	End-of-message marker.
BUFFER_SIZE	int	Buffer size for messages.

Service(name, type='unknown', version='unknown', is_local=True) dataclass

Represents a service in the NetSecGame.

Attributes:

Name	Type	Description
name	str	Name of the service.
type	str	Type of the service. Default uknown
version	str	Version of the service. Default uknown
is_local	bool	Whether the service is local. Default True

from_dict(data) classmethod

Create a Service object from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary with service attributes.	required

Returns:

Name	Type	Description
Service	Service	The created Service object.

Source code in AIDojoCoordinator/game_components.py

@classmethod
def from_dict(cls, data: dict)->"Service":
    """
    Create a Service object from a dictionary.

    Args:
        data (dict): Dictionary with service attributes.

    Returns:
        Service: The created Service object.
    """
    return cls(**data)