#2257: rearrange software pages + creating a list of applications and services which is hopefully a single point that should be referred to
This commit is contained in:
Czar Echavez
@@ -0,0 +1,141 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
|
||||
DataManipulationBot
|
||||
===================
|
||||
|
||||
The ``DataManipulationBot`` class provides functionality to connect to a ``DatabaseService`` and execute malicious SQL statements.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The bot is intended to simulate a malicious actor carrying out attacks like:
|
||||
|
||||
- Dropping tables
|
||||
- Deleting records
|
||||
- Modifying data
|
||||
|
||||
on a database server by abusing an application's trusted database connectivity.
|
||||
|
||||
The bot performs attacks in the following stages to simulate the real pattern of an attack:
|
||||
|
||||
- Logon - *The bot gains credentials and accesses the node.*
|
||||
- Port Scan - *The bot finds accessible database servers on the network.*
|
||||
- Attacking - *The bot delivers the payload to the discovered database servers.*
|
||||
|
||||
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
|
||||
- Database password (if needed)
|
||||
- SQL statement payload
|
||||
- Probabilities for succeeding each of the above attack stages
|
||||
- Call ``run`` to connect and execute the statement.
|
||||
|
||||
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
|
||||
-------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client_1 = Computer(
|
||||
hostname="client_1",
|
||||
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
|
||||
)
|
||||
network.connect(endpoint_b=client_1.network_interface[1], endpoint_a=switch_2.network_interface[1])
|
||||
client_1.software_manager.install(DataManipulationBot)
|
||||
data_manipulation_bot: DataManipulationBot = client_1.software_manager.software.get("DataManipulationBot")
|
||||
data_manipulation_bot.configure(server_ip_address=IPv4Address("192.168.1.14"), payload="DELETE")
|
||||
data_manipulation_bot.run()
|
||||
|
||||
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:
|
||||
# ...
|
||||
agents:
|
||||
- ref: data_manipulation_red_bot
|
||||
team: RED
|
||||
type: RedDatabaseCorruptingAgent
|
||||
|
||||
observation_space:
|
||||
type: UC2RedObservation
|
||||
options:
|
||||
nodes:
|
||||
- node_ref: client_1
|
||||
observations:
|
||||
- logon_status
|
||||
- operating_status
|
||||
applications:
|
||||
- application_ref: data_manipulation_bot
|
||||
observations:
|
||||
operating_status
|
||||
health_status
|
||||
folders: {}
|
||||
|
||||
action_space:
|
||||
action_list:
|
||||
- type: DONOTHING
|
||||
- type: NODE_APPLICATION_EXECUTE
|
||||
options:
|
||||
nodes:
|
||||
- node_ref: client_1
|
||||
applications:
|
||||
- application_ref: data_manipulation_bot
|
||||
max_folders_per_node: 1
|
||||
max_files_per_folder: 1
|
||||
max_services_per_node: 1
|
||||
|
||||
reward_function:
|
||||
reward_components:
|
||||
- type: DUMMY
|
||||
|
||||
agent_settings:
|
||||
start_settings:
|
||||
start_step: 25
|
||||
frequency: 20
|
||||
variance: 5
|
||||
# ...
|
||||
|
||||
simulation:
|
||||
network:
|
||||
nodes:
|
||||
- ref: client_1
|
||||
type: computer
|
||||
# ... additional configuration here
|
||||
applications:
|
||||
- ref: data_manipulation_bot
|
||||
type: DataManipulationBot
|
||||
options:
|
||||
port_scan_p_of_success: 0.1
|
||||
data_manipulation_p_of_success: 0.1
|
||||
payload: "DELETE"
|
||||
server_ip: 192.168.1.14
|
||||
|
||||
Implementation
|
||||
--------------
|
||||
|
||||
The bot extends ``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.
|
||||
@@ -0,0 +1,38 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
|
||||
DatabaseClient
|
||||
===============
|
||||
|
||||
The DatabaseClient provides a client interface for connecting to the ``DatabaseService``.
|
||||
|
||||
Key features
|
||||
^^^^^^^^^^^^
|
||||
|
||||
- Connects to the ``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``.
|
||||
- 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``
|
||||
- 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.
|
||||
@@ -0,0 +1,8 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
DoSBot
|
||||
------
|
||||
|
||||
test
|
||||
@@ -0,0 +1,84 @@
|
||||
.. only:: comment
|
||||
|
||||
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
|
||||
|
||||
|
||||
WebBrowser
|
||||
==========
|
||||
|
||||
The ``WebBrowser`` provides a client interface for connecting to the ``WebServer``.
|
||||
|
||||
Key features
|
||||
^^^^^^^^^^^^
|
||||
|
||||
- Connects to the ``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
|
||||
- GET: performs an HTTP GET request from client to server
|
||||
- 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
|
||||
-------------
|
||||
|
||||
Dependencies
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. 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.system.applications.web_browser import WebBrowser
|
||||
from primaite.simulator.system.services.web_server.web_server_service import WebServer
|
||||
|
||||
Example peer to peer network
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
net = Network()
|
||||
|
||||
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])
|
||||
|
||||
Install the Web Server
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# web browser is automatically installed in computer nodes
|
||||
# IRL this is usually included with an OS
|
||||
client: WebBrowser = pc1.software_manager.software['WebBrowser']
|
||||
|
||||
# install web server
|
||||
srv.software_manager.install(WebServer)
|
||||
webserv: WebServer = srv.software_manager.software['WebServer']
|
||||
|
||||
Open the web page
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# check that the get request succeeded
|
||||
print(client.get_webpage("http://192.168.1.10")) # should be True
|
||||
Reference in New Issue
Block a user