Merge branch 'dev' into feature/2041_2042-Add-NTP-Services

docs/source/about.rst

@@ -18,7 +18,6 @@ PrimAITE provides the following features:
 * Highly configurable network hosts, including definition of software, file system, and network interfaces,
 * Realistic network traffic simulation, including address and sending packets via internet protocols like TCP, UDP, ICMP, etc.
 * Routers with traffic routing and firewall capabilities
-* Interfaces with ARCD GATE to allow training of agents
 * Simulation of customisable deterministic agents
 * Support for multiple agents, each having their own customisable observation space, action space, and reward function definition.
 
@@ -148,7 +147,7 @@ The game layer is built on top of the simulator and it consumes the simulation a
   Observation Spaces
   ******************
   The observation space provides the blue agent with information about the current status of nodes and links.
-  PrimAITE builds on top of Gym Spaces to create an observation space that is easily configurable for users. It's made up of components which are managed by the :py:class:`primaite.environment.observations.ObservationsHandler`. Each training scenario can define its own observation space, and the user can choose which information to inlude, and how it should be formatted.
+  PrimAITE builds on top of Gymnasium Spaces to create an observation space that is easily configurable for users. It's made up of components which are managed by the :py:class:`primaite.environment.observations.ObservationsHandler`. Each training scenario can define its own observation space, and the user can choose which information to inlude, and how it should be formatted.
   NodeLinkTable component
   -----------------------
   For example, the :py:class:`primaite.environment.observations.NodeLinkTable` component represents the status of nodes and links as a ``gym.spaces.Box`` with an example format shown below:
@@ -279,7 +278,7 @@ The game layer is built on top of the simulator and it consumes the simulation a
   3. Any (Agent can take both node-based and ACL-based actions)
   The choice of action space used during a training session is determined in the config_[name].yaml file.
   **Node-Based**
-  The agent is able to influence the status of nodes by switching them off, resetting, or patching operating systems and services. In this instance, the action space is an OpenAI Gym spaces.Discrete type, as follows:
+  The agent is able to influence the status of nodes by switching them off, resetting, or patching operating systems and services. In this instance, the action space is a Gymnasium spaces.Discrete type, as follows:
   * Dictionary item {... ,1: [x1, x2, x3,x4] ...}
     The placeholders inside the list under the key '1' mean the following:
       * [0, num nodes] - Node ID (0 = nothing, node ID)
@@ -287,7 +286,7 @@ The game layer is built on top of the simulator and it consumes the simulation a
       * [0, 3] - Action on property (0 = nothing, 1 = on / scan, 2 = off / repair, 3 = reset / patch / restore)
       * [0, num services] - Resolves to service ID (0 = nothing, resolves to service)
   **Access Control List**
-  The blue agent is able to influence the configuration of the Access Control List rule set (which implements a system-wide firewall). In this instance, the action space is an OpenAI spaces.Discrete type, as follows:
+  The blue agent is able to influence the configuration of the Access Control List rule set (which implements a system-wide firewall). In this instance, the action space is an Gymnasium spaces.Discrete type, as follows:
     * Dictionary item {... ,1: [x1, x2, x3, x4, x5, x6] ...}
     The placeholders inside the list under the key '1' mean the following:
       * [0, 2] - Action (0 = do nothing, 1 = create rule, 2 = delete rule)

docs/source/config.rst

@@ -1,13 +1,80 @@
 Primaite v3 config
 ******************
 
-PrimAITE uses a single configuration file to define a cybersecurity scenario. This includes the computer network and multiple agents. There are three main sections: training_config, game, and simulation.
+PrimAITE uses a single configuration file to define everything needed to train and evaluate an RL policy in a custom cybersecurity scenario. This includes the configuration of the network, the scripted or trained agents that interact with the network, as well as settings that define how to perform training in Stable Baselines 3 or Ray RLLib.
+The entire config is used by the ``PrimaiteSession`` object for users who wish to let PrimAITE handle the agent definition and training. If you wish to define custom agents and control the training loop yourself, you can use the config with the ``PrimaiteGame``, and ``PrimaiteGymEnv`` objects instead. That way, only the network configuration and agent setup parts of the config are used, and the training section is ignored.
 
-The simulation section describes the simulated network environment with which the agetns interact.
+Configurable items
+==================
 
