oxbrbtx/PrimAITE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

#2472: switch to using nbsphinx + added readme steps to setup pandoc + revert changes

Browse Source
This commit is contained in:
Czar Echavez
2024-05-14 07:36:29 +01:00
parent 795004be5b
commit 2774623fba
15 changed files with 208 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
src/primaite/notebooks/Data-Manipulation-Customising-Red-Agent.ipynb
View File

@@ -126,7 +126,13 @@
"There are two important parts of the YAML config for varying red agent behaviour.\n",
"\n",
"### Red agent settings\n",
"Here is an annotated config for the red agent in the data manipulation scenario.\n",
"Here is an annotated config for the red agent in the data manipulation scenario."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```yaml\n",
" - ref: data_manipulation_attacker # name of agent\n",
" team: RED # not used, just for human reference\n",
@@ -171,10 +177,21 @@
" start_step: 25 # first attack at step 25\n",
" frequency: 20 # attacks will happen every 20 steps (on average)\n",
" variance: 5 # the timing of attacks will vary by up to 5 steps earlier or later\n",
"```\n",
"\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Malicious application settings\n",
"The red agent uses an application called `DataManipulationBot` which leverages a node's `DatabaseClient` to send a malicious SQL query to the database server. Here's an annotated example of how this is configured in the yaml *(with impertinent config items omitted)*:\n",
"The red agent uses an application called `DataManipulationBot` which leverages a node's `DatabaseClient` to send a malicious SQL query to the database server. Here's an annotated example of how this is configured in the yaml *(with impertinent config items omitted)*:"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```yaml\n",
"simulation:\n",
" network:\n",

223
src/primaite/notebooks/Data-Manipulation-E2E-Demonstration.ipynb
View File

@@ -160,139 +160,158 @@
"### Mappings\n",
"\n",
"The dict keys for `node_id` are in the following order:\n",
"|node_id|node name|\n",
"|--|--|\n",
"|1|domain_controller|\n",
"|2|web_server|\n",
"|3|database_server|\n",
"|4|backup_server|\n",
"|5|security_suite|\n",
"|6|client_1|\n",
"|7|client_2|\n",
"\n",
"| node_id | node name |\n",
"|---------|------------------|\n",
"| 1 | domain_controller|\n",
"| 2 | web_server |\n",
"| 3 | database_server |\n",
"| 4 | backup_server |\n",
"| 5 | security_suite |\n",
"| 6 | client_1 |\n",
"| 7 | client_2 |\n",
"\n",
"Service 1 on node 2 (web_server) corresponds to the Web Server service. Other services are only there for padding to ensure that each node's observation space has the same shape. They are filled with zeroes.\n",
"\n",
"Folder 1 on node 3 corresponds to the database folder. File 1 in that folder corresponds to the database storage file. Other files and folders are only there for padding to ensure that each node's observation space has the same shape. They are filled with zeroes.\n",
"\n",
"The dict keys for `link_id` are in the following order:\n",
"|link_id|endpoint_a|endpoint_b|\n",
"|--|--|--|\n",
"|1|router_1|switch_1|\n",
"|1|router_1|switch_2|\n",
"|1|switch_1|domain_controller|\n",
"|1|switch_1|web_server|\n",
"|1|switch_1|database_server|\n",
"|1|switch_1|backup_server|\n",
"|1|switch_1|security_suite|\n",
"|1|switch_2|client_1|\n",
"|1|switch_2|client_2|\n",
"|1|switch_2|security_suite|\n",
"\n",
"| link_id | endpoint_a | endpoint_b |\n",
"|---------|------------------|-------------------|\n",
"| 1 | router_1 | switch_1 |\n",
"| 1 | router_1 | switch_2 |\n",
"| 1 | switch_1 | domain_controller |\n",
"| 1 | switch_1 | web_server |\n",
"| 1 | switch_1 | database_server |\n",
"| 1 | switch_1 | backup_server |\n",
"| 1 | switch_1 | security_suite |\n",
"| 1 | switch_2 | client_1 |\n",
"| 1 | switch_2 | client_2 |\n",
"| 1 | switch_2 | security_suite |\n",
"\n",
"\n",
"The ACL rules in the observation space appear in the same order that they do in the actual ACL. Though, only the first 10 rules are shown, there are default rules lower down that cannot be changed by the agent. The extra rules just allow the network to function normally, by allowing pings, ARP traffic, etc.\n",
"\n",
"Most nodes have only 1 network_interface, so the observation for those is placed at NIC index 1 in the observation space. Only the security suite has 2 NICs, the second NIC in the observation space is the one that connects the security suite with swtich_2.\n",
"\n",
"The meaning of the services' operating_state is:\n",
"|operating_state|label|\n",
"|--|--|\n",
"|0|UNUSED|\n",
"|1|RUNNING|\n",
"|2|STOPPED|\n",
"|3|PAUSED|\n",
"|4|DISABLED|\n",
"|5|INSTALLING|\n",
"|6|RESTARTING|\n",
"\n",
"| operating_state | label |\n",
"|-----------------|------------|\n",
"| 0 | UNUSED |\n",
"| 1 | RUNNING |\n",
"| 2 | STOPPED |\n",
"| 3 | PAUSED |\n",
"| 4 | DISABLED |\n",
"| 5 | INSTALLING |\n",
"| 6 | RESTARTING |\n",
"\n",
"The meaning of the services' health_state is:\n",
"|health_state|label|\n",
"|--|--|\n",
"|0|UNUSED|\n",
"|1|GOOD|\n",
"|2|FIXING|\n",
"|3|COMPROMISED|\n",
"|4|OVERWHELMED|\n",
"\n",
"| health_state | label |\n",
"|--------------|-------------|\n",
"| 0 | UNUSED |\n",
"| 1 | GOOD |\n",
"| 2 | FIXING |\n",
"| 3 | COMPROMISED |\n",
"| 4 | OVERWHELMED |\n",
"\n",
"\n",
"The meaning of the files' and folders' health_state is:\n",
"|health_state|label|\n",
"|--|--|\n",
"|0|UNUSED|\n",
"|1|GOOD|\n",
"|2|COMPROMISED|\n",
"|3|CORRUPT|\n",
"|4|RESTORING|\n",
"|5|REPAIRING|\n",
"\n",
"| health_state | label |\n",
"|--------------|-------------|\n",
"| 0 | UNUSED |\n",
"| 1 | GOOD |\n",
"| 2 | COMPROMISED |\n",
"| 3 | CORRUPT |\n",
"| 4 | RESTORING |\n",
"| 5 | REPAIRING |\n",
"\n",
"\n",
"The meaning of the NICs' operating_status is:\n",
"|operating_status|label|\n",
"|--|--|\n",
"|0|UNUSED|\n",
"|1|ENABLED|\n",
"|2|DISABLED|\n",
"\n",
"| operating_status | label |\n",
"|------------------|----------|\n",
"| 0 | UNUSED |\n",
"| 1 | ENABLED |\n",
"| 2 | DISABLED |\n",
"\n",
"\n",
"NMNE (number of malicious network events) means, for inbound or outbound traffic, means:\n",
"|value|NMNEs|\n",
"|--|--|\n",
"|0|None|\n",
"|1|1 - 5|\n",
"|2|6 - 10|\n",
"|3|More than 10|\n",
"\n",
"| value | NMNEs |\n",
"|-------|----------------|\n",
"| 0 | None |\n",
"| 1 | 1 - 5 |\n",
"| 2 | 6 - 10 |\n",
"| 3 | More than 10 |\n",
"\n",
"\n",
"Link load has the following meaning:\n",
"|load|percent utilisation|\n",
"|--|--|\n",
"|0|exactly 0%|\n",
"|1|0-11%|\n",
"|2|11-22%|\n",
"|3|22-33%|\n",
"|4|33-44%|\n",
"|5|44-55%|\n",
"|6|55-66%|\n",
"|7|66-77%|\n",
"|8|77-88%|\n",
"|9|88-99%|\n",
"|10|exactly 100%|\n",
"\n",
"| load | percent utilisation |\n",
"|------|---------------------|\n",
"| 0 | exactly 0% |\n",
"| 1 | 0-11% |\n",
"| 2 | 11-22% |\n",
"| 3 | 22-33% |\n",
"| 4 | 33-44% |\n",
"| 5 | 44-55% |\n",
"| 6 | 55-66% |\n",
"| 7 | 66-77% |\n",
"| 8 | 77-88% |\n",
"| 9 | 88-99% |\n",
"| 10 | exactly 100% |\n",
"\n",
"\n",
"ACL permission has the following meaning:\n",
"|permission|label|\n",
"|--|--|\n",
"|0|UNUSED|\n",
"|1|ALLOW|\n",
"|2|DENY|\n",
"\n",
"| permission | label |\n",
"|------------|--------|\n",
"| 0 | UNUSED |\n",
"| 1 | ALLOW |\n",
"| 2 | DENY |\n",
"\n",
"\n",
"ACL source / destination node ids actually correspond to IP addresses (since ACLs work with IP addresses)\n",
"|source / dest node id|ip_address|label|\n",
"|--|--|--|\n",
"|0| | UNUSED|\n",
"|1| |ALL addresses|\n",
"|2| 192.168.1.10 | domain_controller|\n",
"|3| 192.168.1.12 | web_server \n",
"|4| 192.168.1.14 | database_server|\n",
"|5| 192.168.1.16 | backup_server|\n",
"|6| 192.168.1.110 | security_suite (eth-1)|\n",
"|7| 192.168.10.21 | client_1|\n",
"|8| 192.168.10.22 | client_2|\n",
"|9| 192.168.10.110| security_suite (eth-2)|\n",
"\n",
"| source / dest node id | ip_address | label |\n",
"|-----------------------|----------------|-------------------------|\n",
"| 0 | | UNUSED |\n",
"| 1 | | ALL addresses |\n",
"| 2 | 192.168.1.10 | domain_controller |\n",
"| 3 | 192.168.1.12 | web_server |\n",
"| 4 | 192.168.1.14 | database_server |\n",
"| 5 | 192.168.1.16 | backup_server |\n",
"| 6 | 192.168.1.110 | security_suite (eth-1) |\n",
"| 7 | 192.168.10.21 | client_1 |\n",
"| 8 | 192.168.10.22 | client_2 |\n",
"| 9 | 192.168.10.110 | security_suite (eth-2) |\n",
"\n",
"\n",
"ACL source / destination port ids have the following encoding:\n",
"|port id|port number| port use |\n",
"|--|--|--|\n",
"|0||UNUSED|\n",
"|1||ALL|\n",
"|2|219|ARP|\n",
"|3|53|DNS|\n",
"|4|80|HTTP|\n",
"|5|5432|POSTGRES_SERVER|\n",
"\n",
"| port id | port number | port use |\n",
"|---------|-------------|-----------------|\n",
"| 0 | | UNUSED |\n",
"| 1 | | ALL |\n",
"| 2 | 219 | ARP |\n",
"| 3 | 53 | DNS |\n",
"| 4 | 80 | HTTP |\n",
"| 5 | 5432 | POSTGRES_SERVER |\n",
"\n",
"\n",
"ACL protocol ids have the following encoding:\n",
"|protocol id|label|\n",
"|--|--|\n",
"|0|UNUSED|\n",
"|1|ALL|\n",
"|2|ICMP|\n",
"|3|TCP|\n",
"|4|UDP|\n",
"\n",
"protocol"
"| protocol id | label |\n",
"|-------------|-------|\n",
"| 0 | UNUSED|\n",
"| 1 | ALL |\n",
"| 2 | ICMP |\n",
"| 3 | TCP |\n",
"| 4 | UDP |\n"
]
},
{

7
src/primaite/notebooks/Training-an-RLLIB-MARL-System.ipynb
View File

@@ -88,13 +88,6 @@
" param_space=config\n",
").fit()"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {

7
src/primaite/notebooks/Training-an-RLLib-Agent.ipynb
View File

@@ -79,13 +79,6 @@
" param_space=config\n",
").fit()\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {

10
src/primaite/notebooks/Using-Episode-Schedules.ipynb
View File

@@ -38,6 +38,13 @@
"YAML file with a relative path to the base scenario and a list of paths to be loaded in during each episode.\n",
"\n",
"It takes the following format:\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```yaml\n",
"base_scenario: base.yaml\n",
"schedule:\n",
@@ -47,8 +54,7 @@
" 1: # list of variations to load in at episode 1 (after the first env.reset() call)\n",
" - laydown_2.yaml\n",
" - attack_2.yaml\n",
"```\n",
"\n"
"```\n"
]
},
{

2
src/primaite/notebooks/multi-processing.ipynb
View File

@@ -140,7 +140,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.11"
"version": "3.8.10"
}
},
"nbformat": 4,

6
src/primaite/simulator/_package_data/network_simulator_demo.ipynb
View File

@@ -11,10 +11,11 @@
]
},
{
"cell_type": "raw",
"cell_type": "markdown",
"id": "1",
"metadata": {},
"source": [
"``` text\n",
" +------------+\n",
" | domain_ |\n",
" +------------+ controller |\n",
@@ -43,7 +44,8 @@
" | | | | backup_ |\n",
" +------------+ +------------+ server |\n",
" | |\n",
" +------------+"
" +------------+\n",
"```"
]
},
{