Merge pull request #355 from stratosphereips/ondra-update-docs

Ondra update docs

Author: ondrej-lukas

AIDojoCoordinator/worlds/NSEGameCoordinator.py

@@ -947,6 +947,7 @@ async def reset(self)->bool:
         # write all steps in the episode replay buffer in the file
         self.logger.info('--- Reseting NSG Environment to its initial state ---')
         # change IPs if needed
+        # This is done ONLY if it is (i) enabled in the task config and (ii) all agents requested it
         if self.task_config.get_use_dynamic_addresses():
             if all(self._randomize_topology_requests.values()):
                 self.logger.info("All agents requested reset with randomized topology.")

NetSecGameAgents

@@ -74,7 +74,7 @@ The Action consists of two parts
 #### List of ActionTypes
 - **JoinGame**, params={`agent_info`:AgentInfo(`<name>`, `<role>`)}: Used to register agent in a game with a given `<role>`.
 - **QuitGame**, params={}: Used for termination of agent's interaction.
-- **ResetGame**, params={`request_trajectory`:`bool`}: Used for requesting reset of the game to it's initial position. If `request_trajectory = True`, the coordinator will send back the complete trajectory of the previous run in the next message.
+- **ResetGame**, params={`request_trajectory`:`bool` (default=`False`),  `randomize_topology`=`bool` (default=`True`)}: Used for requesting reset of the game to it's initial position. If `request_trajectory = True`, the coordinator will send back the complete trajectory of the previous run in the next message. If `randomize_topology`=`True`, the agent request topology to be changed in the next episode. NOTE: the topology is changed only if (i) the `use_dynamic_ips` is set to `True` in the task configuration AND all active agents ask for the change.
 ---
 - **ScanNetwork**, params{`source_host`:`<IP>`, `target_network`:`<Network>`}: Scans the given `<Network>` from a specified source host. Discovers ALL hosts in a network that are accessible from `<IP>`. If successful, returns set of discovered `<IP>` objects.
 - **FindServices**, params={`source_host`:`<IP>`, `target_host`:`<IP>`}: Used to discover ALL services running in the `target_host` if the host is accessible from `source_host`. If successful, returns a set of all discovered `<Service>` objects.

docs/architecture.md

@@ -13,7 +13,17 @@ The environment part defines the properties of the environment for the task (see
     -  `two_networks` - 5 clients and 5 servers in separate local networks + remote C&C server
     -  `three_net_scenario` - 5 clients in a local network, 5 servers split in 2 additional local networks + remote C&C server
 - `save_tajectories` - if `True`, interaction of the agents is serialized and stored in a file
-- `use_dynamic_addresses` - if `True`, the network and IP addresses defined in `scenario` are randomly changed at the beginning of **EVERY** episode (the network topology is kept as defined in the `scenario`. Relations between networks are kept, IPs inside networks are chosen at random based on the network IP and mask)
+- `use_dynamic_addresses` - if `True`, the network and IP addresses defined in `scenario` are randomly changed at the beginning of an episode (the network topology is kept as defined in the `scenario`. Relations between networks are kept, IPs inside networks are chosen at random based on the network IP and mask). The change also depend on the input from the agents:
+
+|Task configuration| Agent reset request | Result|
+|----------------------|----------------------|----------------------|
+|`use_dynamic_ips = True` | `randomize_topology = True`| Changed topology |
+|`use_dynamic_ips = True` | `randomize_topology = False`| SAME topology |
+|`use_dynamic_ips = False` | `randomize_topology = True`| SAME topology |
+|`use_dynamic_ips = False` | `randomize_topology = False`| SAME topology |
+
+In summary, the topology change (IP randomization) can't change without allowing it in the task configuration. If allowed in the task config YAML, it can still be rejected by the agents.
+
 - `use_firewall` - if `True` firewall rules defined in `scenario` are used when executing actions. When `False`, the firewall is ignored, and all connections are allowed (Default)
 - `use_global_defender` - if `True`, enables global defendr which is part of the environment and can stop interaction of any playing agent.
 - `required_players` - Minimum required players for the game to start (default 1)