-The game section describes the agents and their capabilities. Each agent has a unique type and is associated with a team (GREEN, RED, or BLUE). Each agent has a configurable observation space, action space, and reward function.
+``training_config``
+-------------------
+This section allows selecting which training framework and algorithm to use, and set some training hyperparameters.
 
-The training_config section describes the training parameters for the learning agents. This includes the number of episodes, the number of steps per episode, and the number of steps before the agents start learning. The training_config section also describes the learning algorithm used by the agents. The learning algorithm is specified by the name of the algorithm and the hyperparameters for the algorithm. The hyperparameters are specific to each algorithm and are described in the documentation for each algorithm.
+``io_settings``
+---------------
+This section configures how the ``PrimaiteSession`` saves data.
 
-.. only:: comment
-    This needs a bit of refactoring so I haven't written extensive documentation about the config yet.
+``game``
+--------
+This section defines high-level settings that apply across the game, currently it's used to help shape the action and observation spaces by restricting which ports and internet protocols should be considered. Here, users can also set the maximum number of steps in an episode.
+
+``agents``
+----------
+Agents can be scripted (deterministic and stochastic), or controlled by a reinforcement learning algorithm. Not to be confused with an RL agent, the term agent here is used to refer to an entity that sends requests to the simulated network. In this part of the config, each agent's action space, observation space, and reward function can be defined. All three are defined in a modular way.
+
+**type**: Specifies which class should be used for the agent. ``ProxyAgent`` is used for agents that receive instructions from an RL algorithm. Scripted agents like ``RedDatabaseCorruptingAgent`` and ``GreenWebBrowsingAgent`` generate their own behaviour.
+
+**team**: Specifies if the agent is malicious (RED), benign (GREEN), or defensive (BLUE). Currently this value is not used for anything.
+
+**observation space:**
+    * ``type``: selects which python class from the ``primaite.game.agent.observation`` module is used for the overall observation structure.
+    * ``options``: allows configuring the chosen observation type. The ``UC2BlueObservation`` should be used for RL Agents.
+        * ``num_services_per_node``, ``num_folders_per_node``, ``num_files_per_folder``, ``num_nics_per_node`` all define the shape of the observation space. The size and shape of the obs space must remain constant, but the number of files, folders, ACL rules, and other components can change within an episode. Therefore padding is performed and these options set the size of the obs space.
+        * ``nodes``: list of nodes that will be present in this agent's observation space. The ``node_ref`` relates to the human-readable unique reference defined later in the ``simulation`` part of the config. Each node can also be configured with services, and files that should be monitored.
+        * ``links``: list of links that will be present in this agent's observation space. The ``link_ref`` relates to the human-readable unique reference defined later in the ``simulation`` part of the config.
+        * ``acl``: configure how the agent reads the access control list on the router in the simulation. ``router_node_ref`` is for selecting which router's ACL table should be used. ``ip_address_order`` sets the encoding of ip addresses as integers within the observation space.
+
+**action space:**
+The action space is configured to be made up of individual action types. Once configured, the agent can select an action type and some optional action parameters at every step. For example: The ``NODE_SERVICE_SCAN`` action takes the parameters ``node_id`` and ``service_id``.
+
+Description of configurable items:
+    * ``action_list``: a list of action modules. The options are listed in the ``primaite.game.agent.actions`` module.
+    * ``action_map``: (optional). Restricts the possible combinations of action type / action parameter values to reduce the overall size of the action space. By default, every possible combination of actions and parameters will be assigned an integer for the agent's ``MultiDiscrete`` action space. Instead, the ``action_map`` allows you to list the actions corresponding to each integer in the ``MultiDiscrete`` space.
+    * ``options``: Options that apply too all action components.
+        * ``nodes``: list the nodes that the agent can act on, the order of this list defines the mapping between nodes and ``node_id`` integers.
+        * ``max_folders_per_node``, ``max_files_per_folder``, ``max_services_per_node``, ``max_nics_per_node``, ``max_acl_rules`` all are used to define the size of the action space.
+
+**reward function:**
+Similar to action space, this is defined as a list of components.
+
+Description of configurable items:
+    * ``reward_components`` a list of reward components from the ``primaite.game.agent.reward`` module.
+        * ``weight``: relative importance of this reward component. The total reward for a step is a weighted sum of all reward components.
+        * ``options``: list of options passed to the reward component during initialisation, the exact options required depend on the reward component.
+
+**agent_settings**:
+Settings passed to the agent during initialisation. These depend on the agent class.
+
+``simulation``
+--------------
+In this section the network layout is defined. This part of the config follows a hierarchical structure. Almost every component defines a ``ref`` field which acts as a human-readable unique identifier, used by other parts of the config, such as agents.
+
+At the top level of the network are ``nodes`` and ``links``.
+
+**nodes:**
+    * ``type``: one of ``router``, ``switch``, ``computer``, or ``server``, this affects what other sub-options should be defined.
+    * ``hostname`` - a non-unique name used for logging and outputs.
+    * ``num_ports`` (optional, routers and switches only): number of network interfaces present on the device.
+    * ``ports`` (optional, routers and switches only): configuration for each network interface, including IP address and subnet mask.
+    * ``acl`` (Router only): Define the ACL rules at each index of the ACL on the router. the possible options are: ``action`` (PERMIT or DENY), ``src_port``, ``dst_port``, ``protocol``, ``src_ip``, ``dst_ip``. Any options left blank default to none which usually means that it will apply across all options. For example leaving ``src_ip`` blank will apply the rule to all IP addresses.
+    * ``services`` (computers and servers only): a list of services to install on the node. They must define a ``ref``, ``type``, and ``options`` that depend on which ``type`` was selected.
+    * ``applications`` (computer and servers only): Similar to services. A list of application to install on the node.
+    * ``nics`` (computers and servers only): If the node has multiple networking devices, the second, third, fourth, etc... must be defined here with an ``ip_address`` and ``subnet_mask``.
+
+**links:**
+    * ``ref``: unique identifier for this link
+    * ``endpoint_a_ref``: Reference to the node at the first end of the link
+    * ``endpoint_a_port``: The ethernet port or switch port index of the second node
+    * ``endpoint_b_ref``: Reference to the node at the second end of the link
+    * ``endpoint_b_port``: The ethernet port or switch port index on the second node

