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

#2248 - Enhances the PrimAITE documentation, covering the Node, network interfaces, Session Manager, Software Manager, PCAP service, SysLog functionality, and network devices like Routers, Switches, Computers, and Switch Nodes. It details their roles, workflows, and integration within the simulation, focusing on frame processing, software management, and logging. The documentation also clarifies the frame reception process, including port checks and application-level dispatching, ensuring a thorough understanding of network operations within the simulation

Browse Source
This commit is contained in:
Chris McCarthy
2024-02-08 22:37:21 +00:00
parent 5eed467271
commit a036160515
21 changed files with 529 additions and 837 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGELOG.md
View File

@@ -67,6 +67,10 @@ SessionManager.
- Created the `ARP` and `ICMP` service classes to handle Address Resolution Protocol operations and Internet Control Message Protocol messages, respectively, with `RouterARP` and `RouterICMP` for router-specific implementations.
- Created `HostNode` as a subclass of `Node`, extending its functionality with host-specific services and applications. This class is designed to represent end-user devices like computers or servers that can initiate and respond to network communications.
- Introduced a new `IPV4Address` type in the Pydantic model for enhanced validation and auto-conversion of IPv4 addresses from strings using an `ipv4_validator`.
- Comprehensive documentation for the Node and its network interfaces, detailing the operational workflow from frame reception to application-level processing.
- Detailed descriptions of the Session Manager and Software Manager functionalities, including their roles in managing sessions, software services, and applications within the simulation.
- Documentation for the Packet Capture (PCAP) service and SysLog functionality, highlighting their importance in logging network frames and system events, respectively.
- Expanded documentation on network devices such as Routers, Switches, Computers, and Switch Nodes, explaining their specific processing logic and protocol support.
### Changed

8
docs/source/simulation.rst
View File

@@ -17,9 +17,15 @@ Contents
simulation_structure
simulation_components/network/base_hardware
simulation_components/network/network_interfaces
simulation_components/network/transport_to_data_link_layer
simulation_components/network/router
simulation_components/network/nodes/host_node
simulation_components/network/nodes/network_node
simulation_components/network/nodes/router
simulation_components/network/switch
simulation_components/network/network
simulation_components/system/internal_frame_processing
simulation_components/system/sys_log
simulation_components/system/pcap
simulation_components/system/session_and_software_manager
simulation_components/system/software

740
docs/source/simulation_components/network/base_hardware.rst
View File

