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

#2257: applications and services docs

Browse Source
This commit is contained in:
Czar Echavez
2024-02-23 16:49:01 +00:00
parent ef61fe219c
commit fb148dc4fb
21 changed files with 956 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/source/simulation_components/system/applications/data_manipulation_bot.rst
View File

@@ -2,14 +2,15 @@
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
.. _DataManipulationBot:
DataManipulationBot
===================
###################
The ``DataManipulationBot`` class provides functionality to connect to a ``DatabaseService`` and execute malicious SQL statements.
The ``DataManipulationBot`` class provides functionality to connect to a :ref:`DatabaseService` and execute malicious SQL statements.
Overview
--------
========
The bot is intended to simulate a malicious actor carrying out attacks like:
@@ -28,7 +29,7 @@ The bot performs attacks in the following stages to simulate the real pattern of
Each of these stages has a random, configurable probability of succeeding (by default 10%). The bot can also be configured to repeat the attack once complete.
Usage
-----
=====
- Create an instance and call ``configure`` to set:
- Target database server IP
@@ -41,16 +42,35 @@ The bot handles connecting, executing the statement, and disconnecting.
In a simulation, the bot can be controlled by using ``DataManipulationAgent`` which calls ``run`` on the bot at configured timesteps.
Example
-------
Implementation
==============
The bot extends :ref:`DatabaseClient` and leverages its connectivity.
- Uses the Application base class for lifecycle management.
- Credentials, target IP and other options set via ``configure``.
- ``run`` handles connecting, executing statement, and disconnecting.
- SQL payload executed via ``query`` method.
- Results in malicious SQL being executed on remote database server.
Examples
========
Python
""""""
.. code-block:: python
from primaite.simulator.network.hardware.nodes.host.computer import Computer
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
from primaite.simulator.system.applications.red_applications.data_manipulation_bot import DataManipulationBot
client_1 = Computer(
hostname="client_1",
ip_address="192.168.10.21",
subnet_mask="255.255.255.0",
default_gateway="192.168.10.1"
default_gateway="192.168.10.1",
operating_state=NodeOperatingState.ON # initialise the computer in an ON state
)
network.connect(endpoint_b=client_1.network_interface[1], endpoint_a=switch_2.network_interface[1])
@@ -62,13 +82,13 @@ Example
This would connect to the database service at 192.168.1.14, authenticate, and execute the SQL statement to drop the 'users' table.
Example with ``DataManipulationAgent``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
""""""""""""""""""""""""""""""""""""""
If not using the data manipulation bot manually, it needs to be used with a data manipulation agent. Below is an example section of configuration file for setting up a simulation with data manipulation bot and agent.
.. code-block:: yaml
game_config:
game:
# ...
agents:
- ref: data_manipulation_red_bot
@@ -129,13 +149,51 @@ If not using the data manipulation bot manually, it needs to be used with a data
payload: "DELETE"
server_ip: 192.168.1.14
Implementation
--------------
Configuration
=============
The bot extends ``DatabaseClient`` and leverages its connectivity.
.. include:: ../common/common_configuration.rst
- Uses the Application base class for lifecycle management.
- Credentials, target IP and other options set via ``configure``.
- ``run`` handles connecting, executing statement, and disconnecting.
- SQL payload executed via ``query`` method.
- Results in malicious SQL being executed on remote database server.
.. |SOFTWARE_NAME| replace:: DataManipulationBot
.. |SOFTWARE_NAME_BACKTICK| replace:: ``DataManipulationBot``
``server_ip``
"""""""""""""
IP address of the :ref:`DatabaseService` which the ``DataManipulationBot`` will try to attack.
This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
``server_password``
"""""""""""""""""""
Optional. Default value is ``None``.
The password that the ``DataManipulationBot`` will use to access the :ref:`DatabaseService`.
``payload``
"""""""""""
Optional. Default value is ``DELETE``.
The payload that the ``DataManipulationBot`` will send to the :ref:`DatabaseService`.
See :ref:`Database Payload List`
``port_scan_p_of_success``
""""""""""""""""""""""""""
Optional. Default value is ``0.1``.
The chance of the ``DataManipulationBot`` to succeed with a port scan (and therefore continue the attack).
This must be a float value between ``0`` and ``1``.
``data_manipulation_p_of_success``
""""""""""""""""""""""""""""""""""
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``.