docs/source/custom_agent.rst

@@ -1,14 +0,0 @@
-.. only:: comment
-
-    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
-
-Custom Agents
-=============
-
-
-Integrating a user defined blue agent
-*************************************
-
-.. note::
-
-    PrimAITE uses ARCD GATE for agent integration. In order to use a custom agent with PrimAITE, you must integrate it with ARCD GATE. Please look at the ARCD GATE documentation for more information.

docs/source/game_layer.rst

@@ -4,9 +4,9 @@ PrimAITE Game layer
 The Primaite codebase consists of two main modules:
 
 * ``simulator``: The simulation logic including the network topology, the network state, and behaviour of various hardware and software classes.
-* ``game``: The agent-training infrastructure which helps reinforcement learning agents interface with the simulation. This includes the observation, action, and rewards, for RL agents, but also scripted deterministic agents. The game layer orchestrates all the interactions between modules, including ARCD GATE.
+* ``game``: The agent-training infrastructure which helps reinforcement learning agents interface with the simulation. This includes the observation, action, and rewards, for RL agents, but also scripted deterministic agents. The game layer orchestrates all the interactions between modules.
 
-These two components have been decoupled to allow the agent training code in ARCD GATE to be reused with other simulators. The simulator and game layer communicate using the PrimAITE State API and the PrimAITE Request API. The game layer communicates with ARCD gate using the `Farama Gymnasium Spaces API <https://gymnasium.farama.org/api/spaces/>`_.
+ The simulator and game layer communicate using the PrimAITE State API and the PrimAITE Request API.
 
 ..
     TODO: write up these APIs and link them here.
@@ -20,13 +20,14 @@ The game layer is responsible for managing agents and getting them to interface
 PrimAITE Session
 ^^^^^^^^^^^^^^^
 
-``PrimaiteSession`` is the main entry point into Primaite and it allows the simultaneous coordination of a simulation and agents that interact with it. It also sends messages to ARCD GATE to perform reinforcement learning. ``PrimaiteSession`` keeps track of multiple agents of different types.
+``PrimaiteSession`` is the main entry point into Primaite and it allows the simultaneous coordination of a simulation and agents that interact with it. ``PrimaiteSession`` keeps track of multiple agents of different types.
 
 Agents
 ^^^^^^
 
 All agents inherit from the :py:class:`primaite.game.agent.interface.AbstractAgent` class, which mandates that they have an ObservationManager, ActionManager, and RewardManager. The agent behaviour depends on the type of agent, but there are two main types:
