Skip to main content

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 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 people, industrial operations and buildings and that BOF must be used carefully.

GitHub license GitHub release

Install

From PyPI

pip install boiboite-opener-framework

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

Manual install

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

Install requirements with:

pip install -r requirements.txt

Protocol implementations use Scapy's format.

Getting started

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

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

Several ways yo discover devices on a network

  • Passive discovery from the discovery module:
from bof.modules.discovery import *

devices = passive_discovery(iface="eth0", verbose=True)
  • Device discovery using a layer's high-level function
from bof.layers.knx import search

devices = search()
for device in devices:
    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))

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

made-with-sphinx-doc

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

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

  1. $> cd docs && make html
  2. 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.

Metadata

Release files for boiboite-opener-framework 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for boiboite-opener-framework 1.2.0
File Size Uploaded Provenance Actions
boiboite-opener-framework-1.2.0.tar.gz 88.7 kB Without provenance Details for boiboite-opener-framework-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for boiboite-opener-framework 1.2.0
File Interpreter ABI Platform Actions
boiboite_opener_framework-1.2.0-py3-none-any.whl Python 3 none any Details for boiboite_opener_framework-1.2.0-py3-none-any.whl

Total release size: 187.6 kB

Release files / boiboite-opener-framework-1.2.0.tar.gz

Download URL boiboite-opener-framework-1.2.0.tar.gz
Size 88.7 kB
Tags Source
SHA-256 checksum
How to use checksums
330e30db69fe69d2a434e6a012720b38f1971604374e56d366036a15521d0236
BLAKE2b-256 checksum
How to use checksums
e2dafed1999355e796cc9e295a4ec3e2a9ef558c4440736f30b6d0b72e20be75
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.4.2 importlib_metadata/4.6.3 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.6.9

Release files / boiboite_opener_framework-1.2.0-py3-none-any.whl

Download URL boiboite_opener_framework-1.2.0-py3-none-any.whl
Size 98.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b067c405af5c81299be37ffa53c4760b7dc2eed35a24f4ffaa1236dd52cf48b2
BLAKE2b-256 checksum
How to use checksums
a92236e627f69a3f4d8467d8053163d54341fad887632e922373c43359b23dd0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.4.2 importlib_metadata/4.6.3 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.6.9

Security for boiboite-opener-framework 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page