@@ -6,719 +6,41 @@
Base Hardware
#############
The physical layer components are models of a NIC (Network Interface Card), SwitchPort, Node, Switch, and a Link.
These components allow modelling of layer 1 (physical layer) in the OSI model and the nodes that connect to and
transmit across layer 1.
The ``base.py`` module in ``primaite.simulator.network.hardware`` provides foundational components, interfaces, and classes for
modeling network hardware within PrimAITE simulations. It establishes core building blocks and abstractions that more
complex, specialized hardware components inherit from and build upon.
===
NIC
===
The key elements defined in ``base.py`` are:
The NIC class provides a realistic model of a Network Interface Card. The NIC acts as the interface between a Node and
a Link, handling IP and MAC addressing, status, and sending/receiving frames.
NetworkInterface
================
----------
Addressing
----------
- Abstract base class for network interfaces like NICs. Defines common attributes like MAC address, speed, MTU.
- Requires subclasses to implement ``enable()``, ``disable()``, ``send_frame()`` and ``receive_frame()``.
- Provides basic state description and request handling capabilities.
A NIC has both an IPv4 address and MAC address assigned:
- **ip_address** - The IPv4 address assigned to the NIC for communication on an IP network.
- **subnet_mask** - The subnet mask that defines the network subnet.
- **gateway** - The default gateway IP address for routing traffic beyond the local network.
- **mac_address** - A unique MAC address assigned to the NIC by the manufacturer.
------
Status
------
The status of the NIC is represented by:
- **enabled** - Indicates if the NIC is active/enabled or disabled/down. It must be enabled to send/receive frames.
- **connected_node** - The Node instance the NIC is attached to.
- **connected_link** - The Link instance the NIC is wired to.
--------------
Packet Capture
--------------
- **pcap** - A PacketCapture instance attached to the NIC for capturing all frames sent and received. This allows packet
capture and analysis.
------------------------
Sending/Receiving Frames
------------------------
The NIC can send and receive Frames to/from the connected Link:
- **send_frame()** - Sends a Frame through the NIC onto the attached Link.
- **receive_frame()** - Receives a Frame from the attached Link and processes it.
This allows a NIC to handle sending, receiving, and forwarding of network traffic at layer 2 of the OSI model.
The Frames contain network data encapsulated with various protocol headers.
-----------
Basic Usage
-----------
.. code-block:: python
nic1 = NIC(
ip_address="192.168.0.100",
subnet_mask="255.255.255.0",
gateway="192.168.0.1"
)
nic1.enable()
frame = Frame(...)
nic1.send_frame(frame)
==========
SwitchPort
==========
The SwitchPort models a port on a network switch. It has similar attributes and methods to NIC for addressing, status,
packet capture, sending/receiving frames, etc.
Key attributes:
- **port_num**: The port number on the switch.
- **connected_switch**: The switch to which this port belongs.
====
Node
====
The Node class represents a base node that communicates on the Network.
Nodes take more than 1 time step to power on (3 time steps by default).
To create a Node that is already powered on, the Node's operating state can be overriden.
Otherwise, the node ``start_up_duration`` (and ``shut_down_duration``) can be set to 0 if
the node will be powered off or on multiple times. This will still need ``power_on()`` to
be called to turn the node on.
e.g.
.. code-block:: python
active_node = Node(hostname='server1', operating_state=NodeOperatingState.ON)
# node is already on, no need to call power_on()
instant_start_node = Node(hostname="client", start_up_duration=0, shut_down_duration=0)
instant_start_node.power_on() # node will still need to be powered on
.. _Node Start up and Shut down:
---------------------------
Node Start up and Shut down
---------------------------
Nodes are powered on and off over multiple timesteps. By default, the node ``start_up_duration`` and ``shut_down_duration`` is 3 timesteps.
Example code where a node is turned on:
.. code-block:: python
from primaite.simulator.network.hardware.base import Node
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
node = Node(hostname="pc_a")
assert node.operating_state is NodeOperatingState.OFF # By default, node is instantiated in an OFF state
node.power_on() # power on the node
assert node.operating_state is NodeOperatingState.BOOTING # node is booting up
for i in range(node.start_up_duration + 1):
# apply timestep until the node start up duration
node.apply_timestep(timestep=i)
assert node.operating_state is NodeOperatingState.ON # node is in ON state
If the node needs to be instantiated in an on state:
.. code-block:: python
from primaite.simulator.network.hardware.base import Node
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
node = Node(hostname="pc_a", operating_state=NodeOperatingState.ON)
assert node.operating_state is NodeOperatingState.ON # node is in ON state
Setting ``start_up_duration`` and/or ``shut_down_duration`` to ``0`` will allow for the ``power_on`` and ``power_off`` methods to be completed instantly without applying timesteps:
.. code-block:: python
from primaite.simulator.network.hardware.base import Node
from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
node = Node(hostname="pc_a", start_up_duration=0, shut_down_duration=0)
assert node.operating_state is NodeOperatingState.OFF # node is in OFF state
node.power_on()
assert node.operating_state is NodeOperatingState.ON # node is in ON state
node.power_off()
assert node.operating_state is NodeOperatingState.OFF # node is in OFF state
------------------
Network Interfaces
------------------
A Node will typically have one or more NICs attached to it for network connectivity:
- **network_interfaces** - A dictionary containing the NIC instances attached to the Node. NICs can be added/removed.
-------------
Configuration
-------------
- **hostname** - Configured hostname of the Node.
- **operating_state** - Current operating state like ON or OFF. The NICs will be enabled/disabled based on this.
----------------
Network Services
----------------
A Node runs various network services and components for handling traffic:
- **session_manager** - Handles establishing sessions to/from the Node.
- **software_manager** - Manages software and applications on the Node.
- **arp** - ARP cache for resolving IP addresses to MAC addresses.
- **icmp** - ICMP service for responding to pings and echo requests.
- **sys_log** - System log service for logging internal events and messages.
The SysLog provides a logging mechanism for the Node:
The SysLog records informational, warning, and error events that occur on the Node during simulation. This allows
debugging and tracing program execution and network activity for each simulated Node. Other Node services like ARP and
ICMP, along with custom Applications, services, and Processes will log to the SysLog.
-----------------
Sending/Receiving
-----------------
The Node handles sending and receiving Frames via its attached NICs:
- **send_frame()** - Sends a Frame to the network through one of the Node's NICs.
- **receive_frame()** - Receives a Frame from the network through a NIC. The Node then processes it appropriately based
on the protocols and payload.
-----------
Basic Usage
-----------
.. code-block:: python
node1 = Node(hostname='server1')
node1.operating_state = NodeOperatingState.ON
nic1 = NIC()
node1.connect_nic(nic1)
Send a frame
frame = Frame(...)
node1.send_frame(frame)
The Node class brings together the NICs, configuration, and services to model a full network node that can send,
receive, process, and forward traffic on a simulated network.
======
Switch
======
The Switch subclass models a network switch. It inherits from Node and acts at layer 2 of the OSI model to forward
frames based on MAC addresses.
--------------------------
Inherits Node Capabilities
--------------------------
Since Switch subclasses Node, it inherits all capabilities from Node like:
- **Managing NICs**
- **Running network services like ARP, ICMP**
- **Sending and receiving frames**
- **Maintaining system logs**
-----
Ports
-----
A Switch has multiple ports implemented using SwitchPort instances:
- **switch_ports** - A dictionary mapping port numbers to SwitchPort instances.
- **num_ports** - The number of ports the Switch has.
----------
Forwarding
----------
A Switch forwards frames between ports based on the destination MAC:
- **dst_mac_table** - MAC address table that maps MACs to SwitchPorts.
- **forward_frame()** - Forwards a frame out the port associated with the destination MAC.
When a frame is received on a SwitchPort:
1. The source MAC address is extracted from the frame.
2. An entry is added to dst_mac_table that maps this source MAC to the SwitchPort it was received on.
3. When a frame with that destination MAC is received in the future, it will be forwarded out this SwitchPort.
This allows the Switch to dynamically build up a mapping table between MAC addresses and SwitchPorts based on traffic
received. If no entry exists for a destination MAC, it floods the frame out all ports.
====
Link
====
The Link class represents a physical link or connection between two network endpoints like NICs or SwitchPorts.
---------
Endpoints
---------
A Link connects two endpoints:
- **endpoint_a** - The first endpoint, a NIC or SwitchPort.
- **endpoint_b** - The second endpoint, a NIC or SwitchPort.
------------
Transmission
------------
Links transmit Frames between the endpoints:
- **transmit_frame()** - Sends a Frame from one endpoint to the other.
Uses bandwidth/load properties to determine if transmission is possible.
----------------
Bandwidth & Load
----------------
- **bandwidth** - The total capacity of the Link in Mbps.
- **current_load** - The current bandwidth utilization of the Link in Mbps.
As Frames are sent over the Link, the load increases. The Link tracks if there is enough unused capacity to transmit a
Frame based on its size and the current load.
------
Status
------
- **up** - Boolean indicating if the Link is currently up/active based on the endpoint status.
- **endpoint_up()/down()** - Notifies the Link when an endpoint goes up or down.
This allows the Link to realistically model the connection and transmission characteristics between two endpoints.
=======================
Putting it all Together
=======================
We'll now demonstrate how the nodes, NICs, switches, and links connect in a network, including full code examples and
syslog extracts to illustrate the step-by-step process.
To demonstrate successful network communication between nodes and switches, we'll model a standard network with four
PC's and two switches.
.. image:: ../../../_static/four_node_two_switch_network.png
-------------------
Create Nodes & NICs
-------------------
First, we'll create the four nodes, each with a single NIC.
.. code-block:: python
from primaite.simulator.network.hardware.base import Node, NodeOperatingState, NIC
pc_a = Node(hostname="pc_a", operating_state=NodeOperatingState.ON)
nic_a = NIC(ip_address="192.168.0.10", subnet_mask="255.255.255.0", gateway="192.168.0.1")
pc_a.connect_nic(nic_a)
pc_b = Node(hostname="pc_b", operating_state=NodeOperatingState.ON)
nic_b = NIC(ip_address="192.168.0.11", subnet_mask="255.255.255.0", gateway="192.168.0.1")
pc_b.connect_nic(nic_b)
pc_c = Node(hostname="pc_c", operating_state=NodeOperatingState.ON)
nic_c = NIC(ip_address="192.168.0.12", subnet_mask="255.255.255.0", gateway="192.168.0.1")
pc_c.connect_nic(nic_c)
pc_d = Node(hostname="pc_d", operating_state=NodeOperatingState.ON)
nic_d = NIC(ip_address="192.168.0.13", subnet_mask="255.255.255.0", gateway="192.168.0.1")
pc_d.connect_nic(nic_d)
Creating the four nodes results in:
**node_a NIC table**
+-------------------+--------------+---------------+-----------------+--------------+----------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+==========+
| 80:af:f2:f6:58:b7 | 102.169.0.10 | 255.255.255.0 | 192.168.0.1 | 100 | Disabled |
+-------------------+--------------+---------------+-----------------+--------------+----------+
**node_a sys log**
.. code-block::
2023-08-08 15:50:08,355 INFO: Connected NIC 80:af:f2:f6:58:b7/192.168.0.10
**node_b NIC table**
+-------------------+--------------+---------------+-----------------+--------------+----------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+==========+
| 98:ad:eb:7c:dc:cb | 102.169.0.11 | 255.255.255.0 | 192.168.0.1 | 100 | Disabled |
+-------------------+--------------+---------------+-----------------+--------------+----------+
**node_b sys log**
.. code-block::
2023-08-08 15:50:08,357 INFO: Connected NIC 98:ad:eb:7c:dc:cb/192.168.0.11
**node_c NIC table**
+-------------------+--------------+---------------+-----------------+--------------+----------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+==========+
| bc:72:82:5d:82:a4 | 102.169.0.12 | 255.255.255.0 | 192.168.0.1 | 100 | Disabled |
+-------------------+--------------+---------------+-----------------+--------------+----------+
**node_c sys log**
.. code-block::
2023-08-08 15:50:08,358 INFO: Connected NIC bc:72:82:5d:82:a4/192.168.0.12
**node_d NIC table**
+-------------------+--------------+---------------+-----------------+--------------+----------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+==========+
| 84:20:7c:ec:a5:c6 | 102.169.0.13 | 255.255.255.0 | 192.168.0.1 | 100 | Disabled |
+-------------------+--------------+---------------+-----------------+--------------+----------+
**node_d sys log**
.. code-block::
2023-08-08 15:50:08,359 INFO: Connected NIC 84:20:7c:ec:a5:c6/192.168.0.13
---------------
Create Switches
---------------
Next, we'll create two six-port switches:
.. code-block:: python
switch_1 = Switch(hostname="switch_1", num_ports=6, operating_state=NodeOperatingState.ON)
switch_2 = Switch(hostname="switch_2", num_ports=6, operating_state=NodeOperatingState.ON)
This produces:
**switch_1 MAC table**
+------+-------------------+--------------+----------+
| Port | MAC Address | Speed (Mbps) | Status |
+======+===================+==============+==========+
| 1 | 9d:ac:59:a0:05:13 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 2 | 45:f5:8e:b6:f5:d3 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 3 | ef:f5:b9:28:cb:ae | 100 | Disabled |
+------+-------------------+--------------+----------+
| 4 | 88:76:0a:72:fc:14 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 5 | 79:de:da:bd:e2:ba | 100 | Disabled |
+------+-------------------+--------------+----------+
| 6 | 91:d5:83:a0:02:f2 | 100 | Disabled |
+------+-------------------+--------------+----------+
**switch_1 sys log**
.. code-block::
2023-08-08 15:50:08,373 INFO: Turned on
**switch_2 MAC table**
+------+-------------------+--------------+----------+
| Port | MAC Address | Speed (Mbps) | Status |
+======+===================+==============+==========+
| 1 | aa:58:fa:66:d7:be | 100 | Disabled |
+------+-------------------+--------------+----------+
| 2 | 72:d2:1e:88:e9:45 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 3 | 8a:fc:2a:56:d5:c5 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 4 | fb:b5:9a:04:4a:49 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 5 | 88:aa:48:d0:21:9e | 100 | Disabled |
+------+-------------------+--------------+----------+
| 6 | 96:77:39:d1:de:44 | 100 | Disabled |
+------+-------------------+--------------+----------+
**switch_2 sys log**
.. code-block::
2023-08-08 15:50:08,374 INFO: Turned on
------------
Create Links
------------
Finally, we'll create the five links that connect the nodes and the switches:
.. code-block:: python
link_nic_a_switch_1 = Link(endpoint_a=nic_a, endpoint_b=switch_1.switch_ports[1])
link_nic_b_switch_1 = Link(endpoint_a=nic_b, endpoint_b=switch_1.switch_ports[2])
link_nic_c_switch_2 = Link(endpoint_a=nic_c, endpoint_b=switch_2.switch_ports[1])
link_nic_d_switch_2 = Link(endpoint_a=nic_d, endpoint_b=switch_2.switch_ports[2])
link_switch_1_switch_2 = Link(
endpoint_a=switch_1.switch_ports[6], endpoint_b=switch_2.switch_ports[6]
)
This produces:
**node_a NIC table**
+-------------------+--------------+---------------+-----------------+--------------+---------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+=========+
| 80:af:f2:f6:58:b7 | 102.169.0.10 | 255.255.255.0 | 192.168.0.1 | 100 | Enabled |
+-------------------+--------------+---------------+-----------------+--------------+---------+
**node_a sys log**
.. code-block::
2023-08-08 15:50:08,355 INFO: Connected NIC 80:af:f2:f6:58:b7/192.168.0.10
2023-08-08 15:50:08,355 INFO: Turned on
2023-08-08 15:50:08,355 INFO: NIC 80:af:f2:f6:58:b7/192.168.0.10 enabled
**node_b NIC table**
+-------------------+--------------+---------------+-----------------+--------------+---------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+=========+
| 98:ad:eb:7c:dc:cb | 102.169.0.11 | 255.255.255.0 | 192.168.0.1 | 100 | Enabled |
+-------------------+--------------+---------------+-----------------+--------------+---------+
**node_b sys log**
.. code-block::
2023-08-08 15:50:08,357 INFO: Connected NIC 98:ad:eb:7c:dc:cb/192.168.0.11
2023-08-08 15:50:08,357 INFO: Turned on
2023-08-08 15:50:08,357 INFO: NIC 98:ad:eb:7c:dc:cb/192.168.0.11 enabled
**node_c NIC table**
+-------------------+--------------+---------------+-----------------+--------------+---------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+=========+
| bc:72:82:5d:82:a4 | 102.169.0.12 | 255.255.255.0 | 192.168.0.1 | 100 | Enabled |
+-------------------+--------------+---------------+-----------------+--------------+---------+
**node_c sys log**
.. code-block::
2023-08-08 15:50:08,358 INFO: Connected NIC bc:72:82:5d:82:a4/192.168.0.12
2023-08-08 15:50:08,358 INFO: Turned on
2023-08-08 15:50:08,358 INFO: NIC bc:72:82:5d:82:a4/192.168.0.12 enabled
**node_d NIC table**
+-------------------+--------------+---------------+-----------------+--------------+---------+
| MAC Address | IP Address | Subnet Mask | Default Gateway | Speed (Mbps) | Status |
+===================+==============+===============+=================+==============+=========+
| 84:20:7c:ec:a5:c6 | 102.169.0.13 | 255.255.255.0 | 192.168.0.1 | 100 | Enabled |
+-------------------+--------------+---------------+-----------------+--------------+---------+
**node_d sys log**
.. code-block::
2023-08-08 15:50:08,359 INFO: Connected NIC 84:20:7c:ec:a5:c6/192.168.0.13
2023-08-08 15:50:08,360 INFO: Turned on
2023-08-08 15:50:08,360 INFO: NIC 84:20:7c:ec:a5:c6/192.168.0.13 enabled
**switch_1 MAC table**
+------+-------------------+--------------+----------+
| Port | MAC Address | Speed (Mbps) | Status |
+======+===================+==============+==========+
| 1 | 9d:ac:59:a0:05:13 | 100 | Enabled |
+------+-------------------+--------------+----------+
| 2 | 45:f5:8e:b6:f5:d3 | 100 | Enabled |
+------+-------------------+--------------+----------+
| 3 | ef:f5:b9:28:cb:ae | 100 | Disabled |
+------+-------------------+--------------+----------+
| 4 | 88:76:0a:72:fc:14 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 5 | 79:de:da:bd:e2:ba | 100 | Disabled |
+------+-------------------+--------------+----------+
| 6 | 91:d5:83:a0:02:f2 | 100 | Enabled |
+------+-------------------+--------------+----------+
**switch_1 sys log**
.. code-block::
2023-08-08 15:50:08,373 INFO: Turned on
2023-08-08 15:50:08,378 INFO: SwitchPort 9d:ac:59:a0:05:13 enabled
2023-08-08 15:50:08,380 INFO: SwitchPort 45:f5:8e:b6:f5:d3 enabled
2023-08-08 15:50:08,384 INFO: SwitchPort 91:d5:83:a0:02:f2 enabled
**switch_2 MAC table**
+------+-------------------+--------------+----------+
| Port | MAC Address | Speed (Mbps) | Status |
+======+===================+==============+==========+
| 1 | aa:58:fa:66:d7:be | 100 | Enabled |
+------+-------------------+--------------+----------+
| 2 | 72:d2:1e:88:e9:45 | 100 | Enabled |
+------+-------------------+--------------+----------+
| 3 | 8a:fc:2a:56:d5:c5 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 4 | fb:b5:9a:04:4a:49 | 100 | Disabled |
+------+-------------------+--------------+----------+
| 5 | 88:aa:48:d0:21:9e | 100 | Disabled |
+------+-------------------+--------------+----------+
| 6 | 96:77:39:d1:de:44 | 100 | Enabled |
+------+-------------------+--------------+----------+
**switch_2 sys log**
.. code-block::
2023-08-08 15:50:08,374 INFO: Turned on
2023-08-08 15:50:08,381 INFO: SwitchPort aa:58:fa:66:d7:be enabled
2023-08-08 15:50:08,383 INFO: SwitchPort 72:d2:1e:88:e9:45 enabled
2023-08-08 15:50:08,384 INFO: SwitchPort 96:77:39:d1:de:44 enabled
------------
Perform Ping
------------
Now with the network setup and operational, we can perform a ping to confirm that communication between nodes over a
switched network is possible. In the below example, we ping 192.168.0.13 (node_d) from node_a:
.. code-block:: python
pc_a.ping("192.168.0.13")
This produces:
**node_a sys log**
.. code-block::
2023-08-08 15:50:08,355 INFO: Connected NIC 80:af:f2:f6:58:b7/192.168.0.10
2023-08-08 15:50:08,355 INFO: Turned on
2023-08-08 15:50:08,355 INFO: NIC 80:af:f2:f6:58:b7/192.168.0.10 enabled
2023-08-08 15:50:08,406 INFO: Attempting to ping 192.168.0.13
2023-08-08 15:50:08,406 INFO: No entry in ARP cache for 192.168.0.13
2023-08-08 15:50:08,406 INFO: Sending ARP request from NIC 80:af:f2:f6:58:b7/192.168.0.10 for ip 192.168.0.13
2023-08-08 15:50:08,413 INFO: Received ARP response for 192.168.0.13 from 84:20:7c:ec:a5:c6 via NIC 80:af:f2:f6:58:b7/192.168.0.10
2023-08-08 15:50:08,413 INFO: Adding ARP cache entry for 84:20:7c:ec:a5:c6/192.168.0.13 via NIC 80:af:f2:f6:58:b7/192.168.0.10
2023-08-08 15:50:08,415 INFO: Sending echo request to 192.168.0.13
2023-08-08 15:50:08,417 INFO: Received echo reply from 192.168.0.13
2023-08-08 15:50:08,419 INFO: Sending echo request to 192.168.0.13
2023-08-08 15:50:08,421 INFO: Received echo reply from 192.168.0.13
2023-08-08 15:50:08,422 INFO: Sending echo request to 192.168.0.13
2023-08-08 15:50:08,424 INFO: Received echo reply from 192.168.0.13
2023-08-08 15:50:08,425 INFO: Sending echo request to 192.168.0.13
2023-08-08 15:50:08,427 INFO: Received echo reply from 192.168.0.13
**node_b sys log**
.. code-block::
2023-08-08 15:50:08,357 INFO: Connected NIC 98:ad:eb:7c:dc:cb/192.168.0.11
2023-08-08 15:50:08,357 INFO: Turned on
2023-08-08 15:50:08,357 INFO: NIC 98:ad:eb:7c:dc:cb/192.168.0.11 enabled
2023-08-08 15:50:08,410 INFO: Received ARP request for 192.168.0.13 from 80:af:f2:f6:58:b7/192.168.0.10
2023-08-08 15:50:08,410 INFO: Ignoring ARP request for 192.168.0.13
**node_c sys log**
.. code-block::
2023-08-08 15:50:08,358 INFO: Connected NIC bc:72:82:5d:82:a4/192.168.0.12
2023-08-08 15:50:08,358 INFO: Turned on
2023-08-08 15:50:08,358 INFO: NIC bc:72:82:5d:82:a4/192.168.0.12 enabled
2023-08-08 15:50:08,411 INFO: Received ARP request for 192.168.0.13 from 80:af:f2:f6:58:b7/192.168.0.10
2023-08-08 15:50:08,411 INFO: Ignoring ARP request for 192.168.0.13
**node_d sys log**
.. code-block::
2023-08-08 15:50:08,359 INFO: Connected NIC 84:20:7c:ec:a5:c6/192.168.0.13
2023-08-08 15:50:08,360 INFO: Turned on
2023-08-08 15:50:08,360 INFO: NIC 84:20:7c:ec:a5:c6/192.168.0.13 enabled
2023-08-08 15:50:08,412 INFO: Received ARP request for 192.168.0.13 from 80:af:f2:f6:58:b7/192.168.0.10
2023-08-08 15:50:08,412 INFO: Adding ARP cache entry for 80:af:f2:f6:58:b7/192.168.0.10 via NIC 84:20:7c:ec:a5:c6/192.168.0.13
2023-08-08 15:50:08,412 INFO: Sending ARP reply from 84:20:7c:ec:a5:c6/192.168.0.13 to 192.168.0.10/80:af:f2:f6:58:b7
2023-08-08 15:50:08,416 INFO: Received echo request from 192.168.0.10
2023-08-08 15:50:08,417 INFO: Sending echo reply to 192.168.0.10
2023-08-08 15:50:08,420 INFO: Received echo request from 192.168.0.10
2023-08-08 15:50:08,420 INFO: Sending echo reply to 192.168.0.10
2023-08-08 15:50:08,423 INFO: Received echo request from 192.168.0.10
2023-08-08 15:50:08,423 INFO: Sending echo reply to 192.168.0.10
2023-08-08 15:50:08,426 INFO: Received echo request from 192.168.0.10
2023-08-08 15:50:08,426 INFO: Sending echo reply to 192.168.0.10
**switch_1 sys log**
.. code-block::
2023-08-08 15:50:08,373 INFO: Turned on
2023-08-08 15:50:08,378 INFO: SwitchPort 9d:ac:59:a0:05:13 enabled
2023-08-08 15:50:08,380 INFO: SwitchPort 45:f5:8e:b6:f5:d3 enabled
2023-08-08 15:50:08,384 INFO: SwitchPort 91:d5:83:a0:02:f2 enabled
2023-08-08 15:50:08,409 INFO: Added MAC table entry: Port 1 -> 80:af:f2:f6:58:b7
2023-08-08 15:50:08,413 INFO: Added MAC table entry: Port 6 -> 84:20:7c:ec:a5:c6
**switch_2 sys log**
.. code-block::
2023-08-08 15:50:08,374 INFO: Turned on
2023-08-08 15:50:08,381 INFO: SwitchPort aa:58:fa:66:d7:be enabled
2023-08-08 15:50:08,383 INFO: SwitchPort 72:d2:1e:88:e9:45 enabled
2023-08-08 15:50:08,384 INFO: SwitchPort 96:77:39:d1:de:44 enabled
2023-08-08 15:50:08,411 INFO: Added MAC table entry: Port 6 -> 80:af:f2:f6:58:b7
2023-08-08 15:50:08,412 INFO: Added MAC table entry: Port 2 -> 84:20:7c:ec:a5:c6
The Node class is the most crucial component defined in base.py, serving as the parent class for all nodes within a
PrimAITE network simulation.
It encapsulates the following key attributes and behaviors:
- ``hostname`` - The node's hostname on the network.
- ``network_interfaces`` - Dict of NetworkInterface objects attached to the node.
- ``operating_state`` - The hardware state (on/off) of the node.
- ``sys_log`` - System log to record node events.
- ``session_manager`` - Manages user sessions on the node.
- ``software_manager`` - Manages software and services installed on the node.
- ``connect_nic()`` - Connects a NetworkInterface to the node.
- ``disconnect_nic()`` - Disconnects a NetworkInterface from the node.
- ``receive_frame()`` - Receive and process an incoming network frame.
- ``apply_timestep()`` - Progresses node state for a simulation timestep.
- ``power_on()`` - Powers on the node and enables NICs.
- ``power_off()`` - Powers off the node and disables NICs.
The Node class handles installation of system software, network connectivity, frame processing, system logging, and
power states. It establishes baseline functionality while allowing subclassing to model specific node types like hosts,
routers, firewalls etc. The flexible architecture enables composing complex network topologies.

