oxbrbtx/PrimAITE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3aec6e5a96235c975fa36f792c9f77aced3adac3
PrimAITE/PRIMAITE/docs/source/config.rst

397 lines
16 KiB
ReStructuredText
Raw Normal View History

Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
.. _config:
The Config Files Explained
==========================
PrimAITE uses two configuration files for its operation:
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* config_main.yaml - used to define the top-level settings of the PrimAITE environment, and the session that is to be run.
* config_[name].yaml - used to define the low-level settings of a session, including the network laydown, green / red agent information exchange requirements (IERSs), Access Control Rules, Action Space type, and the number of steps in each episode.
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
config_main.yaml:
*****************
The config_main.yaml file consists of the following attributes:
**Generic Config Values**
* **agentIdentifier** [enum]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
This identifies the agent to use for the session. Select from one of the following:
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* GENERIC - Where a user developed agent is to be used
* STABLE_BASELINES3_PPO - Use a SB3 PPO agent
* STABLE_BASELINES3_A2C - use a SB3 A2C agent
* **numEpisodes** [int]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
This defines the number of episodes that the agent will train or be evaluated over. Each episode consists of a number of steps (with step number defined in the config_[name].yaml file)
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **timeDelay** [int]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
The time delay (in milliseconds) to take between each step when running a GENERIC agent session
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **configFilename** [filename]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
The name of the config_[name].yaml file to use for this session
* **sessionType** [text]
Type of session to be run (TRAINING or EVALUATION)
* **loadAgent** [bool]
Determine whether to load an agent from file
* **agentLoadFile** [text]
File path and file name of agent if you're loading one in
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **observationSpaceHighValue** [int]
The high value to use for values in the observation space. This is set to 1000000000 by default, and should not need changing in most cases
**Reward-Based Config Values**
* **Generic [allOk]** [int]
The score to give when the current situation (for a given component) is no different from that expected in the baseline (i.e. as though no blue or red agent actions had been undertaken)
* **Node Operating State [offShouldBeOn]** [int]
The score to give when the node should be on, but is off
* **Node Operating State [offShouldBeResetting]** [int]
The score to give when the node should be resetting, but is off
* **Node Operating State [onShouldBeOff]** [int]
The score to give when the node should be off, but is on
* **Node Operating State [onShouldBeResetting]** [int]
The score to give when the node should be resetting, but is on
* **Node Operating State [resettingShouldBeOn]** [int]
The score to give when the node should be on, but is resetting
* **Node Operating State [resettingShouldBeOff]** [int]
The score to give when the node should be off, but is resetting
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **Node Operating State [resetting]** [int]
The score to give when the node is resetting
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **Node Operating System or Service State [goodShouldBePatching]** [int]
The score to give when the state should be patching, but is good
* **Node Operating System or Service State [goodShouldBeCompromised]** [int]
The score to give when the state should be compromised, but is good
* **Node Operating System or Service State [goodShouldBeOverwhelmed]** [int]
The score to give when the state should be overwhelmed, but is good
* **Node Operating System or Service State [patchingShouldBeGood]** [int]
The score to give when the state should be good, but is patching
* **Node Operating System or Service State [patchingShouldBeCompromised]** [int]
The score to give when the state should be compromised, but is patching
* **Node Operating System or Service State [patchingShouldBeOverwhelmed]** [int]
The score to give when the state should be overwhelmed, but is patching
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **Node Operating System or Service State [patching]** [int]
The score to give when the state is patching
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **Node Operating System or Service State [compromisedShouldBeGood]** [int]
The score to give when the state should be good, but is compromised
* **Node Operating System or Service State [compromisedShouldBePatching]** [int]
The score to give when the state should be patching, but is compromised
* **Node Operating System or Service State [compromisedShouldBeOverwhelmed]** [int]
The score to give when the state should be overwhelmed, but is compromised
* **Node Operating System or Service State [compromised]** [int]
The score to give when the state is compromised
* **Node Operating System or Service State [overwhelmedShouldBeGood]** [int]
The score to give when the state should be good, but is overwhelmed
* **Node Operating System or Service State [overwhelmedShouldBePatching]** [int]
The score to give when the state should be patching, but is overwhelmed
* **Node Operating System or Service State [overwhelmedShouldBeCompromised]** [int]
The score to give when the state should be compromised, but is overwhelmed
* **Node Operating System or Service State [overwhelmed]** [int]
The score to give when the state is overwhelmed
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **Node File System State [goodShouldBeRepairing]** [int]
The score to give when the state should be repairing, but is good
* **Node File System State [goodShouldBeRestoring]** [int]
The score to give when the state should be restoring, but is good
* **Node File System State [goodShouldBeCorrupt]** [int]
The score to give when the state should be corrupt, but is good
* **Node File System State [goodShouldBeDestroyed]** [int]
The score to give when the state should be destroyed, but is good
* **Node File System State [repairingShouldBeGood]** [int]
The score to give when the state should be good, but is repairing
* **Node File System State [repairingShouldBeRestoring]** [int]
The score to give when the state should be restoring, but is repairing
* **Node File System State [repairingShouldBeCorrupt]** [int]
The score to give when the state should be corrupt, but is repairing
* **Node File System State [repairingShouldBeDestroyed]** [int]
The score to give when the state should be destroyed, but is repairing
* **Node File System State [repairing]** [int]
The score to give when the state is repairing
* **Node File System State [restoringShouldBeGood]** [int]
The score to give when the state should be good, but is restoring
* **Node File System State [restoringShouldBeRepairing]** [int]
The score to give when the state should be repairing, but is restoring
* **Node File System State [restoringShouldBeCorrupt]** [int]
The score to give when the state should be corrupt, but is restoring
* **Node File System State [restoringShouldBeDestroyed]** [int]
The score to give when the state should be destroyed, but is restoring
* **Node File System State [restoring]** [int]
The score to give when the state is restoring
* **Node File System State [corruptShouldBeGood]** [int]
The score to give when the state should be good, but is corrupt
* **Node File System State [corruptShouldBeRepairing]** [int]
The score to give when the state should be repairing, but is corrupt
* **Node File System State [corruptShouldBeRestoring]** [int]
The score to give when the state should be restoring, but is corrupt
* **Node File System State [corruptShouldBeDestroyed]** [int]
The score to give when the state should be destroyed, but is corrupt
* **Node File System State [corrupt]** [int]
The score to give when the state is corrupt
* **Node File System State [destroyedShouldBeGood]** [int]
The score to give when the state should be good, but is destroyed
* **Node File System State [destroyedShouldBeRepairing]** [int]
The score to give when the state should be repairing, but is destroyed
* **Node File System State [destroyedShouldBeRestoring]** [int]
The score to give when the state should be restoring, but is destroyed
* **Node File System State [destroyedShouldBeCorrupt]** [int]
The score to give when the state should be corrupt, but is destroyed
* **Node File System State [destroyed]** [int]
The score to give when the state is destroyed
* **Node File System State [scanning]** [int]
The score to give when the state is scanning
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **IER Status [redIerRunning]** [int]
The score to give when a red agent IER is permitted to run
* **IER Status [greenIerBlocked]** [int]
The score to give when a green agent IER is prevented from running
**Patching / Reset Durations**
* **osPatchingDuration** [int]
The number of steps to take when patching an Operating System
* **nodeResetDuration** [int]
The number of steps to take when resetting a node's operating state
* **servicePatchingDuration** [int]
The number of steps to take when patching a service
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **fileSystemRepairingLimit** [int]:
The number of steps to take when repairing the file system
* **fileSystemRestoringLimit** [int]
The number of steps to take when restoring the file system
* **fileSystemScanningLimit** [int]
The number of steps to take when scanning the file system
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
config_[name].yaml:
*******************
The config_[name].yaml file consists of the following attributes:
* **itemType: ACTIONS** [enum]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
Determines whether a NODE or ACL action space format is adopted for the session
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **itemType: STEPS** [int]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
Determines the number of steps to run in each episode of the session
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **itemType: PORTS** [int]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
Provides a list of ports modelled in this session
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **itemType: SERVICES** [freetext]
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
Provides a list of services modelled in this session
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **itemType: NODE**
Defines a node included in the system laydown being simulated. It should consist of the following attributes:
* **id** [int]: Unique ID for this YAML item
* **name** [freetext]: Human-readable name of the component
* **baseType** [enum]: Relates to the base type of the node. Can be SERVICE, ACTIVE or PASSIVE. PASSIVE nodes do not have an operating system or services. ACTIVE nodes have an operating system, but no services. SERVICE nodes have both an operating system and one or more services
* **nodeType** [enum]: Relates to the component type. Can be one of CCTV, SWITCH, COMPUTER, LINK, MONITOR, PRINTER, LOP, RTU, ACTUATOR or SERVER
* **priority** [enum]: Provides a priority for each node. Can be one of P1, P2, P3, P4 or P5 (which P1 being the highest)
* **hardwareState** [enum]: The initial hardware state of the node. Can be one of ON, OFF or RESETTING
* **ipAddress** [IP address]: The IP address of the component in format xxx.xxx.xxx.xxx
* **softwareState** [enum]: The intial state of the node operating system. Can be GOOD, PATCHING or COMPROMISED
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **fileSystemState** [enum]: The initial state of the node file system. Can be GOOD, CORRUPT, DESTROYED, REPAIRING or RESTORING
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **services**: For each service associated with the node:
* **name** [freetext]: Free-text name of the service, but must match one of the services defined for the system in the services list
* **port** [int]: Integer value of the port related to this service, but must match one of the ports defined for the system in the ports list
* **state** [enum]: The initial state of the service. Can be one of GOOD, PATCHING, COMPROMISED or OVERWHELMED
* **itemType: LINK**
Defines a link included in the system laydown being simulated. It should consist of the following attributes:
* **id** [int]: Unique ID for this YAML item
* **name** [freetext]: Human-readable name of the component
* **bandwidth** [int]: The bandwidth (in bits/s) of the link
* **source** [int]: The ID of the source node
* **destination** [int]: The ID of the destination node
* **itemType: GREEN_IER**
Defines a green agent Information Exchange Requirement (IER). It should consist of:
* **id** [int]: Unique ID for this YAML item
* **startStep** [int]: The start step (in the episode) for this IER to begin
* **endStep** [int]: The end step (in the episode) for this IER to finish
* **load** [int]: The load (in bits/s) for this IER to apply to links
* **protocol** [freetext]: The protocol to apply to the links. This must match a value in the services list
* **port** [int]: The port that the protocol is running on. This must match a value in the ports list
* **source** [int]: The ID of the source node
* **destination** [int]: The ID of the destination node
* **missionCriticality** [enum]: The mission criticality of this IER (with 5 being highest, 1 lowest)
* **itemType: RED_IER**
Defines a red agent Information Exchange Requirement (IER). It should consist of:
* **id** [int]: Unique ID for this YAML item
* **startStep** [int]: The start step (in the episode) for this IER to begin
* **endStep** [int]: The end step (in the episode) for this IER to finish
* **load** [int]: The load (in bits/s) for this IER to apply to links
* **protocol** [freetext]: The protocol to apply to the links. This must match a value in the services list
* **port** [int]: The port that the protocol is running on. This must match a value in the ports list
* **source** [int]: The ID of the source node
* **destination** [int]: The ID of the destination node
* **missionCriticality** [enum]: Not currently used. Default to 0
* **itemType: GREEN_POL**
Defines a green agent pattern-of-life instruction. It should consist of:
* **id** [int]: Unique ID for this YAML item
* **startStep** [int]: The start step (in the episode) for this PoL to begin
* **endStep** [int]: Not currently used. Default to same as start step
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **nodeId** [int]: The ID of the node to apply the PoL to
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **type** [enum]: The type of PoL to apply. Can be one of OPERATING, OS or SERVICE
* **protocol** [freetext]: The protocol to be affected if SERVICE type is chosen. Must match a value in the services list
* **state** [enuum]: The state to apply to the node (which represents the PoL change). Can be one of ON, OFF or RESETTING (for node state) or GOOD, PATCHING or COMPROMISED (for operating system state) or GOOD, PATCHING, COMPROMISED or OVERWHELMED (for service state)
* **itemType: RED_POL**
Defines a red agent pattern-of-life instruction. It should consist of:
* **id** [int]: Unique ID for this YAML item
* **startStep** [int]: The start step (in the episode) for this PoL to begin
* **endStep** [int]: Not currently used. Default to same as start step
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **targetNodeId** [int]: The ID of the node to apply the PoL to
* **initiator** [enum]: What initiates the PoL. Can be DIRECT, IER or SERVICE
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **type** [enum]: The type of PoL to apply. Can be one of OPERATING, OS or SERVICE
* **protocol** [freetext]: The protocol to be affected if SERVICE type is chosen. Must match a value in the services list
Committed the v1.1.0 code provided by James Short. Had to add setuptools==66 to setup.py as older versions of Gym are uninstallable with setuptools>=67
2023-04-06 11:04:09 +01:00
* **state** [enum]: The state to apply to the node (which represents the PoL change). Can be one of ON, OFF or RESETTING (for node state) or GOOD, PATCHING or COMPROMISED (for operating system state) or GOOD, PATCHING, COMPROMISED or OVERWHELMED (for service state) or GOOD, CORRUPT, DESTROYED, REPAIRING or RESTORING (for file system state)
* **sourceNodeId** [int] The ID of the source node containing the service to check (used for SERVICE initiator)
* **sourceNodeService** [freetext]: The service on the source node to check (used for SERVICE initiator). Must match a value in the services list for this node
* **sourceNodeServiceState** [enum]: The state of the source node service to check (used for SERVICE initiator). Can be one of GOOD, PATCHING, COMPROMISED or OVERWHELMED
Initial commit of v1.0.0. Updated the .gitignore for the standard Python gitignore. Added Azure DevOps release pipeline for proper artifact release from the start.
2023-03-28 17:33:34 +01:00
* **itemType: ACL_RULE**
Defines an initial Access Control List (ACL) rule. It should consist of:
* **id** [int]: Unique ID for this YAML item
* **permission** [enum]: Defines either an allow or deny rule. Value must be either DENY or ALLOW
* **source** [IP address]: Defines the source IP address for the rule in xxx.xxx.xxx.xxx format
* **destination** [IP address]: Defines the destination IP address for the rule in xxx.xxx.xxx.xxx format
* **protocol** [freetext]: Defines the protocol for the rule. Must match a value in the services list
* **port** [int]: Defines the port for the rule. Must match a value in the ports list
Reference in New Issue Copy Permalink