#2257: apply PR suggestions

docs/source/configuration/simulation/nodes/common/common_host_node_attributes.rst

@@ -24,7 +24,7 @@ The IP address that the |NODE| will use as the default gateway. Typically, this
 
 Optional. Default value is ``None``
 
-The IP address of the node which holds an instance of the DNS server. Some applications may use a domain name e.g. the WebBrowser (TODO: WebBrowser page)
+The IP address of the node which holds an instance of the :ref:`DNSServer`. Some applications may use a domain name e.g. the :ref:`WebBrowser`
 
 .. include:: ../software/applications.rst
 

docs/source/configuration/simulation/nodes/firewall.rst

@@ -7,7 +7,7 @@
 ``firewall``
 ============
 
-A basic representation of a network router within the simulation.
+A basic representation of a network firewall within the simulation.
 
 The firewall is similar to how :ref:`Router <router_configuration>` works, with the difference being how firewall has specific ACL rules for inbound and outbound traffic as well as firewall being limited to 3 ports.
 
@@ -133,6 +133,10 @@ example:
         ...
         acl:
             internal_inbound_acl:
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
                 22: # position 22 on ACL list
                     action: PERMIT  # allow packets that
                     src_port: ARP   # are emitted from the ARP port
@@ -155,6 +159,10 @@ example:
         ...
         acl:
             internal_outbound_acl:
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
                 22: # position 22 on ACL list
                     action: PERMIT  # allow packets that
                     src_port: ARP   # are emitted from the ARP port
@@ -178,6 +186,18 @@ example:
         ...
         acl:
             dmz_inbound_acl:
+                19: # position 19 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+                20: # position 20 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTP   # are emitted from the HTTP port
+                    dst_port: HTTP   # are going towards an HTTP port
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTPS   # are emitted from the HTTPS port
+                    dst_port: HTTPS   # are going towards an HTTPS port
                 22: # position 22 on ACL list
                     action: PERMIT  # allow packets that
                     src_port: ARP   # are emitted from the ARP port
@@ -200,6 +220,18 @@ example:
         ...
         acl:
             dmz_outbound_acl:
+                19: # position 19 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
+                20: # position 20 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTP   # are emitted from the HTTP port
+                    dst_port: HTTP   # are going towards an HTTP port
+                21: # position 21 on ACL list
+                    action: PERMIT  # allow packets that
+                    src_port: HTTPS   # are emitted from the HTTPS port
+                    dst_port: HTTPS   # are going towards an HTTPS port
                 22: # position 22 on ACL list
                     action: PERMIT  # allow packets that
                     src_port: ARP   # are emitted from the ARP port
@@ -226,6 +258,10 @@ example:
         ...
         acl:
             external_inbound_acl:
+                21: # position 19 on ACL list
+                    action: DENY  # deny packets that
+                    src_port: POSTGRES_SERVER   # are emitted from the POSTGRES_SERVER port
+                    dst_port: POSTGRES_SERVER   # are going towards an POSTGRES_SERVER port
                 22: # position 22 on ACL list
                     action: PERMIT  # allow packets that
                     src_port: ARP   # are emitted from the ARP port

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

@@ -99,7 +99,7 @@ If not using the data manipulation bot manually, it needs to be used with a data
             type: UC2RedObservation
             options:
               nodes:
-                - node_ref: client_1
+                - node_name: client_1
                   observations:
                   - logon_status
                   - operating_status
@@ -116,7 +116,7 @@ If not using the data manipulation bot manually, it needs to be used with a data
               - type: NODE_APPLICATION_EXECUTE
             options:
               nodes:
-              - node_ref: client_1
+              - node_name: client_1
                 applications:
                   - application_ref: data_manipulation_bot
               max_folders_per_node: 1

docs/source/simulation_components/system/list_of_applications.rst

@@ -1,3 +1,7 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
 .. toctree::
     :maxdepth: 1
     :glob:

docs/source/simulation_components/system/list_of_services.rst

@@ -1,3 +1,7 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
 .. toctree::
     :maxdepth: 1
     :glob:

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

@@ -12,7 +12,7 @@ The ``DatabaseService`` provides a SQL database server simulation by extending t
 Key capabilities
 ================
 
