{"id":13627525,"url":"https://github.com/Orange-Cyberdefense/bof","last_synced_at":"2025-04-17T00:31:52.298Z","repository":{"id":47528424,"uuid":"271485387","full_name":"Orange-Cyberdefense/bof","owner":"Orange-Cyberdefense","description":"BOF (Boiboite Opener Framework) is a testing framework for industrial protocols implementations and devices.","archived":false,"fork":false,"pushed_at":"2024-01-15T09:15:01.000Z","size":810,"stargazers_count":38,"open_issues_count":0,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-03-14T19:18:15.855Z","etag":null,"topics":["industrial-network","industrial-security","knx","modbus","network-attacks","network-discovery","offensive-security","python-library"],"latest_commit_sha":null,"homepage":"https://bof.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Orange-Cyberdefense.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-11T07:52:18.000Z","updated_at":"2024-06-13T06:25:48.332Z","dependencies_parsed_at":"2024-01-14T08:33:25.263Z","dependency_job_id":"ee0e3876-fcdd-4d0a-a32e-9cb17f6dcadc","html_url":"https://github.com/Orange-Cyberdefense/bof","commit_stats":{"total_commits":294,"total_committers":6,"mean_commits":49.0,"dds":0.326530612244898,"last_synced_commit":"06da12fb8d3669d4cbe7d0775cea7efd4f6d70b8"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Fbof","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Fbof/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Fbof/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-Cyberdefense%2Fbof/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Orange-Cyberdefense","download_url":"https://codeload.github.com/Orange-Cyberdefense/bof/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223735013,"owners_count":17194027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["industrial-network","industrial-security","knx","modbus","network-attacks","network-discovery","offensive-security","python-library"],"created_at":"2024-08-01T22:00:35.171Z","updated_at":"2024-11-08T18:30:37.950Z","avatar_url":"https://github.com/Orange-Cyberdefense.png","language":"Python","funding_links":[],"categories":["KNXnet/IP"],"sub_categories":["Tools"],"readme":"BOF \n===\n\nBOF (Boiboite Opener Framework) is a testing framework for field protocols\nimplementations and devices. It is a Python 3.6+ library that provides means to\nsend, receive, create, parse and manipulate frames from supported protocols.\n\nThe library currently provides discovery and extended testing features for\n**KNXnet/IP**, which is our focus, but it can be extended to other types of BMS\nor industrial network protocols. It also provides multicast and/or end-to-end\ndiscovery functions for industrial networks relying on KNXnet/IP, LLDP,\nProfinet DCP and Modbus TCP.\n\n**Please note that targeting industrial systems can have a severe impact on\npeople, industrial operations and buildings and that BOF must be used\ncarefully.**\n\n[![GitHub license](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://github.com/Orange-Cyberdefense/bof/blob/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/Orange-Cyberdefense/bof.svg)](https://gitHub.com/Orange-Cyberdefense/bof/releases/)\n\nInstall\n-------\n\n### From PyPI\n\n```\npip install boiboite-opener-framework\n```\n\nhttps://pypi.org/project/boiboite-opener-framework/\n\n### Manual install\n\n```\ngit clone https://github.com/Orange-Cyberdefense/bof.git\n```\n\nInstall requirements with:\n\n```\npip install -r requirements.txt\n```\n\nProtocol implementations use [Scapy](https://scapy.readthedocs.io/en/latest/)'s format.\n\nGetting started\n---------------\n\nBOF is a Python 3.6+ library that should be imported in scripts.\n\n```python\nimport bof\nfrom bof.layers import profinet, knx\nfrom bof.layers.knx import KnxPacket\n```\n\nThere are three ways to use BOF, not all of them are available depending on the\nlayer:\n\n* **Automated**: Import or call directly higher-level functions from layers. No\n    knowledge about the protocol required. For instance, the **discovery**\n    module contains a few functions to discover devices using several industrial\n    network protocols.\n\n* **Standard**: Craft packets from layers to interact with remote devices. Basic\n    knowledge about the protocol required.\n\n* **Playful**: Play with packets, misuse the protocol (we fuzz devices with it).\n  The end user should have started digging into the protocol's specifications.\n\n|              | Automated | Standard | Playful |\n|--------------|-----------|----------|---------|\n| KNX          | X         | X        | X       |\n| LLDP         | X         |          |         |\n| Modbus       | X         | X        | X       |\n| Profinet DCP | X         |          |         |\n\n\nNow you can start using BOF!\n\nTL;DR\n-----\n\n### Several ways to discover devices on a network\n\n* Mutlcast discovery from the discovery module (currently with LLDP, Profinet\n  DCP, KNX):\n\n```python\nfrom bof.modules.discovery import *\n\ndevices = multicast_discovery(iface=\"eth0\", verbose=True)\n```\n\n* Device discovery using a layer's high-level function\n\n```python\nfrom bof.layers.knx import search\n\ndevices = search()\nfor device in devices:\n    print(device)\n```\n\n* Create and send your own discovery packet:\n\n```\nfrom bof.layers.knx import *\n\npkt = KNXPacket(type=\"search request\")\nresponses = KNXnet.multicast(pkt, (KNX_MULTICAST_ADDR, KNX_PORT))\nfor response, _ in responses:\n    print(KNXPacket(response))\n```\n\n### Send and receive packets\n\n```python\nfrom bof.layers.knx import KNXnet, KNXPacket, SID\nfrom bof import BOFNetworkError\n\ntry:\n    knxnet = KNXnet().connect(\"192.168.1.242\", 3671)\n    pkt = KNXPacket(type=SID.description_request,\n                    ip_address=knxnet.source_address,\n                    port=knxnet.source_port)\n    pkt.show2()\n    response, _ = knxnet.sr(pkt)\n    response.show2()\nexcept BOFNetworkError as bne:\n    pass\nfinally:\n    knxnet.disconnect()\n```\n\n### Craft your own packets\n\n```python\nfrom bof.layers.knx import KNXPacket, SID\nfrom bof.layers.raw_scapy.knx import LcEMI\n\npkt = KNXPacket(type=SID.description_request)\npkt.ip_address = b\"\\x01\\x01\"\npkt.port = 99999 # Yes it's too large\npkt.append(LcEMI())\npkt.show2() # This may output something strange\n```\n\n\u003e A recipient device will probably not respond to that, but at least you know\n  that BOF won't stop you from messing with your packets.\n\n### Interface with Scapy\n\nBOF relies on Scapy for protocol implementations, with an additional layer that\ntranslates BOF code to changes on Scapy packets and fields. Why? Because BOF may\nslightly modify or override Scapy’s internal behavior.\n\nYou do not need to know how to use Scapy to use BOF, however if you do, you are\nfree to interact with the Scapy packet directly as well.\n\n```python\npacket = KNXPacket(type=connect_request)\npacket.field1 = 1 # Applying additional BOF operations (ex: change types)\npacket.scapy_pkt.field1 = 1 # Direct access to Scapy Packet object\n```\n\nComplete documentation\n----------------------\n\n[![made-with-sphinx-doc](https://img.shields.io/badge/Made%20with-Sphinx-1f425f.svg)](https://www.sphinx-doc.org/)\n\nLink to the documentation: https://bof.readthedocs.io\n\nThe HTML user manual and source code documentation can be built from the\nrepository:\n \n1. `$\u003e cd docs \u0026\u0026 make html`\n2. Navigate to `[path to repository]/docs/_build/html/index.html`\n\nExample scripts are in folder `examples`.\n\nContributing\n------------\n\nContributors are welcome! BOF is still an ongoing project, which relies on\nindustrial network protocol implementations in Scapy format. You can first\ncontribute by contributing to Scapy and adding new protocols (\"layers\"). Or, you\ncan contribute by integrating a Scapy protocol to BOF. The documentation\nexplains how to do it. Furthermore, there will still be room for higher-level\nfunctions that will make tests easier or implement known attack against\nprotocols or protocol implementations.\n\nHere a few things to know beforehand:\n\n* We like clean code and expect contributions to be PEP-8 compliant as much as\n  possible (even though we don't test for it). New code should be readable\n  easily and maintainable. And remember: if you need to use \"and\" while\n  explaining what your function does, then you can probably split it.\n\n* Please write Unit tests and make sure existing ones still pass! They are in\n  `tests/`. You can run all unit tests with: `python -m unittest discover -s\n  tests`\n\nReporting issues\n----------------\n\nReport bugs, ask questions or request for missing documentation and new features\nby submitting an issue with GitHub. For bugs, please describe your problem as\nclearly as you can.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOrange-Cyberdefense%2Fbof","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOrange-Cyberdefense%2Fbof","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOrange-Cyberdefense%2Fbof/lists"}