8
docs/source/simulation_components/network/network.rst
View File

@@ -66,9 +66,9 @@ we'll use the following Network that has a client, server, two switches, and a r
.. code-block:: python
network.connect(endpoint_a=router_1.ethernet_ports[1], endpoint_b=switch_1.switch_ports[6])
network.connect(endpoint_a=router_1.network_interfaces[1], endpoint_b=switch_1.network_interface[6])
router_1.enable_port(1)
network.connect(endpoint_a=router_1.ethernet_ports[2], endpoint_b=switch_2.switch_ports[6])
network.connect(endpoint_a=router_1.network_interfaces[2], endpoint_b=switch_2.network_interface[6])
router_1.enable_port(2)
6. Create the Client and Server nodes.
@@ -94,8 +94,8 @@ we'll use the following Network that has a client, server, two switches, and a r
.. code-block:: python
network.connect(endpoint_a=switch_2.switch_ports[1], endpoint_b=client_1.ethernet_port[1])
network.connect(endpoint_a=switch_1.switch_ports[1], endpoint_b=server_1.ethernet_port[1])
network.connect(endpoint_a=switch_2.network_interface[1], endpoint_b=client_1.network_interface[1])
network.connect(endpoint_a=switch_1.network_interface[1], endpoint_b=server_1.network_interface[1])
8. Add ACL rules on the Router to allow ARP and ICMP traffic.

