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-11 16:42:46 +00:00
parent d2b5097dce 678a500c5e
commit 99d4e228c9
1 changed files with 163 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
docs/source/how_to_guides/primaite_yaml_migration_guide.rst
View File

@@ -40,7 +40,9 @@ More information can be found in the detailed in the configuration page: :ref:`i
No reformatting required for ``game`` section.
However, any installed plugins that introduce new ports or protocols are required to be set within this config as with any other base options:
If users have installed plugins that introduce new ports or protocols then the game must 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
@@ -49,12 +51,12 @@ However, any installed plugins that introduce new ports or protocols are requir
ports:
- HTTP
- POSTGRES_SERVER
- EXAMPLE_PLUGIN_PORT
- <EXAMPLE_PLUGIN_PORT>
protocols:
- ICMP
- TCP
- UDP
- EXAMPLE_PLUGIN_PROTOCOL
- <EXAMPLE_PLUGIN_PROTOCOL>
thresholds:
nmne:
high: 10
@@ -72,16 +74,16 @@ To match the new schema, 3.0.0 agent's must adhere to the following:
- The ``action_list`` sub-section within the ``action_space`` is no longer required and can be removed.
- The ``options`` sub-section can also be removed. (Note that you do not accidentally remove ``options`` sub-section within the ``observation_space``)
- The agent that require an ``action_map`` sub-section require the following alterations:
- Action's must now be converted to camel-case:
- Action's must now be converted to kebab-case:
- Action ``options`` that previously required identifiers now instead require names.
.. code-block:: yaml
# scan webapp service (4.0.0)
1:
action: node-service-scan # camel-case
action: node-service-scan # kebab-case
options:
node_name: web_server # id's are no longer used - reference the name directly.
node_name: web_server # IDs are no longer used - reference the name directly.
service_name: web-server
# scan webapp service (3.0.0)
@@ -91,44 +93,167 @@ To match the new schema, 3.0.0 agent's must adhere to the following:
node_id: 1
service_id: 0
- All reward component types must be converted to camel-case. (``SHARED_REWARD`` - ``shared-reward``)
- All agent types must be converted to camel-case. (``ProxyAgent`` - ``proxy-agent``)
- TAP agent settings are no longer set within ``tap_settings`` and settings be need a single tab dedent.
- TAP003 no longer accepts ``default_target_node`` & ``target_nodes`` as valid config options (These configuration were vestigial and ignored by TAP003).
- TAP003's ACL configuration options have been slightly altered as shown in the comments 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`` |
+-------------------------------------+-------------------------------------+
.. code-block:: yaml
# TAP003 Configuration yaml (4.0.0)
agent_settings: # ``tap_settings`` no longer required
start_step: 1
frequency: 3
variance: 0
repeat_kill_chain: false
repeat_kill_chain_stages: true
default_starting_node: "example_host"
starting_nodes:
kill_chain:
EXPLOIT:
probability: 1
malicious_acls:
- target_router: example_target_router
ip_address: 192.168.1.10
position: 1
permission: DENY
src_ip: ALL # source_ip_address
src_wildcard: 0.0.255.255 # source_wildcard_mask
dst_ip: ALL # dest_ip_address
dest_wildcard: 0.0.255.255 # dest_wildcard_mask
src_port: ALL # source_port
dst_port: ALL # dest_port
protocol_name: ALL # protocol
- 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 camel-case:
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* |
@@ -169,4 +294,4 @@ The only simulation yaml changes are that all software has been renamed to use c
+-----------------------+------------------------+
A simple search and replace can be used with the list above to update any configs.
A simple search and replace can be used with the lists above to update any configs.