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

Merge branch 'feature/#3110-userguide-fixes' of ssh.dev.azure.com:v3/ma-dev-uk/PrimAITE/PrimAITE into feature/#3110-userguide-fixes

Browse Source
This commit is contained in:
Nick Todd
2025-03-12 10:22:26 +00:00
parent f19422e1f0 213ed045ee
commit 747fe72065
2 changed files with 64 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
src/primaite/notebooks/How-To-Use-Primaite-Dev-Mode.ipynb
View File

@@ -6,11 +6,11 @@
"source": [
"# PrimAITE Developer mode\n",
"\n",
"PrimAITE has built in developer tools.\n",
"© Crown-owned copyright 2025, Defence Science and Technology Laboratory UK\n",
"\n",
"The dev-mode is designed to help make the development of PrimAITE easier.\n",
"`NOTE: For the purposes of the notebook, the commands are preceded by \"!\". When running the commands, remove the \"!\".`\n",
"\n",
"`NOTE: For the purposes of the notebook, the commands are preceeded by \"!\". When running the commands, run it without the \"!\".`\n",
"PrimAITE has built in developer tools which are designed to aid in PrimAITE development.\n",
"\n",
"To display the available dev-mode options, run the command below:"
]
@@ -41,14 +41,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Dev mode options"
"## PrimAITE developer mode CLI options"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### enable\n",
"### ``enable``\n",
"\n",
"Enables the dev mode for PrimAITE.\n",
"\n",
@@ -70,7 +70,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### disable\n",
"### ``disable``\n",
"\n",
"Disables the dev mode for PrimAITE.\n",
"\n",
@@ -90,7 +90,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### show\n",
"### ``show``\n",
"\n",
"Shows if PrimAITE is running in dev mode or production mode.\n",
"\n",
@@ -110,7 +110,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### config\n",
"### ``config``\n",
"\n",
"Configure the PrimAITE developer mode"
]
@@ -128,7 +128,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### path\n",
"#### ``path``\n",
"\n",
"Set the path where generated session files will be output.\n",
"\n",
@@ -154,7 +154,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### --sys-log-level or -slevel\n",
"#### ``--sys-log-level`` or ``-slevel``\n",
"\n",
"Set the system log level.\n",
"\n",
@@ -189,7 +189,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### --agent-log-level or -alevel\n",
"#### ``--agent-log-level`` or ``-alevel``\n",
"\n",
"Set the agent log level.\n",
"\n",
@@ -224,7 +224,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### --output-sys-logs or -sys\n",
"#### ``--output-sys-logs`` or ``-sys``\n",
"\n",
"If enabled, developer mode will output system logs.\n",
"\n",
@@ -268,7 +268,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### --output-agent-logs or -agent\n",
"#### ``--output-agent-logs`` or ``-agent``\n",
"\n",
"If enabled, developer mode will output agent action logs.\n",
"\n",
@@ -312,7 +312,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### --output-pcap-logs or -pcap\n",
"#### ``--output-pcap-logs`` or ``-pcap``\n",
"\n",
"If enabled, developer mode will output PCAP logs.\n",
"\n",
@@ -356,7 +356,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"#### --output-to-terminal or -t\n",
"#### ``--output-to-terminal`` or ``-t``\n",
"\n",
"If enabled, developer mode will output logs to the terminal.\n",
"\n",

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

