Merge remote-tracking branch 'origin/release/3.3.0' into 4.0.0a1
This commit is contained in:
Marek Wolan
@@ -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,
|
||||
|
||||
@@ -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 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.
|
||||
|
||||
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:
|
||||
|
||||
@@ -254,11 +254,6 @@ Via Configuration
|
||||
C2 Beacon Configuration
|
||||
=======================
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: C2Beacon
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``C2Beacon``
|
||||
|
||||
``c2_server_ip_address``
|
||||
""""""""""""""""""""""""
|
||||
|
||||
@@ -275,7 +270,7 @@ How often should the C2 Beacon confirm it's connection in timesteps.
|
||||
For example, if the keep alive Frequency is set to one then every single timestep
|
||||
the C2 connection will be confirmed.
|
||||
|
||||
It's worth noting that this may be useful option when investigating
|
||||
It's worth noting that this may be a useful option when investigating
|
||||
network blue agent observation space.
|
||||
|
||||
This must be a valid integer i.e ``10``. Defaults to ``5``.
|
||||
@@ -288,7 +283,7 @@ The protocol that the C2 Beacon will use to communicate to the C2 Server with.
|
||||
|
||||
Currently only ``TCP`` and ``UDP`` are valid masquerade protocol 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 *UDP*. Defaults to ``TCP``.
|
||||
|
||||
@@ -301,19 +296,24 @@ 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``.
|
||||
|
||||
*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``
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: C2Server
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``C2Server``
|
||||
See :ref:`Common Configuration`
|
||||
|
||||
@@ -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``
|
||||
"""""""""""""
|
||||
@@ -203,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`
|
||||
|
||||
@@ -90,11 +90,6 @@ Via Configuration
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: DatabaseClient
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``DatabaseClient``
|
||||
|
||||
|
||||
``db_server_ip``
|
||||
""""""""""""""""
|
||||
@@ -109,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`
|
||||
|
||||
@@ -98,11 +98,6 @@ Via Configuration
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: DoSBot
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``DoSBot``
|
||||
|
||||
``target_ip_address``
|
||||
"""""""""""""""""""""
|
||||
|
||||
@@ -161,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`
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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``
|
||||
"""""""""""""
|
||||
@@ -83,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`
|
||||
|
||||
@@ -92,10 +92,6 @@ Via Configuration
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: WebBrowser
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``WebBrowser``
|
||||
|
||||
``target_url``
|
||||
""""""""""""""
|
||||
@@ -109,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`
|
||||
|
||||
@@ -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 configuration options are the attributes that fall under the options for an application.
|
||||
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 or service.
|
||||
|
||||
``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 set 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,20 +43,15 @@ 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: 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
|
||||
|
||||
@@ -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 Attributes``
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
See :ref:`Common Configuration`
|
||||
|
||||
@@ -84,10 +84,6 @@ Via Configuration
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: DNSClient
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``DNSClient``
|
||||
|
||||
``dns_server``
|
||||
""""""""""""""
|
||||
@@ -97,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`
|
||||
|
||||
@@ -83,16 +83,17 @@ 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.
|
||||
|
||||
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`
|
||||
|
||||
@@ -83,7 +83,7 @@ Via Configuration
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
``Common Attributes``
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: FTPClient
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``FTPClient``
|
||||
See :ref:`Common Configuration`
|
||||
|
||||
@@ -81,14 +81,14 @@ Via Configuration
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: FTPServer
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``FTPServer``
|
||||
|
||||
``server_password``
|
||||
"""""""""""""""""""
|
||||
|
||||
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`
|
||||
|
||||
@@ -80,11 +80,6 @@ Via Configuration
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: NTPClient
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``NTPClient``
|
||||
|
||||
``ntp_server_ip``
|
||||
"""""""""""""""""
|
||||
|
||||
@@ -93,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`
|
||||
|
||||
@@ -75,10 +75,8 @@ Via Configuration
|
||||
- ref: ntp_server
|
||||
type: NTPServer
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
.. include:: ../common/common_configuration.rst
|
||||
``Common Attributes``
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. |SOFTWARE_NAME| replace:: NTPServer
|
||||
.. |SOFTWARE_NAME_BACKTICK| replace:: ``NTPServer``
|
||||
See :ref:`Common Configuration`
|
||||
|
||||
@@ -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 ``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.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
@@ -172,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`
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user