412 lines
22 KiB
ReStructuredText
412 lines
22 KiB
ReStructuredText
.. only:: comment
|
|
|
|
© Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
|
|
|
|
.. _migration_guide:
|
|
|
|
|
|
PrimAITE 4.0.0 YAML Configuration Migration Guide
|
|
*************************************************
|
|
|
|
Users upgrading from previous PrimAITE versions will be required to update their pre-existing YAML configs.
|
|
|
|
This migration guide details how to update any 3.0.0 yaml configs section by section to match the new 4.0.0 schema.
|
|
|
|
Any users accustomed to PrimAITE 2.0.0 are encouraged to make a fresh start to fully adapt to the changes since 2.0.0 release.
|
|
|
|
``io_settings``
|
|
===============
|
|
|
|
No major schema alterations are required for ``io_settings``.
|
|
|
|
However, a few more options have been introduced:
|
|
|
|
.. code-block:: yaml
|
|
|
|
io_settings:
|
|
save_agent_actions: false
|
|
save_step_metadata: false
|
|
save_pcap_logs: false
|
|
save_sys_logs: false
|
|
save_agent_logs: false
|
|
write_sys_log_to_terminal: false
|
|
sys_log_level: WARNING
|
|
agent_log_level: INFO
|
|
|
|
More information can be found in the detailed in the configuration page: :ref:`io_settings`.
|
|
|
|
``game``
|
|
========
|
|
|
|
No reformatting required for ``game`` section.
|
|
|
|
If users have installed plugins that introduce new ports or protocols then the game can be configured with use them.
|
|
|
|
This can be done by adding to the ``ports`` and ``protocols`` list as shown in the yaml snippet below:
|
|
|
|
.. code-block:: yaml
|
|
|
|
game:
|
|
max_episode_length: 128
|
|
ports:
|
|
- HTTP
|
|
- POSTGRES_SERVER
|
|
- <EXAMPLE_PLUGIN_PORT>
|
|
protocols:
|
|
- ICMP
|
|
- TCP
|
|
- UDP
|
|
- <EXAMPLE_PLUGIN_PROTOCOL>
|
|
thresholds:
|
|
nmne:
|
|
high: 10
|
|
medium: 5
|
|
low: 0
|
|
|
|
|
|
``agents``
|
|
==========
|
|
|
|
PrimAITE 4.0.0 changes action parameters to use meaningful names instead of indexes.
|
|
|
|
To match the new schema, agent configs written for PrimAITE 3.X should make the following changes:
|
|
|
|
``action_space``
|
|
----------------
|
|
|
|
- remove the ``options``, and ``action_list`` sections.
|
|
- update the ``action_map`` to use the new naming schema for actions, they use kebab case instead of camel case. A conversion table is provided below.
|
|
- update the ``action_map`` to follow the new parameter schemas. ID-based parameters were replaced with name-based parameters. Use your old config's ``action_space.options`` field to find the appropriate mapping for action parameters in your particular scenario.
|
|
- ``node_id`` is now ``node_name``
|
|
- ``application_id`` is now ``application_name``
|
|
- ``service_id`` is now ``service_name``
|
|
- ``folder_id`` is now ``folder_name``
|
|
- ``nic_id`` is now ``nic_num`` (and is now 1-indexed instead of 0-indexed for consistency with the simulation)
|
|
- ``port_id`` is now ``port_num`` (and is now 1-indexed instead of 0-indexed for consistency with the simulation)
|
|
- ``source_ip_id`` is now ``src_ip``
|
|
- ``source_wildcard_id`` is now ``src_wildcard``
|
|
- ``source_port_id`` is now ``src_port``
|
|
- ``dest_port_id`` is now ``dst_port``
|
|
- ``dest_wildcard_id`` is now ``dst_wildcard``
|
|
- ``dest_port_id`` is now ``dst_port``
|
|
- ``protocol_id`` is now ``protocol``
|
|
|
|
**Example on how to map old paramater IDs to new paramter names**
|
|
|
|
.. code-block:: yaml
|
|
|
|
game:
|
|
max_episode_length: 128
|
|
ports:
|
|
- FTP
|
|
- HTTP
|
|
protocols:
|
|
- TCP
|
|
- UDP
|
|
|
|
# ...
|
|
|
|
options:
|
|
nodes:
|
|
- node_name: PC-1
|
|
applications:
|
|
- application_name: DatabaseClient
|
|
folders:
|
|
- folder_name: downloads
|
|
files:
|
|
- file_name: chrome.exe
|
|
- folder_name: other_folder
|
|
files:
|
|
- file_name: firefox.exe
|
|
- node_name: PC-2
|
|
applications:
|
|
- application_name: WebBrowser
|
|
folders:
|
|
- folder_name: folder_1
|
|
files:
|
|
- file_name: file2.jpg
|
|
- folder_name: folder_2
|
|
files:
|
|
- file_name: file3.jpg
|
|
- node_name: PC-3
|
|
services:
|
|
- service_name: FTPClient
|
|
- node_name: PC-4
|
|
- node_name: PC-5
|
|
|
|
max_folders_per_node: 1
|
|
max_files_per_folder: 1
|
|
max_services_per_node: 2
|
|
max_nics_per_node: 8
|
|
max_acl_rules: 10
|
|
ip_list:
|
|
# 0 reserved for padding to align with observations
|
|
# 1 reserved for ALL ips
|
|
- 192.168.1.11 # 2
|
|
- 200.10.1.10 # 3
|
|
|
|
|
|
wildcard_list:
|
|
- 0.0.0.1 # 0
|
|
- 0.0.0.255 # 1
|
|
- 0.0.255.255 # 2
|
|
|
|
From the above old-style YAML ``action_space.options`` example, the following changes should be made to action map:
|
|
|
|
- Actions with ``node_id: 0`` should use ``node_name: PC-1``
|
|
- Actions with ``node_id: 1`` should use ``node_name: PC-2``
|
|
- Actions with ``node_id: 2`` should use ``node_name: PC-3``
|
|
- Actions with ``node_id: 3`` should use ``node_name: PC-4``
|
|
- Actions with ``node_id: 4`` should use ``node_name: PC-5``
|
|
- Actions with ``node_id: 0`` and ``application_id: 0`` should use ``application_name: DatabaseClient`` (The application list is specific to each node)
|
|
- Actions with ``node_id: 1`` and ``application_id: 0`` should use ``application_name: WebBrowser`` (The application list is specific to each node)
|
|
- Actions with ``node_id: 0`` and ``folder_id: 0`` should use ``folder_name: downloads`` (The folder list is specific to each node)
|
|
- Actions with ``node_id: 0`` and ``folder_id: 1`` should use ``folder_name: other_folder`` (The folder list is specific to each node)
|
|
- Actions with ``node_id: 1`` and ``folder_id: 0`` should use ``folder_name: folder_1`` (The folder list is specific to each node)
|
|
- Actions with ``node_id: 1`` and ``folder_id: 1`` should use ``folder_name: folder_2`` (The folder list is specific to each node)
|
|
- Actions with ``node_id: 0`` and ``folder_id: 0`` and ``file_id: 0`` should use ``file_name: chrome.exe`` (The file list is specific to each node and folder)
|
|
- Actions with ``node_id: 0`` and ``folder_id: 1`` and ``file_id: 0`` should use ``file_name: firefox.exe`` (The file list is specific to each node and folder)
|
|
- Actions with ``node_id: 1`` and ``folder_id: 0`` and ``file_id: 0`` should use ``file_name: file2.jpg`` (The file list is specific to each node and folder)
|
|
- Actions with ``node_id: 1`` and ``folder_id: 1`` and ``file_id: 0`` should use ``file_name: file3.jpg`` (The file list is specific to each node and folder)
|
|
- Actions with ``nic_id: <N>`` should use ``nic_num: <N+1>``
|
|
- Actions with ``port_id: <N>`` should use ``port_num: <N+1>``
|
|
- Actions with ``source_ip_id: 0`` should not be present in your original config as this has no effect
|
|
- Actions with ``source_ip_id: 1`` should use ``src_ip: ALL``
|
|
- Actions with ``source_ip_id: 2`` should use ``src_ip: 192.168.1.11``
|
|
- Actions with ``source_ip_id: 3`` should use ``src_ip: 200.10.1.10``
|
|
- Actions with ``dest_ip_id: 0`` should not be present in your original config as this has no effect
|
|
- Actions with ``dest_ip_id: 1`` should use ``dst_ip: ALL``
|
|
- Actions with ``dest_ip_id: 2`` should use ``dst_ip: 192.168.1.11``
|
|
- Actions with ``dest_ip_id: 3`` should use ``dst_ip: 200.10.1.10``
|
|
- Actions with ``source_wildcard_id: 0`` should use ``src_wildcard: 0.0.0.1``
|
|
- Actions with ``source_wildcard_id: 0`` should use ``src_wildcard: 0.0.0.255``
|
|
- Actions with ``source_wildcard_id: 0`` should use ``src_wildcard: 0.0.255.255``
|
|
- Actions with ``dest_wildcard_id: 0`` should use ``dst_wildcard: 0.0.0.1``
|
|
- Actions with ``dest_wildcard_id: 0`` should use ``dst_wildcard: 0.0.0.255``
|
|
- Actions with ``dest_wildcard_id: 0`` should use ``dst_wildcard: 0.0.255.255``
|
|
- Actions with ``source_port_id: 0`` should not be present in your original config as this has no effect
|
|
- Actions with ``source_port_id: 1`` should use ``src_port: ALL``
|
|
- Actions with ``source_port_id: 2`` should use ``src_port: FTP``
|
|
- Actions with ``source_port_id: 3`` should use ``src_port: HTTP``
|
|
- Actions with ``dest_port_id: 0`` should not be present in your original config as this has no effect
|
|
- Actions with ``dest_port_id: 1`` should use ``dst_port: ALL``
|
|
- Actions with ``dest_port_id: 2`` should use ``dst_port: FTP``
|
|
- Actions with ``dest_port_id: 3`` should use ``dst_port: HTTP``
|
|
- Actions with ``protocol_id: 0`` should not be present in your original config as this has no effect
|
|
- Actions with ``protocol_id: 1`` should use ``protocol: ALL``
|
|
- Actions with ``protocol_id: 2`` should use ``protocol: TCP``
|
|
- Actions with ``protocol_id: 3`` should use ``protocol: UDP``
|
|
|
|
``observation_space``
|
|
---------------------
|
|
|
|
- the ``type`` parameter values now use lower kebab case. A conversion table is provided below.
|
|
|
|
``reward_function``
|
|
-------------------
|
|
- the ``type`` parameter values now use lower kebab case. A conversion table is provided below.
|
|
|
|
|
|
+-------------------------------------+-------------------------------------+
|
|
| *3.0.0 action name* | *4.0.0 action name* |
|
|
+=====================================+=====================================+
|
|
| ``DONOTHING`` | ``do-nothing`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_SCAN`` | ``node-service-scan`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_STOP`` | ``node-service-stop`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_START`` | ``node-service-start`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_PAUSE`` | ``node-service-pause`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_RESUME`` | ``node-service-resume`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_RESTART`` | ``node-service-restart`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_DISABLE`` | ``node-service-disable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_ENABLE`` | ``node-service-enable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SERVICE_FIX`` | ``node-service-fix`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_APPLICATION_REMOVE`` | ``node-application-remove`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_APPLICATION_CLOSE`` | ``node-application-close`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_APPLICATION_SCAN`` | ``node-application-scan`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_APPLICATION_FIX`` | ``node-application-fix`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_SCAN`` | ``node-file-scan`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_CHECKHASH`` | ``node-file-checkhash`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_DELETE`` | ``node-file-delete`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_REPAIR`` | ``node-file-repair`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_RESTORE`` | ``node-file-restore`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FOLDER_SCAN`` | ``node-folder-scan`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FOLDER_CHECKHASH`` | ``node-folder-checkhash`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FOLDER_REPAIR`` | ``node-folder-repair`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FOLDER_RESTORE`` | ``node-folder-restore`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_OS_SCAN`` | ``node-os-scan`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SHUTDOWN`` | ``node-shutdown`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_STARTUP`` | ``node-startup`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_RESET`` | ``node-reset`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``HOST_NIC_ENABLE`` | ``host-nic-enable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``HOST_NIC_DISABLE`` | ``host-nic-disable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NETWORK_PORT_ENABLE`` | ``network-port-enable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NETWORK_PORT_DISABLE`` | ``network-port-disable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``ROUTER_ACL_ADDRULE`` | ``router-acl-addrule`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``ROUTER_ACL_REMOVERULE`` | ``router-acl-removerule`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``FIREWALL_ACL_ADDRULE`` | ``firewall-acl-addrule`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``FIREWALL_ACL_REMOVERULE`` | ``firewall-acl-removerule`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_APPLICATION_EXECUTE`` | ``node-application-execute`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_APPLICATION_INSTALL`` | ``node-application-install`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FOLDER_CREATE`` | ``node-folder-create`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_CREATE`` | ``node-file-create`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_ACCESS`` | ``node-file-access`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_NMAP_PING_SCAN`` | ``node-nmap-ping-scan`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_NMAP_PORT_SCAN`` | ``node-nmap-port-scan`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_NMAP_NETWORK_SERVICE_RECON`` | ``node-nmap-network-service-recon`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``CONFIGURE_RANSOMWARE_SCRIPT`` | ``configure-ransomware-script`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``CONFIGURE_C2_BEACON`` | ``configure-c2-beacon`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``CONFIGURE_DATABASE_CLIENT`` | ``configure-database-client`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``CONFIGURE_DOS_BOT`` | ``configure-dos-bot`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``C2_SERVER_RANSOMWARE_LAUNCH`` | ``c2-server-ransomware-launch`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``C2_SERVER_RANSOMWARE_CONFIGURE`` | ``c2-server-ransomware-configure`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``C2_SERVER_TERMINAL_COMMAND`` | ``c2-server-terminal-command`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``C2_SERVER_DATA_EXFILTRATE`` | ``c2-server-data-exfiltrate`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``HOST_NIC_ENABLE`` | ``host-nic-enable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``HOST_NIC_DISABLE`` | ``host-nic-disable`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_FILE_CORRUPT`` | ``node-file-corrupt`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SESSION_REMOTE_LOGIN`` | ``node-session-remote-login`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SESSION_REMOTE_LOGOFF`` | ``node-session-remote-logoff`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_ACCOUNT_CHANGE_PASSWORD`` | ``node-account-change-password`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
| ``NODE_SEND_REMOTE_COMMAND`` | ``node-send-remote-command`` |
|
|
+-------------------------------------+-------------------------------------+
|
|
|
|
|
|
- All reward component types must be converted to kebab-case. (``SHARED_REWARD`` - ``shared-reward``)
|
|
|
|
+----------------------------------------------+----------------------------------------------+
|
|
| *3.0.0 reward type* | *4.0.0 reward name* |
|
|
+==============================================+==============================================+
|
|
| ``SHARED_REWARD`` | ``shared-reward`` |
|
|
+----------------------------------------------+----------------------------------------------+
|
|
| ``WEB_SERVER_404_PENALTY`` | ``web-server-404-penalty`` |
|
|
+----------------------------------------------+----------------------------------------------+
|
|
| ``WEBPAGE_UNAVAILABLE_PENALTY`` | ``webpage-unavailable-penalty`` |
|
|
+----------------------------------------------+----------------------------------------------+
|
|
| ``GREEN_ADMIN_DATABASE_UNREACHABLE_PENALTY`` | ``green-admin-database-unreachable-penalty`` |
|
|
+----------------------------------------------+----------------------------------------------+
|
|
| ``ACTION_PENALTY | ``action-penalty`` |
|
|
+----------------------------------------------+----------------------------------------------+
|
|
| ``DATABASE_FILE_INTEGRITY`` | ``database-file-integrity`` |
|
|
+----------------------------------------------+----------------------------------------------+
|
|
|
|
|
|
- All agent types must be converted to kebab-case. (``ProxyAgent`` - ``proxy-agent``)
|
|
|
|
+--------------------------------+-----------------------------------+
|
|
| *3.0.0 action type* | *4.0.0 agent type* |
|
|
+================================+===================================+
|
|
| ``ProxyAgent`` | ``proxy-agent`` |
|
|
+--------------------------------+-----------------------------------+
|
|
| ``RedDatabaseCorruptingAgent`` | ``red-database-corrupting-agent`` |
|
|
+--------------------------------+-----------------------------------+
|
|
| ``ProbabilisticAgent`` | ``probabilistic-agent`` |
|
|
+--------------------------------+-----------------------------------+
|
|
| ``RandomAgent`` | ``random-agent`` |
|
|
+--------------------------------+-----------------------------------+
|
|
| ``PeriodicAgent`` | ``periodic-agent`` |
|
|
+--------------------------------+-----------------------------------+
|
|
|
|
|
|
``simulation``
|
|
==============
|
|
|
|
The only simulation yaml changes are that all software has been renamed to use kebab-case:
|
|
|
|
+-----------------------+------------------------+
|
|
|*3.0.0 software name* |*4.0.0 software name* |
|
|
+=======================+========================+
|
|
| ``WebBrowser`` | ``web-browser`` |
|
|
+-----------------------+------------------------+
|
|
| ``DatabaseClient`` | ``database-client`` |
|
|
+-----------------------+------------------------+
|
|
| ``DNSClient`` | ``dns-client`` |
|
|
+-----------------------+------------------------+
|
|
| ``FTPServer`` | ``ftp-server`` |
|
|
+-----------------------+------------------------+
|
|
| ``C2Beacon`` | ``c2-beacon`` |
|
|
+-----------------------+------------------------+
|
|
| ``C2Server`` | ``c2-server`` |
|
|
+-----------------------+------------------------+
|
|
| ``RansomwareScript`` | ``ransomware-script`` |
|
|
+-----------------------+------------------------+
|
|
| ``WebServer`` | ``web-server`` |
|
|
+-----------------------+------------------------+
|
|
| ``DOSBot`` | ``dos-bot`` |
|
|
+-----------------------+------------------------+
|
|
| ``FTPClient`` | ``ftp-client`` |
|
|
+-----------------------+------------------------+
|
|
| ``DNSServer`` | ``dns-server`` |
|
|
+-----------------------+------------------------+
|
|
| ``Terminal`` | ``terminal`` |
|
|
+-----------------------+------------------------+
|
|
| ``NTPClient`` | ``ntp-client`` |
|
|
+-----------------------+------------------------+
|
|
| ``NTPServer`` | ``ntp-server`` |
|
|
+-----------------------+------------------------+
|
|
| ``NMAP`` | ``nmap`` |
|
|
+-----------------------+------------------------+
|
|
| ``HostARP`` | ``host-arp`` |
|
|
+-----------------------+------------------------+
|
|
| ``ICMP`` | ``icmp`` |
|
|
+-----------------------+------------------------+
|
|
|
|
|
|
A simple search and replace can be used with the lists above to update any configs.
|