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

3110 Fix formatting and code examples in docs

Browse Source
This commit is contained in:
Marek Wolan
2025-03-13 14:18:26 +00:00
parent dc65681f2c
commit d4287d6690
2 changed files with 34 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/source/simulation_components/network/nodes/wireless_router.rst
View File

@@ -64,7 +64,7 @@ other wireless devices within the same frequency band.
Example Scenario
----------------
This example sets up a network with two PCs (PC A and PC B), each connected to their own `WirelessRouter`
This example sets up a network with two PCs (PC A and PC B), each connected to their own ``WirelessRouter``
(Router 1 and Router 2). These routers are then wirelessly connected to each other, enabling communication between the
PCs through the routers over the airspace. Access Control Lists (ACLs) are configured on the routers to permit ARP and
ICMP traffic, ensuring basic network connectivity and ping functionality.
@@ -160,7 +160,7 @@ network segments.
Viewing Wireless Network Configuration
--------------------------------------
The `AirSpace.show()` function is an invaluable tool for inspecting the current wireless network configuration within
The :py:meth:`AirSpace.show() <primaite.simulator.network.airspace.AirSpace.show()>` function is an invaluable tool for inspecting the current wireless network configuration within
the PrimAITE environment. It presents a table summarising all wireless interfaces, including routers and access points,
that are active within the airspace. The table outlines each device's connected node name, MAC address, IP address,
subnet mask, operating frequency, and status, providing a comprehensive view of the wireless network topology.
@@ -168,7 +168,7 @@ subnet mask, operating frequency, and status, providing a comprehensive view of
Example Output
^^^^^^^^^^^^^^^
Below is an example output of the `AirSpace.show()` function, demonstrating the visibility it provides into the
Below is an example output of the :py:meth:`AirSpace.show() <primaite.simulator.network.airspace.AirSpace.show()>` function, demonstrating the visibility it provides into the
wireless network:
.. code-block:: none
@@ -182,10 +182,10 @@ wireless network:
This table aids in verifying that wireless devices are correctly configured and operational. It also helps in
diagnosing connectivity issues by ensuring that devices are on the correct frequency and have the appropriate network
settings. The `Status` column, indicating whether a device is enabled or disabled, further assists in troubleshooting
settings. The ``Status`` column, indicating whether a device is enabled or disabled, further assists in troubleshooting
by quickly identifying any devices that are not actively participating in the network.
Utilising the `AirSpace.show()` function is particularly beneficial in complex network simulations where multiple
Utilising the :py:meth:`AirSpace.show() <primaite.simulator.network.airspace.AirSpace.show()>` function is particularly beneficial in complex network simulations where multiple
wireless devices are in use. It provides a snapshot of the wireless landscape, facilitating the understanding of how
devices interact within the network and ensuring that configurations are aligned with the intended network architecture.

52
docs/source/simulation_structure.rst
View File

@@ -7,8 +7,7 @@ Simulation Structure
====================
The simulation is made up of many smaller components which are related to each other in a tree-like structure. At the
top level, there is the :py:meth:`primaite.simulator.sim_container.Simulation`, which keeps track of the physical network
and a domain controller for managing software and users.
top level, there is the :py:meth:`primaite.simulator.sim_container.Simulation`, which keeps track of the physical network and a domain controller for managing software and users.
Each node of the simulation 'tree' has responsibility for creating, deleting, and updating its direct descendants. Also,
when a component's ``describe_state()`` method is called, it will include the state of its descendants. The
@@ -25,48 +24,55 @@ relationship between components.
Actions
=======
Agents can interact with the simulation by using actions. Actions are standardised with the
:py:class:`primaite.simulation.core.RequestType` class, which just holds a reference to two special functions.
Agents can interact with the simulation by using actions. Actions adhere to the Common Action and Observation Space (CAOS) specification, and are converted into Requests for use by the simulation. Requests are standardised via the :py:class:`primaite.simulation.core.RequestType` class, which just holds a reference to two special functions.
1. The request function itself, it must accept a `request` parameters which is a list of strings that describe what the
action should do. It must also accept a `context` dict which can house additional information surrounding the action.
For example, the context will typically include information about which entity intiated the action.
2. A validator function. This function should return a boolean value that decides if the request is permitted or not.
It uses the same paramters as the action function.
1. The function that actions the request, it must accept a `request` parameters which is a list of strings that describe what the action should do. It must also accept a `context` dict which can house additional information surrounding the action.
2. A validator function. This function should return a boolean value that decides if the request is permitted or not. It uses the same paramters as the action function.
Action Permissions
Action Validation
------------------
When an agent tries to perform an action on a simulation component, that action will only be executed if the request is
validated. For example, some actions can require that an agent is logged into an admin account. Each action defines its
When an agent tries to perform an action on a simulation component, that action will only be executed if the request is validated. For example, some actions can require that the target network node is powered on. Each action defines its
own permissions using an instance of :py:class:`primaite.simulation.core.ActionPermissionValidator`. The below code
snippet demonstrates usage of the ``ActionPermissionValidator``.
.. code:: python
from primaite.simulator.core import Action, RequestManager, SimComponent
from primaite.simulator.domain.controller import AccountGroup, GroupMembershipValidator
from primaite.simulator.core import Action, RequestManager, SimComponent, ActionPermissionValidator
from primaite.interface.request import RequestResponse
class Smartphone(SimComponent):
name: str
apps = []
connected: bool
apps: List = []
class _ConnectedToNetworkValidator(ActionPermissionValidator):
smartphone: Smarphone
"""A reference to the smartphone object."""
def __call__(self, request: RequestFormat, context: Dict) -> bool:
return self.smartphone.connected
def _init_request_manager(self) -> RequestManager:
am = super()._init_request_manager()
am.add_request(
"reset_factory_settings",
Action(
func = lambda request, context: self.reset_factory_settings(),
validator = GroupMembershipValidator([AccountGroup.DOMAIN_ADMIN]),
ReqeustType(
func = lambda request, context: RequestResponse.from_bool(self.reset_factory_settings()),
validator = Smartphone._ConnectedToNetworkValidator(smartphone=self),
)
)
def reset_factory_settings(self):
self.apps = []
return True
phone = Smartphone(name="phone1")
phone = Smartphone(name="phone1", connected=False)
phone.apply_request(request=["reset_factory_settings"])
# >>> False
# try to wipe the phone as a domain user, this will have no effect
phone.apply_action(["reset_factory_settings"], context={"request_source":{"groups":["DOMAIN_USER"]})
phone2 = Smartphone(name="phone2", connected=True)
phone.apply_request(request=["reset_factory_settings"])
# >>> True
# try to wipe the phone as an admin user, this will wipe the phone
phone.apply_action(["reset_factory_settings"], context={"request_source":{"groups":["DOMAIN_ADMIN"]})