-* RL agents action during each step is decided by an RL algorithm which lives inside of ARCD GATE. The agent within PrimAITE just acts to format and forward actions decided by an RL policy.
+
+* RL agents action during each step is decided by an appropriate RL algorithm. The agent within PrimAITE just acts to format and forward actions decided by an RL policy.
 * Deterministic agents perform all of their decision making within the PrimAITE game layer. They typically have a scripted policy which always performs the same action or a rule-based policy which performs actions based on the current state of the simulation. They can have a stochastic element, and their seed will be settable.
 
 ..

docs/source/getting_started.rst

@@ -87,22 +87,7 @@ Install PrimAITE
 
     pip install path\to\your\primaite.whl
 
-
-5. Install ARCD GATE from wheel file
-
-
-.. code-block:: bash
-    :caption: Unix
-
-    pip install path/to/your/arcd_gate-0.1.0-py3-none-any.whl
-
-.. code-block:: powershell
-    :caption: Windows (Powershell)
-
-    pip install path\to\your\arcd_gate-0.1.0-py3-none-any.whl
-
-
-6. Perform the PrimAITE setup
+5. Perform the PrimAITE setup
 
 .. code-block:: bash
     :caption: Unix
@@ -153,17 +138,4 @@ of your choice:
 
     pip install -e .[dev]
 
-
-4. Install ARCD GATE from wheel file
-
-.. code-block:: bash
-    :caption: Unix
-
-    pip install GATE/arcd_gate-0.1.0-py3-none-any.whl
-
-.. code-block:: powershell
-    :caption: Windows (Powershell)
-
-    pip install GATE\arcd_gate-0.1.0-py3-none-any.whl
-
 To view the complete list of packages installed during PrimAITE installation, go to the dependencies page (:ref:`Dependencies`).

docs/source/glossary.rst

@@ -74,8 +74,8 @@ Glossary
     Laydown
         The laydown is a file which defines the training scenario. It contains the network topology, firewall rules, services, protocols, and details about green and red agent behaviours.
 
-    Gym
-        PrimAITE uses the Gym reinforcement learning framework API to create a training environment and interface with RL agents. Gym defines a common way of creating observations, actions, and rewards.
+    Gymnasium
+        PrimAITE uses the Gymnasium reinforcement learning framework API to create a training environment and interface with RL agents. Gymnasium defines a common way of creating observations, actions, and rewards.
 
     User app home
-        PrimAITE supports upgrading software version while retaining user data. The user data directory is where configs, notebooks, and results are stored, this location is `~/primaite<version>` on linux/darwin and `C:\Users\<username>\primaite\<version>` on Windows.
+        PrimAITE supports upgrading software version while retaining user data. The user data directory is where configs, notebooks, and results are stored, this location is `~/primaite<version>` on linux/darwin and `C:\\Users\\<username>\\primaite\\<version>` on Windows.

docs/source/request_system.rst

@@ -5,12 +5,12 @@
 Request System
 ==============
 
-``SimComponent`` in the simulation are decoupled from the agent training logic. However, they still need a managed means of accepting requests to perform actions. For this, they use ``RequestManager`` and ``RequestType``.
+``SimComponent`` objects in the simulation are decoupled from the agent training logic. However, they still need a managed means of accepting requests to perform actions. For this, they use ``RequestManager`` and ``RequestType``.
 
-Just like other aspects of SimComponent, the request typess are not managed centrally for the whole simulation, but instead they are dynamically created and updated based on the nodes, links, and other components that currently exist. This was achieved in the following way:
+Just like other aspects of SimComponent, the request types are not managed centrally for the whole simulation, but instead they are dynamically created and updated based on the nodes, links, and other components that currently exist. This was achieved in the following way:
 
 - API