118
docs/source/simulation_components/network/network_interfaces.rst Normal file
View File

@@ -0,0 +1,118 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
#################################
Network Interface Hierarchy Model
#################################
The network interface hierarchy model is designed to represent the various types of network interfaces and their
functionalities within a networking system. This model is organised into five distinct layers, each serving a specific
purpose in the abstraction, implementation, and utilisation of network interfaces. This hierarchical structure
facilitates modular development, enhances maintainability, and supports scalability by clearly separating concerns and
allowing for focused enhancements within each layer.
.. image:: primaite_network_interface_model.png
Layer Descriptions
==================
#. **Base Layer**
* **Purpose:** Serves as the foundation of the hierarchy, defining the most abstract properties and behaviours common
to all network interfaces.
* **Content:** Contains the NetworkInterface class, which abstracts basic functionalities such as enabling/disabling
the interface, sending, and receiving frames.
* **Significance:** Ensures that core functionalities are universally available across all types of network
interfaces, promoting code reuse and consistency.
#. **Connection Type Layer**
* **Purpose:** Differentiates network interfaces based on their physical connection type: wired or wireless.
* **Content:** Includes ``WiredNetworkInterface`` and ``WirelessNetworkInterface`` classes, each tailoring the base
functionalities to specific mediums.
* **Significance:** Allows the development of medium-specific features (e.g., handling point-to-point links in
wired devices) while maintaining a clear separation from IP-related functionalities.
#. **IP Layer**
* **Purpose:** Introduces Internet Protocol (IP) capabilities to network interfaces, enabling IP-based networking.
* **Content:** Includes ``IPWiredNetworkInterface`` and ``IPWirelessNetworkInterface`` classes, extending connection
type-specific classes with IP functionalities.
* **Significance:** Facilitates the implementation of IP address assignment, subnetting, and other Layer 3
networking features, crucial for modern networking applications.
#. **Interface Layer**
* **Purpose:** Defines concrete implementations of network interfaces for specific devices or roles within a network.
* **Content:** Includes ``NIC``, ``RouterInterface``, ``SwitchPort``, ``WirelessNIC``, and ``WirelessAccessPoint``
classes, each designed for a particular networking function or device.
* **Significance:** This layer allows developers to directly utilise or extend pre-built interfaces tailored to
specific networking tasks, enhancing development efficiency and clarity.
#. **Device Layer**
* **Purpose:** Maps the concrete interface implementations to their respective devices within a network,
illustrating practical usage scenarios.
* **Content:** Conceptually groups devices such as ``Computer``, ``Server``, ``Switch``, ``Router``, and ``Firewall``
with the interfaces they utilise (e.g., ``Computer`` might use ``NIC`` or ``WirelessNIC``).
* **Significance:** Provides a clear understanding of how various network interfaces are applied in real-world
devices, aiding in system design and architecture planning.
Network Interface Classes
=========================
**NetworkInterface (Base Layer)**
Abstract base class defining core interface properties like MAC address, speed, MTU.
Requires subclasses implement key methods like send/receive frames, enable/disable interface.
Establishes universal network interface capabilities.
**WiredNetworkInterface (Connection Type Layer)**
- Extends NetworkInterface for wired connection interfaces.
- Adds notions of physical/logical connectivity and link management.
- Mandates subclasses implement wired-specific methods.
**WirelessNetworkInterface (Connection Type Layer)**
- Extends NetworkInterface for wireless interfaces.
- Encapsulates wireless-specific behaviours like signal strength handling.
- Requires wireless-specific methods in subclasses.
**Layer3Interface (IP Layer)**
- Introduces IP addressing abilities with ip_address and subnet_mask.
- Validates address configuration.
- Enables participation in IP networking.
**IPWiredNetworkInterface (IP Layer)**
- Merges Layer3Interface and WiredNetworkInterface.
- Defines wired interfaces with IP capabilities.
- Meant to be extended, doesn't implement methods.
**IPWirelessNetworkInterface (IP Layer)**
- Combines Layer3Interface and WirelessNetworkInterface.
- Represents wireless interfaces with IP capabilities.
- Intended to be extended and specialised.
**NIC (Interface Layer)**
- Concrete wired NIC implementation combining IPWiredNetworkInterface and Layer3Interface.
- Provides network connectivity for host nodes.
- Manages MAC and IP addressing, frame processing.
**WirelessNIC (Interface Layer)**
- Concrete wireless NIC implementation combining IPWirelessNetworkInterface and Layer3Interface.
- Delivers wireless connectivity with IP for hosts.
- Handles wireless transmission/reception.
**WirelessAccessPoint (Interface Layer)**
- Concrete wireless access point implementation using IPWirelessNetworkInterface and Layer3Interface.
- Bridges wireless and wired networks.
- Manages wireless network.