-- Creates a database file in the ``Node`` 's ``FileSystem`` upon creation.
+- Creates a database file in the ``FileSystem`` of the ``Node`` (which the ``DatabaseService`` is installed on) upon creation.
 - Handles connecting clients by maintaining a dictionary of connections mapped to session IDs.
 - Authenticates connections using a configurable password.
 - Simulates ``SELECT``, ``DELETE`` and ``INSERT`` SQL queries.

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

@@ -20,6 +20,7 @@ Key features
     - RETR: retrieves a file from the FTP server
     - QUIT: disconnect from server
 - Leverages the Service base class for install/uninstall, status tracking, etc.
+- :ref:`FTPClient` and ``FTPServer`` utilise port 21 (FTP) throughout all file transfer / request
 
 Usage
 =====
@@ -52,7 +53,7 @@ Python
         hostname="server",
         ip_address="192.168.2.2",
         subnet_mask="255.255.255.0",
-        default_gateway="192.168.1.1Ó",
+        default_gateway="192.168.1.10",
         start_up_duration=0,
     )
     server.power_on()

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

@@ -17,12 +17,13 @@ Key capabilities
     - STOR: stores a file from client to server
     - RETR: retrieves a file from the FTP server
 - Leverages the Service base class for install/uninstall, status tracking, etc.
+- :ref:`FTPClient` and ``FTPServer`` utilise port 21 (FTP) throughout all file transfer / request
 
 Usage
 =====
 
 - Install on a Node via the ``SoftwareManager`` to start the FTP server service.
-- Service runs on FTP (command) port 21 by default. (TODO: look at in depth implementation of FTP PORT command)
+- Service runs on FTP (command) port 21 by default
 
 Implementation
 ==============

src/primaite/game/agent/rewards.py

@@ -13,7 +13,7 @@ the structure:
             - type: DATABASE_FILE_INTEGRITY
             weight: 0.5
             options:
-                node_ref: database_server
+                node_name: database_server
                 folder_name: database
                 file_name: database.db
 
@@ -21,7 +21,7 @@ the structure:
             - type: WEB_SERVER_404_PENALTY
             weight: 0.5
             options:
