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

Updates to documentation and inclusion of how-to guides

Browse Source
This commit is contained in:
Charlie Crane
2025-02-27 18:16:45 +00:00
parent 891467d1d3
commit 1f6f007941
25 changed files with 188 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/source/how_to_guides/custom_environments.rst
View File

@@ -16,6 +16,10 @@ You configuration file should follow the hierarchy seen below:
metadata:
version: 4.0
required_plugins:
- name: Example_Plugin
version: 1.0
io_settings:
...
game:
@@ -25,9 +29,17 @@ You configuration file should follow the hierarchy seen below:
simulation:
...
MetaData Tag
============
MetaData
========
It's important to include the metadata tag within your YAML file, as this is used to ensure PrimAITE can interpret the configuration correctly. This should also include any plugins that are required for the defined environment, along with their respective version.
Required Plugins
================
Should your custom environment need any additional PrimAITE plugins, each must be specified under the `required_plugins` tab, as seen in the above example.
Configuration Items
===================
For detailed information about the remaining configuration items found within the configuration file, see :ref:`Configurable Items`.

2
docs/source/how_to_guides/custom_rewards.rst
View File

@@ -9,6 +9,8 @@ Creating Custom Rewards in PrimAITE
Rewards within PrimAITE are contained within ``rewards.py``, which details the rewards available for all agents within training sessions, how they are calculated and any other specific information where necessary.
Rewards within PrimAITE have been updated to facilitate extensability and the creation of plugins with the release of PrimAITE version 4.0. Additional information about this is covered within :ref:`extensible_rewards`.
Custom Rewards within PrimAITE should inherit from the ``AbstractReward`` class, found in ``rewards.py``. It's important to include an identifier for any class created within PrimAITE.
.. code:: Python

2
docs/source/how_to_guides/extensible_actions.rst
View File

@@ -65,4 +65,4 @@ The above action would fail pydantic validation as the discriminator "node-folde
form_request method
###################
PrimAITE actions need to have a `form_request` method, which can be passed to the `RequestManager` for processing. This allows the custom action to be actioned within the simulation environment.
PrimAITE actions need to have a `form_request` method, which can be passed to the `RequestManager` for processing. This allows the custom action to be actioned within the simulation environment. Further information and an example of this can be seen in :ref:`custom_actions`.

32
docs/source/simulation_components/network/base_hardware.rst
View File