47
docs/source/simulation_components/network/nodes/host_node.rst Normal file
View File

@@ -0,0 +1,47 @@
#########
Host Node
#########
The ``host_node.py`` module is a core component of the PrimAITE project, aimed at simulating network host. It
encapsulates the functionality necessary for modelling the behaviour, communication capabilities, and interactions of
hosts in a networked environment.
HostNode Class
==============
The ``HostNode`` class acts as a foundational representation of a networked device or computer, capable of both
initiating and responding to network communications.
**Attributes:**
- Manages IP addressing with support for IPv4.
- Employs ``NIC`` or ``WirelessNIC`` (subclasses of``IPWiredNetworkInterface``) to simulate wired network connections.
- Integrates with ``SysLog`` for logging operational events, aiding in debugging and monitoring the host node's
behaviour.
**Key Methods:**
- Facilitates the sending and receiving of ``Frame`` objects to simulate data link layer communications.
- Manages a variety of network services and applications, enhancing the simulation's realism and functionality.
Default Services and Applications
=================================
Both the ``HostNode`` and its subclasses come equipped with a suite of default services and applications critical for
fundamental network operations:
1. **ARP (Address Resolution Protocol):** The ``HostARP`` subclass enhances ARP functionality for host-specific
operations.
2. **DNS (Domain Name System) Client:** Facilitates domain name resolution to IP addresses, enabling web navigation.
3. **FTP (File Transfer Protocol) Client:** Supports file transfers across the network.
4. **ICMP (Internet Control Message Protocol):** Utilised for network diagnostics and control, such as executing ping
requests.
5. **NTP (Network Time Protocol) Client:** Synchronises the host's clock with network time servers.
6. **Web Browser:** A simulated application that allows the host to request and display web content.

