v3.3.0

PrimAITE 3.3.0 Release Note

📰 Headlines 📰

• Terminal software - A new service which allows the execution of arbitrary commands on nodes by leveraging the existing request system. Terminals on different nodes communicate via the SSH protocol allowing remote command execution.
• Local accounts - Nodes now support local user accounts with regular or elevated privileges. This integrates with the terminal to simulate scenarios involving stolen credentials.
• Command and control - A set of malicious services which can infect computers and execute remotely, including sending SSH traffic masked as other protocols.

✨ What else is New ✨

• Determinism - PrimAITE now supports setting a random seed which ensures reproducible behaviour. This has been tested with seeded stable-baselines3 and Ray RLLib agents which produces identical training runs.
• Login and logout actions - New agent actions were added to allow agents to log in and out of nodes.
• User account observations - Agents can now observe how many users are logged in to each node.
• Terminal actions - Agents can send terminal commands as actions.
• Reward component stickiness - Green and Blue agents can optionally return reward data per timestep regardless of whether the corresponding agent executed an action.

🚀 Improvements 🚀

• Multi-port listening - Software can now listen on multiple network ports.
• Enhanced agent history - Agent history includes more information about how the reward was calculated.
• Richer response data - Response data was added to some request types which previously didn't return additional success data.

🐛 Bug Fixes 🐛

• Folder observations - no longer necessary to scan to get true health state.
• SoftwareManager update
  • install and uninstall methods replace functionality previous handled by equivalent methods in Node class.
  • receive_payload_from_session_manager sends copy of data to any software listening on the destination port of the Frame.

🚦 Tests

• Tested against the a beta release checklist to ensure the software does not crash and produces expected results.

⌛ Deprecated ⌛

No features were deprecated in this update.

🔍 Known Issues 🔍

• Agent actions - Agents action spaces must use the gymnasium.spaces.Discrete shape, and a list of actions must be provided using the action_map config option for each agent. Other action spaces and more flexible action space definition will be part of a future release.
• Ray incompatibility with Python 3.8 - Recent versions of Ray fail to install on Python 3.8. Users who are using Python 3.8 cannot use the [rl] optional dependency flag when installing PrimAITE; they must manually install their desired version of Ray.
  i.e. Instead of running pip install path/to/primaite/wheel.whl[rl], users should run pip install path/to/primaite/wheel.rl and then pip install ray[rllib]
  This issue is not present when installing PrimAITE on Python 3.9 and later.
• Determinism - RayMultiAgent RL appears to be immune to random number generator seed setting as it's currently implemented and will continue to generate non-determinsistic output even if a seed is set.
  When using StableBaselines 3, different results will be generated for the same seed if trained on a CPU vs a GPU. For example: WSL will perform training on the CPU but Windows will attempt to train on a graphics card if possible. In the notebook Training-an-SB3-Agent add the following argument to the PPO command (cells 6 and 9): device=cpu, to force training on the CPU rather than GPU. NB: This can impact training times.
  This issue has not been observed with Single Agent Ray RLLib notebooks.
• NMNE - when using NMNE both config parameters include_nmne and capture_nmne must be set to the same Boolean value.

⬆️ Upgrade Instructions ⬆️

From wheel

pip install path/to/primaite-3.3.0-wheel.whl[rl] --upgrade

As a repo

git fetch
git checkout tags/v3.3.0
pip install -e .[rl] --upgrade

👥 Contributors 👥

@pufferfish-seaweed
@CharlieC-QQ
@czar-ec-envitia
@ChrisMcCarthyDev
@MethodsGRS
@jamesshort1
@njtodd
@marek-methods

📚 References 📚

PrimAITE 3.3.0 supports CAOS 0.10 but the new CAOS features are optional so it is still possible to use configs designed around CAOS 0.9