Release hotfix 1.0.2 for Scapy 2.4.5 compat

Author: claire-lex

bof/layers/raw_scapy/knx.py

@@ -352,7 +352,7 @@ class LcEMI(Packet):
         BitEnumField("sequence_type", 0, 1, {
             0: "unnumbered"
         }),
-        BitField("reserved", 0, 4),
+        BitField("reserved2", 0, 4),
         BitEnumField("acpi", 2, 4, KNX_ACPI_CODES),
         ConditionalField(BitField("data", 0, 6),
                          lambda pkt:pkt.packet_type==0)

bof/packet.py

@@ -323,6 +323,8 @@ def _field_generator(self, start_packet:object=None, terminal=False) -> tuple:
             for field in packet.fields_desc:
                 if isinstance(field, MultipleTypeField):
                     field = field._find_fld()
+                elif isinstance(field, ConditionalField) and field._evalcond(packet):
+                    field = field.fld
                 if isinstance(field, PacketField) or isinstance(field, Packet):
                     yield from self._field_generator(getattr(packet, field.name))
                 if isinstance(field, Field):
@@ -339,7 +341,10 @@ def _get_field(self, name:str, start_packet:object=None, packets:bool=False) ->
         """
         for field, parent in self._field_generator(start_packet):
             if field.name == name:
-                field_and_val = parent.getfield_and_val(name)
+                try:
+                    field_and_val = parent.getfield_and_val(name)
+                except ValueError:
+                    field_and_val = None
                 # We do not return packetfields directly because we should not
                 # manipulate them outside direct call to Scapy or direct access
                 # to the fields they contain.
@@ -402,7 +407,7 @@ def _any2i(self, parent, field, new_value) -> bool:
             self._setattr(parent, field, new_value)
             raw(parent)
             return True
-        except struct_error:
+        except (ValueError, struct_error):
             pass # Any other exception is unexpected and we let it happen
         return False
 

docs/man/user.rst

@@ -46,11 +46,14 @@ free to interact with the Scapy packet directly as well.**
 	    :width: 450
 	    :align: center
 
-For instance, in the code sample below, lines 2 and 3 do the same thing and
-modify the same packet object. However for line 2, you set a value to the
-``field1`` from **BOF**'s packet, applying any change provided by BOF when
-setting a value. In line 3, the field is modified directly in **Scapy**'s
-packet, BOF does not interfer.
+For instance, in the code sample below, lines 2 and 3 do the same
+thing and modify the same packet object. However for line 2, you set a
+value to the ``field1`` from **BOF**'s packet, applying any change
+provided by BOF when setting a value. In line 3, the field is modified
+directly in **Scapy**'s packet, BOF does not interfer. In other words,
+a ``BOFPacket`` object (here ``KNXPacket``) acts as a wrapper around a
+Scapy object representing the actual packet using the specified
+protocol.
 
 .. code-block:: python
    :linenos:
@@ -59,6 +62,46 @@ packet, BOF does not interfer.
    packet.field1 = 1
    packet.scapy_pkt.field1 = 1
 
+The reason we did that is because there is nothing
+better than Scapy to handle protocol implementations, and by using
+Scapy we can also use all the implementations that were written for
+it. But BOF and Scapy do not have the same usage and aim: First, we
+made some choices about BOF's script syntax and sometimes Scapy's
+syntax don't follow these choices. But most of all, we sometimes can't
+rely on Scapy's behavior for what we want to do with BOF because they
+are not compatible. Just to mention a few:
+
+:Field-oriented usage:
+   BOF's preferred usage when altering packets is to change specific
+   fields directly. Why? Because BOF has been written to write attack
+   scripts, including fuzzers. In these fuzzers, we want to stick to
+   the protocol's specification because if we don't, devices we target
+   may just drop our frames. And to stick to the specification, we
+   have to keep a valid frame format, and to do that we just modify
+   specific fields. Scapy does not work this way and, although we can
+   modify isolated fields, it's hard to get and set values in a
+   script, mostly because we can't refer to a field without referring
+   to its parent packet holding its value.
+:BOF does not care about types:
+  But Scapy does. Field objects in Scapy have a type and you can't
+  change it easily or just use a field objectthat doesn't have a type
+  without losing some capabilities. For us, packets are just a bunch
+  of bytes so we might as well set values directly as bytes to fields,
+  and Scapy won't allow that. It won't allow setting a value with the
+  wrong type either, and we don't want field types to be a thing in
+  BOF: a user should not need to know the type of a field, or she may
+  be able to implicitly change it. That's what BOF's wrapper around
+  the Scapy object does.
+
+.. code-block:: python
+
+   # Setting value to field from BOF, type is changed automatically
+   bofpacket.host_protocol = "test"
+
+   # Setting value to field directly on Scapy packet, type is invalid
+   # and will trigger an error when the packet is reconstructed.
+   bofpacket.scapy_pkt.control_endpoint.host_protocol = "test"
+   
 TL;DR
 =====
 

examples/knx/cemi_fuzzer.py

@@ -142,7 +142,7 @@ def fuzz(ip:str, generator:object, base_pkt:KNXPacket) -> None:
 # Open log file
 LOG_FD = open(LOG_FILENAME, "w+")
 # Create the base frame to mutate during fuzzing
-base_pkt = KNXPacket(type=SID.configuration_request, cemi=CEMI.propread_req)
+base_pkt = KNXPacket(type=SID.configuration_request, cemi=CEMI.m_propread_req)
 base_pkt.number_of_elements = 1
 base_pkt.show2()
 

requirements.txt

@@ -1 +1 @@
-scapy
+scapy==2.4.5

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="boiboite-opener-framework",
-    version="1.0.0",
+    version="1.0.2",
     author="Claire Vacherot",
     author_email="claire.vacherot@orange.com",
     description="Industrial network protocols testing framework",