41
docs/source/simulation_components/network/nodes/network_node.rst Normal file
View File

@@ -0,0 +1,41 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
############
Network Node
############
The ``network_node.py`` module within the PrimAITE project is pivotal for simulating network nodes like routers and
switches, which are integral to network traffic management. This module establishes the framework for these devices,
enabling them to receive and process network frames effectively.
Overview
========
The module defines the ``NetworkNode`` class, an abstract base class that outlines essential behaviours for network
devices tasked with handling network traffic. It is designed to be extended by more specific device simulations that
implement these foundational capabilities.
NetworkNode Class
=================
The ``NetworkNode`` class is at the heart of the module, providing an interface for network devices that participate
in the transmission and routing of data within the simulated environment.
**Key Features:**
- **Frame Processing:** Central to the class is the ability to receive and process network frames, facilitating the
simulation of data flow through network devices.
- **Abstract Methods:** Includes abstract methods such as ``receive_frame``, which subclasses must implement to specify
how devices handle incoming traffic.
- **Extensibility:** Designed for extension, allowing for the creation of specific device simulations, such as router
and switch classes, that embody unique behaviours and functionalities.
The ``network_node.py`` module's abstract approach to defining network devices allows the PrimAITE project to simulate
a wide range of network behaviours and scenarios comprehensively. By providing a common framework for all network
nodes, it facilitates the development of a modular and scalable simulation environment.

41
docs/source/simulation_components/network/nodes/router.rst Normal file
View File

@@ -0,0 +1,41 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
######
Router
######
The ``router.py`` module is a pivotal component of the PrimAITE, designed to simulate the complex functionalities of a
router within a network simulation. Routers are essential for directing traffic between different network segments,
and this module provides the tools necessary to model these devices' behaviour and capabilities accurately.
Router Class
------------
The ``Router`` class embodies the core functionalities of a network router, extending the ``NetworkNode`` class to
incorporate routing-specific behaviours.
**Key Features:**
- **IP Routing:** Supports dynamic handling of IP packets, including forwarding based on destination IP addresses and
subnetting.
- **Routing Table:** Maintains a routing table to determine the best path for forwarding packets.
- **Protocol Support:** Implements support for key networking protocols, including ARP for address resolution and ICMP
for diagnostic messages.
- **Interface Management:** Manages multiple ``RouterInterface`` instances, enabling connections to different network
segments.
- **Network Interface Configuration:** Tools for configuring router interfaces, including setting IP addresses, subnet
masks, and enabling/disabling interfaces.
- **Logging and Monitoring:** Integrates with ``SysLog`` for logging operational events, aiding in debugging and
monitoring router behaviour.
**Operations:**
- **Packet Forwarding:** Utilises the routing table to forward packets to their correct destination across
interconnected networks.
- **ARP Handling:** Responds to ARP requests for any IP addresses configured on its interfaces, facilitating
communication within local networks.
- **ICMP Processing:** Generates and processes ICMP packets, such as echo requests and replies, for network diagnostics.
The ``router.py`` module offers a comprehensive simulation of router functionalities. By providing detailed modelling of router operations, including packet forwarding, interface management, and protocol handling, PrimAITE enables the exploration of advanced network topologies and routing scenarios.

29
docs/source/simulation_components/network/nodes/switch.rst Normal file
View File

@@ -0,0 +1,29 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
######
Switch
######
The ``switch.py`` module is a crucial component of the PrimAITE, aimed at simulating network switches within a network simulation environment. Network switches play a vital role in managing data flow within local area networks (LANs) by forwarding frames based on MAC addresses. This module provides a comprehensive framework for modelling switch operations and behaviours.
Switch Class Overview
---------------------
The module introduces the concept of switch ports through the ``SwitchPort`` class, which extends the functionality of ``WiredNetworkInterface`` to simulate the operation of switch ports in a network.
**Key Features:**
- **Data Link Layer Operation:** Operates at the data link layer (Layer 2) of the OSI model, handling the reception and forwarding of frames based on MAC addresses.
- **Port Management:** Tools for configuring switch ports, including enabling/disabling ports, setting port speeds, and managing port security features.
- **Logging and Monitoring:** Integrates with ``SysLog`` for logging operational events, aiding in debugging and
monitoring switch behaviour.
Functionality and Implementation
---------------------------------
- **MAC Address Learning:** Dynamically learns and associates MAC addresses with switch ports, enabling intelligent frame forwarding.
- **Frame Forwarding:** Utilises the learned MAC address table to forward frames only to the specific port associated with the destination MAC address, minimising unnecessary network traffic.
The ``switch.py`` module offers a realistic and configurable representation of switch operations. By detailing the functionalities of the ``SwitchPort`` class, the module lays the foundation for simulating complex network topologies.

BIN
docs/source/simulation_components/network/primaite_network_interface_model.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

73
docs/source/simulation_components/network/router.rst
View File

