Merge branch 'dev' into feature/2706-Terminal_Sim_Component

docs/source/simulation_components/network/airspace.rst

@@ -0,0 +1,42 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _airspace:
+
+AirSpace
+========
+
+
+1. Introduction
+---------------
+
+The AirSpace class is the central component for wireless networks in PrimAITE and is designed to model and manage the behavior and interactions of wireless network interfaces within a simulated wireless network environment. This documentation provides a detailed overview of the AirSpace class, its components, and how they interact to create a realistic simulation of wireless network dynamics.
+
+2. Overview of the AirSpace System
+----------------------------------
+
+The AirSpace is a virtual representation of a physical wireless environment, managing multiple wireless network interfaces that simulate devices connected to the wireless network. These interfaces communicate over radio frequencies, with their interactions influenced by various factors modeled within the AirSpace.
+
+2.1 Key Components
+^^^^^^^^^^^^^^^^^^
+
+- **Wireless Network Interfaces**: Representations of network interfaces connected physical devices like routers, computers, or IoT devices that can send and receive data wirelessly.
+- **Bandwidth Management**: Tracks data transmission over frequencies to prevent overloading and simulate real-world network congestion.
+
+
+3. Managing Wireless Network Interfaces
+---------------------------------------
+
+- Interfaces can be dynamically added or removed.
+- Configurations can be changed in real-time.
+- The AirSpace handles data transmissions, ensuring data sent by an interface is received by all other interfaces on the same frequency.
+
+
+4. AirSpace Inspection
+----------------------
+
+The AirSpace class provides methods for visualizing network behavior:
+
+- ``show_wireless_interfaces()``: Displays current state of all interfaces
+- ``show_bandwidth_load()``: Shows bandwidth utilisation

docs/source/simulation_components/network/nodes/wireless_router.rst

@@ -37,7 +37,7 @@ additional steps to configure wireless settings:
 .. code-block:: python
 
     from primaite.simulator.network.hardware.nodes.network.wireless_router import WirelessRouter
-    from primaite.simulator.network.airspace import AirSpaceFrequency
+    from primaite.simulator.network.airspace import AirSpaceFrequency, ChannelWidth
 
     # Instantiate the WirelessRouter
     wireless_router = WirelessRouter(hostname="MyWirelessRouter")
@@ -49,7 +49,7 @@ additional steps to configure wireless settings:
     wireless_router.configure_wireless_access_point(
         port=1, ip_address="192.168.2.1",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
     )
 
 
@@ -71,7 +71,7 @@ ICMP traffic, ensuring basic network connectivity and ping functionality.
 
 .. code-block:: python
 
-    from primaite.simulator.network.airspace import AIR_SPACE, AirSpaceFrequency
+    from primaite.simulator.network.airspace import AirSpaceFrequency, ChannelWidth
     from primaite.simulator.network.container import Network
     from primaite.simulator.network.hardware.nodes.host.computer import Computer
     from primaite.simulator.network.hardware.nodes.network.router import ACLAction
@@ -130,13 +130,13 @@ ICMP traffic, ensuring basic network connectivity and ping functionality.
         port=1,
         ip_address="192.168.1.1",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
     )
     router_2.configure_wireless_access_point(
         port=1,
         ip_address="192.168.1.2",
         subnet_mask="255.255.255.0",
-        frequency=AirSpaceFrequency.WIFI_2_4
+        frequency=AirSpaceFrequency.WIFI_2_4,
     )
 
     # Configure routes for inter-router communication

docs/source/simulation_components/system/applications/dos_bot.rst

@@ -7,7 +7,10 @@
 DoSBot
 ######
 
-The ``DoSBot`` is an implementation of a Denial of Service attack within the PrimAITE simulation. This specifically simulates a `Slow Loris attack <https://en.wikipedia.org/wiki/Slowloris_(computer_security)>`.
+The ``DoSBot`` is an implementation of a Denial of Service attack within the PrimAITE simulation.
+This specifically simulates a `Slow Loris attack`_.
+
+.. _Slow Loris Attack: https://en.wikipedia.org/wiki/Slowloris_(computer_security)
 
 Key features
 ============

docs/source/simulation_components/system/applications/nmap.rst

@@ -5,10 +5,10 @@
 .. _NMAP:
 
 NMAP
-====
+####
 
 Overview
---------
+========
 
 The NMAP application is used to simulate network scanning activities. NMAP is a powerful tool that helps in discovering
 hosts and services on a network. It provides functionalities such as ping scans to discover active hosts and port scans
@@ -19,8 +19,8 @@ structure, identify active devices, and find potential vulnerabilities by discov
 However, it is also a tool frequently used by attackers during the reconnaissance stage of a cyber attack to gather
 information about the target network.
 
-Scan Types
-----------
+Scan Type
+=========
 
 Ping Scan
 ^^^^^^^^^