-                node_ref: web_server
+                node_name: web_server
                 service_ref: web_server_database_client
 ```
 """
@@ -184,7 +184,7 @@ class WebServer404Penalty(AbstractReward):
         service_name = config.get("service_name")
         if not (node_hostname and service_name):
             msg = (
-                f"{cls.__name__} could not be initialised from config because node_ref and service_ref were not "
+                f"{cls.__name__} could not be initialised from config because node_name and service_ref were not "
                 "found in reward config."
             )
             _LOGGER.warning(msg)

src/primaite/simulator/network/hardware/nodes/network/firewall.py

@@ -497,66 +497,66 @@ class Firewall(Router):
     @classmethod
     def from_config(cls, cfg: dict) -> "Firewall":
         """Create a firewall based on a config dict."""
-        new = Firewall(hostname=cfg["hostname"], operating_state=NodeOperatingState.ON)
+        firewall = Firewall(hostname=cfg["hostname"], operating_state=NodeOperatingState.ON)
         if "ports" in cfg:
             internal_port = cfg["ports"]["internal_port"]
             external_port = cfg["ports"]["external_port"]
             dmz_port = cfg["ports"]["dmz_port"]
 
             # configure internal port
-            new.configure_internal_port(
+            firewall.configure_internal_port(
                 ip_address=IPV4Address(internal_port.get("ip_address")),
                 subnet_mask=IPV4Address(internal_port.get("subnet_mask", "255.255.255.0")),
             )
 
             # configure external port
-            new.configure_external_port(
+            firewall.configure_external_port(
                 ip_address=IPV4Address(external_port.get("ip_address")),
                 subnet_mask=IPV4Address(external_port.get("subnet_mask", "255.255.255.0")),
             )
 
             # configure dmz port
-            new.configure_dmz_port(
+            firewall.configure_dmz_port(
                 ip_address=IPV4Address(dmz_port.get("ip_address")),
                 subnet_mask=IPV4Address(dmz_port.get("subnet_mask", "255.255.255.0")),
             )
         if "acl" in cfg:
             # acl rules for internal_inbound_acl
             if cfg["acl"]["internal_inbound_acl"]:
-                new.internal_inbound_acl.max_acl_rules
+                firewall.internal_inbound_acl.max_acl_rules
-                new.internal_inbound_acl._default_config = cfg["acl"]["internal_inbound_acl"]
+                firewall.internal_inbound_acl._default_config = cfg["acl"]["internal_inbound_acl"]
-                new.internal_inbound_acl._reset_rules_to_default()
+                firewall.internal_inbound_acl._reset_rules_to_default()
 
             # acl rules for internal_outbound_acl
             if cfg["acl"]["internal_outbound_acl"]:
-                new.internal_outbound_acl._default_config = cfg["acl"]["internal_outbound_acl"]
+                firewall.internal_outbound_acl._default_config = cfg["acl"]["internal_outbound_acl"]
-                new.internal_outbound_acl._reset_rules_to_default()
+                firewall.internal_outbound_acl._reset_rules_to_default()
 
             # acl rules for dmz_inbound_acl
             if cfg["acl"]["dmz_inbound_acl"]:
-                new.dmz_inbound_acl._default_config = cfg["acl"]["dmz_inbound_acl"]
+                firewall.dmz_inbound_acl._default_config = cfg["acl"]["dmz_inbound_acl"]
-                new.dmz_inbound_acl._reset_rules_to_default()
+                firewall.dmz_inbound_acl._reset_rules_to_default()
 
             # acl rules for dmz_outbound_acl
             if cfg["acl"]["dmz_outbound_acl"]:
-                new.dmz_outbound_acl._default_config = cfg["acl"]["dmz_outbound_acl"]
+                firewall.dmz_outbound_acl._default_config = cfg["acl"]["dmz_outbound_acl"]
-                new.dmz_outbound_acl._reset_rules_to_default()
+                firewall.dmz_outbound_acl._reset_rules_to_default()
 
             # acl rules for external_inbound_acl
             if cfg["acl"]["external_inbound_acl"]:
-                new.external_inbound_acl._default_config = cfg["acl"]["external_inbound_acl"]
+                firewall.external_inbound_acl._default_config = cfg["acl"]["external_inbound_acl"]
-                new.external_inbound_acl._reset_rules_to_default()
+                firewall.external_inbound_acl._reset_rules_to_default()
 
             # acl rules for external_outbound_acl
             if cfg["acl"]["external_outbound_acl"]:
-                new.external_outbound_acl._default_config = cfg["acl"]["external_outbound_acl"]
+                firewall.external_outbound_acl._default_config = cfg["acl"]["external_outbound_acl"]
-                new.external_outbound_acl._reset_rules_to_default()
+                firewall.external_outbound_acl._reset_rules_to_default()
         if "routes" in cfg:
             for route in cfg.get("routes"):
-                new.route_table.add_route(
+                firewall.route_table.add_route(
                     address=IPv4Address(route.get("address")),
                     subnet_mask=IPv4Address(route.get("subnet_mask", "255.255.255.0")),
                     next_hop_ip_address=IPv4Address(route.get("next_hop_ip_address")),
                     metric=float(route.get("metric", 0)),
                 )
-        return new
+        return firewall

src/primaite/simulator/network/hardware/nodes/network/router.py

@@ -1480,27 +1480,27 @@ class Router(NetworkNode):
         :return: Configured router.
         :rtype: Router
         """
-        new = Router(
+        router = Router(
             hostname=cfg["hostname"],
             num_ports=int(cfg.get("num_ports", "5")),
             operating_state=NodeOperatingState.ON,
         )
         if "ports" in cfg:
             for port_num, port_cfg in cfg["ports"].items():
-                new.configure_port(
+                router.configure_port(
                     port=port_num,
                     ip_address=port_cfg["ip_address"],
                     subnet_mask=IPv4Address(port_cfg.get("subnet_mask", "255.255.255.0")),
                 )
         if "acl" in cfg:
-            new.acl._default_config = cfg["acl"]  # save the config to allow resetting
+            router.acl._default_config = cfg["acl"]  # save the config to allow resetting
-            new.acl._reset_rules_to_default()  # read the config and apply rules
+            router.acl._reset_rules_to_default()  # read the config and apply rules
         if "routes" in cfg:
             for route in cfg.get("routes"):
-                new.route_table.add_route(
+                router.route_table.add_route(
                     address=IPv4Address(route.get("address")),
                     subnet_mask=IPv4Address(route.get("subnet_mask", "255.255.255.0")),
                     next_hop_ip_address=IPv4Address(route.get("next_hop_ip_address")),
                     metric=float(route.get("metric", 0)),
                 )
-        return new
+        return router