PrimAITE/docs/source/simulation_components/system/services/terminal.rst

.. only:: comment

    © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK

.. _Terminal:

Terminal
########

The ``Terminal.py`` class provides a generic terminal simulation, by extending the base Service class within PrimAITE. The aim of this is to act as the primary entrypoint for Nodes within the environment.


Overview
========

The Terminal service uses Secure Socket (SSH) as the communication method between terminals. They operate on port 22, and are part of the services automatically
installed on Nodes when they are instantiated.

Key capabilities
""""""""""""""""

 - Ensures packets are matched to an existing session
 - Simulates common Terminal processes/commands.
 - Leverages the Service base class for install/uninstall, status tracking etc.

Usage
"""""

 - Pre-Installs on any `Node` component (with the exception of `Switches`).
 - Terminal Clients connect, execute commands and disconnect from remote nodes.
 - Ensures that users are logged in to the component before executing any commands.
 - Service runs on SSH port 22 by default.
 - Enables Agents to send commands both remotely and locally.

Implementation
""""""""""""""

 - Manages remote connections in a dictionary by session ID.
 - Processes commands, forwarding to the ``RequestManager`` or ``SessionManager`` where appropriate.
 - Extends Service class.

A detailed guide on the implementation and functionality of the Terminal class can be found in the "Terminal-Processing" jupyter notebook.

Command Format
^^^^^^^^^^^^^^

Terminals implement their commands through leveraging the pre-existing :ref:`request_system`.

Due to this Terminals will only accept commands passed within the ``RequestFormat``.

:py:class:`primaite.game.interface.RequestFormat`

For example, ``terminal`` command actions when used in ``yaml`` format are formatted as follows:

.. code-block:: yaml

    command:
        - "file_system"
        - "create"
        - "file"
        - "downloads"
        - "cat.png"
        - "False

This is then loaded from yaml into a dictionary containing the terminal command:

.. code-block:: python

    {"command":["file_system", "create", "file", "downloads", "cat.png", "False"]}

Which is then passed to the ``Terminals`` Request Manager to be executed.

Game Layer Usage (Agents)
========================

The below code examples demonstrate how to use terminal related actions in yaml files.

yaml
""""

``node-send-local-command``
"""""""""""""""""""""""""""

Agents can execute local commands without needing to perform a separate remote login action (``node-session-remote-login``).

.. code-block:: yaml

    ...
        ...
          action: node-send-local-command
          options:
            node_name: node_a
            username: admin
            password: admin
            command: # Example command - Creates a file called 'cat.png' in the downloads folder.
              - "file_system"
              - "create"
              - "file"
              - "downloads"
              - "cat.png"
              - "False"


``node-session-remote-login``
"""""""""""""""""

Agents are able to use the terminal to login into remote nodes via ``SSH`` which allows for agents to execute commands on remote hosts.

.. code-block:: yaml

    ...
        ...
          action: node-session-remote-login
          options:
            node_name: node_a
            username: admin
            password: admin
            remote_ip: 192.168.0.10 # Example Ip Address. (The remote host's IP that will be used by ssh)


``node-send-remote-command``
""""""""""""""""""""""""""""

After remotely logging into another host, an agent can use the ``node-send-remote-command`` to execute commands across the network remotely.

.. code-block:: yaml

    ...
        ...
          action: node-send-remote-command
          options:
            node_name: node_a
            remote_ip: 192.168.0.10
            command:
              - "file_system"
              - "create"
              - "file"
              - "downloads"
              - "cat.png"
              - "False"



Simulation Layer Usage
======================


The below code examples demonstrate how to create a terminal, a remote terminal, and how to send a basic application install command to a remote node.

Python
""""""

.. code-block:: python

    from ipaddress import IPv4Address

    from primaite.simulator.network.hardware.nodes.host.computer import Computer
    from primaite.simulator.system.services.terminal.terminal import Terminal
    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState

    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")

Creating Remote Terminal Connection
"""""""""""""""""""""""""""""""""""


.. code-block:: python

    from primaite.simulator.system.services.terminal.terminal import Terminal
    from primaite.simulator.network.container import Network
    from primaite.simulator.network.hardware.nodes.host.computer import Computer
    from primaite.simulator.system.services.terminal.terminal import RemoteTerminalConnection


    network = Network()
    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(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])

    terminal_a: Terminal = node_a.software_manager.software.get("terminal")


    term_a_term_b_remote_connection: RemoteTerminalConnection = terminal_a.login(username="admin", password="Admin123!", ip_address="192.168.0.11")



Executing a basic application install command
"""""""""""""""""""""""""""""""""""""""""""""

.. code-block:: python

    from primaite.simulator.system.services.terminal.terminal import Terminal
    from primaite.simulator.network.container import Network
    from primaite.simulator.network.hardware.nodes.host.computer import Computer
    from primaite.simulator.system.services.terminal.terminal import RemoteTerminalConnection
    from primaite.simulator.system.applications.red_applications.ransomware_script import RansomwareScript


    network = Network()
    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(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])

    terminal_a: Terminal = node_a.software_manager.software.get("terminal")


    term_a_term_b_remote_connection: RemoteTerminalConnection = terminal_a.login(username="admin", password="Admin123!", ip_address="192.168.0.11")

    term_a_term_b_remote_connection.execute(["software_manager", "application", "install", "ransomware-script"])



Creating a folder on a remote node
""""""""""""""""""""""""""""""""""

.. code-block:: python

    from primaite.simulator.system.services.terminal.terminal import Terminal
    from primaite.simulator.network.container import Network
    from primaite.simulator.network.hardware.nodes.host.computer import Computer
    from primaite.simulator.system.services.terminal.terminal import RemoteTerminalConnection
    from primaite.simulator.system.applications.red_applications.ransomware_script import RansomwareScript


    network = Network()
    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(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])

    terminal_a: Terminal = node_a.software_manager.software.get("terminal")


    term_a_term_b_remote_connection: RemoteTerminalConnection = terminal_a.login(username="admin", password="Admin123!", ip_address="192.168.0.11")

    term_a_term_b_remote_connection.execute(["file_system", "create", "folder", "downloads"])


Disconnect from Remote Node
"""""""""""""""""""""""""""

.. code-block:: python

    from primaite.simulator.system.services.terminal.terminal import Terminal
    from primaite.simulator.network.container import Network
    from primaite.simulator.network.hardware.nodes.host.computer import Computer
    from primaite.simulator.system.services.terminal.terminal import RemoteTerminalConnection
    from primaite.simulator.system.applications.red_applications.ransomware_script import RansomwareScript


    network = Network()
    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(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])

    terminal_a: Terminal = node_a.software_manager.software.get("terminal")


    term_a_term_b_remote_connection: RemoteTerminalConnection = terminal_a.login(username="admin", password="Admin123!", ip_address="192.168.0.11")

    term_a_term_b_remote_connection.disconnect()


``Common Attributes``
^^^^^^^^^^^^^^^^^^^^^

See :ref:`Common Configuration`