@@ -46,7 +46,7 @@ identifying potential entry points for attacks. There are three types of port sc
   It gives a comprehensive view of the network's service landscape.
 
 Example Usage
--------------
+^^^^^^^^^^^^^
 
 The network we use for these examples is defined below:
 
@@ -345,3 +345,11 @@ Perform a full box scan on all ports, over both TCP and UDP, on a whole subnet:
    | 192.168.1.13 | 123  | NTP             | UDP      |
    | 192.168.1.13 | 219  | ARP             | UDP      |
    +--------------+------+-----------------+----------+
+
+Configuration
+=============
+
+.. include:: ../common/common_configuration.rst
+
+.. |SOFTWARE_NAME| replace:: NMAP
+.. |SOFTWARE_NAME_BACKTICK| replace:: ``NMAP``

docs/source/simulation_components/system/applications/ransomware_script.rst

@@ -0,0 +1,85 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _RansomwareScript:
+
+RansomwareScript
+###################
+
+The RansomwareScript class provides functionality to connect to a :ref:`DatabaseService` and set a database's database.db into a ``CORRUPTED`` state.
+
+Overview
+========
+
+The ransomware script intends to simulate a generic implementation of ransomware.
+
+Currently, due to simulation restraints, the ransomware script is unable to attack a host without an active database service.
+
+The ransomware script is similar to that of the data_manipulation_bot but does not have any separate stages or configurable probabilities.
+
+Additionally, similar to the data_manipulation_bot, the ransomware script must be installed on a host with a pre-existing :ref:`DatabaseClient` application installed.
+
+Usage
+=====
+
+- Create an instance and call ``configure`` to set:
+    - Target Database IP
+    - Database password (if needed)
+- Call ``Execute`` to connect and execute the ransomware script.
+
+This application handles connections to the database server and the connection made to encrypt the database but it does not handle disconnections.
+
+Implementation
+==============
+
+Currently, the ransomware script connects to a :ref:`DatabaseClient` and leverages its connectivity. The host running ``RansomwareScript`` must also have a :ref:`DatabaseClient` installed on it.
+
+- Uses the Application base class for lifecycle management.
+- Target IP and other options set via ``configure``.
+- ``execute`` handles connecting and encrypting.
+
+
+Examples
+========
+
+Python
+""""""
+.. code-block:: python
+
+    from primaite.simulator.network.hardware.nodes.host.computer import Computer
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+    from primaite.simulator.system.applications.red_applications.RansomwareScript import RansomwareScript
+    from primaite.simulator.system.applications.database_client import DatabaseClient
+
+    client_1 = Computer(
+        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
+    )
+    network.connect(endpoint_b=client_1.network_interface[1], endpoint_a=switch_2.network_interface[1])
+    client_1.software_manager.install(DatabaseClient)
+    client_1.software_manager.install(RansomwareScript)
+    RansomwareScript: RansomwareScript = client_1.software_manager.software.get("RansomwareScript")
+    RansomwareScript.configure(server_ip_address=IPv4Address("192.168.1.14"))
+    RansomwareScript.execute()
+
+
+Configuration
+=============
+
+The RansomwareScript inherits configuration options such as ``fix_duration`` from its parent class. However, for the ``RansomwareScript`` the most relevant option is ``server_ip``.
+
+.. include:: ../common/common_configuration.rst
+
+.. |SOFTWARE_NAME| replace:: RansomwareScript
+.. |SOFTWARE_NAME_BACKTICK| replace:: ``RansomwareScript``
+
+``server_ip``
+"""""""""""""
+
+IP address of the :ref:`DatabaseService` which the ``RansomwareScript`` will encrypt.
+
+This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.

docs/source/simulation_components/system/applications/web_browser.rst

@@ -23,7 +23,7 @@ Usage
 =====
 
 - Install on a Node via the ``SoftwareManager`` to start the ``WebBrowser``.
-- Service runs on HTTP port 80 by default. (TODO: HTTPS)
+- Service runs on HTTP port 80 by default.
 - Execute sending an HTTP GET request with ``get_webpage``
 
 Implementation

docs/source/simulation_components/system/services/ftp_client.rst

@@ -87,5 +87,3 @@ Configuration
 
 .. |SOFTWARE_NAME| replace:: FTPClient
 .. |SOFTWARE_NAME_BACKTICK| replace:: ``FTPClient``
-
-**FTPClient has no configuration options**

docs/source/simulation_components/system/services/ntp_server.rst

@@ -82,5 +82,3 @@ Configuration
 
 .. |SOFTWARE_NAME| replace:: NTPServer
 .. |SOFTWARE_NAME_BACKTICK| replace:: ``NTPServer``
-
-**NTPServer has no configuration options**

docs/source/simulation_components/system/services/web_server.rst

@@ -82,5 +82,3 @@ Configuration
 
 .. |SOFTWARE_NAME| replace:: WebServer
 .. |SOFTWARE_NAME_BACKTICK| replace:: ``WebServer``
-
-**WebServer has no configuration options**