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

Revisions to make the how-to guides show in navigation pane

Browse Source
This commit is contained in:
Charlie Crane
2025-02-26 15:31:03 +00:00
parent 0d93981ef8
commit 7fe4915f42
9 changed files with 2045 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.pre-commit-config.yaml
View File

@@ -1,10 +1,10 @@
repos:
# - repo: local
# hooks:
# - id: ensure-copyright-clause
# name: ensure copyright clause
# entry: python copyright_clause_pre_commit_hook.py
# language: python
- repo: local
hooks:
- id: ensure-copyright-clause
name: ensure copyright clause
entry: python copyright_clause_pre_commit_hook.py
language: python
- repo: http://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:

12
docs/index.rst
View File

@@ -17,6 +17,18 @@ What is PrimAITE?
source/dependencies
source/glossary
.. toctree::
:maxdepth: 8
:caption: How To
:hidden:
source/how_to
source/how_to_guides/custom_actions
source/how_to_guides/custom_environments
source/how_to_guides/custom_rewards
source/how_to_guides/custom_software
source/how_to_guides/using_dev_cli
.. toctree::
:caption: Usage:
:hidden:

10
docs/source/how_to.rst Normal file
View File

@@ -0,0 +1,10 @@
.. only:: comment
© Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
How-To Guides
=============
These how-to guides aim to provide a starting point for development within PrimAITE, creating your own custom components and environments for use when training agents. More detailed information for each section can be found within the documentation.
There are also some additional notebooks which provide a walkthrough of established content. It's encouraged to reference these when developing for PrimAITE.

10
docs/source/how_to_guides/custom_actions.rst
View File

