From d282575467257bd3fe8095fe7dcd2f2b7cd5f3a6 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Wed, 4 Sep 2024 12:07:32 +0100 Subject: [PATCH 01/12] #2837 - Updating the User Guide as per review comments. [skip ci] --- .../nodes/common/common_node_attributes.rst | 9 +++----- docs/source/primaite-dependencies.rst | 10 ++++---- .../network/nodes/wireless_router.rst | 2 +- .../system/applications/c2_suite.rst | 20 ++++++++-------- .../system/common/common_configuration.rst | 8 +++---- .../system/services/terminal.rst | 23 +++++++++++++------ .../Command-&-Control-E2E-Demonstration.ipynb | 10 ++++---- 7 files changed, 43 insertions(+), 39 deletions(-) diff --git a/docs/source/configuration/simulation/nodes/common/common_node_attributes.rst b/docs/source/configuration/simulation/nodes/common/common_node_attributes.rst index 7cf11eb4..6a95911f 100644 --- a/docs/source/configuration/simulation/nodes/common/common_node_attributes.rst +++ b/docs/source/configuration/simulation/nodes/common/common_node_attributes.rst @@ -58,7 +58,7 @@ The number of time steps required to occur in order for the node to cycle from ` --------- The list of pre-existing users that are additional to the default admin user (``username=admin``, ``password=admin``). -Additional users are configured as an array nd must contain a ``username``, ``password``, and can contain an optional +Additional users are configured as an array and must contain a ``username``, ``password``, and can contain an optional boolean ``is_admin``. Example of adding two additional users to a node: @@ -68,11 +68,8 @@ Example of adding two additional users to a node: simulation: network: nodes: - - hostname: client_1 - type: computer - ip_address: 192.168.10.11 - subnet_mask: 255.255.255.0 - default_gateway: 192.168.10.1 + - hostname: [hostname] + type: [Node Type] users: - username: jane.doe password: '1234' diff --git a/docs/source/primaite-dependencies.rst b/docs/source/primaite-dependencies.rst index 04987054..8367ee61 100644 --- a/docs/source/primaite-dependencies.rst +++ b/docs/source/primaite-dependencies.rst @@ -7,7 +7,7 @@ +===================+=========+====================================+=======================================================================================================+====================================================================+ | gymnasium | 0.28.1 | MIT License | A standard API for reinforcement learning and a diverse set of reference environments (formerly Gym). | https://farama.org | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ -| ipywidgets | 8.1.3 | BSD License | Jupyter interactive widgets | http://jupyter.org | +| ipywidgets | 8.1.5 | BSD License | Jupyter interactive widgets | http://jupyter.org | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ | jupyterlab | 3.6.1 | BSD License | JupyterLab computational environment | https://jupyter.org | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ @@ -23,7 +23,7 @@ +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ | plotly | 5.15.0 | MIT License | An open-source, interactive data visualization library for Python | https://plotly.com/python/ | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ -| polars | 0.18.4 | MIT License | Blazingly fast DataFrame library | https://www.pola.rs/ | +| polars | 0.20.30 | MIT License | Blazingly fast DataFrame library | https://www.pola.rs/ | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ | prettytable | 3.8.0 | BSD License (BSD (3 clause)) | A simple Python library for easily displaying tabular data in a visually appealing ASCII table format | https://github.com/jazzband/prettytable | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ @@ -31,7 +31,7 @@ +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ | PyYAML | 6.0 | MIT License | YAML parser and emitter for Python | https://pyyaml.org/ | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ -| ray | 2.23.0 | Apache 2.0 | Ray provides a simple, universal API for building distributed applications. | https://github.com/ray-project/ray | +| ray | 2.32.0 | Apache 2.0 | Ray provides a simple, universal API for building distributed applications. | https://github.com/ray-project/ray | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ | stable-baselines3 | 2.1.0 | MIT | Pytorch version of Stable Baselines, implementations of reinforcement learning algorithms. | https://github.com/DLR-RM/stable-baselines3 | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ @@ -39,7 +39,7 @@ +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ | typer | 0.9.0 | MIT License | Typer, build great CLIs. Easy to code. Based on Python type hints. | https://github.com/tiangolo/typer | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ -| Deepdiff | 7.0.1 | MIT License | Deep difference of dictionaries, iterables, strings, and any other object objects. | https://github.com/seperman/deepdiff | +| Deepdiff | 8.0.1 | MIT License | Deep difference of dictionaries, iterables, strings, and any other object objects. | https://github.com/seperman/deepdiff | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ -| sb3_contrib | 2.3.0 | MIT License | Contrib package for Stable-Baselines3 - Experimental reinforcement learning (RL) code (Action Masking)| https://github.com/Stable-Baselines-Team/stable-baselines3-contrib | +| sb3_contrib | 2.1.0 | MIT License | Contrib package for Stable-Baselines3 - Experimental reinforcement learning (RL) code (Action Masking)| https://github.com/Stable-Baselines-Team/stable-baselines3-contrib | +-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+ diff --git a/docs/source/simulation_components/network/nodes/wireless_router.rst b/docs/source/simulation_components/network/nodes/wireless_router.rst index c78c8419..80f0e124 100644 --- a/docs/source/simulation_components/network/nodes/wireless_router.rst +++ b/docs/source/simulation_components/network/nodes/wireless_router.rst @@ -3,7 +3,7 @@ © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK ###### -Router +Wireless Router ###### The ``WirelessRouter`` class extends the functionality of the standard ``Router`` class within PrimAITE, diff --git a/docs/source/simulation_components/system/applications/c2_suite.rst b/docs/source/simulation_components/system/applications/c2_suite.rst index 034158d7..5fd1021e 100644 --- a/docs/source/simulation_components/system/applications/c2_suite.rst +++ b/docs/source/simulation_components/system/applications/c2_suite.rst @@ -7,8 +7,8 @@ Command and Control Application Suite ##################################### -Comprising of two applications, the Command and Control (C2) suites intends to introduce -malicious network architecture and begin to further the realism of red agents within primAITE. +Comprising of two applications, the Command and Control (C2) suite intends to introduce +malicious network architecture and further the realism of red agents within PrimAITE. Overview: ========= @@ -24,7 +24,7 @@ The C2 Server application is intended to represent the malicious infrastructure The C2 Server is configured to listen and await ``keep alive`` traffic from a C2 beacon. Once received the C2 Server is able to send and receive C2 commands. -Currently, the C2 Server offers three commands: +Currently, the C2 Server offers four commands: +---------------------+---------------------------------------------------------------------------+ |C2 Command | Meaning | @@ -40,12 +40,12 @@ Currently, the C2 Server offers three commands: It's important to note that in order to keep PrimAITE realistic from a cyber perspective, -The C2 Server application should never be visible or actionable upon directly by the blue agent. +the C2 Server application should never be visible or actionable upon directly by the blue agent. This is because in the real world, C2 servers are hosted on ephemeral public domains that would not be accessible by private network blue agent. Therefore granting blue agent(s) the ability to perform counter measures directly against the application would be unrealistic. -It is more accurate to see the host that the C2 Server is installed on as being able to route to the C2 Server (Internet Access). +It is more accurate to see the host that the C2 Beacon is installed on as being able to route to the C2 Server (Internet Access). ``C2 Beacon`` """"""""""""" @@ -54,19 +54,19 @@ The C2 Beacon application is intended to represent malware that is used to estab A C2 Beacon will need to be first configured with the C2 Server IP Address which can be done via the ``configure`` method. -Once installed and configured; the c2 beacon can establish connection with the C2 Server via executing the application. +Once installed and configured; the C2 beacon can establish connection with the C2 Server via executing the application. This will send an initial ``keep alive`` to the given C2 Server (The C2 Server IPv4Address must be given upon C2 Beacon configuration). -Which is then resolved and responded by another ``Keep Alive`` by the c2 server back to the C2 beacon to confirm connection. +Which is then resolved and responded by another ``Keep Alive`` by the C2 server back to the C2 beacon to confirm connection. -The C2 Beacon will send out periodic keep alive based on it's configuration parameters to configure it's active connection with the c2 server. +The C2 Beacon will send out periodic keep alive based on it's configuration parameters to configure it's active connection with the C2 server. It's recommended that a C2 Beacon is installed and configured mid episode by a Red Agent for a more cyber realistic simulation. Usage ===== -As mentioned, the C2 Suite is intended to grant Red Agents further flexibility whilst also expanding a blue agent's observation_space. +As mentioned, the C2 Suite is intended to grant Red Agents further flexibility whilst also expanding a blue agent's observation space. Adding to this, the following behaviour of the C2 beacon can be configured by users for increased domain randomisation: @@ -301,7 +301,7 @@ What port that the C2 Beacon will use to communicate to the C2 Server with. Currently only ``FTP``, ``HTTP`` and ``DNS`` are valid masquerade port options. -It's worth noting that this may be useful option to bypass ACL rules. +It's worth noting that this may be a useful option to bypass ACL rules. This must be a string i.e ``DNS``. Defaults to ``HTTP``. diff --git a/docs/source/simulation_components/system/common/common_configuration.rst b/docs/source/simulation_components/system/common/common_configuration.rst index 420166dd..49e3188b 100644 --- a/docs/source/simulation_components/system/common/common_configuration.rst +++ b/docs/source/simulation_components/system/common/common_configuration.rst @@ -30,7 +30,7 @@ The number of timesteps the |SOFTWARE_NAME| will remain in a ``FIXING`` state be ``listen_on_ports`` """"""""""""""""""" -The set of ports to listen on. This is in addition to the main port the software is designated. This set can either be +The set of ports to listen on. This is in addition to the main port the software is designated. This can either be the string name of ports or the port integers Example: @@ -46,14 +46,12 @@ Example: subnet_mask: 255.255.255.0 default_gateway: 192.168.10.1 services: - - type: DatabaseService + - type: [Service Type] options: - backup_server_ip: 10.10.1.12 listen_on_ports: - 631 applications: - - type: WebBrowser + - type: [Application Type] options: - target_url: http://sometech.ai listen_on_ports: - SMB diff --git a/docs/source/simulation_components/system/services/terminal.rst b/docs/source/simulation_components/system/services/terminal.rst index f982145d..9db2ac7a 100644 --- a/docs/source/simulation_components/system/services/terminal.rst +++ b/docs/source/simulation_components/system/services/terminal.rst @@ -23,13 +23,6 @@ Key capabilities - Simulates common Terminal processes/commands. - Leverages the Service base class for install/uninstall, status tracking etc. -Usage -""""" - - - Pre-Installs on any `Node` (component with the exception of `Switches`). - - Terminal Clients connect, execute commands and disconnect from remote nodes. - - Ensures that users are logged in to the component before executing any commands. - - Service runs on SSH port 22 by default. Implementation """""""""""""" @@ -40,6 +33,14 @@ Implementation - A detailed guide on the implementation and functionality of the Terminal class can be found in the "Terminal-Processing" jupyter notebook. +Usage +""""" + + - Pre-Installs on all ``Node`` (with the exception of ``Switch``). + - Terminal Clients connect, execute commands and disconnect from remote nodes. + - Ensures that users are logged in to the component before executing any commands. + - Service runs on SSH port 22 by default. + Usage ===== @@ -172,3 +173,11 @@ Disconnect from Remote Node term_a_term_b_remote_connection: RemoteTerminalConnection = terminal_a.login(username="admin", password="Admin123!", ip_address="192.168.0.11") term_a_term_b_remote_connection.disconnect() + +Configuration +============= + +.. include:: ../common/common_configuration.rst + +.. |SOFTWARE_NAME| replace:: Terminal +.. |SOFTWARE_NAME_BACKTICK| replace:: ``Terminal`` \ No newline at end of file diff --git a/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb b/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb index b6b13f28..4e36db17 100644 --- a/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb +++ b/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb @@ -188,7 +188,7 @@ "source": [ "## **Notebook Setup** | Network Prerequisites\n", "\n", - "Before the Red Agent is able to perform any C2 specific actions, the C2 Server needs to be installed and run before the Red Agent can perform any C2 specific action.\n", + "Before the Red Agent is able to perform any C2 specific actions, the C2 Server needs to be installed and run.\n", "This is because in higher fidelity environments (and the real-world) a C2 server would not be accessible by a private network blue agent and the C2 Server would already be in place before the an adversary (Red Agent) starts.\n", "\n", "The cells below install and run the C2 Server on client_1 directly via the simulation API." @@ -1164,7 +1164,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now we are unable to do so as the C2 Server is unable has lost it's connection to the C2 Beacon:" + "Now we are unable to do so as the C2 Server has lost it's connection to the C2 Beacon:" ] }, { @@ -1276,7 +1276,7 @@ "source": [ "#### Blocking C2 Traffic via ACL.\n", "\n", - "Another potential option a blue agent could take is by placing an ACL rule which blocks traffic between the C2 Server can C2 Beacon.\n", + "Another potential option a blue agent could take is by placing an ACL rule which blocks traffic between the C2 Server and C2 Beacon.\n", "\n", "It's worth noting the potential effectiveness of this approach is connected to the current green agent traffic on the network. For example, if there are multiple green agents using the C2 Beacon's host node then blocking all traffic would lead to a negative reward. The same applies for the previous example." ] @@ -1450,7 +1450,7 @@ "source": [ "### **Command and Control** | Configurability | C2 Server IP Address\n", "\n", - "As with a majority of client and server based application configuration in primaite, the remote IP of server must be supplied.\n", + "As with a majority of client and server based application configuration in primaite, the remote IP of a server must be supplied.\n", "\n", "In the case of the C2 Beacon, the C2 Server's IP address must be supplied before the C2 beacon will be able to perform any other actions (including ``APPLICATION EXECUTE``).\n", "\n", @@ -1727,7 +1727,7 @@ "\n", "\n", "\n", - "The next set of code cells will demonstrate the impact this option from a blue agent perspective." + "The next set of code cells will demonstrate the impact of this option from a blue agent perspective." ] }, { From b3080100fd9883edffa6141c986109cb4fe8441c Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Wed, 4 Sep 2024 12:08:12 +0100 Subject: [PATCH 02/12] #2837 - Updating the User Guide as per review comments. [skip ci] --- docs/source/simulation_components/system/services/terminal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/simulation_components/system/services/terminal.rst b/docs/source/simulation_components/system/services/terminal.rst index 9db2ac7a..041169b1 100644 --- a/docs/source/simulation_components/system/services/terminal.rst +++ b/docs/source/simulation_components/system/services/terminal.rst @@ -180,4 +180,4 @@ Configuration .. include:: ../common/common_configuration.rst .. |SOFTWARE_NAME| replace:: Terminal -.. |SOFTWARE_NAME_BACKTICK| replace:: ``Terminal`` \ No newline at end of file +.. |SOFTWARE_NAME_BACKTICK| replace:: ``Terminal`` From f0cc821ff85b2f2cfbeef76cf416f7b73a8e0f84 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Wed, 4 Sep 2024 14:12:10 +0100 Subject: [PATCH 03/12] #2837 - Updates to some more documentation files to cover new features [skip ci] --- CHANGELOG.md | 3 ++- docs/source/configuration/agents.rst | 5 +++++ docs/source/configuration/game.rst | 6 ++++++ 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d08974c..3c4b949a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,8 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [3.3.0] - 2024-08-30 + ### Added - Random Number Generator Seeding by specifying a random number seed in the config file. - Implemented Terminal service class, providing a generic terminal simulation. diff --git a/docs/source/configuration/agents.rst b/docs/source/configuration/agents.rst index 2fe35ac7..39a71fb5 100644 --- a/docs/source/configuration/agents.rst +++ b/docs/source/configuration/agents.rst @@ -172,3 +172,8 @@ The amount of timesteps that the frequency can randomly change. --------------- If ``True``, gymnasium flattening will be performed on the observation space before sending to the agent. Set this to ``True`` if your agent does not support nested observation spaces. + +``Agent History`` +----------------- + +Agents will record their action log for each step. This is a summary of what the agent did, along with response information from requests within the simulation. \ No newline at end of file diff --git a/docs/source/configuration/game.rst b/docs/source/configuration/game.rst index 02ee8110..1d08b8e4 100644 --- a/docs/source/configuration/game.rst +++ b/docs/source/configuration/game.rst @@ -28,6 +28,7 @@ This section defines high-level settings that apply across the game, currently i high: 10 medium: 5 low: 0 + seed: 1 ``max_episode_length`` ---------------------- @@ -54,3 +55,8 @@ See :ref:`List of IPProtocols ` for a list of protocols. -------------- These are used to determine the thresholds of high, medium and low categories for counted observation occurrences. + +``seed`` +-------- + +Used to configure the random seeds used within PrimAITE, ensuring determinism within episode/session runs. If empty or set to -1, no seed is set. \ No newline at end of file From 16e0df5cfc9422548b9c292164cf851f0c19208d Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Wed, 4 Sep 2024 14:12:39 +0100 Subject: [PATCH 04/12] #2837 - Updates to some more documentation files to cover new features [skip ci] --- docs/source/configuration/agents.rst | 2 +- docs/source/configuration/game.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/configuration/agents.rst b/docs/source/configuration/agents.rst index 39a71fb5..dece94c5 100644 --- a/docs/source/configuration/agents.rst +++ b/docs/source/configuration/agents.rst @@ -176,4 +176,4 @@ If ``True``, gymnasium flattening will be performed on the observation space bef ``Agent History`` ----------------- -Agents will record their action log for each step. This is a summary of what the agent did, along with response information from requests within the simulation. \ No newline at end of file +Agents will record their action log for each step. This is a summary of what the agent did, along with response information from requests within the simulation. diff --git a/docs/source/configuration/game.rst b/docs/source/configuration/game.rst index 1d08b8e4..2048708c 100644 --- a/docs/source/configuration/game.rst +++ b/docs/source/configuration/game.rst @@ -59,4 +59,4 @@ These are used to determine the thresholds of high, medium and low categories fo ``seed`` -------- -Used to configure the random seeds used within PrimAITE, ensuring determinism within episode/session runs. If empty or set to -1, no seed is set. \ No newline at end of file +Used to configure the random seeds used within PrimAITE, ensuring determinism within episode/session runs. If empty or set to -1, no seed is set. From ba737c57a8fac390dcf00c46feabaea2463d0441 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Wed, 4 Sep 2024 20:46:35 +0100 Subject: [PATCH 05/12] #2837 - Minor structure reshuffle to address confusion around the listen_on_ports variable [skip ci] --- .../system/applications/c2_suite.rst | 9 ++-- .../applications/data_manipulation_bot.rst | 4 -- .../system/applications/database_client.rst | 5 --- .../system/applications/dos_bot.rst | 3 ++ .../system/applications/nmap.rst | 8 ++-- .../system/applications/ransomware_script.rst | 4 -- .../system/applications/web_browser.rst | 4 -- .../system/common/common_configuration.rst | 42 +++++++++---------- .../system/services/database_service.rst | 10 ++--- .../system/services/dns_client.rst | 4 -- .../system/services/dns_server.rst | 8 +--- .../system/services/ftp_client.rst | 5 --- .../system/services/ftp_server.rst | 5 --- .../system/services/ntp_client.rst | 5 --- .../system/services/ntp_server.rst | 8 ---- .../system/services/terminal.rst | 8 ---- .../system/services/web_server.rst | 8 ++-- .../simulation_components/system/software.rst | 9 ++++ 18 files changed, 49 insertions(+), 100 deletions(-) diff --git a/docs/source/simulation_components/system/applications/c2_suite.rst b/docs/source/simulation_components/system/applications/c2_suite.rst index 5fd1021e..82519ab6 100644 --- a/docs/source/simulation_components/system/applications/c2_suite.rst +++ b/docs/source/simulation_components/system/applications/c2_suite.rst @@ -254,6 +254,9 @@ Via Configuration C2 Beacon Configuration ======================= +``Common Configuration`` +"""""""""""""""""""""""" + .. include:: ../common/common_configuration.rst .. |SOFTWARE_NAME| replace:: C2Beacon @@ -311,9 +314,3 @@ C2 Server Configuration ======================= *The C2 Server does not currently offer any unique configuration options and will configure itself to match the C2 beacon's network behaviour.* - - -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: C2Server -.. |SOFTWARE_NAME_BACKTICK| replace:: ``C2Server`` diff --git a/docs/source/simulation_components/system/applications/data_manipulation_bot.rst b/docs/source/simulation_components/system/applications/data_manipulation_bot.rst index 8bcbb265..dd8b7114 100644 --- a/docs/source/simulation_components/system/applications/data_manipulation_bot.rst +++ b/docs/source/simulation_components/system/applications/data_manipulation_bot.rst @@ -158,10 +158,6 @@ If not using the data manipulation bot manually, it needs to be used with a data Configuration ============= -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: DataManipulationBot -.. |SOFTWARE_NAME_BACKTICK| replace:: ``DataManipulationBot`` ``server_ip`` """"""""""""" diff --git a/docs/source/simulation_components/system/applications/database_client.rst b/docs/source/simulation_components/system/applications/database_client.rst index d51465b2..45252e67 100644 --- a/docs/source/simulation_components/system/applications/database_client.rst +++ b/docs/source/simulation_components/system/applications/database_client.rst @@ -90,11 +90,6 @@ Via Configuration Configuration ============= -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: DatabaseClient -.. |SOFTWARE_NAME_BACKTICK| replace:: ``DatabaseClient`` - ``db_server_ip`` """""""""""""""" diff --git a/docs/source/simulation_components/system/applications/dos_bot.rst b/docs/source/simulation_components/system/applications/dos_bot.rst index 9925dc93..5be5383e 100644 --- a/docs/source/simulation_components/system/applications/dos_bot.rst +++ b/docs/source/simulation_components/system/applications/dos_bot.rst @@ -98,6 +98,9 @@ Via Configuration Configuration ============= +``Common Configuration`` +"""""""""""""""""""""""" + .. include:: ../common/common_configuration.rst .. |SOFTWARE_NAME| replace:: DoSBot diff --git a/docs/source/simulation_components/system/applications/nmap.rst b/docs/source/simulation_components/system/applications/nmap.rst index 1e7f5ea4..dbb8a022 100644 --- a/docs/source/simulation_components/system/applications/nmap.rst +++ b/docs/source/simulation_components/system/applications/nmap.rst @@ -346,10 +346,8 @@ Perform a full box scan on all ports, over both TCP and UDP, on a whole subnet: | 192.168.1.13 | 219 | ARP | UDP | +--------------+------+-----------------+----------+ -Configuration -============= -.. include:: ../common/common_configuration.rst +``Common Attributes`` +""""""""""""""""""""" -.. |SOFTWARE_NAME| replace:: NMAP -.. |SOFTWARE_NAME_BACKTICK| replace:: ``NMAP`` +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/ransomware_script.rst b/docs/source/simulation_components/system/applications/ransomware_script.rst index a2a853e9..a5ee990c 100644 --- a/docs/source/simulation_components/system/applications/ransomware_script.rst +++ b/docs/source/simulation_components/system/applications/ransomware_script.rst @@ -72,10 +72,6 @@ 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`` """"""""""""" diff --git a/docs/source/simulation_components/system/applications/web_browser.rst b/docs/source/simulation_components/system/applications/web_browser.rst index dbe2da28..52cfce28 100644 --- a/docs/source/simulation_components/system/applications/web_browser.rst +++ b/docs/source/simulation_components/system/applications/web_browser.rst @@ -92,10 +92,6 @@ Via Configuration Configuration ============= -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: WebBrowser -.. |SOFTWARE_NAME_BACKTICK| replace:: ``WebBrowser`` ``target_url`` """""""""""""" diff --git a/docs/source/simulation_components/system/common/common_configuration.rst b/docs/source/simulation_components/system/common/common_configuration.rst index 49e3188b..73971b37 100644 --- a/docs/source/simulation_components/system/common/common_configuration.rst +++ b/docs/source/simulation_components/system/common/common_configuration.rst @@ -2,35 +2,38 @@ © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK -``ref`` -======= +.. _Common Configuration: -Human readable name used as reference for the |SOFTWARE_NAME_BACKTICK|. Not used in code. +Common Configuration +-------------------- -``type`` -======== +ref +""" -The type of software that should be added. To add |SOFTWARE_NAME| this must be |SOFTWARE_NAME_BACKTICK|. +Human readable name used as reference for the software class. Not used in code. -``options`` -=========== +type +"""" + +The type of software that should be added. To add the required software, this must be it's name. + +options +""""""" The configuration options are the attributes that fall under the options for an application. - - -``fix_duration`` -"""""""""""""""" +fix_duration +"""""""""""" Optional. Default value is ``2``. -The number of timesteps the |SOFTWARE_NAME| will remain in a ``FIXING`` state before going into a ``GOOD`` state. +The number of timesteps the software will remain in a ``FIXING`` state before going into a ``GOOD`` state. -``listen_on_ports`` -""""""""""""""""""" +listen_on_ports +^^^^^^^^^^^^^^^ -The set of ports to listen on. This is in addition to the main port the software is designated. This can either be +Optional. The set of ports to listen on. This is in addition to the main port the software is designated. This can either be the string name of ports or the port integers Example: @@ -40,11 +43,8 @@ Example: simulation: network: nodes: - - hostname: client - type: computer - ip_address: 192.168.10.11 - subnet_mask: 255.255.255.0 - default_gateway: 192.168.10.1 + - hostname: [hostname] + type: [Node Type] services: - type: [Service Type] options: diff --git a/docs/source/simulation_components/system/services/database_service.rst b/docs/source/simulation_components/system/services/database_service.rst index 2f0452f0..7613b8ca 100644 --- a/docs/source/simulation_components/system/services/database_service.rst +++ b/docs/source/simulation_components/system/services/database_service.rst @@ -94,11 +94,6 @@ Via Configuration Configuration ============= -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: DatabaseService -.. |SOFTWARE_NAME_BACKTICK| replace:: ``DatabaseService`` - ``backup_server_ip`` """""""""""""""""""" @@ -114,3 +109,8 @@ This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.25 Optional. Default value is ``None``. The password that needs to be provided by connecting clients in order to create a successful connection. + +``Common Configuration`` +"""""""""""""""""""""""" + +Common configuration variables are detailed within :ref:`software` diff --git a/docs/source/simulation_components/system/services/dns_client.rst b/docs/source/simulation_components/system/services/dns_client.rst index c0025114..2cab953e 100644 --- a/docs/source/simulation_components/system/services/dns_client.rst +++ b/docs/source/simulation_components/system/services/dns_client.rst @@ -84,10 +84,6 @@ Via Configuration Configuration ============= -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: DNSClient -.. |SOFTWARE_NAME_BACKTICK| replace:: ``DNSClient`` ``dns_server`` """""""""""""" diff --git a/docs/source/simulation_components/system/services/dns_server.rst b/docs/source/simulation_components/system/services/dns_server.rst index b681f32f..3e90a551 100644 --- a/docs/source/simulation_components/system/services/dns_server.rst +++ b/docs/source/simulation_components/system/services/dns_server.rst @@ -83,13 +83,9 @@ Via Configuration Configuration ============= -.. include:: ../common/common_configuration.rst -.. |SOFTWARE_NAME| replace:: DNSServer -.. |SOFTWARE_NAME_BACKTICK| replace:: ``DNSServer`` - -domain_mapping -"""""""""""""" +``domain_mapping`` +"""""""""""""""""" Domain mapping takes the domain and IP Addresses as a key-value pairs i.e. diff --git a/docs/source/simulation_components/system/services/ftp_client.rst b/docs/source/simulation_components/system/services/ftp_client.rst index fdf9cfcf..21bd9f2e 100644 --- a/docs/source/simulation_components/system/services/ftp_client.rst +++ b/docs/source/simulation_components/system/services/ftp_client.rst @@ -82,8 +82,3 @@ Via Configuration Configuration ============= - -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: FTPClient -.. |SOFTWARE_NAME_BACKTICK| replace:: ``FTPClient`` diff --git a/docs/source/simulation_components/system/services/ftp_server.rst b/docs/source/simulation_components/system/services/ftp_server.rst index 9b26157d..e0e1a394 100644 --- a/docs/source/simulation_components/system/services/ftp_server.rst +++ b/docs/source/simulation_components/system/services/ftp_server.rst @@ -81,11 +81,6 @@ Via Configuration Configuration ============= -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: FTPServer -.. |SOFTWARE_NAME_BACKTICK| replace:: ``FTPServer`` - ``server_password`` """"""""""""""""""" diff --git a/docs/source/simulation_components/system/services/ntp_client.rst b/docs/source/simulation_components/system/services/ntp_client.rst index 6faad108..e578651b 100644 --- a/docs/source/simulation_components/system/services/ntp_client.rst +++ b/docs/source/simulation_components/system/services/ntp_client.rst @@ -80,11 +80,6 @@ Via Configuration Configuration ============= -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: NTPClient -.. |SOFTWARE_NAME_BACKTICK| replace:: ``NTPClient`` - ``ntp_server_ip`` """"""""""""""""" diff --git a/docs/source/simulation_components/system/services/ntp_server.rst b/docs/source/simulation_components/system/services/ntp_server.rst index 3ddb51ea..30d0b2fa 100644 --- a/docs/source/simulation_components/system/services/ntp_server.rst +++ b/docs/source/simulation_components/system/services/ntp_server.rst @@ -74,11 +74,3 @@ Via Configuration services: - ref: ntp_server type: NTPServer - -Configuration -============= - -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: NTPServer -.. |SOFTWARE_NAME_BACKTICK| replace:: ``NTPServer`` diff --git a/docs/source/simulation_components/system/services/terminal.rst b/docs/source/simulation_components/system/services/terminal.rst index 041169b1..24cfe6e1 100644 --- a/docs/source/simulation_components/system/services/terminal.rst +++ b/docs/source/simulation_components/system/services/terminal.rst @@ -173,11 +173,3 @@ Disconnect from Remote Node term_a_term_b_remote_connection: RemoteTerminalConnection = terminal_a.login(username="admin", password="Admin123!", ip_address="192.168.0.11") term_a_term_b_remote_connection.disconnect() - -Configuration -============= - -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: Terminal -.. |SOFTWARE_NAME_BACKTICK| replace:: ``Terminal`` diff --git a/docs/source/simulation_components/system/services/web_server.rst b/docs/source/simulation_components/system/services/web_server.rst index f0294223..04b9b16a 100644 --- a/docs/source/simulation_components/system/services/web_server.rst +++ b/docs/source/simulation_components/system/services/web_server.rst @@ -75,10 +75,8 @@ Via Configuration - ref: web_server type: WebServer -Configuration -============= -.. include:: ../common/common_configuration.rst +``Common Attributes`` +""""""""""""""""""""" -.. |SOFTWARE_NAME| replace:: WebServer -.. |SOFTWARE_NAME_BACKTICK| replace:: ``WebServer`` +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/software.rst b/docs/source/simulation_components/system/software.rst index 3acfb9b4..c8f0e2d3 100644 --- a/docs/source/simulation_components/system/software.rst +++ b/docs/source/simulation_components/system/software.rst @@ -2,6 +2,8 @@ © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK +.. _software: + Software ======== @@ -63,3 +65,10 @@ Processes ######### `To be implemented` + +Common Software Configuration +############################# + +Below is a list of the common configuration items within Software components of PrimAITE: + +.. include:: common/common_configuration.rst From 0140982d5e666914cae439c9a4dc71630cba45bd Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Thu, 5 Sep 2024 08:41:04 +0100 Subject: [PATCH 06/12] #2837 - Updating link to common attributes within Software components following Review comments. [skip ci] --- .../system/applications/c2_suite.rst | 13 ++++++++----- .../system/applications/data_manipulation_bot.rst | 5 +++++ .../system/applications/database_client.rst | 5 +++++ .../system/applications/dos_bot.rst | 13 +++++-------- .../system/applications/ransomware_script.rst | 5 +++++ .../system/applications/web_browser.rst | 6 ++++++ .../system/services/database_service.rst | 6 +++--- .../system/services/dns_client.rst | 5 +++++ .../system/services/dns_server.rst | 5 +++++ .../system/services/ftp_client.rst | 5 +++++ .../system/services/ftp_server.rst | 5 +++++ .../system/services/ntp_client.rst | 5 +++++ .../system/services/ntp_server.rst | 6 ++++++ .../system/services/terminal.rst | 6 ++++++ 14 files changed, 74 insertions(+), 16 deletions(-) diff --git a/docs/source/simulation_components/system/applications/c2_suite.rst b/docs/source/simulation_components/system/applications/c2_suite.rst index 82519ab6..3e2b669c 100644 --- a/docs/source/simulation_components/system/applications/c2_suite.rst +++ b/docs/source/simulation_components/system/applications/c2_suite.rst @@ -254,13 +254,11 @@ Via Configuration C2 Beacon Configuration ======================= -``Common Configuration`` -"""""""""""""""""""""""" +``Common Attributes`` +""""""""""""""""""""" -.. include:: ../common/common_configuration.rst +See :ref:`Common Configuration` -.. |SOFTWARE_NAME| replace:: C2Beacon -.. |SOFTWARE_NAME_BACKTICK| replace:: ``C2Beacon`` ``c2_server_ip_address`` """""""""""""""""""""""" @@ -314,3 +312,8 @@ C2 Server Configuration ======================= *The C2 Server does not currently offer any unique configuration options and will configure itself to match the C2 beacon's network behaviour.* + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/data_manipulation_bot.rst b/docs/source/simulation_components/system/applications/data_manipulation_bot.rst index dd8b7114..ade46d3a 100644 --- a/docs/source/simulation_components/system/applications/data_manipulation_bot.rst +++ b/docs/source/simulation_components/system/applications/data_manipulation_bot.rst @@ -199,3 +199,8 @@ Optional. Default value is ``0.1``. The chance of the ``DataManipulationBot`` to succeed with a data manipulation attack. This must be a float value between ``0`` and ``1``. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/database_client.rst b/docs/source/simulation_components/system/applications/database_client.rst index 45252e67..4a5e17c2 100644 --- a/docs/source/simulation_components/system/applications/database_client.rst +++ b/docs/source/simulation_components/system/applications/database_client.rst @@ -104,3 +104,8 @@ This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.25 Optional. Default value is ``None``. The password that the ``DatabaseClient`` will use to access the :ref:`DatabaseService`. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/dos_bot.rst b/docs/source/simulation_components/system/applications/dos_bot.rst index 5be5383e..bf7b1037 100644 --- a/docs/source/simulation_components/system/applications/dos_bot.rst +++ b/docs/source/simulation_components/system/applications/dos_bot.rst @@ -98,14 +98,6 @@ Via Configuration Configuration ============= -``Common Configuration`` -"""""""""""""""""""""""" - -.. include:: ../common/common_configuration.rst - -.. |SOFTWARE_NAME| replace:: DoSBot -.. |SOFTWARE_NAME_BACKTICK| replace:: ``DoSBot`` - ``target_ip_address`` """"""""""""""""""""" @@ -164,3 +156,8 @@ Optional. Default value is ``1000``. The maximum number of sessions the ``DoSBot`` is able to make. This must be an integer value equal to or greater than ``0``. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/ransomware_script.rst b/docs/source/simulation_components/system/applications/ransomware_script.rst index a5ee990c..db5be2ed 100644 --- a/docs/source/simulation_components/system/applications/ransomware_script.rst +++ b/docs/source/simulation_components/system/applications/ransomware_script.rst @@ -79,3 +79,8 @@ The RansomwareScript inherits configuration options such as ``fix_duration`` fro 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``. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/web_browser.rst b/docs/source/simulation_components/system/applications/web_browser.rst index 52cfce28..b0466ad1 100644 --- a/docs/source/simulation_components/system/applications/web_browser.rst +++ b/docs/source/simulation_components/system/applications/web_browser.rst @@ -105,3 +105,9 @@ The domain ``arcd.com`` can be matched by - http://arcd.com/ - http://arcd.com/users/ - arcd.com + + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/database_service.rst b/docs/source/simulation_components/system/services/database_service.rst index 7613b8ca..f1b617e6 100644 --- a/docs/source/simulation_components/system/services/database_service.rst +++ b/docs/source/simulation_components/system/services/database_service.rst @@ -110,7 +110,7 @@ Optional. Default value is ``None``. The password that needs to be provided by connecting clients in order to create a successful connection. -``Common Configuration`` -"""""""""""""""""""""""" +``Common Attributes`` +""""""""""""""""""""" -Common configuration variables are detailed within :ref:`software` +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/dns_client.rst b/docs/source/simulation_components/system/services/dns_client.rst index 2cab953e..17fe0219 100644 --- a/docs/source/simulation_components/system/services/dns_client.rst +++ b/docs/source/simulation_components/system/services/dns_client.rst @@ -93,3 +93,8 @@ Optional. Default value is ``None``. The IP Address of the :ref:`DNSServer`. This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/dns_server.rst b/docs/source/simulation_components/system/services/dns_server.rst index 3e90a551..0b6acb01 100644 --- a/docs/source/simulation_components/system/services/dns_server.rst +++ b/docs/source/simulation_components/system/services/dns_server.rst @@ -92,3 +92,8 @@ Domain mapping takes the domain and IP Addresses as a key-value pairs i.e. If the domain is "arcd.com" and the IP Address attributed to the domain is 192.168.0.10, then the value should be ``arcd.com: 192.168.0.10`` The key must be a string and the IP Address must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ftp_client.rst b/docs/source/simulation_components/system/services/ftp_client.rst index 21bd9f2e..265a03ea 100644 --- a/docs/source/simulation_components/system/services/ftp_client.rst +++ b/docs/source/simulation_components/system/services/ftp_client.rst @@ -82,3 +82,8 @@ Via Configuration Configuration ============= + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ftp_server.rst b/docs/source/simulation_components/system/services/ftp_server.rst index e0e1a394..9b068d68 100644 --- a/docs/source/simulation_components/system/services/ftp_server.rst +++ b/docs/source/simulation_components/system/services/ftp_server.rst @@ -87,3 +87,8 @@ Configuration Optional. Default value is ``None``. The password that needs to be provided by a connecting :ref:`FTPClient` in order to create a successful connection. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ntp_client.rst b/docs/source/simulation_components/system/services/ntp_client.rst index e578651b..8096a4fe 100644 --- a/docs/source/simulation_components/system/services/ntp_client.rst +++ b/docs/source/simulation_components/system/services/ntp_client.rst @@ -88,3 +88,8 @@ Optional. Default value is ``None``. The IP address of an NTP Server which provides a time that the ``NTPClient`` can synchronise to. This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``. + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ntp_server.rst b/docs/source/simulation_components/system/services/ntp_server.rst index 30d0b2fa..f2bb6684 100644 --- a/docs/source/simulation_components/system/services/ntp_server.rst +++ b/docs/source/simulation_components/system/services/ntp_server.rst @@ -74,3 +74,9 @@ Via Configuration services: - ref: ntp_server type: NTPServer + + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/terminal.rst b/docs/source/simulation_components/system/services/terminal.rst index 24cfe6e1..c319d264 100644 --- a/docs/source/simulation_components/system/services/terminal.rst +++ b/docs/source/simulation_components/system/services/terminal.rst @@ -173,3 +173,9 @@ Disconnect from Remote Node term_a_term_b_remote_connection: RemoteTerminalConnection = terminal_a.login(username="admin", password="Admin123!", ip_address="192.168.0.11") term_a_term_b_remote_connection.disconnect() + + +``Common Attributes`` +""""""""""""""""""""" + +See :ref:`Common Configuration` From e18ac0914fbe95809f9bba6cfafe71137f3883e7 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Thu, 5 Sep 2024 08:42:38 +0100 Subject: [PATCH 07/12] #2837 - Correcting date on changelog v3.3 release --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c4b949a..4b9ca8e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [3.3.0] - 2024-08-30 +## [3.3.0] - 2024-09-04 ### Added - Random Number Generator Seeding by specifying a random number seed in the config file. From 3feb908900309b1445236bc79c9f1541307254e9 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Thu, 5 Sep 2024 09:02:07 +0100 Subject: [PATCH 08/12] #2837 - Added a description of how some rewards can be made sticky/instantaneous. [skip ci] --- docs/source/rewards.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/rewards.rst b/docs/source/rewards.rst index 921544e8..0163284c 100644 --- a/docs/source/rewards.rst +++ b/docs/source/rewards.rst @@ -7,6 +7,9 @@ Rewards Rewards in PrimAITE are based on a system of individual components that react to events in the simulation. An agent's reward function is calculated as the weighted sum of several reward components. +Some rewards, such as the ``GreenAdminDatabaseUnreachablePenalty``, can be marked as 'sticky' in their configuration. Setting this to ``True`` will mean that they continue to output the same value after an event until another event of that type. +In the instance of the ``GreenAdminDatabaseUnreachablePenalty``, the database admin reward will stay negative until the next successful database request is made, even if the database admin agents do nothing and the database returns a good state. + Components ********** The following API pages describe the use of each reward component and the possible configuration options. An example of configuring each via yaml is also provided. From fcbde31dad1722bd98ba0a8f49f9239c4f649200 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Thu, 5 Sep 2024 11:23:52 +0100 Subject: [PATCH 09/12] #2837 - Actioning review comments and fixing a bug with links to the common attributes within software documents --- .../system/applications/c2_suite.rst | 16 ++++++++-------- .../applications/data_manipulation_bot.rst | 2 +- .../system/applications/database_client.rst | 2 +- .../system/applications/dos_bot.rst | 2 +- .../system/applications/ransomware_script.rst | 2 +- .../system/applications/web_browser.rst | 2 +- .../system/common/common_configuration.rst | 2 +- .../system/services/database_service.rst | 2 +- .../system/services/dns_client.rst | 2 +- .../system/services/dns_server.rst | 2 +- .../system/services/ftp_client.rst | 2 +- .../system/services/ftp_server.rst | 2 +- .../system/services/ntp_client.rst | 2 +- .../system/services/ntp_server.rst | 2 +- .../system/services/terminal.rst | 4 ++-- .../system/services/web_server.rst | 2 +- 16 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/source/simulation_components/system/applications/c2_suite.rst b/docs/source/simulation_components/system/applications/c2_suite.rst index 3e2b669c..fd9ee546 100644 --- a/docs/source/simulation_components/system/applications/c2_suite.rst +++ b/docs/source/simulation_components/system/applications/c2_suite.rst @@ -59,7 +59,7 @@ Once installed and configured; the C2 beacon can establish connection with the C This will send an initial ``keep alive`` to the given C2 Server (The C2 Server IPv4Address must be given upon C2 Beacon configuration). Which is then resolved and responded by another ``Keep Alive`` by the C2 server back to the C2 beacon to confirm connection. -The C2 Beacon will send out periodic keep alive based on it's configuration parameters to configure it's active connection with the C2 server. +The C2 Beacon will send out periodic keep alive based on its configuration parameters to configure it's active connection with the C2 server. It's recommended that a C2 Beacon is installed and configured mid episode by a Red Agent for a more cyber realistic simulation. @@ -254,12 +254,6 @@ Via Configuration C2 Beacon Configuration ======================= -``Common Attributes`` -""""""""""""""""""""" - -See :ref:`Common Configuration` - - ``c2_server_ip_address`` """""""""""""""""""""""" @@ -308,12 +302,18 @@ This must be a string i.e ``DNS``. Defaults to ``HTTP``. *Please refer to the ``IPProtocol`` class for further reference.* +``Common Attributes`` +^^^^^^^^^^^^^^^^^^^^^ + +See :ref:`Common Configuration` + + C2 Server Configuration ======================= *The C2 Server does not currently offer any unique configuration options and will configure itself to match the C2 beacon's network behaviour.* ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/data_manipulation_bot.rst b/docs/source/simulation_components/system/applications/data_manipulation_bot.rst index ade46d3a..1a387514 100644 --- a/docs/source/simulation_components/system/applications/data_manipulation_bot.rst +++ b/docs/source/simulation_components/system/applications/data_manipulation_bot.rst @@ -201,6 +201,6 @@ The chance of the ``DataManipulationBot`` to succeed with a data manipulation at This must be a float value between ``0`` and ``1``. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/database_client.rst b/docs/source/simulation_components/system/applications/database_client.rst index 4a5e17c2..1fea78ab 100644 --- a/docs/source/simulation_components/system/applications/database_client.rst +++ b/docs/source/simulation_components/system/applications/database_client.rst @@ -106,6 +106,6 @@ Optional. Default value is ``None``. The password that the ``DatabaseClient`` will use to access the :ref:`DatabaseService`. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/dos_bot.rst b/docs/source/simulation_components/system/applications/dos_bot.rst index bf7b1037..6ad45424 100644 --- a/docs/source/simulation_components/system/applications/dos_bot.rst +++ b/docs/source/simulation_components/system/applications/dos_bot.rst @@ -158,6 +158,6 @@ The maximum number of sessions the ``DoSBot`` is able to make. This must be an integer value equal to or greater than ``0``. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/ransomware_script.rst b/docs/source/simulation_components/system/applications/ransomware_script.rst index db5be2ed..5bff6991 100644 --- a/docs/source/simulation_components/system/applications/ransomware_script.rst +++ b/docs/source/simulation_components/system/applications/ransomware_script.rst @@ -81,6 +81,6 @@ IP address of the :ref:`DatabaseService` which the ``RansomwareScript`` will enc This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/applications/web_browser.rst b/docs/source/simulation_components/system/applications/web_browser.rst index b0466ad1..c56c450d 100644 --- a/docs/source/simulation_components/system/applications/web_browser.rst +++ b/docs/source/simulation_components/system/applications/web_browser.rst @@ -108,6 +108,6 @@ The domain ``arcd.com`` can be matched by ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/common/common_configuration.rst b/docs/source/simulation_components/system/common/common_configuration.rst index 73971b37..7b32a463 100644 --- a/docs/source/simulation_components/system/common/common_configuration.rst +++ b/docs/source/simulation_components/system/common/common_configuration.rst @@ -5,7 +5,7 @@ .. _Common Configuration: Common Configuration --------------------- +"""""""""""""""""""" ref """ diff --git a/docs/source/simulation_components/system/services/database_service.rst b/docs/source/simulation_components/system/services/database_service.rst index f1b617e6..f3e800cd 100644 --- a/docs/source/simulation_components/system/services/database_service.rst +++ b/docs/source/simulation_components/system/services/database_service.rst @@ -111,6 +111,6 @@ Optional. Default value is ``None``. The password that needs to be provided by connecting clients in order to create a successful connection. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/dns_client.rst b/docs/source/simulation_components/system/services/dns_client.rst index 17fe0219..eca152f0 100644 --- a/docs/source/simulation_components/system/services/dns_client.rst +++ b/docs/source/simulation_components/system/services/dns_client.rst @@ -95,6 +95,6 @@ The IP Address of the :ref:`DNSServer`. This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/dns_server.rst b/docs/source/simulation_components/system/services/dns_server.rst index 0b6acb01..1e30b9bd 100644 --- a/docs/source/simulation_components/system/services/dns_server.rst +++ b/docs/source/simulation_components/system/services/dns_server.rst @@ -94,6 +94,6 @@ If the domain is "arcd.com" and the IP Address attributed to the domain is 192.1 The key must be a string and the IP Address must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ftp_client.rst b/docs/source/simulation_components/system/services/ftp_client.rst index 265a03ea..c8a21743 100644 --- a/docs/source/simulation_components/system/services/ftp_client.rst +++ b/docs/source/simulation_components/system/services/ftp_client.rst @@ -84,6 +84,6 @@ Configuration ============= ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ftp_server.rst b/docs/source/simulation_components/system/services/ftp_server.rst index 9b068d68..f52fa043 100644 --- a/docs/source/simulation_components/system/services/ftp_server.rst +++ b/docs/source/simulation_components/system/services/ftp_server.rst @@ -89,6 +89,6 @@ Optional. Default value is ``None``. The password that needs to be provided by a connecting :ref:`FTPClient` in order to create a successful connection. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ntp_client.rst b/docs/source/simulation_components/system/services/ntp_client.rst index 8096a4fe..7af831bf 100644 --- a/docs/source/simulation_components/system/services/ntp_client.rst +++ b/docs/source/simulation_components/system/services/ntp_client.rst @@ -90,6 +90,6 @@ The IP address of an NTP Server which provides a time that the ``NTPClient`` can This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``. ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/ntp_server.rst b/docs/source/simulation_components/system/services/ntp_server.rst index f2bb6684..a09c8bdd 100644 --- a/docs/source/simulation_components/system/services/ntp_server.rst +++ b/docs/source/simulation_components/system/services/ntp_server.rst @@ -77,6 +77,6 @@ Via Configuration ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/terminal.rst b/docs/source/simulation_components/system/services/terminal.rst index c319d264..6909786e 100644 --- a/docs/source/simulation_components/system/services/terminal.rst +++ b/docs/source/simulation_components/system/services/terminal.rst @@ -36,7 +36,7 @@ Implementation Usage """"" - - Pre-Installs on all ``Node`` (with the exception of ``Switch``). + - Pre-Installs on all ``Nodes`` (with the exception of ``Switches``). - Terminal Clients connect, execute commands and disconnect from remote nodes. - Ensures that users are logged in to the component before executing any commands. - Service runs on SSH port 22 by default. @@ -176,6 +176,6 @@ Disconnect from Remote Node ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` diff --git a/docs/source/simulation_components/system/services/web_server.rst b/docs/source/simulation_components/system/services/web_server.rst index 04b9b16a..cec20a60 100644 --- a/docs/source/simulation_components/system/services/web_server.rst +++ b/docs/source/simulation_components/system/services/web_server.rst @@ -77,6 +77,6 @@ Via Configuration ``Common Attributes`` -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ See :ref:`Common Configuration` From a5e75f9fed4044e4b9aab4f631945b7c99572023 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Thu, 5 Sep 2024 11:24:52 +0100 Subject: [PATCH 10/12] #2837 - Actioning notebook review comments --- .../notebooks/Command-&-Control-E2E-Demonstration.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb b/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb index 4e36db17..97b436cb 100644 --- a/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb +++ b/src/primaite/notebooks/Command-&-Control-E2E-Demonstration.ipynb @@ -1450,7 +1450,7 @@ "source": [ "### **Command and Control** | Configurability | C2 Server IP Address\n", "\n", - "As with a majority of client and server based application configuration in primaite, the remote IP of a server must be supplied.\n", + "As with a majority of client and server based application configurations in primaite, the remote IP of a server must be supplied.\n", "\n", "In the case of the C2 Beacon, the C2 Server's IP address must be supplied before the C2 beacon will be able to perform any other actions (including ``APPLICATION EXECUTE``).\n", "\n", @@ -1818,7 +1818,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.10.11" } }, "nbformat": 4, From 9fe48bb2410b027b0be08ccd1909f6845b07ffa1 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Thu, 5 Sep 2024 11:32:39 +0100 Subject: [PATCH 11/12] #2837 - Commiting a typo correction in Using Episode Schedules notebook [skip ci] --- src/primaite/notebooks/Using-Episode-Schedules.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/primaite/notebooks/Using-Episode-Schedules.ipynb b/src/primaite/notebooks/Using-Episode-Schedules.ipynb index 14012264..cb06e0f9 100644 --- a/src/primaite/notebooks/Using-Episode-Schedules.ipynb +++ b/src/primaite/notebooks/Using-Episode-Schedules.ipynb @@ -199,7 +199,7 @@ "metadata": {}, "source": [ "### Episode 0\n", - "Let' run the episodes to verify that the agents are changing as expected. In episode 0, there should be no green or red agents, just the defender blue agent." + "Let's run the episodes to verify that the agents are changing as expected. In episode 0, there should be no green or red agents, just the defender blue agent." ] }, { From 60e2225a2c6d3f0f7d387248eb2d5552f04ebb52 Mon Sep 17 00:00:00 2001 From: Charlie Crane Date: Thu, 5 Sep 2024 12:03:20 +0100 Subject: [PATCH 12/12] #2837 - Correcting formatting on action masking table [skip ci] --- docs/source/action_masking.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/source/action_masking.rst b/docs/source/action_masking.rst index 2b17075b..264ab254 100644 --- a/docs/source/action_masking.rst +++ b/docs/source/action_masking.rst @@ -111,35 +111,35 @@ The following logic is applied: +------------------------------------------+---------------------------------------------------------------------+ | **FIREWALL_ACL_REMOVERULE** | Firewall is on. | +------------------------------------------+---------------------------------------------------------------------+ -| NODE_NMAP_PING_SCAN | Node is on. | +| **NODE_NMAP_PING_SCAN** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| NODE_NMAP_PORT_SCAN | Node is on. | +| **NODE_NMAP_PORT_SCAN** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| NODE_NMAP_NETWORK_SERVICE_RECON | Node is on. | +| **NODE_NMAP_NETWORK_SERVICE_RECON** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| CONFIGURE_DATABASE_CLIENT | Node is on. | +| **CONFIGURE_DATABASE_CLIENT** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| CONFIGURE_RANSOMWARE_SCRIPT | Node is on. | +| **CONFIGURE_RANSOMWARE_SCRIPT** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| CONFIGURE_DOSBOT | Node is on. | +| **CONFIGURE_DOSBOT** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| CONFIGURE_C2_BEACON | Node is on. | +| **CONFIGURE_C2_BEACON** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| C2_SERVER_RANSOMWARE_LAUNCH | Node is on. | +| **C2_SERVER_RANSOMWARE_LAUNCH** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| C2_SERVER_RANSOMWARE_CONFIGURE | Node is on. | +| **C2_SERVER_RANSOMWARE_CONFIGURE** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| C2_SERVER_TERMINAL_COMMAND | Node is on. | +| **C2_SERVER_TERMINAL_COMMAND** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| C2_SERVER_DATA_EXFILTRATE | Node is on. | +| **C2_SERVER_DATA_EXFILTRATE** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| NODE_ACCOUNTS_CHANGE_PASSWORD | Node is on. | +| **NODE_ACCOUNTS_CHANGE_PASSWORD** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| SSH_TO_REMOTE | Node is on. | +| **SSH_TO_REMOTE** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| SESSIONS_REMOTE_LOGOFF | Node is on. | +| **SESSIONS_REMOTE_LOGOFF** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+ -| NODE_SEND_REMOTE_COMMAND | Node is on. | +| **NODE_SEND_REMOTE_COMMAND** | Node is on. | +------------------------------------------+---------------------------------------------------------------------+