Release 1.2.0

Author: claire-lex

README.md

@@ -5,24 +5,14 @@ BOF (Boiboite Opener Framework) is a testing framework for field protocols
 implementations and devices. It is a Python 3.6+ library that provides means to
 send, receive, create, parse and manipulate frames from supported protocols.
 
-The library currently supports **KNXnet/IP**, which is our focus, but it can be
-extended to other types of BMS or industrial network protocols.
-
-There are three ways to use BOF:
-
-* Automated: Use of higher-level interaction functions to discover devices and
-  start basic exchanges, without requiring to know anything about the protocol.
-
-* Standard: Perform more advanced (legitimate) operations. This requires the end
-  user to know how the protocol works (how to establish connections, what kind
-  of messages to send).
-
-* Playful: Modify every single part of exchanged frames and misuse the protocol
-  instead of using it (we fuzz devices with it). The end user should have
-  started digging into the protocol's specifications.
+The library currently provides discovery and extended testing features for
+**KNXnet/IP**, which is our focus, but it can be extended to other types of BMS
+or industrial network protocols. It also provides passive discovery functions
+for industrial networks relying on KNXnet/IP, LLDP and Profinet DCP.
 
 **Please note that targeting industrial systems can have a severe impact on
-buildings and people and that BOF must be used carefully.**
+people, industrial operations and buildings and that BOF must be used
+carefully.**
 
 [![GitHub license](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://github.com/Orange-Cyberdefense/bof/blob/master/LICENSE)
 [![GitHub release](https://img.shields.io/github/release/Orange-Cyberdefense/bof.svg)](https://gitHub.com/Orange-Cyberdefense/bof/releases/)
@@ -55,22 +45,50 @@ Protocol implementations use [Scapy](https://scapy.readthedocs.io/en/latest/)'s
 Getting started
 ---------------
 
-BOF is a Python 3.6+ library that should be imported in scripts.  It has no
-installer yet so you need to refer to the `bof` subdirectory which contains the
-library (inside the repository) in your project or to copy the folder to your
-project's folder. Then, inside your code (or interactively), you can import the
-library:
+BOF is a Python 3.6+ library that should be imported in scripts.
 
 ```python
 import bof
+from bof.layers import profinet, knx
+from bof.layers.knx import KnxPacket
 ```
 
+There are three ways to use BOF, not all of them are available depending on the
+layer:
+
+* **Automated**: Import or call directly higher-level functions from layers. No
+    knowledge about the protocol required.
+
+* **Standard**: Craft packets from layers to interact with remote devices. Basic
+    knowledge about the protocol requred.
+
+* **Playful**: Play with packets, misuse the protocol (we fuzz devices with it).
+  The end user should have started digging into the protocol's specifications.
+
+|              | Automated | Standard | Playful |
+|--------------|-----------|----------|---------|
+| KNX          | X         | X        | X       |
+| LLDP         | X         |          |         |
+| Modbus       |           | X        | X       |
+| Profinet DCP | X         |          |         |
+
+
 Now you can start using BOF!
 
 TL;DR
 -----
 
-### Discover devices on a network
+### Several ways yo discover devices on a network
+
+* Passive discovery from the discovery module:
+
+```python
+from bof.modules.discovery import *
+
+devices = passive_discovery(iface="eth0", verbose=True)
+```
+
+* Device discovery using a layer's high-level function
 
 ```python
 from bof.layers.knx import search
@@ -80,10 +98,15 @@ for device in devices:
     print(device)
 ```
 
-Should output something like:
+* Create and send your own discovery packet:
 
 ```
-Device: "boiboite" @ 192.168.1.242:3671 - KNX address: 15.15.255 - Hardware: 00:00:ff:ff:ff:ff (SN: 0123456789)
+from bof.layers.knx import *
+
+pkt = KNXPacket(type="search request")
+responses = KNXnet.multicast(pkt, (KNX_MULTICAST_ADDR, KNX_PORT))
+for response, _ in responses:
+    print(KNXPacket(response))
 ```
 
 ### Send and receive packets

bof/__init__.py

@@ -1,5 +1,4 @@
-"""
-Introduction
+"""Introduction
 ============
 
 Boiboite Opener Framework / Ouvre-Boiboite Framework contains a set of features
@@ -18,19 +17,29 @@
     new protocol submodule.
 
 :packet:
-    Base classe for specialized BOF packets in layers. Such classes link BOF
+    Base class for specialized BOF packets in layers. Such classes link BOF
     content and usage to protocol implementations in Scapy. In other words,
     they interface BOF's syntax used by the end user with Scapy Packet and
     Field objects used for the packet itself. The base class ``BOFPacket``
     is not supposed to be instantiated directly, but whatever. 
 
+:device:
+    Global object for representing industrial devices. All objects in
+    layers built using data extracted from responses to protocol-specific
+    discovery requests shall inherit ``BOFDevice``.
+
 :layers:
     Protocol implementations to be imported in BOF. Importing ``layers`` gives
-    acces to BOF protocol implementations inheriting from ``BOFPacket``
+    access to BOF protocol implementations inheriting from ``BOFPacket``
     (interface between BOF and Scapy worlds).  The directory
     ``layers/raw_scapy`` may contain protocol implementations in Scapy which
     are not integrated to Scapy's repository (for instance, if you wrote your
     own but did not contribute (yet)).
+
+:modules:
+    Higher level functions gathered around a specific usage that may rely on
+    several protocols (layers).
+
 """
 
 ###############################################################################
@@ -40,4 +49,6 @@
 from .base import *
 from .network import *
 from .packet import *
+from .device import *
 from .layers import *
+from .modules import *

bof/device.py

@@ -0,0 +1,33 @@
+"""Global object for representing industrial devices.
+
+All objects in layers built using data extracted from responses to
+protocol-specific discovery requests shall inherit ``BOFDevice``.
+"""
+class BOFDevice(object):
+    """Interface class for devices, to inherit in layer-specific device classes.
+
+    Device objects are usually built from device description requests in layers.
+    A device has a set of basic information: a name, a description, a MAC
+    address and an IP address. All of them are attributes to this base object,
+    but not all of them may be provided when asking protocols for device
+    descriptions. On the other hand, most of protocol-specific devices will have
+    additional attributes.
+    """
+    protocol:str = "BOF"
+    name:str = None
+    description:str = None
+    mac_address:str = None
+    ip_address:str = None
+
+    # Requires unit testing
+    def __init__(self, name: str=None, description: str=None,
+                 mac_address: str=None, ip_address: str=None):
+        self.name = name
+        self.description = description
+        self.mac_address = mac_address
+        self.ip_address = ip_address
+
+    def __str__(self):
+        return "[{0}] Device name: {1}\n\tDescription: {2}\n\tMAC address: {3}" \
+            "\n\tIP address: {4}".format(self.protocol, self.name, self.description,
+                                         self.mac_address, self.ip_address)

bof/layers/__init__.py

@@ -31,3 +31,5 @@
 
 from .knx import *
 from .modbus import *
+from .lldp import *
+from .profinet import *

bof/layers/knx/__init__.py

@@ -27,13 +27,17 @@
 :knx_packet:
     Object representation of a KNX packet. ``KNXPacket`` inherits ``BOFPacket``
     and uses Scapy's implementation of KNX (located in ``bof/layers/raw_scapy``
-    until contribution to Scapy). Contains method to build, read or alter a
+    or directly in Scapy contrib). Contains method to build, read or alter a
     frame or part of it, even if this does not follow KNX's specifications.
 
-:knx_feature:
+:knx_messages:
+    Set of functions that build specific KNX messages with the right values.
+
+:knx_functions:
     Higher-level functions to discover and interact with devices via KNXnet/IP.
 """
 
 from .knx_network import *
 from .knx_packet import *
-from .knx_feature import *
+from .knx_messages import *
+from .knx_functions import *

bof/layers/knx/knx_constants.py

@@ -0,0 +1,34 @@
+"""
+Profinet DCP constants
+----------------------
+
+Protocol-dependent constants (network and functions) for PNDCP.
+"""
+
+from ... import to_property
+from ...layers.raw_scapy import knx as scapy_knx
+
+KNX_MULTICAST_ADDR = MULTICAST_ADDR = "224.0.23.12"
+KNX_PORT = PORT = 3671
+
+# Converts Scapy KNX's SERVICE_IDENTIFIER_CODES & CEMI dicts with format
+# {byte value: service name} to the opposite, so that the end user can call
+# services by their names instead of their values.
+SID = type('SID', (object,),
+           {to_property(v):k.to_bytes(2, byteorder='big') \
+            for k,v in scapy_knx.SERVICE_IDENTIFIER_CODES.items()})()
+CEMI = type('CEMI', (object,),
+           {to_property(v):k for k,v in scapy_knx.MESSAGE_CODES.items()})()
+ACPI = type('ACPI', (object,),
+           {to_property(v):k for k,v in scapy_knx.KNX_ACPI_CODES.items()})()
+
+CONNECTION_TYPE_CODES = type('CONNECTION_TYPE_CODES', (object,),
+                             {to_property(v):k for k,v in scapy_knx.CONNECTION_TYPE_CODES.items()})()
+CEMI_OBJECT_TYPES = type('CEMI_OBJECT_TYPES', (object,),
+                         {to_property(v):k for k,v in scapy_knx.CEMI_OBJECT_TYPES.items()})()
+
+CEMI_PROPERTIES = type('CEMI_PROPERTIES', (object,),
+                       {to_property(v):k for k,v in scapy_knx.CEMI_PROPERTIES.items()})()
+
+TYPE_FIELD = "service_identifier"
+CEMI_FIELD = "cemi"

bof/layers/knx/knx_feature.py bof/layers/knx/knx_functions.pybof/layers/knx/knx_feature.py renamed to bof/layers/knx/knx_functions.py

@@ -1,16 +1,15 @@
 """
-KNX features
-------------
+KNX functions
+-------------
 
-This module contains a set of higher-level functions to interact with devices
-using KNXnet/IP without prior knowledge about the protocol.
+Higher-level functions to interact with devices using KNXnet/IP.
 
 Contents:
 
 :KNXDevice:
-    An object representation of a KNX device with multiple properties. Only
+    Object representation of a KNX device with multiple properties. Only
     supports KNXnet/IP servers so far, but will be extended to KNX devices.
-:Features:
+:Functions:
     High-level functions to interact with a device: search, discover, read,
     write, etc.
 
@@ -19,27 +18,12 @@
 
 from ipaddress import ip_address
 # Internal
-from ... import BOFNetworkError, BOFProgrammingError
+from ... import BOFNetworkError, BOFProgrammingError, BOFDevice, IS_IP
 from .knx_network import *
 from .knx_packet import *
 from .knx_messages import *
 from ...layers.raw_scapy import knx as scapy_knx 
 
-###############################################################################
-# CONSTANTS                                                                   #
-###############################################################################
-
-MULTICAST_ADDR = "224.0.23.12"
-KNX_PORT = 3671
-
-def IS_IP(ip: str):
-    """Check that ip is a valid IPv4 address."""
-    try:
-        ip_address(ip)
-    except ValueError:
-        raise BOFProgrammingError("Invalid IP {0}".format(ip)) from None
-
-
 def INDIV_ADDR(x: int) -> str:
     """Converts an int to KNX individual address."""
     return "%d.%d.%d" % ((x >> 12) & 0xf, (x >> 8) & 0xf, (x & 0xff))
@@ -52,7 +36,7 @@ def GROUP_ADDR(x: int) -> str:
 # KNX DEVICE REPRESENTATION                                                   #
 ###############################################################################
 
-class KNXDevice(object):
+class KNXDevice(BOFDevice):
     """Object representing a KNX device.
 
     Data stored to the object is the one returned by SEARCH RESPONSE and
@@ -66,10 +50,12 @@ class KNXDevice(object):
 
     The information gathered from devices may be completed, improved later.
     """
+    protocol:str = "KNX"
     def __init__(self, name: str, ip_address: str, port: int, knx_address: str,
                  mac_address: str, multicast_address: str=MULTICAST_ADDR,
                  serial_number: str=""):
         self.name = name
+        self.description = None
         self.ip_address = ip_address
         self.port = port
         self.knx_address = knx_address
@@ -78,13 +64,10 @@ def __init__(self, name: str, ip_address: str, port: int, knx_address: str,
         self.serial_number = serial_number
 
     def __str__(self):
-        descr = ["Device: \"{0}\" @ {1}:{2}".format(self.name,
-                                                    self.ip_address,
-                                                    self.port)]
-        descr += ["- KNX address: {0}".format(self.knx_address)]
-        descr += ["- Hardware: {0} (SN: {1})".format(self.mac_address,
-                                                     self.serial_number)]
-        return " ".join(descr)
+        return "{0}\n\tPort: {1}\n\tMulticast address: {2}\n\t" \
+            "KNX address: {3}\n\tSerial number: {4}".format(
+                super().__str__(), self.port, self.multicast_address,
+                self.knx_address, self.serial_number)
 
     @classmethod
     def init_from_search_response(cls, response: KNXPacket):
@@ -139,7 +122,7 @@ def init_from_description_response(cls, response: KNXPacket, source: tuple):
         return cls(**args)
 
 ###############################################################################
-# FEATURES                                                                    #
+# FUNCTIONS                                                                   #
 ###############################################################################
 
 #-----------------------------------------------------------------------------#

bof/layers/knx/knx_packet.py

@@ -27,32 +27,7 @@
 from bof.layers.raw_scapy import knx as scapy_knx
 from bof.packet import BOFPacket
 from bof.base import BOFProgrammingError, to_property
-
-###############################################################################
-# CONSTANTS                                                                   #
-###############################################################################
-
-# Converts Scapy KNX's SERVICE_IDENTIFIER_CODES & CEMI dicts with format
-# {byte value: service name} to the opposite, so that the end user can call
-# services by their names instead of their values.
-SID = type('SID', (object,),
-           {to_property(v):k.to_bytes(2, byteorder='big') \
-            for k,v in scapy_knx.SERVICE_IDENTIFIER_CODES.items()})()
-CEMI = type('CEMI', (object,),
-           {to_property(v):k for k,v in scapy_knx.MESSAGE_CODES.items()})()
-ACPI = type('ACPI', (object,),
-           {to_property(v):k for k,v in scapy_knx.KNX_ACPI_CODES.items()})()
-
-CONNECTION_TYPE_CODES = type('CONNECTION_TYPE_CODES', (object,),
-                             {to_property(v):k for k,v in scapy_knx.CONNECTION_TYPE_CODES.items()})()
-CEMI_OBJECT_TYPES = type('CEMI_OBJECT_TYPES', (object,),
-                         {to_property(v):k for k,v in scapy_knx.CEMI_OBJECT_TYPES.items()})()
-
-CEMI_PROPERTIES = type('CEMI_PROPERTIES', (object,),
-                       {to_property(v):k for k,v in scapy_knx.CEMI_PROPERTIES.items()})()
-
-TYPE_FIELD = "service_identifier"
-CEMI_FIELD = "cemi"
+from .knx_constants import *
 
 ###############################################################################
 # KNXPacket class                                                             #