oxbrbtx/PrimAITE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

#2837 - Updating the User Guide as per review comments. [skip ci]

Browse Source
This commit is contained in:
Charlie Crane
2024-09-04 12:07:32 +01:00
parent a5d84c1254
commit d282575467
7 changed files with 43 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/source/configuration/simulation/nodes/common/common_node_attributes.rst
View File

@@ -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'

10
docs/source/primaite-dependencies.rst
View File

@@ -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 |
+-------------------+---------+------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------+

2
docs/source/simulation_components/network/nodes/wireless_router.rst
View File

@@ -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,

20
docs/source/simulation_components/system/applications/c2_suite.rst
View File

@@ -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``.

8
docs/source/simulation_components/system/common/common_configuration.rst
View File

@@ -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

23
docs/source/simulation_components/system/services/terminal.rst
View File

@@ -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``