whad-lab 0.1.0__tar.gz

whad_lab-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: whad-lab
+Version: 0.1.0
+Summary: WHAD Lab environment for hands-on exercises (Experimental)
+Author-email: Damien Cauquil <virtualabs@gmail.com>
+License-Expression: MIT
+Keywords: whad,lab,hands-on,exercise,learn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=13
+Requires-Dist: pyyaml>=6
+Requires-Dist: whad>=1.2
+Requires-Dist: scapy>=2.5

whad_lab-0.1.0/README.rst

@@ -0,0 +1,4 @@
+WHAD Lab Environment
+====================
+
+This project is EXPERIMENTAL and not ready for production.

whad_lab-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+
+[project]
+name = "whad-lab"
+version = "0.1.0"
+description = "WHAD Lab environment for hands-on exercises (Experimental)"
+requires-python = ">=3.10"
+dependencies = [
+    "websockets>=13",
+    "pyyaml>=6",
+    "whad>=1.2",
+    "scapy>=2.5",
+]
+readme = "README.md"
+license = "MIT"
+keywords = ["whad", "lab", "hands-on", "exercise", "learn"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+]
+authors = [
+    {name = "Damien Cauquil", email = "virtualabs@gmail.com"},
+]
+
+[project.scripts]
+wlab = "wlab.server:cli"
+
+[tool.setuptools.package-data]
+wlab = ['assets/*', 'static/*', 'exercises/*', 'exercises/ble_tracker/*']

whad_lab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

whad_lab-0.1.0/whad_lab.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: whad-lab
+Version: 0.1.0
+Summary: WHAD Lab environment for hands-on exercises (Experimental)
+Author-email: Damien Cauquil <virtualabs@gmail.com>
+License-Expression: MIT
+Keywords: whad,lab,hands-on,exercise,learn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=13
+Requires-Dist: pyyaml>=6
+Requires-Dist: whad>=1.2
+Requires-Dist: scapy>=2.5

whad_lab-0.1.0/whad_lab.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.rst
+pyproject.toml
+whad_lab.egg-info/PKG-INFO
+whad_lab.egg-info/SOURCES.txt
+whad_lab.egg-info/dependency_links.txt
+whad_lab.egg-info/entry_points.txt
+whad_lab.egg-info/requires.txt
+whad_lab.egg-info/top_level.txt
+wlab/arena.py
+wlab/progress.py
+wlab/server.py
+wlab/tracker_v2.py
+wlab/assets/tracker-profile.json
+wlab/assets/tracker.png
+wlab/exercises/ble_tracker/device.py
+wlab/exercises/ble_tracker/lab.yaml
+wlab/static/index.html
+wlab/static/landing.html
+wlab/static/marked.min.js

whad_lab-0.1.0/whad_lab.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

whad_lab-0.1.0/whad_lab.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wlab = wlab.server:cli

whad_lab-0.1.0/whad_lab.egg-info/requires.txt

@@ -0,0 +1,4 @@
+websockets>=13
+pyyaml>=6
+whad>=1.2
+scapy>=2.5

whad_lab-0.1.0/whad_lab.egg-info/top_level.txt

@@ -0,0 +1 @@
+wlab

whad_lab-0.1.0/wlab/arena.py

