Repository files navigation

BOF (Boiboite Opener Framework) is a testing framework for field protocolsimplementations and devices. It is a Python 3.6+ library that provides means tosend, receive, create, parse and manipulate frames from supported protocols.

The library currently provides discovery and extended testing features forKNXnet/IP, which is our focus, but it can be extended to other types of BMSor industrial network protocols. It also provides multicast and/or end-to-enddiscovery functions for industrial networks relying on KNXnet/IP, LLDP,Profinet DCP and Modbus TCP.

Please note that targeting industrial systems can have a severe impact onpeople, industrial operations and buildings and that BOF must be usedcarefully.

pip install boiboite-opener-framework

https://pypi.org/project/boiboite-opener-framework/

git clone https://github.com/Orange-Cyberdefense/bof.git

Install requirements with:

pip install -r requirements.txt

Protocol implementations useScapy's format.

BOF is a Python 3.6+ library that should be imported in scripts.

importboffrombof.layersimportprofinet,knxfrombof.layers.knximportKnxPacket

There are three ways to use BOF, not all of them are available depending on thelayer:

• Automated: Import or call directly higher-level functions from layers. Noknowledge about the protocol required. For instance, thediscoverymodule contains a few functions to discover devices using several industrialnetwork protocols.

• Standard: Craft packets from layers to interact with remote devices. Basicknowledge about the protocol required.

• Playful: Play with packets, misuse the protocol (we fuzz devices with it).The end user should have started digging into the protocol's specifications.

Now you can start using BOF!

• Mutlcast discovery from the discovery module (currently with LLDP, ProfinetDCP, KNX):

frombof.modules.discoveryimport*devices=multicast_discovery(iface="eth0",verbose=True)

• Device discovery using a layer's high-level function

frombof.layers.knximportsearchdevices=search()fordeviceindevices:print(device)

• Create and send your own discovery packet:

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))

frombof.layers.knximportKNXnet,KNXPacket,SIDfrombofimportBOFNetworkErrortry:knxnet=KNXnet().connect("192.168.1.242",3671)pkt=KNXPacket(type=SID.description_request,ip_address=knxnet.source_address,port=knxnet.source_port)pkt.show2()response,_=knxnet.sr(pkt)response.show2()exceptBOFNetworkErrorasbne:passfinally:knxnet.disconnect()

frombof.layers.knximportKNXPacket,SIDfrombof.layers.raw_scapy.knximportLcEMIpkt=KNXPacket(type=SID.description_request)pkt.ip_address=b"\x01\x01"pkt.port=99999# Yes it's too largepkt.append(LcEMI())pkt.show2()# This may output something strange

A recipient device will probably not respond to that, but at least you knowthat BOF won't stop you from messing with your packets.

BOF relies on Scapy for protocol implementations, with an additional layer thattranslates BOF code to changes on Scapy packets and fields. Why? Because BOF mayslightly modify or override Scapy’s internal behavior.

You do not need to know how to use Scapy to use BOF, however if you do, you arefree to interact with the Scapy packet directly as well.

packet=KNXPacket(type=connect_request)packet.field1=1# Applying additional BOF operations (ex: change types)packet.scapy_pkt.field1=1# Direct access to Scapy Packet object

Link to the documentation:https://bof.readthedocs.io

The HTML user manual and source code documentation can be built from therepository:

1. $> cd docs && make html
2. Navigate to[path to repository]/docs/_build/html/index.html

Example scripts are in folderexamples.

Contributors are welcome! BOF is still an ongoing project, which relies onindustrial network protocol implementations in Scapy format. You can firstcontribute by contributing to Scapy and adding new protocols ("layers"). Or, youcan contribute by integrating a Scapy protocol to BOF. The documentationexplains how to do it. Furthermore, there will still be room for higher-levelfunctions that will make tests easier or implement known attack againstprotocols or protocol implementations.

Here a few things to know beforehand:

• We like clean code and expect contributions to be PEP-8 compliant as much aspossible (even though we don't test for it). New code should be readableeasily and maintainable. And remember: if you need to use "and" whileexplaining what your function does, then you can probably split it.

• Please write Unit tests and make sure existing ones still pass! They are intests/. You can run all unit tests with:python -m unittest discover -s tests

Report bugs, ask questions or request for missing documentation and new featuresby submitting an issue with GitHub. For bugs, please describe your problem asclearly as you can.