@@ -1,73 +0,0 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
.. _router:
Router Module
=============
The router module contains classes for simulating the functions of a network router.
Router
------
The Router class represents a multi-port network router that can receive, process, and route network packets between its ports and other Nodes
The router maintains internal state including:
- RouteTable - Routing table to lookup where to forward packets.
- AccessControlList - Access control rules to block or allow packets.
- ARP cache - MAC address lookups for connected devices.
- ICMP handler - Handles ICMP requests to router interfaces.
The router receives incoming frames on enabled ports. It processes the frame headers and applies the following logic:
1. Checks the AccessControlList if the packet is permitted. If blocked, it is dropped.
2. For permitted packets, routes the frame based on:
- ARP cache lookups for destination MAC address.
- ICMP echo requests handled directly.
- RouteTable lookup to forward packet out other ports.
3. Updates ARP cache as it learns new information about the Network.
RouteTable
----------
The RouteTable holds RouteEntry objects representing routes. It finds the best route for a destination IP using a metric and the longest prefix match algorithm.
Routes can be added and looked up based on destination IP address. The RouteTable is used by the Router when forwarding packets between other Nodes.
AccessControlList
-----------------
The AccessControlList defines Access Control Rules to block or allow packets. Packets are checked against the rules to determine if they are permitted to be forwarded.
Rules can be added to deny or permit traffic based on IP, port, and protocol. The ACL is checked by the Router when packets are received.
Packet Processing
-----------------
-The Router supports the following protocols and packet types:
ARP
^^^
- Handles both ARP requests and responses.
- Updates ARP cache.
- Proxies ARP replies for connected networks.
- Routes ARP requests.
ICMP
^^^^
- Responds to ICMP echo requests to Router interfaces.
- Routes other ICMP messages based on routes.
TCP/UDP
^^^^^^^
- Forwards packets based on routes like IP.
- Applies ACL rules based on protocol, source/destination IP address, and source/destination port numbers.
- Decrements TTL and drops expired TTL packets.

2
docs/source/simulation_components/system/data_manipulation_bot.rst
View File

@@ -52,7 +52,7 @@ Example
default_gateway="192.168.10.1"
operating_state=NodeOperatingState.ON # initialise the computer in an ON state
)
network.connect(endpoint_b=client_1.ethernet_port[1], endpoint_a=switch_2.switch_ports[1])
network.connect(endpoint_b=client_1.network_interface[1], endpoint_a=switch_2.network_interface[1])
client_1.software_manager.install(DataManipulationBot)
data_manipulation_bot: DataManipulationBot = client_1.software_manager.software.get("DataManipulationBot")
data_manipulation_bot.configure(server_ip_address=IPv4Address("192.168.1.14"), payload="DELETE")

2
docs/source/simulation_components/system/ftp_client_server.rst
View File

@@ -98,7 +98,7 @@ Example peer to peer network
subnet_mask="255.255.255.0",
operating_state=NodeOperatingState.ON # initialise the server in an ON state
)
net.connect(pc1.ethernet_port[1], srv.ethernet_port[1])
net.connect(pc1.network_interface[1], srv.network_interface[1])
Install the FTP Server
^^^^^^^^^^^^^^^^^^^^^^

BIN
docs/source/simulation_components/system/node_session_software_model_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

51
docs/source/simulation_components/system/pcap.rst Normal file
View File

@@ -0,0 +1,51 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
PCAP
====
The ``packet_capture.py`` module introduces a Packet Capture (PCAP) service within PrimAITE, designed to simulate
packet capturing functionalities for the simulated network environment. This service enables the logging of network
frames as JSON strings, providing valuable insights into the data flowing across the network.
Overview
--------
Packet capture is a crucial tool in network analysis, troubleshooting, and monitoring, allowing for the examination of
packets traversing the network. Within the context of the PrimAITE simulation, the PCAP service enhances the realism
and depth of network simulations by offering detailed visibility into network communications. Notably, PCAP is created
by default at the NetworkInterface level.
PacketCapture Class
-------------------
The ``PacketCapture`` class represents the core of the PCAP service, facilitating the capture and logging of network
frames for analysis.
**Features:**
- **Automatic Creation:** PCAP is automatically created at the NetworkInterface level, simplifying setup and integration.
- **Inbound and Outbound Frame Capture:** Frames can be captured and logged separately for inbound and outbound
traffic, offering granular insight into network communications.
- **Logging Format:** Captures and logs frames as JSON strings, ensuring that the data is structured and easily
interpretable.
- **File Location:** PCAP logs are saved to a specified directory within the simulation output, organised by hostname
and IP address to facilitate easy retrieval and analysis.
Usage
-----
The PCAP service is seamlessly integrated within the simulation, automatically capturing and logging frames for both
inbound and outbound traffic at the NetworkInterface level. This automatic functionality, combined with the ability
to separate traffic directions, significantly enhances network analysis and troubleshooting capabilities.
This service is particularly useful for:
- **Network Analysis:** Detailed examination of packet flows and protocols within the simulated environment.
- **Troubleshooting:** Identifying and resolving network issues by analysing packet transmissions and errors.
- **Educational Purposes:** Teaching network principles and diagnostics through hands-on packet analysis.
The introduction of the ``packet_capture.py`` module significantly enhances the network simulation capabilities of
PrimAITE. By providing a robust tool for packet capture and analysis, PrimAITE allows users to gain deeper insights
into network operations, supporting a wide range of educational, developmental, and research activities.

90
docs/source/simulation_components/system/session_and_software_manager.rst Normal file
View File

@@ -0,0 +1,90 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
Session and Software Manager
============================
The Software Manager and Session Manager are core components of the Node in PrimAITE. These managers orchestrate the
flow of network frames through the Node, ensuring that frames are processed accurately and passed to the relevant
services or applications.
The following flow diagram illustrates the journey of a network frame as it navigates through various components within
the node. Starting from the network interface, the frame progresses to the node, then to the session manager, and
subsequently to the software manager. From there, it may be directed to one of three potential software destinations:
ARP, ICMP, or the Web Client. This pathway exemplifies the structured processing sequence designed to ensure that
each frame reaches its intended target within the simulated environment.
.. image:: node_session_software_model_example.png
Session Manager
---------------
The `SessionManager` acts as the intermediary between the Node's hardware-level interactions and higher-level software
processes. It receives frames from the Node and determines the appropriate session or connection context for further
processing.
**Key Responsibilities:**
- **Frame Handling:** Receives network frames and identifies the session context based on headers and session state.
- **Protocol Management:** Supports various protocols (e.g., ARP, ICMP) by interpreting protocol-specific information
within frames and facilitating their processing.
- **Session Tracking:** Maintains a record of active sessions and manages their lifecycle, including creation,
maintenance, and termination.
**Implementation Overview:**
- Utilises IP and transport layer information to route frames to the correct session.
- Integrates closely with the `SoftwareManager` to ensure seamless transmission of session-specific data to the
application layer.
Software Manager
----------------
The `SoftwareManager` is responsible for the final step in the frame processing pipeline, handling the delivery of
network frames to the appropriate software services or applications within the Node.
**Key Responsibilities:**
- **Application Routing:** Determines the target application or service for incoming frames based on protocol and port
information.
- **Software Management:** Oversees the registration, installation, and management of software services and
applications, facilitating communication between network layers and application processes.
- **Frame Dispatching:** Directs frames to their designated applications or services, enabling the processing of
network communications at the application layer.
- **Installation and Uninstallation:** Responsible for the installing and uninstalling of services and applications,
managing the availability of software resources on the Node.
**Implementation Overview:**
- Maintains a registry of services and applications, keyed by protocol and port numbers, to efficiently route network
traffic.
- Interacts with the `FileSystem` and other core components to manage application state and data persistence,
supporting complex software interactions within the simulated environment.
Integration and Workflow
------------------------
1. **Initial Port Check:** Upon receiving a network frame at the hardware level, the Node first checks if the
destination port and protocol match any software currently running, as managed by the `SoftwareManager`. This step
determines if the port is open and if the frame's destination is actively listening for incoming traffic on the Node.
2. **Frame Acceptance:** If the frame's destination port and protocol are open on the Node, indicating that there is
software prepared to handle such traffic, the Node accepts the frame. This verification ensures that only relevant
traffic is processed further, enhancing network security and efficiency.
3. **Session Manager Processing:** Accepted frames are then passed to the `SessionManager`, which analyses the frames
within the context of existing sessions or connections. The Session Manager performs protocol-specific handling,
routing the frames based on session state and protocol requirements.
4. **Software Manager Dispatch:** After session processing, frames are dispatched to the `SoftwareManager`, which
routes them to the appropriate services or applications. The Software Manager identifies the target based on the
frame's destination port and protocol, aligning with the initial port check.
5. **Application Processing:** The relevant applications or services process the received frames, completing the
communication pathway within the Node. This step involves the actual handling of frame data by the intended software,
facilitating the intended network operations or communications.
Together, the Software Manager and Session Manager form a critical part of the Node's architecture in the PrimAITE,
facilitating a structured and efficient processing pipeline for network frames. This architecture enables the
simulation of realistic network environments, where frames are accurately routed and processed, mirroring the
complexities of real-world network communications. The addition of installation and uninstallation capabilities by
the Software Manager further enhances the Node's functionality, allowing for dynamic software management within the
simulated network.