-    An ``RequestType`` contains two elements:
+    A ``RequestType`` contains two elements:
 
     1. ``request`` - selects which action you want to take on this ``SimComponent``. This is formatted as a list of strings such as `['network', 'node', '<node-uuid>', 'service', '<service-uuid>', 'restart']`.
     2. ``context`` - optional extra information that can be used to decide how to process the request. This is formatted as a dictionary. For example, if the request requires authentication, the context can include information about the user that initiated the request to decide if their permissions are sufficient.

docs/source/simulation.rst

@@ -23,8 +23,3 @@ Contents
    simulation_components/network/network
    simulation_components/system/internal_frame_processing
    simulation_components/system/software
-   simulation_components/system/data_manipulation_bot
-   simulation_components/system/database_client_server
-   simulation_components/system/dns_client_server
-   simulation_components/system/ftp_client_server
-   simulation_components/system/web_browser_and_web_server_service

docs/source/simulation_components/network/base_hardware.rst

@@ -109,6 +109,67 @@ e.g.
     instant_start_node = Node(hostname="client", start_up_duration=0, shut_down_duration=0)
     instant_start_node.power_on() # node will still need to be powered on
 
+.. _Node Start up and Shut down:
+
+---------------------------
+Node Start up and Shut down
+---------------------------
+
+Nodes are powered on and off over multiple timesteps. By default, the node ``start_up_duration`` and ``shut_down_duration`` is 3 timesteps.
+
+Example code where a node is turned on:
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a")
+
+    assert node.operating_state is NodeOperatingState.OFF # By default, node is instantiated in an OFF state
+
+    node.power_on() # power on the node
+
+    assert node.operating_state is NodeOperatingState.BOOTING # node is booting up
+
+    for i in range(node.start_up_duration + 1):
+        # apply timestep until the node start up duration
+        node.apply_timestep(timestep=i)
+
+    assert node.operating_state is NodeOperatingState.ON # node is in ON state
+
+
+If the node needs to be instantiated in an on state:
+
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a", operating_state=NodeOperatingState.ON)
+
+    assert node.operating_state is NodeOperatingState.ON  # node is in ON state
+
+Setting ``start_up_duration`` and/or ``shut_down_duration`` to ``0`` will allow for the ``power_on`` and ``power_off`` methods to be completed instantly without applying timesteps:
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+
+    node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
+
+    assert node.operating_state is NodeOperatingState.OFF  # node is in OFF state
+
+    node.power_on()
+
+    assert node.operating_state is NodeOperatingState.ON  # node is in ON state
+
+    node.power_off()
+
+    assert node.operating_state is NodeOperatingState.OFF  # node is in OFF state
+
 ------------------
 Network Interfaces
 ------------------
@@ -357,7 +418,6 @@ Creating the four nodes results in:
 
     2023-08-08 15:50:08,359 INFO: Connected NIC 84:20:7c:ec:a5:c6/192.168.0.13
 
-
 ---------------
 Create Switches
 ---------------

docs/source/simulation_components/system/data_manipulation_bot.rst

@@ -16,43 +16,125 @@ The bot is intended to simulate a malicious actor carrying out attacks like:
 - Dropping tables
 - Deleting records
 - Modifying data
-On a database server by abusing an application's trusted database connectivity.
+on a database server by abusing an application's trusted database connectivity.
+
+The bot performs attacks in the following stages to simulate the real pattern of an attack:
+
+- Logon - *The bot gains credentials and accesses the node.*
+- Port Scan - *The bot finds accessible database servers on the network.*
+- Attacking - *The bot delivers the payload to the discovered database servers.*
+
+Each of these stages has a random, configurable probability of succeeding (by default 10%). The bot can also be configured to repeat the attack once complete.
 
 Usage
 -----
 
 - Create an instance and call ``configure`` to set:
-  - Target database server IP
-  - Database password (if needed)
-  - SQL statement payload
+    - Target database server IP
+    - Database password (if needed)
+    - SQL statement payload
+    - Probabilities for succeeding each of the above attack stages
 - Call ``run`` to connect and execute the statement.
 
 The bot handles connecting, executing the statement, and disconnecting.
 
+In a simulation, the bot can be controlled by using ``DataManipulationAgent`` which calls ``run`` on the bot at configured timesteps.
+
 Example
 -------
 
 .. code-block:: python
 
     client_1 = Computer(
-        hostname="client_1", ip_address="192.168.10.21", subnet_mask="255.255.255.0", default_gateway="192.168.10.1"
+        hostname="client_1",
+        ip_address="192.168.10.21",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.10.1"
+        operating_state=NodeOperatingState.ON # initialise the computer in an ON state
     )