@@ -0,0 +1,381 @@
+"""
+WHAD wireless arena
+
+This arena can host multiple nodes and ensures communication between them
+as it would be the case in a real wireless environment. The implementation
+of nodes and the messages they exchange is entirely flexible and can be
+defined to fit any scenario.
+
+Combined with a custom control node and a specific PHY layer, it is possible
+to equip any node with a protocol stack and make it interact with a control
+node, a specific node acting as an interface between the arena and its nodes
+and the outside world.
+"""
+from threading import Thread
+from typing import Optional, Any, Union, Generator, Tuple, List
+from queue import Queue, Empty
+from scapy.packet import Packet
+
+class NodeMessage:
+    """Root class for all node messages.
+
+    This class shall be used to define any message designed to be exchanged
+    between nodes in a wireless arena.
+    """
+
+    def __init__(self, from_id: str, to_id: Optional[str] = None):
+        """Initialization of a node message.
+
+        This message keeps track of the originating node and optionally of
+        its destination node.
+
+        :param from_id: Identifier of the origin node
+        :type  from_id: str
+        :param to_id: Identifier of the destination node
+        :type  to_id: str, optional
+        """
+        self.__origin = from_id
+        self.__dest = to_id
+
+    @property
+    def origin(self) -> str:
+        """Originating node's identifier."""
+        return self.__origin
+
+    @property
+    def destination(self) -> Optional[str]:
+        """Destination node's identifier."""
+        return self.__dest
+
+class MetadataMsg(NodeMessage):
+    """This node message class holds a set of metadata in the form
+    of a set of parameters. It provides a very flexible way to store
+    and access metadata.
+    """
+
+    def __init__(self, from_id: str, to_id: str, **parameters):
+        """Initialization.
+
+        :param from_id: Identifier of the origin node
+        :type  from_id: str
+        :param to_id: Identifier of the destination node
+        :type  to_id: str, optional
+        :param **parameters: set of parameters to attach to the message as metadata
+        :type  **parameters: dict
+        """
+        super().__init__(from_id, to_id)
+        self.__parameters = parameters
+
+    @property
+    def parameters(self) -> dict:
+        """Set of parameters as dict.
+
+        :return: Dictionary of parameters (read-only)
+        :rtype: dict
+        """
+        return self.__parameters
+
+    def __getitem__(self, key: str) -> Any:
+        """Parameters read primitives, implementing an array behavior."""
+        if key in self.__parameters:
+            return self.__parameters[key]
+        raise IndexError
+
+class ConnectionMsg(MetadataMsg):
+    """Generic connection request message."""
+
+class ConnectionResultMsg(MetadataMsg):
+    """Generic connection response message."""
+
+class DisconnectionMsg(MetadataMsg):
+    """Generic disconnection request."""
+
+class DisconnectionResultMsg(MetadataMsg):
+    """Generic disconnection response."""
+
+class DataMsg(MetadataMsg):
+    """Generic data (PDU) message."""
+
+    def __init__(self, from_id: str, to_id: str, data: Packet):
+        super().__init__(from_id, to_id, data=data)
+
+    @property
+    def data(self) -> Packet:
+        return self['data']
+
+class Arena:
+    """Wireless arena where devices are placed."""
+
+    def __init__(self):
+        """Initialize wireless arena."""
+        self.__nodes = {}
+
+    def send(self, message: NodeMessage, node_id: Optional[str]) -> bool:
+        """Send message to one or more nodes in the arena.
+
+        :param message: Message to send to other nodes.
+        :type  message: NodeMessage
+        :param node_id: Destination node's identifier (set to `None` to broadcast to other nodes)
+        :type  node_id: str, optional
+        :return: `True` if message was successfully sent, `False` otherwise.
+        :rtype: bool
+        """
+        if node_id is not None:
+            # Add message into the target node's message queue, if found
+            if node_id in self.__nodes:
+                self.__nodes[node_id].add_message(message)
+                return True
+
+            # Could not find node, cannot send.
+            return False
+        else:
+            # Broadcast message to other nodes
+            for node_id, node in self.__nodes.items():
+                if node_id != message.origin:
+                    node.add_message(message)
+            return True
+
+    def find_node(self, node_id: str) -> Optional['Node']:
+        """Find a node in the arena based on its identifier.
+
+        :param node_id: Node's identifier
+        :type  node_id: str
+
+        :return: Corresponding node if found, `None` otherwise.
+        :rtype: Node, optional
+        """
+        if node_id in self.__nodes:
+            return self.__nodes[node_id]
+        return None
+
+    def add_node(self, node: 'Node') -> bool:
+        """Add node into the arena.
+
+        :param node: Node to put inside the arena.
+        :type  node: Node
+        :return: `True` on success, `False` otherwise.
+        :rtype: bool
+        """
+        if node.id not in self.__nodes:
+            self.__nodes[node.id] = node
+            node.enter_arena(self)
+            return True
+        return False
+
+    def remove_node(self, node: Union[str, 'Node']) -> bool:
+        """Remove a node from the arena.
+
+        :param node: Node to remove from the arena.
+        :type  node: Node
+        :type  node: str
+        :return: `True` on success, `False` otherwise.
+        :rtype: bool
+        """
+        if isinstance(node, Node):
+            if node.id in self.__nodes:
+                self.__nodes[node.id].leave_arena()
+                del self.__nodes[node.id]
+                return True
+        elif isinstance(node, str):
+            if node in self.__nodes:
+                self.__nodes[node].leave_arena()
+                del self.__nodes[node]
+                return True
+        return False
+
+    def enable_node(self, node: Union[str, 'Node']) -> bool:
+        """Enable a node present in the arena.
+
+        :param node: Node to enable
+        :type  node: Node
+        :type  node: str
+
+        :return: `True` if node has been enabled, `False` otherwise.
+        :rtype: bool
+        """
+        if isinstance(node, str):
+            n = self.find_node(node)
+        else:
+            n = node
+
+        # Node found, enable.
+        if n is not None:
+            n.enable()
+            return True
+
+        # Failure.
+        return False
+
+    def disable_node(self, node: Union[str, 'Node']) -> bool:
+        """Disable a node present in the arena.
+
+        :param node: Node to enable
+        :type  node: Node
+        :type  node: str
+
+        :return: `True` if node has been disabled, `False` otherwise.
+        :rtype: bool
+        """
+        if isinstance(node, str):
+            n = self.find_node(node)
+        else:
+            n = node
+
+        # Node found, enable.
+        if n is not None:
+            n.disable()
+            return True
+
+        # Failure.
+        return False
+
+
+    def list_all_nodes(self) -> Generator[Tuple[str, 'Node'], None, None]:
+        """Enumerate all nodes (active and inactive)."""
+        yield from self.__nodes.items()
+
+
+    def list_active_nodes(self) -> Generator[Tuple[str, 'Node'], None, None]:
+        """Enumerate only active nodes."""
+        for node_id,node in self.__nodes.items():
+            if node.active:
+                yield (node_id, node)
+
+
+class Node:
+    """Wireless device present in the arena.
+
+    Each device has its own thread to manage its state at its own
+    pace. Communication with a node is done through message queues,
+    as generic WHAD devices do.
+
+    The arena acts as an arbiter for nodes and dispatch messages
+    between nodes.
+    """
+
+    def __init__(self, node_id: str):
+        """Initialize a node with its own identifier. A node is not
+        placed into a specific arena when created.
+
+        :param node_id: Node identifier
+        :type node_id: str
+        """
+        self.__id = node_id
+        self.__arena: Optional[Arena] = None
+        self.__msg_queue = Queue()
+        self.__active = True
+
+    @property
+    def id(self) -> str:
+        """Node identifier"""
+        return self.__id
+
+    @property
+    def arena(self) -> Optional[Arena]:
+        """Current arena."""
+        return self.__arena
+
+    @property
+    def active(self) -> bool:
+        """Node active state"""
+        return self.__active
+
+    def disable(self):
+        """Disable node."""
+        self.__active = False
+
+    def enable(self):
+        """Enable node."""
+        self.__active = True
+
+    def add_message(self, message: NodeMessage):
+        """Add a node message into our queue.
+
+        :param message: Message to add into the node's message queue.
+        :type  message: NodeMessage
+        """
+        self.__msg_queue.put(message)
+
+    def get_message(self, timeout: Optional[float] = None) -> Optional[NodeMessage]:
+        """Retrieve a message from the message queue.
+        This method blocks until a message is available in
+        the queue.
+
+        :param timeout: Timeout in seconds
+        :type timeout: float, optional
+
+        :return: Node message to process if any, `None` otherwise.
+        :rtype: NodeMessage, optional
+        """
+        if timeout is None:
+            return self.__msg_queue.get()
+        else:
+            try:
+                return self.__msg_queue.get(timeout=timeout)
+            except Empty:
+                return None
+
+    def enter_arena(self, arena: Arena):
+        """Set the node's arena.
+
+        :param arena: Arena where the node is placed.
+        :type arena: Arena
+        """
+        self.__arena = arena
+
+    def leave_arena(self):
+        """Clear the node's arena."""
+        self.__arena = None
+
+    def send(self, message: NodeMessage, node_id: Optional[str] = None) -> bool:
+        """Send a packet to a node identified by `node_id`.
+
+        :param message: Message to send to other node(s).
+        :type message: NodeMessage
+        :param node_id: Destination node's identifier
+        :type node_id: str, optional
+
+        :return: `True` if message has been sent, `False` otherwise
+        :rtype: bool
+        """
+        if self.__arena is not None:
+            return self.__arena.send(message, node_id)
+        return False
+
+class DeviceNode(Node, Thread):
+    """This class defines a node that has its own thread. This configuration
+    helps when a node needs to have its own protocol stack, like an emulated
+    device.
+    """
+    def __init__(self, node_id: str):
+        """Initialization.
+
+        :param node_id: Node identifier
+        :type node_id: str
+        """
+        Node.__init__(self, node_id)
+        Thread.__init__(self)
+
+class ControlNode(Node):
+    """This class defines a control node, a node that is driven by a component
+    outside the arena and that interacts with other nodes inside the arena. It
+    acts like a bridge and has access to the whole arena.
+
+    It shares the same communication mechanism all nodes in the arena use, is able
+    to send and receive messages, but has control on other nodes as well.
+    """
+
+    def __init__(self, node_id: str):
+        """Initialize our control node."""
+        super().__init__(node_id)
+
+    def list_all_nodes(self) -> List[Node]:
+        """Return a list of all nodes present in the arena.
+
+        :return: List of all nodes.
+        :rtype: list
+        """
+        if self.arena is not None:
+            return [n[1] for n in list(self.arena.list_all_nodes())]
+        return []
+