@@ -8,6 +8,8 @@
"\n",
"© Crown-owned copyright 2025, Defence Science and Technology Laboratory UK\n",
"\n",
"_This notebook uses alternative version of [UC7](./UC7-E2E-Demo.ipynb) which has a larger focus on PrimAITE's simulation capabilities._\n",
"\n",
"## Overview\n",
"\n",
"This Jupyter notebook demonstrates a cyber scenario focusing on internal privilege escalation and data loss through the manipulation of SSH access and Access Control Lists (ACLs). The scenario is designed to model and visualise how a disgruntled junior engineer might exploit internal network vulnerabilities and social engineering of account credentials to escalate privileges and cause significant data loss and disruption to services.\n",
@@ -21,11 +23,11 @@
"</a>\n",
"\n",
"\n",
"- **SomeTech Developer PC (`some_tech_jnr_dev_pc`)**: The workstation used by the junior engineer.\n",
"- **SomeTech Core Router (`some_tech_rt`)**: A critical network device that controls access between nodes.\n",
"- **SomeTech PostgreSQL Database Server (`some_tech_db_srv`)**: Hosts the company’s critical database.\n",
"- **SomeTech Storage Server (`some_tech_storage_srv`)**: Stores important files and database backups.\n",
"- **SomeTech Web Server (`some_tech_web_srv`)**: Serves the company’s website.\n",
"- **SomeTech Developer PC** (`some_tech_jnr_dev_pc`): The workstation used by the junior engineer.\n",
"- **SomeTech Core Router** (`some_tech_rt`): A critical network device that controls access between nodes.\n",
"- **SomeTech PostgreSQL Database Server** (`some_tech_db_srv`): Hosts the company’s critical database.\n",
"- **SomeTech Storage Server** (`some_tech_storage_srv`): Stores important files and database backups.\n",
"- **SomeTech Web Server** (`some_tech_web_srv`): Serves the company’s website.\n",
"\n",
"By default, the junior developer PC is restricted from connecting to the storage server via FTP or SSH due to ACL rules that permit only senior members of the engineering team to access these services.\n",
"\n",
@@ -35,12 +37,12 @@
"\n",
"1. **Privilege Escalation**: The junior engineer uses social engineering to obtain login credentials for the core router, SSHs into the router, and modifies the ACL rules to allow SSH access from their PC to the storage server.\n",
"2. **Remote Access**: The junior engineer then uses the newly gained SSH access to connect to the storage server from their PC. This step is crucial for executing further actions, such as deleting files.\n",
"3. **File Deletion**: With SSH access to the storage server, the engineer deletes the backup file from the storage server and subsequently removes critical data from the PostgreSQL database, bringing down the sometech.ai website.\n",
"4. **Website Impact Verification:** After the deletion of the database backup, the scenario checks the sometech.ai website's status to confirm it has been brought down due to the data loss.\n",
"3. **File Deletion**: With SSH access to the storage server, the engineer deletes the backup file from the storage server and subsequently removes critical data from the PostgreSQL database, bringing down the *sometech.ai* website.\n",
"4. **Website Impact Verification:** After the deletion of the database backup, the scenario checks the *sometech.ai* website's status to confirm it has been brought down due to the data loss.\n",
"5. **Database Restore Failure:** An attempt is made to restore the deleted backup, demonstrating that the restoration fails and highlighting the severity of the data loss.\n",
"\n",
"### Notes:\n",
"- The demo will utilise CAOS (Common Action and Observation Space) actions wherever they are available. For actions where a CAOS action does not yet exist, the action will be performed manually on the node/service.\n",
"- The demo will utilise **CAOS** (Common Action and Observation Space) actions wherever they are available. For actions where a CAOS action does not yet exist, the action will be performed manually on the node/service via the PrimAITE simulation API.\n",
"- This notebook will be updated to incorporate new CAOS actions as they become supported."
]
},
@@ -72,6 +74,8 @@
"\n",
"from primaite import PRIMAITE_PATHS\n",
"from primaite.game.game import PrimaiteGame\n",
"from primaite.simulator.file_system.folder import Folder\n",
"from primaite.utils.validation.port import PORT_LOOKUP\n",
"from primaite.simulator.network.hardware.nodes.host.computer import Computer\n",
"from primaite.simulator.network.hardware.nodes.network.router import Router\n",
"from primaite.simulator.network.hardware.nodes.host.server import Server\n",
@@ -186,8 +190,8 @@
},
"outputs": [],
"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"
"db_backup_folder_list = [folder.name for folder in some_tech_storage_srv.file_system.folders.values() if folder.name != \"root\"]\n",
"db_backup_folder = db_backup_folder_list[0]"
]
},
{
@@ -209,11 +213,11 @@
},
"outputs": [],
"source": [
"caos_action = [\n",
"simulation_request = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
" \"service\", \"terminal\", \"node-session-remote-login\", \"admin\", \"admin\", str(some_tech_storage_srv.network_interface[1].ip_address)\n",
" \"service\", \"terminal\", \"node_session_remote_login\", \"admin\", \"admin\", str(some_tech_storage_srv.network_interface[1].ip_address)\n",
"]\n",
"game.simulation.apply_request(caos_action)"
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -233,8 +237,8 @@
},
"outputs": [],
"source": [
"caos_action = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(caos_action)"
"simulation_request = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -267,11 +271,11 @@
},
"outputs": [],
"source": [
"caos_action = [\n",
"simulation_request = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
" \"service\", \"terminal\", \"node-session-remote-login\", \"admin\", \"admin\", str(some_tech_rt.network_interface[4].ip_address)\n",
" \"service\", \"terminal\", \"node_session_remote_login\", \"admin\", \"admin\", str(some_tech_rt.network_interface[4].ip_address)\n",
"]\n",
"game.simulation.apply_request(caos_action)"
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -313,20 +317,20 @@
},
"outputs": [],
"source": [
"caos_action = [\n",
"simulation_request = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
" \"service\", \"terminal\", \"send_remote_command\", str(some_tech_rt.network_interface[4].ip_address),\n",
" {\n",
" \"command\": [\n",
" \"acl\", \"add_rule\", \"PERMIT\", \"TCP\",\n",
" str(some_tech_jnr_dev_pc.network_interface[1].ip_address), \"0.0.0.0\", \"SSH\",\n",
" str(some_tech_storage_srv.network_interface[1].ip_address), \"0.0.0.0\", \"SSH\",\n",
" str(some_tech_jnr_dev_pc.network_interface[1].ip_address), \"0.0.0.0\", PORT_LOOKUP[\"SSH\"],\n",
" str(some_tech_storage_srv.network_interface[1].ip_address), \"0.0.0.0\", PORT_LOOKUP[\"SSH\"],\n",
" 1\n",
" ]\n",
" }\n",
"]\n",
"\n",
"game.simulation.apply_request(caos_action)"
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -366,11 +370,11 @@
},
"outputs": [],
"source": [
"caos_action = [\n",
"simulation_request = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
" \"service\", \"terminal\", \"remote_logoff\", str(some_tech_rt.network_interface[4].ip_address)\n",
"]\n",
"game.simulation.apply_request(caos_action)"
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -404,11 +408,11 @@
"metadata": {},
"outputs": [],
"source": [
"caos_action = [\n",
"simulation_request = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
" \"service\", \"terminal\", \"node-session-remote-login\", \"admin\", \"admin\", str(some_tech_storage_srv.network_interface[1].ip_address)\n",
" \"service\", \"terminal\", \"node_session_remote_login\", \"admin\", \"admin\", str(some_tech_storage_srv.network_interface[1].ip_address)\n",
"]\n",
"game.simulation.apply_request(caos_action)"
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -419,7 +423,7 @@
},
"outputs": [],
"source": [
"caos_action = [\n",
"simulation_request = [\n",
" \"network\", \"node\", \"some_tech_jnr_dev_pc\", \n",
" \"service\", \"terminal\", \"send_remote_command\", str(some_tech_storage_srv.network_interface[1].ip_address),\n",
" {\n",
@@ -429,7 +433,7 @@
" }\n",
"]\n",
"\n",
"game.simulation.apply_request(caos_action)"
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -450,6 +454,16 @@
"some_tech_storage_srv.file_system.show(full=True)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Should return 'None' as the database.db file has been deleted (as shown in the above table)\n",
"print(some_tech_storage_srv.file_system.get_file(folder_name=db_backup_folder, file_name=\"database.db\", include_deleted=False))"
]
},
{
"cell_type": "markdown",
"metadata": {},
@@ -476,8 +490,8 @@
},
"outputs": [],
"source": [
"caos_action = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(caos_action)"
"simulation_request = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -535,8 +549,8 @@
},
"outputs": [],
"source": [
"caos_action = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(caos_action)"
"simulation_request = [\"network\", \"node\", \"some_tech_jnr_dev_pc\", \"application\", \"web-browser\", \"execute\"]\n",
"game.simulation.apply_request(simulation_request)"
]
},
{
@@ -595,7 +609,7 @@
],
"metadata": {
"kernelspec": {
"display_name": ".venv",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
@@ -609,7 +623,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.11"
"version": "3.10.12"
}
},
"nbformat": 4,