90
docs/source/simulation_components/system/applications/database_client.rst
View File

@@ -2,37 +2,111 @@
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
.. _DatabaseClient:
DatabaseClient
===============
##############
The DatabaseClient provides a client interface for connecting to the ``DatabaseService``.
The ``DatabaseClient`` provides a client interface for connecting to the :ref:`DatabaseService`.
Key features
^^^^^^^^^^^^
============
- Connects to the ``DatabaseService`` via the ``SoftwareManager``.
- Connects to the :ref:`DatabaseService` via the ``SoftwareManager``.
- Handles connecting and disconnecting.
- Executes SQL queries and retrieves result sets.
Usage
^^^^^
=====
- Initialise with server IP address and optional password.
- Connect to the ``DatabaseService`` with ``connect``.
- Connect to the :ref:`DatabaseService` with ``connect``.
- Retrieve results in a dictionary.
- Disconnect when finished.
To create database backups:
- Configure the backup server on the ``DatabaseService`` by providing the Backup server ``IPv4Address`` with ``configure_backup``
- Configure the backup server on the :ref:`DatabaseService` by providing the Backup server ``IPv4Address`` with ``configure_backup``
- Create a backup using ``backup_database``. This fails if the backup server is not configured.
- Restore a backup using ``restore_backup``. By default, this uses the database created via ``backup_database``.
Implementation
^^^^^^^^^^^^^^
==============
- Leverages ``SoftwareManager`` for sending payloads over the network.
- Connect and disconnect methods manage sessions.
- Payloads serialised as dictionaries for transmission.
- Extends base Application class.
Examples
========
Python
""""""
.. code-block:: python
from ipaddress import IPv4Address
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
from primaite.simulator.network.hardware.nodes.host.computer import Computer
from primaite.simulator.system.applications.database_client import DatabaseClient
client = Computer(
hostname="client",
ip_address="192.168.10.21",
subnet_mask="255.255.255.0",
default_gateway="192.168.10.1",
operating_state=NodeOperatingState.ON # initialise the computer in an ON state
)
# install DatabaseClient
client.software_manager.install(DatabaseClient)
database_client: DatabaseClient = client.software_manager.software.get("DatabaseClient")
# Configure the DatabaseClient
database_client.configure(server_ip_address=IPv4Address("192.168.0.1")) # address of the DatabaseService
database_client.run()
Via Configuration
"""""""""""""""""
.. code-block:: yaml
simulation:
network:
nodes:
- ref: example_computer
hostname: example_computer
type: computer
...
applications:
- ref: database_client
type: DatabaseClient
options:
db_server_ip: 192.168.0.1
Configuration
=============
.. include:: ../common/common_configuration.rst
.. |SOFTWARE_NAME| replace:: DatabaseClient
.. |SOFTWARE_NAME_BACKTICK| replace:: ``DatabaseClient``
``db_server_ip``
""""""""""""""""
IP address of the :ref:`DatabaseService` that the ``DatabaseClient`` will connect to
This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
``server_password``
"""""""""""""""""""
Optional. Default value is ``None``.
The password that the ``DatabaseClient`` will use to access the :ref:`DatabaseService`.

156
docs/source/simulation_components/system/applications/dos_bot.rst
View File