whad_lab-0.1.0/wlab/assets/tracker-profile.json

@@ -0,0 +1 @@
+{"services": [{"uuid": "1800", "type_uuid": "2800", "start_handle": 1, "end_handle": 5, "characteristics": [{"handle": 2, "uuid": "2803", "properties": 18, "security": 0, "value": {"handle": 3, "uuid": "2A00", "data": "69544147202020202020202020202020"}, "descriptors": []}, {"handle": 4, "uuid": "2803", "properties": 2, "security": 0, "value": {"handle": 5, "uuid": "2A01", "data": "0000"}, "descriptors": []}]}, {"uuid": "180F", "type_uuid": "2800", "start_handle": 6, "end_handle": 8, "characteristics": [{"handle": 7, "uuid": "2803", "properties": 18, "security": 0, "value": {"handle": 8, "uuid": "2A19", "data": "63"}, "descriptors": []}]}, {"uuid": "1802", "type_uuid": "2800", "start_handle": 9, "end_handle": 11, "characteristics": [{"handle": 10, "uuid": "2803", "properties": 28, "security": 0, "value": {"handle": 11, "uuid": "2A06", "data": ""}, "descriptors": []}]}, {"uuid": "FFE0", "type_uuid": "2800", "start_handle": 12, "end_handle": 14, "characteristics": [{"handle": 13, "uuid": "2803", "properties": 18, "security": 0, "value": {"handle": 14, "uuid": "FFE1", "data": "00"}, "descriptors": []}]}], "devinfo": {"adv_data": "020105020a000319c1030302e0ff", "bd_addr": "ff:ff:30:03:70:72", "addr_type": 0, "scan_rsp": "110969544147202020202020202020202020"}}