@@ -7,13 +7,15 @@
Creating Custom Actions in PrimAITE
***********************************
PrimAITE contains a selection of available actions that can be exercised within a training session, listed within ``actions.py``. `Note`: Agents are only able to perform the actions listed within it's action_map, defined within it's configuration YAML. See :ref:`custom_environment` for more information.
PrimAITE contains a selection of possible actions that can be exercised within a training environment. Actions provided as a part of PrimAITE can be seen within `src/primaite/game/agent/actions`. `Note`: Agents are only able to perform the actions listed within it's action_map, defined within it's configuration YAML. See :ref:`custom_environment` for more information.
Developing Custom Actions
============================
=========================
Actions within PrimAITE follow a default format, as seen below and in ``actions.py``. It's important that they have an identifier when declared, as this is used when creating the training environment.
An example of a custom action is seen below, with key information about what is required for new actions in :ref:`extensible_actions`.
.. code:: Python
class ExampleActionClass(AbstractAction, identifier="ExampleActions"):
@@ -36,9 +38,9 @@ Any custom actions should then be added to the `ActionManager` class, and the `a
Interaction with the PrimAITE Request Manager
==============================================
=============================================
Where an action would cause a request to be sent through the PrimAITE RequestManager, a `form_request` method is expected to be defined within the Action Class. This should format the action into a format that can be ingested by the `RequestManager`. Examples of this include the `NodeFolderCreateAction`, which sends a formed request to create a folder on a given node (seen below).
Where an action would cause a request to be sent through the PrimAITE RequestManager, a `form_request` method is expected to be defined within the Action Class. This should format the action into a format that can be ingested by the `RequestManager`. Examples of this include the `NodeFolderCreateAction`, which sends a formed request to create a folder on a given node (seen below):
.. code:: Python

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

@@ -25,7 +25,9 @@ You configuration file should follow the hierarchy seen below:
simulation:
...
MetaData Tag
============
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.
For detailed information about each configuration item found within the configuration file, see :ref:`Configurable Items`.
For detailed information about the remaining configuration items found within the configuration file, see :ref:`Configurable Items`.

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

@@ -7,7 +7,6 @@
Extensible Actions
******************
Changes to Actions class Structure.
===================================
@@ -33,7 +32,7 @@ The ConfigSchema sub-class of the action must contain all `configurable` variabl
Unique discriminator
#################
####################
When declaring a custom class, it must have a unique discriminator string, that allows PrimAITE to generate the correct action when needed.

1780
src/primaite/notebooks/Command-and-Control-E2E-Demonstration.ipynb
View File

File diff suppressed because it is too large Load Diff

407
src/primaite/notebooks/Privilege-Escalation-and-Data-Loss-Example.ipynb
View File

@@ -53,16 +53,37 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 1,
"metadata": {},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"C:\\Users\\CharlieCrane\\primaite\\4.0.0a1-dev\\notebooks\\example_notebooks\\Privilege-Escalation-and-Data-Loss-Example.ipynb\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"2025-02-26 14:11:04,193: Performing the PrimAITE first-time setup...\n",
"2025-02-26 14:11:04,193: Building the PrimAITE app directories...\n",
"2025-02-26 14:11:04,193: Building primaite_config.yaml...\n",
"2025-02-26 14:11:04,193: Rebuilding the demo notebooks...\n",
"2025-02-26 14:11:04,226: Reset example notebook: C:\\Users\\CharlieCrane\\primaite\\4.0.0a1-dev\\notebooks\\example_notebooks\\Privilege-Escalation-and-Data-Loss-Example.ipynb\n",
"2025-02-26 14:11:04,246: Rebuilding the example notebooks...\n",
"2025-02-26 14:11:04,251: PrimAITE setup complete!\n"
]
}
],
"source": [
"!primaite setup"
]
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 2,
"metadata": {
"tags": []
},
@@ -90,7 +111,7 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 3,
"metadata": {
"tags": []
},
@@ -113,7 +134,7 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 4,
"metadata": {
"tags": []
},
@@ -140,33 +161,73 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 5,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"+--------------------------------------------------------------------+\n",
"| some_tech_storage_srv File System |\n",
"+-----------+------+---------------+-----------------------+---------+\n",
"| File Path | Size | Health status | Visible health status | Deleted |\n",
"+-----------+------+---------------+-----------------------+---------+\n",
"| root | 0 B | GOOD | NONE | False |\n",
"+-----------+------+---------------+-----------------------+---------+\n"
]
}
],
"source": [
"some_tech_storage_srv.file_system.show(full=True)"
]
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 6,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"True"
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"some_tech_db_service.backup_database()"
]
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 7,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"+--------------------------------------------------------------------------------------------------------------+\n",
"| some_tech_storage_srv File System |\n",
"+--------------------------------------------------+---------+---------------+-----------------------+---------+\n",
"| File Path | Size | Health status | Visible health status | Deleted |\n",
"+--------------------------------------------------+---------+---------------+-----------------------+---------+\n",
"| ed8587f2-7100-4837-bfbb-2a06bfafa8db/database.db | 4.77 MB | GOOD | NONE | False |\n",
"| root | 0 B | GOOD | NONE | False |\n",
"+--------------------------------------------------+---------+---------------+-----------------------+---------+\n"
]
}
],
"source": [
"some_tech_storage_srv.file_system.show(full=True)"
]
@@ -180,11 +241,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 8,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"'ed8587f2-7100-4837-bfbb-2a06bfafa8db'"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"db_backup_folder = [folder.name for folder in some_tech_storage_srv.file_system.folders.values() if folder.name != \"root\"][0]\n",
"db_backup_folder"
@@ -203,11 +275,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 9,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='failure', data={})"
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
@@ -227,11 +310,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 10,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='success', data={})"
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(caos_action)"
@@ -252,20 +346,42 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 11,
"metadata": {},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"[]"
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"game.get_sim_state()[\"network\"][\"nodes\"][\"some_tech_rt\"][\"services\"][\"user-session-manager\"][\"active_remote_sessions\"]"
]
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 12,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='success', data={'ip_address': '10.10.2.1', 'username': 'admin'})"
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
@@ -276,11 +392,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 13,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"['ee4b75dc-1f70-4f93-a25f-d0466afecfd9']"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"game.get_sim_state()[\"network\"][\"nodes\"][\"some_tech_rt\"][\"services\"][\"user-session-manager\"][\"active_remote_sessions\"]"
]
@@ -296,22 +423,59 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 14,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"+---------------------------------------------------------------------------------------------------------------------+\n",
"| some_tech_rt Access Control List |\n",
"+-------+--------+----------+-------------+--------------+----------+-------------+--------------+----------+---------+\n",
"| Index | Action | Protocol | Src IP | Src Wildcard | Src Port | Dst IP | Dst Wildcard | Dst Port | Matched |\n",
"+-------+--------+----------+-------------+--------------+----------+-------------+--------------+----------+---------+\n",
"| 11 | PERMIT | ANY | 94.10.180.6 | 0.0.0.0 | 5432 | 10.10.1.11 | 0.0.0.0 | 5432 | 2 |\n",
"| 12 | PERMIT | ANY | 10.10.1.11 | 0.0.0.0 | 5432 | 94.10.180.6 | 0.0.0.0 | 5432 | 2 |\n",
"| 13 | DENY | ANY | 10.10.2.12 | 0.0.0.0 | 21 | 10.10.1.12 | 0.0.0.0 | 21 | 0 |\n",
"| 14 | DENY | ANY | 10.10.2.12 | 0.0.0.0 | 22 | 10.10.1.12 | 0.0.0.0 | 22 | 1 |\n",
"| 15 | PERMIT | ANY | 10.10.2.0 | 0.0.0.255 | ANY | 10.10.1.0 | 0.0.0.255 | ANY | 0 |\n",
"| 16 | PERMIT | ANY | 10.10.1.0 | 0.0.0.255 | ANY | 10.10.2.0 | 0.0.0.255 | ANY | 0 |\n",
"| 17 | PERMIT | ANY | ANY | ANY | 80 | ANY | ANY | 80 | 2 |\n",
"| 18 | PERMIT | ANY | 10.10.0.0 | 0.0.255.255 | 219 | ANY | ANY | ANY | 7 |\n",
"| 19 | PERMIT | icmp | 10.10.0.0 | 0.0.255.255 | ANY | ANY | ANY | ANY | 0 |\n",
"| 21 | PERMIT | ANY | 94.10.180.6 | 0.0.0.0 | 80 | 10.10.0.0 | 0.0.255.255 | 80 | 0 |\n",
"| 22 | PERMIT | ANY | ANY | ANY | 53 | ANY | ANY | 53 | 2 |\n",
"| 23 | PERMIT | ANY | ANY | ANY | 22 | ANY | ANY | 22 | 1 |\n",
"| 24 | DENY | ANY | ANY | ANY | ANY | ANY | ANY | ANY | 0 |\n",
"+-------+--------+----------+-------------+--------------+----------+-------------+--------------+----------+---------+\n"
]
}
],
"source": [
"some_tech_rt.acl.show()"
]
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 15,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='success', data={})"
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
@@ -340,11 +504,38 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 16,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"+---------------------------------------------------------------------------------------------------------------------+\n",
"| some_tech_rt Access Control List |\n",
"+-------+--------+----------+-------------+--------------+----------+-------------+--------------+----------+---------+\n",
"| Index | Action | Protocol | Src IP | Src Wildcard | Src Port | Dst IP | Dst Wildcard | Dst Port | Matched |\n",
"+-------+--------+----------+-------------+--------------+----------+-------------+--------------+----------+---------+\n",
"| 1 | PERMIT | tcp | 10.10.2.12 | 0.0.0.0 | 22 | 10.10.1.12 | 0.0.0.0 | 22 | 0 |\n",
"| 11 | PERMIT | ANY | 94.10.180.6 | 0.0.0.0 | 5432 | 10.10.1.11 | 0.0.0.0 | 5432 | 2 |\n",
"| 12 | PERMIT | ANY | 10.10.1.11 | 0.0.0.0 | 5432 | 94.10.180.6 | 0.0.0.0 | 5432 | 2 |\n",
"| 13 | DENY | ANY | 10.10.2.12 | 0.0.0.0 | 21 | 10.10.1.12 | 0.0.0.0 | 21 | 0 |\n",
"| 14 | DENY | ANY | 10.10.2.12 | 0.0.0.0 | 22 | 10.10.1.12 | 0.0.0.0 | 22 | 1 |\n",
"| 15 | PERMIT | ANY | 10.10.2.0 | 0.0.0.255 | ANY | 10.10.1.0 | 0.0.0.255 | ANY | 0 |\n",
"| 16 | PERMIT | ANY | 10.10.1.0 | 0.0.0.255 | ANY | 10.10.2.0 | 0.0.0.255 | ANY | 0 |\n",
"| 17 | PERMIT | ANY | ANY | ANY | 80 | ANY | ANY | 80 | 2 |\n",
"| 18 | PERMIT | ANY | 10.10.0.0 | 0.0.255.255 | 219 | ANY | ANY | ANY | 7 |\n",
"| 19 | PERMIT | icmp | 10.10.0.0 | 0.0.255.255 | ANY | ANY | ANY | ANY | 0 |\n",
"| 21 | PERMIT | ANY | 94.10.180.6 | 0.0.0.0 | 80 | 10.10.0.0 | 0.0.255.255 | 80 | 0 |\n",
"| 22 | PERMIT | ANY | ANY | ANY | 53 | ANY | ANY | 53 | 2 |\n",
"| 23 | PERMIT | ANY | ANY | ANY | 22 | ANY | ANY | 22 | 2 |\n",
"| 24 | DENY | ANY | ANY | ANY | ANY | ANY | ANY | ANY | 0 |\n",
"+-------+--------+----------+-------------+--------------+----------+-------------+--------------+----------+---------+\n"
]
}
],
"source": [
"some_tech_rt.acl.show()"
]
@@ -360,11 +551,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 17,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='success', data={})"
]
},
"execution_count": 17,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
@@ -382,9 +584,20 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 18,
"metadata": {},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"[]"
]
},
"execution_count": 18,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"game.get_sim_state()[\"network\"][\"nodes\"][\"some_tech_rt\"][\"services\"][\"user-session-manager\"][\"active_remote_sessions\"]"
]
@@ -400,9 +613,20 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 19,
"metadata": {},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='success', data={'ip_address': '10.10.1.12', 'username': 'admin'})"
]
},
"execution_count": 19,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
@@ -413,11 +637,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 20,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='success', data={})"
]
},
"execution_count": 20,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
@@ -441,11 +676,26 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 21,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"+--------------------------------------------------------------------------------------------------------------+\n",
"| some_tech_storage_srv File System |\n",
"+--------------------------------------------------+---------+---------------+-----------------------+---------+\n",
"| File Path | Size | Health status | Visible health status | Deleted |\n",
"+--------------------------------------------------+---------+---------------+-----------------------+---------+\n",
"| ed8587f2-7100-4837-bfbb-2a06bfafa8db/database.db | 4.77 MB | GOOD | NONE | True |\n",
"| root | 0 B | GOOD | NONE | False |\n",
"+--------------------------------------------------+---------+---------------+-----------------------+---------+\n"
]
}
],
"source": [
"some_tech_storage_srv.file_system.show(full=True)"
]
@@ -470,11 +720,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 22,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='success', data={})"
]
},
"execution_count": 22,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(caos_action)"
@@ -489,11 +750,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 23,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"DatabaseClientConnection(connection_id='cb712d1e-68d2-4504-94a2-8c67d3652ccd', is_active=True)"
]
},
"execution_count": 23,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"some_tech_jnr_dev_db_client.server_ip_address = some_tech_db_srv.network_interface[1].ip_address\n",
"some_tech_jnr_dev_db_connection = some_tech_jnr_dev_db_client.get_new_connection()\n",
@@ -511,11 +783,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 24,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"True"
]
},
"execution_count": 24,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"some_tech_jnr_dev_db_connection.query(\"DELETE\")"
]
@@ -529,11 +812,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 25,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"RequestResponse(status='failure', data={})"
]
},
"execution_count": 25,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"caos_action = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(caos_action)"
@@ -550,11 +844,22 @@
},
{
"cell_type": "code",
"execution_count": null,
"execution_count": 26,
"metadata": {
"tags": []
},
"outputs": [],
"outputs": [
{
"data": {
"text/plain": [
"False"
]
},
"execution_count": 26,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"some_tech_db_service.restore_backup()"
]
@@ -595,7 +900,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"display_name": ".venv",
"language": "python",
"name": "python3"
},
@@ -609,7 +914,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.12"
"version": "3.10.11"
}
},
"nbformat": 4,