@@ -2,7 +2,157 @@
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
DoSBot
------
.. _DoSBot:
test
DoSBot
######
The ``DoSBot`` is an implementation of a Denial of Service attack within the PrimAITE simulation. This specifically simulates a `Slow Loris attack <https://en.wikipedia.org/wiki/Slowloris_(computer_security)>`.
Key features
============
- Connects to the :ref:`DatabaseService` via the ``SoftwareManager``.
- Makes many connections to the :ref:`DatabaseService` which ends up using up the available connections.
Usage
=====
- Configure with target IP address and optional password.
- use ``run`` to run the application_loop of DoSBot to begin attacks
- DoSBot runs through different actions at each timestep
Implementation
==============
- Leverages :ref:`DatabaseClient` to create connections with :ref`DatabaseServer`.
- Extends base Application class.
Examples
========
Python
""""""
.. code-block:: python
from ipaddress import IPv4Address
from primaite.simulator.network.hardware.nodes.host.computer import Computer
from primaite.simulator.system.applications.red_applications.dos_bot import DoSBot
# Create Computer
computer = Computer(
hostname="computer",
ip_address="192.168.1.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
)
computer.power_on()
# Install DoSBot on computer
computer.software_manager.install(DoSBot)
dos_bot: DoSBot = computer.software_manager.software.get("DoSBot")
# Configure the DoSBot
dos_bot.configure(
target_ip_address=IPv4Address("192.168.0.10"),
payload="SPOOF DATA",
repeat=False,
port_scan_p_of_success=0.8,
dos_intensity=1.0,
max_sessions=1000
)
# run DoSBot
dos_bot.run()
Via Configuration
"""""""""""""""""
.. code-block:: yaml
simulation:
network:
nodes:
- ref: example_computer
hostname: example_computer
type: computer
...
applications:
- ref: dos_bot
type: DoSBot
options:
target_ip_address: 192.168.0.10
payload: SPOOF DATA
repeat: False
port_scan_p_of_success: 0.8
dos_intensity: 1.0
max_sessions: 1000
Configuration
=============
.. include:: ../common/common_configuration.rst
.. |SOFTWARE_NAME| replace:: DoSBot
.. |SOFTWARE_NAME_BACKTICK| replace:: ``DoSBot``
``target_ip_address``
"""""""""""""""""""""
IP address of the :ref:`DatabaseService` which the ``DataManipulationBot`` will try to attack.
This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
``target_port``
"""""""""""""""
Optional. Default value is ``5432``.
Port of the target service.
See :ref:`List of IPProtocols <List of IPProtocols>` for a list of protocols.
``payload``
"""""""""""
Optional. Default value is ``None``.
The payload that the ``DoSBot`` sends as part of its attack.
``repeat``
""""""""""
Optional. Default value is ``False``.
If ``True`` the ``DoSBot`` will maintain its attack.
``port_scan_p_of_success``
""""""""""""""""""""""""""
Optional. Default value is ``0.1``.
The chance of the ``DoSBot`` to succeed with a port scan (and therefore continue the attack).
This must be a float value between ``0`` and ``1``.
``dos_intensity``
"""""""""""""""""
Optional. Default value is ``1.0``.
The intensity of the Denial of Service attack. This is multiplied by the number of ``max_sessions``.
This must be a float value between ``0`` and ``1``.
``max_sessions``
""""""""""""""""
Optional. Default value is ``1000``.
The maximum number of sessions the ``DoSBot`` is able to make.
This must be an integer value above equal to or greater than ``0``.

103
docs/source/simulation_components/system/applications/web_browser.rst
View File

@@ -2,16 +2,17 @@
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
.. _WebBrowser:
WebBrowser
==========
##########
The ``WebBrowser`` provides a client interface for connecting to the ``WebServer``.
The ``WebBrowser`` provides a client interface for connecting to the :ref:`WebServer`.
Key features
^^^^^^^^^^^^
============
- Connects to the ``WebServer`` via the ``SoftwareManager``.
- Connects to the :ref:`WebServer` via the ``SoftwareManager``.
- Simulates HTTP requests and HTTP packet transfer across a network
- Allows the emulation of HTTP requests between client and server:
- Automatically uses ``DNSClient`` to resolve domain names
@@ -19,66 +20,92 @@ Key features
- Leverages the Service base class for install/uninstall, status tracking, etc.
Usage
^^^^^
=====
- Install on a Node via the ``SoftwareManager`` to start the ``WebBrowser``.
- Service runs on HTTP port 80 by default. (TODO: HTTPS)
- Execute sending an HTTP GET request with ``get_webpage``
Implementation
^^^^^^^^^^^^^^
==============
- Leverages ``SoftwareManager`` for sending payloads over the network.
- Provides easy interface for making HTTP requests between an HTTP client and server.
- Extends base Service class.
Example Usage
-------------
Examples
========
Dependencies
^^^^^^^^^^^^
Python
""""""
The ``WebBrowser`` utilises :ref:`DNSClient` and :ref:`DNSServer` to resolve a URL.
The :ref:`DNSClient` must be configured to use the :ref:`DNSServer`. The :ref:`DNSServer` should be configured to have the ``WebBrowser`` ``target_url`` within its ``domain_mapping``.
.. code-block:: python
from primaite.simulator.network.container import Network
from primaite.simulator.network.hardware.nodes.computer import Computer
from primaite.simulator.network.hardware.nodes.server import Server
from primaite.simulator.network.hardware.nodes.host.computer import Computer
from primaite.simulator.system.applications.web_browser import WebBrowser
from primaite.simulator.system.services.web_server.web_server_service import WebServer
Example peer to peer network
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# Create Computer
computer = Computer(
hostname="computer",
ip_address="192.168.1.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
)
computer.power_on()
.. code-block:: python
# Install WebBrowser on computer
computer.software_manager.install(WebBrowser)
web_browser: WebBrowser = computer.software_manager.software.get("WebBrowser")
web_browser.run()
net = Network()
# configure the WebBrowser
web_browser.target_url = "arcd.com"
pc1 = Computer(hostname="pc1", ip_address="192.168.1.50", subnet_mask="255.255.255.0")
srv = Server(hostname="srv", ip_address="192.168.1.10", subnet_mask="255.255.255.0")
pc1.power_on()
srv.power_on()
net.connect(pc1.network_interface[1], srv.network_interface[1])
# once DNS server is configured with the correct domain mapping
# this should work
web_browser.get_webpage()
Install the Web Server
^^^^^^^^^^^^^^^^^^^^^^
Via Configuration
"""""""""""""""""
.. code-block:: python
.. code-block:: yaml
# web browser is automatically installed in computer nodes
# IRL this is usually included with an OS
client: WebBrowser = pc1.software_manager.software['WebBrowser']
simulation:
network:
nodes:
- ref: example_computer
hostname: example_computer
type: computer
...
applications:
- ref: web_browser
type: WebBrowser
options:
target_url: http://arcd.com/
# install web server
srv.software_manager.install(WebServer)
webserv: WebServer = srv.software_manager.software['WebServer']
Configuration
=============
Open the web page
^^^^^^^^^^^^^^^^^
.. include:: ../common/common_configuration.rst
Using a domain name to connect to a website requires setting up DNS Servers. For this example, it is possible to use the IP address directly
.. |SOFTWARE_NAME| replace:: WebBrowser
.. |SOFTWARE_NAME_BACKTICK| replace:: ``WebBrowser``
.. code-block:: python
``target_url``
""""""""""""""
# check that the get request succeeded
print(client.get_webpage("http://192.168.1.10")) # should be True
The URL that the ``WebBrowser`` will request when ``get_webpage`` is called without parameters.
The URL can be in any format so long as the domain is within it e.g.
The domain ``arcd.com`` can be matched by
- http://arcd.com/
- http://arcd.com/users/
- arcd.com