51
docs/source/simulation_components/system/sys_log.rst Normal file
View File

@@ -0,0 +1,51 @@
.. only:: comment
© Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
SysLog
======
The ``sys_log.py`` module introduces a system logging (SysLog) service within PrimAITE, designed to facilitate the
management and recording of system logs for nodes in the simulated network environment. This essential service tracks
system events, assists in debugging, and aids network analysis by providing a structured and accessible log of
activities.
Overview
--------
System logging is vital in network management and diagnostics, offering a timestamped record of events within network
devices. In the PrimAITE simulation context, the SysLog service automatically enables logging at the node level,
enhancing the simulation's analysis and troubleshooting capabilities without manual configuration.
SysLog Class
------------
**Features:**
- **Automatic Activation:** SysLog is enabled by default at the node level, ensuring comprehensive activity logging
with no additional setup.
- **Log Levels:** Supports various logging levels, including debug, info, error, etc., allowing for detailed
categorisation and severity indication of log messages.
- **Terminal Output:** Logs can be printed to the terminal by setting `to_terminal=True`, offering real-time monitoring
and debugging capabilities.
- **Logging Format:** Records system logs in standard text format for enhanced readability and interpretability.
- **File Location:** Systematically saves logs to a designated directory within the simulation output, organised by
hostname, facilitating log management and retrieval.
Usage
-----
SysLog service is seamlessly integrated into the simulation, with automatic activation for each node and support for
various logging levels. The addition of terminal output capabilities further enhances the utility of SysLog for
real-time event monitoring and troubleshooting.
This service is invaluable for:
- **Event Tracking:** Documents key system events, configuration changes, and operational status updates.
- **Debugging:** Aids in identifying and resolving simulated network issues by providing a comprehensive event history.
- **Network Analysis:** Offers insights into network node behaviour and interactions.
The ``sys_log.py`` module significantly enhances PrimAITE's network simulation capabilities. Providing a robust system
logging tool, automatically enabled at the node level and featuring various log levels and terminal output options,
PrimAITE enables users to conduct in-depth network simulations.

2
docs/source/simulation_components/system/web_browser_and_web_server_service.rst
View File

@@ -84,7 +84,7 @@ Example peer to peer network
srv = Server(hostname="srv", ip_address="192.168.1.10", subnet_mask="255.255.255.0")
pc1.power_on()
srv.power_on()
net.connect(pc1.ethernet_port[1], srv.ethernet_port[1])
net.connect(pc1.network_interface[1], srv.network_interface[1])
Install the Web Server
^^^^^^^^^^^^^^^^^^^^^^

9
src/primaite/simulator/network/hardware/network_interface/wireless/wireless_access_point.py
View File

@@ -1,11 +1,14 @@
from typing import Dict
from primaite.simulator.network.hardware.base import WirelessNetworkInterface
from primaite.simulator.network.hardware.network_interface.layer_3_interface import Layer3Interface
from primaite.simulator.network.hardware.base import (
IPWirelessNetworkInterface,
Layer3Interface,
WirelessNetworkInterface,
)
from primaite.simulator.network.transmission.data_link_layer import Frame
class WirelessAccessPoint(WirelessNetworkInterface, Layer3Interface):
class WirelessAccessPoint(IPWirelessNetworkInterface):
"""
Represents a Wireless Access Point (AP) in a network.

9
src/primaite/simulator/network/hardware/network_interface/wireless/wireless_nic.py
View File

@@ -1,11 +1,14 @@
from typing import Dict
from primaite.simulator.network.hardware.base import WirelessNetworkInterface
from primaite.simulator.network.hardware.network_interface.layer_3_interface import Layer3Interface
from primaite.simulator.network.hardware.base import (
IPWirelessNetworkInterface,
Layer3Interface,
WirelessNetworkInterface,
)
from primaite.simulator.network.transmission.data_link_layer import Frame
class WirelessNIC(WirelessNetworkInterface, Layer3Interface):
class WirelessNIC(IPWirelessNetworkInterface):
"""
Represents a Wireless Network Interface Card (Wireless NIC) in a network device.

41
src/primaite/simulator/network/hardware/nodes/network/router.py
View File

@@ -810,47 +810,6 @@ class RouterICMP(ICMP):
return True
class RouterNIC(IPWiredNetworkInterface):
"""
A Router-specific Network Interface Card (NIC) that extends the standard NIC functionality.
This class overrides the standard Node NIC's Layer 3 (L3) broadcast/unicast checks. It is designed
to handle network frames in a manner specific to routers, allowing them to efficiently process
and route network traffic.
"""
def receive_frame(self, frame: Frame) -> bool:
"""
Receive and process a network frame from the connected link, provided the NIC is enabled.
This method is tailored for router behavior. It decrements the frame's Time To Live (TTL), checks for TTL
expiration, and captures the frame using PCAP (Packet Capture). The frame is accepted if it is destined for
this NIC's MAC address or is a broadcast frame.
Key Differences from Standard NIC:
- Does not perform Layer 3 (IP-based) broadcast checks.
- Only checks for Layer 2 (Ethernet) destination MAC address and broadcast frames.
:param frame: The network frame being received. This should be an instance of the Frame class.
:return: Returns True if the frame is processed and passed to the connected node, False otherwise.
"""
if self.enabled:
frame.decrement_ttl()
if frame.ip and frame.ip.ttl < 1:
self._connected_node.sys_log.info("Frame discarded as TTL limit reached")
return False
frame.set_received_timestamp()
self.pcap.capture_inbound(frame)
# If this destination or is broadcast
if frame.ethernet.dst_mac_addr == self.mac_address or frame.ethernet.dst_mac_addr == "ff:ff:ff:ff:ff:ff":
self._connected_node.receive_frame(frame=frame, from_network_interface=self)
return True
return False
def __str__(self) -> str:
return f"{self.mac_address}/{self.ip_address}"
class RouterInterface(IPWiredNetworkInterface):
"""
Represents a Router Interface.