Industrial network protocols testing framework
Project description
BOF
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.
Please note that targeting industrial systems can have a severe impact on buildings and people and that BOF must be used carefully.
Getting started
git clone https://github.com/Orange-Cyberdefense/bof.git
Requirements (Protocol implementations use
Scapy's format): pip install scapy
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:
import bof
Now you can start using BOF!
TL;DR
Discover devices on a network
from bof.layers.knx import search
devices = search()
for device in devices:
print(device)
Should output something like:
Device: "boiboite" @ 192.168.1.242:3671 - KNX address: 15.15.255 - Hardware: 00:00:ff:ff:ff:ff (SN: 0123456789)
Send and receive packets
from bof.layers.knx import KNXnet, KNXPacket, SID
from bof import BOFNetworkError
try:
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()
except BOFNetworkError as bne:
pass
finally:
knxnet.disconnect()
Craft your own packets
from bof.layers.knx import KNXPacket, SID
from bof.layers.raw_scapy.knx import LcEMI
pkt = KNXPacket(type=SID.description_request)
pkt.ip_address = b"\x01\x01"
pkt.port = 99999 # Yes it's too large
pkt.append(LcEMI())
pkt.show2() # This may output something strange
A recipient device will probably not respond to that, but at least you know that BOF won't stop you from messing with your packets.
Interface with Scapy
BOF relies on Scapy for protocol implementations, with an additional layer that translates BOF code to changes on Scapy packets and fields. Why? Because BOF may slightly 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 are free 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
Complete documentation
Link to the documentation: https://bof.readthedocs.io
The HTML user manual and source code documentation can be built from the repository:
$> cd docs && make html
- Navigate to
[path to repository]/docs/_build/html/index.html
Example scripts are in folder examples
.
Contributing
Contributors are welcome! BOF is still an ongoing project, which relies on industrial network protocol implementations in Scapy format. You can first contribute by contributing to Scapy and adding new protocols ("layers"). Or, you can contribute by integrating a Scapy protocol to BOF. The documentation explains how to do it. Furthermore, there will still be room for higher-level functions that will make tests easier or implement known attack against protocols or protocol implementations.
Here a few things to know beforehand:
-
We like clean code and expect contributions to be PEP-8 compliant as much as possible (even though we don't test for it). New code should be readable easily and maintainable. And remember: if you need to use "and" while explaining what your function does, then you can probably split it.
-
Please write Unit tests and make sure existing ones still pass! They are in
tests/
. You can run all unit tests with:python -m unittest discover -s tests
Reporting issues
Report bugs, ask questions or request for missing documentation and new features by submitting an issue with GitHub. For bugs, please describe your problem as clearly as you can.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for boiboite-opener-framework-1.0.3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | de8b40066ed014cc3900e289332c9e6db66cb596b4bff12bf7a9f9b34eaa814b |
|
MD5 | 87b3d155d37451ee97a0e60501c19a25 |
|
BLAKE2b-256 | 1c0372d2617d4543000d3a46c3e35734ca8103a11da29820fe112537c48d5b13 |
Hashes for boiboite_opener_framework-1.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 478caa19e95b2054402cdb4e1055482c077a2a0b553047cde14ed7fb5755457b |
|
MD5 | 5d02db7fede188b979b1662ff27ff008 |
|
BLAKE2b-256 | fbf955f8c558559d9a926fc7a29392b8aa973596a03e3c3ffbf407aa4e968a0e |