-    client_1.power_on()
     network.connect(endpoint_b=client_1.ethernet_port[1], endpoint_a=switch_2.switch_ports[1])
     client_1.software_manager.install(DataManipulationBot)
-    data_manipulation_bot: DataManipulationBot = client_1.software_manager.software["DataManipulationBot"]
+    data_manipulation_bot: DataManipulationBot = client_1.software_manager.software.get("DataManipulationBot")
     data_manipulation_bot.configure(server_ip_address=IPv4Address("192.168.1.14"), payload="DELETE")
     data_manipulation_bot.run()
 
 This would connect to the database service at 192.168.1.14, authenticate, and execute the SQL statement to drop the 'users' table.
 
+Example with ``DataManipulationAgent``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If not using the data manipulation bot manually, it needs to be used with a data manipulation agent. Below is an example section of configuration file for setting up a simulation with data manipulation bot and agent.
+
+.. code-block:: yaml
+
+    game_config:
+      # ...
+      agents:
+        - ref: data_manipulation_red_bot
+          team: RED
+          type: RedDatabaseCorruptingAgent
+
+          observation_space:
+            type: UC2RedObservation
+            options:
+              nodes:
+                - node_ref: client_1
+                  observations:
+                  - logon_status
+                  - operating_status
+                  applications:
+                  - application_ref: data_manipulation_bot
+                    observations:
+                      operating_status
+                      health_status
+                  folders: {}
+
+          action_space:
+            action_list:
+              - type: DONOTHING
+              - type: NODE_APPLICATION_EXECUTE
+            options:
+              nodes:
+              - node_ref: client_1
+                applications:
+                  - application_ref: data_manipulation_bot
+              max_folders_per_node: 1
+              max_files_per_folder: 1
+              max_services_per_node: 1
+
+          reward_function:
+            reward_components:
+              - type: DUMMY
+
+          agent_settings:
+            start_settings:
+              start_step: 25
+              frequency: 20
+              variance: 5
+    # ...
+
+    simulation:
+      network:
+        nodes:
+        - ref: client_1
+          type: computer
+          # ... additional configuration here
+          applications:
+          - ref: data_manipulation_bot
+            type: DataManipulationBot
+            options:
+              port_scan_p_of_success: 0.1
+              data_manipulation_p_of_success: 0.1
+              payload: "DELETE"
+              server_ip: 192.168.1.14
+
 Implementation
 --------------
 
 The bot extends ``DatabaseClient`` and leverages its connectivity.
 
 - Uses the Application base class for lifecycle management.
-- Credentials and target IP set via ``configure``.
+- Credentials, target IP and other options set via ``configure``.
 - ``run`` handles connecting, executing statement, and disconnecting.
 - SQL payload executed via ``query`` method.
 - Results in malicious SQL being executed on remote database server.

docs/source/simulation_components/system/database_client_server.rst

@@ -45,17 +45,14 @@ Key features
 ^^^^^^^^^^^^
 
 - Connects to the ``DatabaseService`` via the ``SoftwareManager``.
+- Handles connecting and disconnecting.
 - Executes SQL queries and retrieves result sets.
-- Handles connecting, querying, and disconnecting.
-- Provides a simple ``query`` method for running SQL.
-
 
 Usage
 ^^^^^
 
 - Initialise with server IP address and optional password.
 - Connect to the ``DatabaseService`` with ``connect``.
-- Execute SQL queries via ``query``.
 - Retrieve results in a dictionary.
 - Disconnect when finished.
 
@@ -70,6 +67,5 @@ Implementation
 
 - Leverages ``SoftwareManager`` for sending payloads over the network.
 - Connect and disconnect methods manage sessions.
-- Provides easy interface for applications to query database.
 - Payloads serialised as dictionaries for transmission.
 - Extends base Application class.

docs/source/simulation_components/system/ftp_client_server.rst

