Merge origin/dev into feature/1859

docs/source/simulation_components/system/data_manipulation_bot.rst

@@ -16,8 +16,7 @@ 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:
 
@@ -47,9 +46,12 @@ 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"]

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["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