@@ -42,7 +42,7 @@ Example code where a node is turned on:
from primaite.simulator.network.hardware.base import Node
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
node = Node(hostname="pc_a")
node = Node(config={"hostname":"pc_a"})
assert node.operating_state is NodeOperatingState.OFF # By default, node is instantiated in an OFF state
@@ -65,7 +65,7 @@ If the node needs to be instantiated in an on state:
from primaite.simulator.network.hardware.base import Node
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
node = Node(hostname="pc_a", operating_state=NodeOperatingState.ON)
node = Node(config={"hostname":"pc_a", "operating_state":NodeOperatingState.ON})
assert node.operating_state is NodeOperatingState.ON # node is in ON state
@@ -76,7 +76,7 @@ Setting ``start_up_duration`` and/or ``shut_down_duration`` to ``0`` will allow
from primaite.simulator.network.hardware.base import Node
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
node = Node(config={"hostname":"pc_a", "start_up_duration":0, "shut_down_duration":0})
assert node.operating_state is NodeOperatingState.OFF # node is in OFF state
@@ -196,21 +196,23 @@ Setting up a Client-Server Network
def client_server_network() -> Tuple[Computer, Server, Network]:
network = Network()
client = Computer(
hostname="client",
ip_address="192.168.1.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
client = Computer(config={
"hostname":"client",
"ip_address":"192.168.1.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
client.power_on()
server = Server(
hostname="server",
ip_address="192.168.1.3",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.1.3",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
server.power_on()

28
docs/source/simulation_components/network/network.rst
View File

@@ -48,7 +48,7 @@ we'll use the following Network that has a client, server, two switches, and a r
.. code-block:: python
router_1 = Router(hostname="router_1", num_ports=3)
router_1 = Router(config={"hostname":"router_1", "num_ports":3})
router_1.power_on()
router_1.configure_port(port=1, ip_address="192.168.1.1", subnet_mask="255.255.255.0")
router_1.configure_port(port=2, ip_address="192.168.2.1", subnet_mask="255.255.255.0")
@@ -57,9 +57,9 @@ we'll use the following Network that has a client, server, two switches, and a r
.. code-block:: python
switch_1 = Switch(hostname="switch_1", num_ports=6)
switch_1 = Switch(config={"hostname":"switch_1", "num_ports":6})
switch_1.power_on()
switch_2 = Switch(hostname="switch_2", num_ports=6)
switch_2 = Switch(config={"hostname":"switch_2", "num_ports":6})
switch_2.power_on()
5. Connect the Switches to the Router
@@ -75,18 +75,20 @@ we'll use the following Network that has a client, server, two switches, and a r
.. code-block:: python
client_1 = Computer(
hostname="client_1",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.2.1"
client_1 = Computer(config = {
"hostname":"client_1",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.2.1",
}
)
client_1.power_on()
server_1 = Server(
hostname="server_1",
ip_address="192.168.1.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1"
server_1 = Server(config= {
"hostname":"server_1",
"ip_address":"192.168.1.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
}
)
server_1.power_on()

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

@@ -128,19 +128,19 @@ Python
network = Network()
switch = Switch(hostname="switch", start_up_duration=0, num_ports=4)
switch = Switch(config={"hostname":"switch", "start_up_duration":0, "num_ports":4})
switch.power_on()
node_a = Computer(hostname="node_a", ip_address="192.168.0.10", subnet_mask="255.255.255.0", start_up_duration=0)
node_a = Computer(config={"hostname":"node_a", "ip_address":"192.168.0.10", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_a.power_on()
network.connect(node_a.network_interface[1], switch.network_interface[1])
node_b = Computer(hostname="node_b", ip_address="192.168.0.11", subnet_mask="255.255.255.0", start_up_duration=0)
node_b = Computer(config={"hostname":"node_b", "ip_address":"192.168.0.11", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_b.power_on()
network.connect(node_b.network_interface[1], switch.network_interface[2])
node_c = Computer(hostname="node_c", ip_address="192.168.0.12", subnet_mask="255.255.255.0", start_up_duration=0)
node_c = Computer(config={"hostname":"node_c", "ip_address":"192.168.0.12", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_c.power_on()
network.connect(node_c.network_interface[1], switch.network_interface[3])

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

@@ -67,12 +67,13 @@ Python
from primaite.simulator.system.applications.red_applications.data_manipulation_bot import DataManipulationBot
from primaite.simulator.system.applications.database_client import DatabaseClient
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
client_1 = Computer(config={
"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(DatabaseClient)

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

@@ -48,12 +48,13 @@ Python
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
client_1 = Computer(config={
"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
}
)
# install DatabaseClient

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

@@ -45,12 +45,13 @@ Python
from primaite.simulator.system.applications.red_applications.dos_bot import dos-bot
# 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 = Computer(config={
"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()

40
docs/source/simulation_components/system/applications/nmap.rst
View File

@@ -70,39 +70,41 @@ The network we use for these examples is defined below:
router.configure_port(port=1, ip_address="192.168.1.1", subnet_mask="255.255.255.0")
# Set up PC 1
pc_1 = Computer(
hostname="pc_1",
ip_address="192.168.1.11",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0
pc_1 = Computer(config = {
"hostname":"pc_1",
"ip_address":"192.168.1.11",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
pc_1.power_on()
# Set up PC 2
pc_2 = Computer(
hostname="pc_2",
ip_address="192.168.1.12",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0
pc_2 = Computer(config = {
"hostname":"pc_2",
"ip_address":"192.168.1.12",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
pc_2.power_on()
pc_2.software_manager.install(DatabaseService)
pc_2.software_manager.software["DatabaseService"].start() # start the postgres server
# Set up PC 3
pc_3 = Computer(
hostname="pc_3",
ip_address="192.168.1.13",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0
pc_3 = Computer(config = {
"hostname";"pc_3",
"ip_address":"192.168.1.13",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0
)
# Don't power on PC 3
# Set up the switch
switch = Switch(hostname="switch", start_up_duration=0)
switch = Switch(config={"hostname":"switch", "start_up_duration":0})
switch.power_on()
# Connect devices

13
docs/source/simulation_components/system/applications/ransomware_script.rst
View File

@@ -52,12 +52,13 @@ Python
from primaite.simulator.system.applications.red_applications.RansomwareScript import RansomwareScript
from primaite.simulator.system.applications.database_client import DatabaseClient
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
client_1 = Computer(config={
"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(DatabaseClient)

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

@@ -50,12 +50,13 @@ The :ref:`DNSClient` must be configured to use the :ref:`DNSServer`. The :ref:`D
from primaite.simulator.system.applications.web_browser import WebBrowser
# 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 = Computer(config={
"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()

13
docs/source/simulation_components/system/services/database_service.rst
View File

@@ -55,12 +55,13 @@ Python
from primaite.simulator.system.services.database.database_service import DatabaseService
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
server.power_on()

13
docs/source/simulation_components/system/services/dns_client.rst
View File

@@ -45,12 +45,13 @@ Python
from primaite.simulator.system.services.dns.dns_client import DNSClient
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
server.power_on()

13
docs/source/simulation_components/system/services/dns_server.rst
View File

@@ -42,12 +42,13 @@ Python
from primaite.simulator.system.services.dns.dns_server import DNSServer
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
server.power_on()

13
docs/source/simulation_components/system/services/ftp_client.rst
View File

@@ -49,12 +49,13 @@ Python
from primaite.simulator.system.services.ftp.ftp_client import FTPClient
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.10",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.10",
"start_up_duration":0,
}
)
server.power_on()

13
docs/source/simulation_components/system/services/ftp_server.rst
View File

@@ -44,12 +44,13 @@ Python
from primaite.simulator.system.services.ftp.ftp_server import FTPServer
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.10",
"start_up_duration":0,
}
)
server.power_on()

13
docs/source/simulation_components/system/services/ntp_client.rst
View File

@@ -42,12 +42,13 @@ Python
from primaite.simulator.system.services.ntp.ntp_client import NTPClient
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.10",
"start_up_duration":0,
}
)
server.power_on()

13
docs/source/simulation_components/system/services/ntp_server.rst
View File

@@ -44,12 +44,13 @@ Python
from primaite.simulator.system.services.ntp.ntp_server import NTPServer
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.10",
"start_up_duration":0,
}
)
server.power_on()

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

@@ -57,12 +57,13 @@ Python
from primaite.simulator.system.services.terminal.terminal import Terminal
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
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,
client = Computer(config= {
"hostname":"client",
"ip_address":"192.168.10.21",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.10.1",
"operating_state":NodeOperatingState.ON,
}
)
terminal: Terminal = client.software_manager.software.get("Terminal")
@@ -80,9 +81,9 @@ Creating Remote Terminal Connection
network = Network()
node_a = Computer(hostname="node_a", ip_address="192.168.0.10", subnet_mask="255.255.255.0", start_up_duration=0)
node_a = Computer(config={"hostname":"node_a", "ip_address":"192.168.0.10", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_a.power_on()
node_b = Computer(hostname="node_b", ip_address="192.168.0.11", subnet_mask="255.255.255.0", start_up_duration=0)
node_b = Computer(config={"hostname":"node_b", "ip_address":"192.168.0.11", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_b.power_on()
network.connect(node_a.network_interface[1], node_b.network_interface[1])
@@ -106,9 +107,9 @@ Executing a basic application install command
network = Network()
node_a = Computer(hostname="node_a", ip_address="192.168.0.10", subnet_mask="255.255.255.0", start_up_duration=0)
node_a = Computer(config={"hostname":"node_a", "ip_address":"192.168.0.10", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_a.power_on()
node_b = Computer(hostname="node_b", ip_address="192.168.0.11", subnet_mask="255.255.255.0", start_up_duration=0)
node_b = Computer(config={"hostname":"node_b", "ip_address":"192.168.0.11", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_b.power_on()
network.connect(node_a.network_interface[1], node_b.network_interface[1])
@@ -134,9 +135,9 @@ Creating a folder on a remote node
network = Network()
node_a = Computer(hostname="node_a", ip_address="192.168.0.10", subnet_mask="255.255.255.0", start_up_duration=0)
node_a = Computer(config={"hostname":"node_a", "ip_address":"192.168.0.10", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_a.power_on()
node_b = Computer(hostname="node_b", ip_address="192.168.0.11", subnet_mask="255.255.255.0", start_up_duration=0)
node_b = Computer(config={"hostname":"node_b", "ip_address":"192.168.0.11", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_b.power_on()
network.connect(node_a.network_interface[1], node_b.network_interface[1])
@@ -161,9 +162,9 @@ Disconnect from Remote Node
network = Network()
node_a = Computer(hostname="node_a", ip_address="192.168.0.10", subnet_mask="255.255.255.0", start_up_duration=0)
node_a = Computer(config={"hostname":"node_a", "ip_address":"192.168.0.10", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_a.power_on()
node_b = Computer(hostname="node_b", ip_address="192.168.0.11", subnet_mask="255.255.255.0", start_up_duration=0)
node_b = Computer(config={"hostname":"node_b", "ip_address":"192.168.0.11", "subnet_mask":"255.255.255.0", "start_up_duration":0})
node_b.power_on()
network.connect(node_a.network_interface[1], node_b.network_interface[1])

13
docs/source/simulation_components/system/services/web_server.rst
View File

@@ -45,12 +45,13 @@ Python
from primaite.simulator.system.services.web_server.web_server import WebServer
# Create Server
server = Server(
hostname="server",
ip_address="192.168.2.2",
subnet_mask="255.255.255.0",
default_gateway="192.168.1.1",
start_up_duration=0,
server = Server(config = {
"hostname":"server",
"ip_address":"192.168.2.2",
"subnet_mask":"255.255.255.0",
"default_gateway":"192.168.1.1",
"start_up_duration":0,
}
)
server.power_on()

2
docs/source/simulation_components/system/software.rst
View File

@@ -23,7 +23,7 @@ See :ref:`Node Start up and Shut down`
from primaite.simulator.system.services.service import ServiceOperatingState
from primaite.simulator.system.services.web_server.web_server import WebServer
node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
node = Node(config={"hostname":"pc_a", "start_up_duration":0, "shut_down_duration":0})
node.power_on()
assert node.operating_state is NodeOperatingState.ON