@@ -77,6 +77,7 @@ Dependencies
     from primaite.simulator.network.hardware.nodes.server import Server
     from primaite.simulator.system.services.ftp.ftp_server import FTPServer
     from primaite.simulator.system.services.ftp.ftp_client import FTPClient
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
 
 Example peer to peer network
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -85,10 +86,18 @@ Example peer to peer network
 
     net = Network()
 
-    pc1 = Computer(hostname="pc1", ip_address="120.10.10.10", subnet_mask="255.255.255.0")
-    srv = Server(hostname="srv", ip_address="120.10.10.20", subnet_mask="255.255.255.0")
-    pc1.power_on()
-    srv.power_on()
+    pc1 = Computer(
+        hostname="pc1",
+        ip_address="120.10.10.10",
+        subnet_mask="255.255.255.0",
+        operating_state=NodeOperatingState.ON # initialise the computer in an ON state
+    )
+    srv = Server(
+        hostname="srv",
+        ip_address="120.10.10.20",
+        subnet_mask="255.255.255.0",
+        operating_state=NodeOperatingState.ON # initialise the server in an ON state
+    )
     net.connect(pc1.ethernet_port[1], srv.ethernet_port[1])
 
 Install the FTP Server

docs/source/simulation_components/system/software.rst

@@ -6,14 +6,45 @@
 Software
 ========
 
+-------------
+Base Software
+-------------
+
+All software which inherits ``IOSoftware`` installed on a node will not work unless the node has been turned on.
+
+See :ref:`Node Start up and Shut down`
+
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.base import Node
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+    from primaite.simulator.system.services.service import ServiceOperatingState
+    from primaite.simulator.system.services.web_server.web_server import WebServer
+
+    node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
+
+    node.power_on()
+    assert node.operating_state is NodeOperatingState.ON
+
+    node.software_manager.install(WebServer)
+
+    web_server: WebServer = node.software_manager.software.get("WebServer")
+    assert web_server.operating_state is ServiceOperatingState.RUNNING # service is immediately ran after install
+
+    node.power_off()
+    assert node.operating_state is NodeOperatingState.OFF
+    assert web_server.operating_state is ServiceOperatingState.STOPPED # service stops when node is powered off
+
+    node.power_on()
+    assert node.operating_state is NodeOperatingState.ON
+    assert web_server.operating_state is ServiceOperatingState.RUNNING # service turned back on when node is powered on
 
 
-
-Contents
-########
+Services, Processes and Applications:
+#####################################
 
 .. toctree::
-   :maxdepth: 8
+   :maxdepth: 2
 
    database_client_server
    data_manipulation_bot

docs/source/state_system.rst

@@ -5,9 +5,9 @@
 Simulation State
 ==============
 
-``SimComponent`` in the simulation have a method called ``describe_state`` which returns a dictionary of the state of the component. This is used to report pertinent data that could impact agent's actions or rewards. For instance, the name and health status of a node is reported, which can be used by a reward function to punish corrupted or compromised nodes and reward healthy nodes. Each ``SimComponent`` reports not only it's own attributes in the state but also that of its child components. I.e. a computer node will report the state of its ``FileSystem``, and the ``FileSystem`` will report the state of its files and folders. This happens by recursively calling childrens' own ``describe_state`` methods.
+``SimComponent`` objects in the simulation have a method called ``describe_state`` which return a dictionary of the state of the component. This is used to report pertinent data that could impact an agent's actions or rewards. For instance, the name and health status of a node is reported, which can be used by a reward function to punish corrupted or compromised nodes and reward healthy nodes. Each ``SimComponent`` object reports not only its own attributes in the state but also those of its child components. I.e. a computer node will report the state of its ``FileSystem`` and the ``FileSystem`` will report the state of its files and folders. This happens by recursively calling the childrens' own ``describe_state`` methods.
 
-The game layer calls ``describe_state`` on the trunk ``SimComponent`` (the top-level parent) and then pass the state to the agents once per simulation step. For this reason, all ``SimComponent`` must have a ``describe_state`` method, and they must all be linked to the trunk ``SimComponent``.
+The game layer calls ``describe_state`` on the trunk ``SimComponent`` (the top-level parent) and then passes the state to the agents once per simulation step. For this reason, all ``SimComponent`` objetcs must have a ``describe_state`` method, and they must all be linked to the trunk ``SimComponent``.
 
 This code snippet demonstrates how the state information is defined within the ``SimComponent`` class: