PrimAITE/src/primaite/notebooks/Terminal-Processing.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Terminal Processing\n",
    "\n",
    "© Crown-owned copyright 2024, Defence Science and Technology Laboratory UK"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook serves as a guide on the functionality and use of the new Terminal simulation component.\n",
    "\n",
    "By default, the Terminal will come pre-installed on any simulation component which inherits from `HostNode` (Computer, Server, Printer), and simulates the Secure Shell (SSH) protocol as the communication method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from primaite.simulator.system.services.terminal.terminal import Terminal\n",
    "from primaite.simulator.network.container import Network\n",
    "from primaite.simulator.network.hardware.nodes.host.computer import Computer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def basic_network() -> Network:\n",
    "    \"\"\"Utility function for creating a default network to demonstrate Terminal functionality\"\"\"\n",
    "    network = Network()\n",
    "    node_a = Computer(hostname=\"node_a\", ip_address=\"192.168.0.10\", subnet_mask=\"255.255.255.0\", start_up_duration=0)\n",
    "    node_a.power_on()\n",
    "    node_b = Computer(hostname=\"node_b\", ip_address=\"192.168.0.11\", subnet_mask=\"255.255.255.0\", start_up_duration=0)\n",
    "    node_b.power_on()\n",
    "    network.connect(node_a.network_interface[1], node_b.network_interface[1])\n",
    "    return network"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The terminal can be accessed from a `HostNode` via the `software_manager` as demonstrated below. \n",
    "\n",
    "In the example, we have a basic network consisting of two computers "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "network: Network = basic_network()\n",
    "computer_a: Computer = network.get_node_by_hostname(\"node_a\")\n",
    "terminal_a: Terminal = computer_a.software_manager.software.get(\"Terminal\")\n",
    "computer_b: Computer = network.get_node_by_hostname(\"node_b\")\n",
    "terminal_b: Terminal = computer_b.software_manager.software.get(\"Terminal\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To be able to send commands from `node_a` to `node_b`, you will need to `login` to `node_b` first, using valid user credentials. In the example below, we are logging in to the 'admin' account on `node_b`. \n",
    "If you are not logged in, any commands sent will be rejected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Login to the remote (node_b) from local (node_a)\n",
    "terminal_a.login(username=\"admin\", password=\"Admin123!\", ip_address=computer_b.network_interface[1].ip_address)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can view all remote connections to a terminal through use of the `show()` method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "terminal_b.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Terminal can be used to send requests to install new software. The code block below demonstrates how the Terminal class allows the user of `terminal_a`, on `computer_a`, to send a command to `computer_b` to install the `RansomwareScript` application. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from primaite.simulator.network.protocols.ssh import SSHConnectionMessage, SSHPacket, SSHTransportMessage\n",
    "from primaite.simulator.system.applications.red_applications.ransomware_script import RansomwareScript\n",
    "\n",
    "computer_b.software_manager.show()\n",
    "\n",
    "payload: SSHPacket = SSHPacket(\n",
    "    payload=[\"software_manager\", \"application\", \"install\", \"RansomwareScript\"],\n",
    "    transport_message=SSHTransportMessage.SSH_MSG_SERVICE_REQUEST,\n",
    "    connection_message=SSHConnectionMessage.SSH_MSG_CHANNEL_OPEN,\n",
    "    sender_ip_address=computer_a.network_interface[1].ip_address,\n",
    "    target_ip_address=computer_b.network_interface[1].ip_address,\n",
    ")\n",
    "\n",
    "# Send command to install RansomwareScript\n",
    "terminal_a.send(payload=payload, dest_ip_address=computer_b.network_interface[1].ip_address)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `RansomwareScript` can then be seen in the list of applications on the `node_b Software Manager`.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "computer_b.software_manager.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The below example shows how you can send a command via the terminal to create a folder on the target Node.\n",
    "\n",
    "Here, we send a command to `computer_b` to create a new folder titled \"Downloads\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "computer_b.file_system.show()\n",
    "\n",
    "payload: SSHPacket = SSHPacket(\n",
    "    payload=[\"file_system\", \"create\", \"folder\", \"Downloads\"],\n",
    "    transport_message=SSHTransportMessage.SSH_MSG_SERVICE_REQUEST,\n",
    "    connection_message=SSHConnectionMessage.SSH_MSG_CHANNEL_OPEN,\n",
    "    sender_ip_address=computer_a.network_interface[1].ip_address,\n",
    "    target_ip_address=computer_b.network_interface[1].ip_address,\n",
    ")\n",
    "\n",
    "terminal_a.send(payload=payload, dest_ip_address=computer_b.network_interface[1].ip_address)\n",
    "\n",
    "computer_b.file_system.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The resultant call to `computer_b.file_system.show()` shows that the new folder has been created."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}