Merge branch 'dev' into feature/2712-Terminal_Login_Handling
This commit is contained in:
Charlie Crane
@@ -123,6 +123,7 @@ Head over to the :ref:`getting-started` page to install and setup PrimAITE!
|
||||
source/environment
|
||||
source/customising_scenarios
|
||||
source/varying_config_files
|
||||
source/action_masking
|
||||
|
||||
.. toctree::
|
||||
:caption: Notebooks:
|
||||
|
||||
80
docs/source/action_masking.rst
Normal file
80
docs/source/action_masking.rst
Normal file
@@ -0,0 +1,80 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
|
||||
|
||||
Action Masking
|
||||
**************
|
||||
The PrimAITE simulation is able to provide action masks in the environment output. These action masks let the agents know
|
||||
about which actions are invalid based on the current environment state. For instance, it's not possible to install
|
||||
software on a node that is turned off. Therefore, if an agent has a NODE_SOFTWARE_INSTALL in it's action map for that node,
|
||||
the action mask will show `0` in the corresponding entry.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
Action masking is supported for agents that use the `ProxyAgent` class (the class used for connecting to RL algorithms).
|
||||
In order to use action masking, set the agent_settings.action_masking parameter to True in the config file.
|
||||
|
||||
Masking Logic
|
||||
=============
|
||||
The following logic is applied:
|
||||
|
||||
* **DONOTHING** : Always possible
|
||||
* **NODE_HOST_SERVICE_SCAN** : Node is on. Service is running.
|
||||
* **NODE_HOST_SERVICE_STOP** : Node is on. Service is running.
|
||||
* **NODE_HOST_SERVICE_START** : Node is on. Service is stopped.
|
||||
* **NODE_HOST_SERVICE_PAUSE** : Node is on. Service is running.
|
||||
* **NODE_HOST_SERVICE_RESUME** : Node is on. Service is paused.
|
||||
* **NODE_HOST_SERVICE_RESTART** : Node is on. Service is running.
|
||||
* **NODE_HOST_SERVICE_DISABLE** : Node is on.
|
||||
* **NODE_HOST_SERVICE_ENABLE** : Node is on. Service is disabled.
|
||||
* **NODE_HOST_SERVICE_FIX** : Node is on. Service is running.
|
||||
* **NODE_HOST_APPLICATION_EXECUTE** : Node is on.
|
||||
* **NODE_HOST_APPLICATION_SCAN** : Node is on. Application is running.
|
||||
* **NODE_HOST_APPLICATION_CLOSE** : Node is on. Application is running.
|
||||
* **NODE_HOST_APPLICATION_FIX** : Node is on. Application is running.
|
||||
* **NODE_HOST_APPLICATION_INSTALL** : Node is on.
|
||||
* **NODE_HOST_APPLICATION_REMOVE** : Node is on.
|
||||
* **NODE_HOST_FILE_SCAN** : Node is on. File exists. File not deleted.
|
||||
* **NODE_HOST_FILE_CREATE** : Node is on.
|
||||
* **NODE_HOST_FILE_CHECKHASH** : Node is on. File exists. File not deleted.
|
||||
* **NODE_HOST_FILE_DELETE** : Node is on. File exists.
|
||||
* **NODE_HOST_FILE_REPAIR** : Node is on. File exists. File not deleted.
|
||||
* **NODE_HOST_FILE_RESTORE** : Node is on. File exists. File is deleted.
|
||||
* **NODE_HOST_FILE_CORRUPT** : Node is on. File exists. File not deleted.
|
||||
* **NODE_HOST_FILE_ACCESS** : Node is on. File exists. File not deleted.
|
||||
* **NODE_HOST_FOLDER_CREATE** : Node is on.
|
||||
* **NODE_HOST_FOLDER_SCAN** : Node is on. Folder exists. Folder not deleted.
|
||||
* **NODE_HOST_FOLDER_CHECKHASH** : Node is on. Folder exists. Folder not deleted.
|
||||
* **NODE_HOST_FOLDER_REPAIR** : Node is on. Folder exists. Folder not deleted.
|
||||
* **NODE_HOST_FOLDER_RESTORE** : Node is on. Folder exists. Folder is deleted.
|
||||
* **NODE_HOST_OS_SCAN** : Node is on.
|
||||
* **NODE_HOST_NIC_ENABLE** : NIC is disabled. Node is on.
|
||||
* **NODE_HOST_NIC_DISABLE** : NIC is enabled. Node is on.
|
||||
* **NODE_HOST_SHUTDOWN** : Node is on.
|
||||
* **NODE_HOST_STARTUP** : Node is off.
|
||||
* **NODE_HOST_RESET** : Node is on.
|
||||
* **NODE_HOST_NMAP_PING_SCAN** : Node is on.
|
||||
* **NODE_HOST_NMAP_PORT_SCAN** : Node is on.
|
||||
* **NODE_HOST_NMAP_NETWORK_SERVICE_RECON** : Node is on.
|
||||
* **NODE_ROUTER_PORT_ENABLE** : Router is on.
|
||||
* **NODE_ROUTER_PORT_DISABLE** : Router is on.
|
||||
* **NODE_ROUTER_ACL_ADDRULE** : Router is on.
|
||||
* **NODE_ROUTER_ACL_REMOVERULE** : Router is on.
|
||||
* **NODE_FIREWALL_PORT_ENABLE** : Firewall is on.
|
||||
* **NODE_FIREWALL_PORT_DISABLE** : Firewall is on.
|
||||
* **NODE_FIREWALL_ACL_ADDRULE** : Firewall is on.
|
||||
* **NODE_FIREWALL_ACL_REMOVERULE** : Firewall is on.
|
||||
|
||||
|
||||
Mechanism
|
||||
=========
|
||||
The environment iterates over the RL agent's ``action_map`` and generates the corresponding simulator request string.
|
||||
It uses the ``RequestManager.check_valid()`` method to invoke the relevant ``RequestPermissionValidator`` without
|
||||
actually running the request on the simulation.
|
||||
|
||||
Current Limitations
|
||||
===================
|
||||
Currently, action masking only considers whether the action as a whole is possible, it doesn't verify that the exact
|
||||
parameter combination passed to the action make sense in the current context. For instance, if ACL rule 3 on router_1 is
|
||||
already populated, the action for adding another rule at position 3 will be available regardless, as long as that router
|
||||
is turned on. This will never block valid actions. It will just occasionally allow invalid actions.
|
||||
@@ -18,8 +18,11 @@ This section configures how PrimAITE saves data during simulation and training.
|
||||
save_step_metadata: False
|
||||
save_pcap_logs: False
|
||||
save_sys_logs: False
|
||||
save_agent_logs: False
|
||||
write_sys_log_to_terminal: False
|
||||
write_agent_log_to_terminal: False
|
||||
sys_log_level: WARNING
|
||||
agent_log_level: INFO
|
||||
|
||||
|
||||
``save_logs``
|
||||
@@ -57,6 +60,12 @@ Optional. Default value is ``False``.
|
||||
|
||||
If ``True``, then the log files which contain all node actions during the simulation will be saved.
|
||||
|
||||
``save_agent_logs``
|
||||
-----------------
|
||||
|
||||
Optional. Default value is ``False``.
|
||||
|
||||
If ``True``, then the log files which contain all human readable agent behaviour during the simulation will be saved.
|
||||
|
||||
``write_sys_log_to_terminal``
|
||||
-----------------------------
|
||||
@@ -65,16 +74,25 @@ Optional. Default value is ``False``.
|
||||
|
||||
If ``True``, PrimAITE will print sys log to the terminal.
|
||||
|
||||
``write_agent_log_to_terminal``
|
||||
-----------------------------
|
||||
|
||||
``sys_log_level``
|
||||
-------------
|
||||
Optional. Default value is ``False``.
|
||||
|
||||
If ``True``, PrimAITE will print all human readable agent behaviour logs to the terminal.
|
||||
|
||||
|
||||
``sys_log_level & agent_log_level``
|
||||
---------------------------------
|
||||
|
||||
Optional. Default value is ``WARNING``.
|
||||
|
||||
The level of logging that should be visible in the sys logs or the logs output to the terminal.
|
||||
The level of logging that should be visible in the syslog, agent logs or the logs output to the terminal.
|
||||
|
||||
``save_sys_logs`` or ``write_sys_log_to_terminal`` has to be set to ``True`` for this setting to be used.
|
||||
|
||||
This is also true for agent behaviour logging.
|
||||
|
||||
Available options are:
|
||||
|
||||
- ``DEBUG``: Debug level items and the items below
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
==============
|
||||
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``.
|
||||
At the top level of the network are ``nodes``, ``links`` and ``airspace``.
|
||||
|
||||
e.g.
|
||||
|
||||
@@ -19,6 +19,9 @@ e.g.
|
||||
...
|
||||
links:
|
||||
...
|
||||
airspace:
|
||||
...
|
||||
|
||||
|
||||
``nodes``
|
||||
---------
|
||||
@@ -101,3 +104,27 @@ This accepts an integer value e.g. if port 1 is to be connected, the configurati
|
||||
``bandwidth``
|
||||
|
||||
This is an integer value specifying the allowed bandwidth across the connection. Units are in Mbps.
|
||||
|
||||
``airspace``
|
||||
------------
|
||||
|
||||
This section configures settings specific to the wireless network's virtual airspace.
|
||||
|
||||
``frequency_max_capacity_mbps``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This setting allows the user to override the default maximum bandwidth capacity set for each frequency. The key should
|
||||
be the AirSpaceFrequency name and the value be the desired maximum bandwidth capacity in mbps (megabits per second) for
|
||||
a single timestep.
|
||||
|
||||
The below example would permit 123.45 megabits to be transmit across the WiFi 2.4 GHz frequency in a single timestep.
|
||||
Setting a frequencies max capacity to 0.0 blocks that frequency on the airspace.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
simulation:
|
||||
network:
|
||||
airspace:
|
||||
frequency_max_capacity_mbps:
|
||||
WIFI_2_4: 123.45
|
||||
WIFI_5: 0.0
|
||||
|
||||
@@ -27,6 +27,7 @@ Contents
|
||||
simulation_components/network/nodes/firewall
|
||||
simulation_components/network/switch
|
||||
simulation_components/network/network
|
||||
simulation_components/network/airspace
|
||||
simulation_components/system/internal_frame_processing
|
||||
simulation_components/system/sys_log
|
||||
simulation_components/system/pcap
|
||||
|
||||
42
docs/source/simulation_components/network/airspace.rst
Normal file
42
docs/source/simulation_components/network/airspace.rst
Normal file
@@ -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
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user