{"id":14109740,"url":"https://github.com/rene-d/sysbus","last_synced_at":"2025-10-24T21:47:44.834Z","repository":{"id":42425455,"uuid":"52149189","full_name":"rene-d/sysbus","owner":"rene-d","description":"Contrôle par script d'une Livebox 2, 3 et 4","archived":false,"fork":false,"pushed_at":"2023-05-04T07:54:04.000Z","size":1571,"stargazers_count":153,"open_issues_count":5,"forks_count":28,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-10-19T09:01:56.122Z","etag":null,"topics":["livebox","sysbus"],"latest_commit_sha":null,"homepage":"http://rene-d.github.io/sysbus/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rene-d.png","metadata":{"files":{"readme":"README.en.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}},"created_at":"2016-02-20T11:01:07.000Z","updated_at":"2024-09-13T08:09:39.000Z","dependencies_parsed_at":"2024-01-08T08:03:53.958Z","dependency_job_id":null,"html_url":"https://github.com/rene-d/sysbus","commit_stats":{"total_commits":105,"total_committers":10,"mean_commits":10.5,"dds":"0.22857142857142854","last_synced_commit":"8f711f76e9170e91b359113574be027135bcc577"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rene-d%2Fsysbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rene-d%2Fsysbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rene-d%2Fsysbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rene-d%2Fsysbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rene-d","download_url":"https://codeload.github.com/rene-d/sysbus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608151,"owners_count":20965952,"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":["livebox","sysbus"],"created_at":"2024-08-14T10:02:28.351Z","updated_at":"2025-10-24T21:47:44.762Z","avatar_url":"https://github.com/rene-d.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# sysbus.py\n\n[![Build Status](https://travis-ci.org/rene-d/sysbus.svg?branch=master)](https://travis-ci.org/rene-d/sysbus)\n[![pyi](https://img.shields.io/pypi/v/sysbus.svg)](https://pypi.python.org/pypi/sysbus)\n[![pyi](https://img.shields.io/pypi/pyversions/sysbus.svg)](https://pypi.python.org/pypi/sysbus)\n\n[🇫🇷 Original version in French 🇫🇷](README.md)\n\n**WARNING**: I am not the author of this translation. It may contain errors or typos (especially with spaces...).\n\n**WARNING**: Some information may be out of date and irrelevant since Livebox software has been updated by Orange.\n\n`sysbus.py` is a Python 3 script that allows you to programmatically control a Livebox and explore control possibilities and other hidden information. It is an \"experimental\" tool.\n\nThere is - unfortunately - no crunchy hidden information to discover, or so I have not found anything. The Livebox is closed well enough.\n\n## Installation\n\nThe script is written in [Python 3](https://www.python.org/downloads/). It also requires [requests](http://docs.python-requests.org/) which greatly simplifies HTTP requests. It may use [Graphviz](http://www.graphviz.org) and one of its Python interface modules [graphviz](https://pypi.python.org/pypi/graphviz) to draw graphs.\n\nIt will also install the Graphviz engine. On OSX we can use [brew](http://brew.sh). On Linux, `sudo apt-get install graphviz` or equivalent depending on the distribution.\n\nThis should work also with Windows. Refer to the sites of the various software for installation procedures.\n\n### pip\n\nThis installs the latest stable, released version.\n\n    $ pip3 install sysbus\n\n### Manually (from the sources)\n\n    $ pip3 install -r requirements.txt\n    $ pip3 install .\n\n### Without installation (run from the sources)\n\n    $ pip3 install requests\n    $ cd src/sysbus\n    $ ./sysbus.py -h\n\n_In this case, replace `sysbus` by `./sysbus.py` in the following commands._\n\n**Nota**\n\nThe Python module [manuf.py](http://github.com/coolbho3k/manuf) displays the [OUI](https://fr.wikipedia.org/wiki/Organizationally_Unique_Identifier) from [MAC](https://fr.wikipedia.org/wiki/Adresse_MAC) addresses. The database `manuf` can be updated with `sysbus --update-oui`.\n\n## Configuration\n\nMost requests require authentication. This is the user `admin` and the admin password (by default the first 8 characters of the Wi-Fi key).\n\nThe script stores the password (as well as the address of the Livebox and its version if you do not use the default values) in the `~ / .sysbusrc` file.\n\nThe version of the livebox defaults to `lb4` (Livebox 4) but can be replaced (` lb3` for example) after the `-lversion` argument.\n\nTo configure, type the following command (assuming that the password is SECRET):\n\n    $ sysbus -config -password SECRET [-url http://192.168.1.1/] [-lversion lb4]\n\nFrom now on, the script will use this login information each time. One can test by asking the time of the equipment:\n\n    $ sysbus\n    Livebox time: Sun, 14 Feb 2016 22:08:32 GMT + 0100\n\n## Use\n\nA certain number of requests are integrated in the script (like the request time, or Wi-Fi keys, devices present, etc.) with more or less formatting of the result.\n\nThe script is also able to send almost any request, provided that it is fully specified on the command line.\n\n    $ sysbus Time:getTime\n    Livebox time: Sun, 14 Feb 2016 22:13:30 GMT + 0100\n\nThe `-h` or` --help` option displays all the possible syntax.\n\n## The sysbus interface\n\nBy browsing the sources made available by Orange [here](http://opensource.orange.com/), we can establish that the Liveboxes since version 2 use a middleware developed by [SoftAtHome](http://www.softathome.com) and a home datamodel engine named \"pcb\".\n\nUnfortunately I have not found any Internet references to this proprietary technology, or it is embedded among all the [meanings(https://fr.wikipedia.org/wiki/PCB) of the acronym, including _Printed Circuit Board_ . Orange and his friend SoftAtHome therefore offer a treasure hunt and puzzles.\n\nThis internal datamodel communicates with the outside via an HTTP interface and JSON named \"sysbus\".\n\nThis interface is used by the administration interface [http: //livebox.home] or the apps [iOS](https://itunes.apple.com/en/app/ma-livebox/id445573616?mt=8) and [Android](https://play.google.com/store/apps/details?id=com.orange.mylivebox.fr\u0026hl=en).\n\nThe principle is to send POST requests with a list of parameters in a JSON object, the return will be a JSON object containing the result of the request.\n\nIt is reasonable to think that this is also the way that Orange administers Liveboxes (activation of shared Wi-Fi, updates) and perhaps network and / or hardware diagnostics.\n\n### Example with curl\n\nAPI used by Livebox 4 (firmware SG40_sip-en-2.14.8.1_7.21.3.1), which works with Livebox 3 (with firmware SG30_sip-en-5.17.3.1 at least):\n\n```bash\ncurl -s -X POST -H \"Content-Type: application/x-sah-ws-1-call+json\" -d '{\"service\":\"NMC\",\"method\":\"getWANStatus\",\"parameters\":{}}' http://192.168.1.1/ws\n```\n\nAPI used on old Livebox and the mobile apps:\n\n```bash\ncurl -s -X POST -H \"Content-Type: application/json\" -d '{\"parameters\":{}}' http://192.168.1.1/sysbus/NMC:getWANStatus | jq .\n```\n\nResult:\n\n```json\n{\n    \"result\": {\n        \"status\": true,\n        \"data\": {\n            \"LinkType\": \"ethernet\",\n            \"LinkState\": \"up\",\n            \"MACAddress\": \"3C:81:D8:xx:yy:zz\",\n            \"Protocol\": \"dhcp\",\n            \"ConnectionState\": \"Bound\",\n            \"LastConnectionError\": \"None\",\n            \"IPAddress\": \"aa.bb.cc.dd\",\n            \"RemoteGateway\": \"aa.bb.cc.dd\",\n            \"DNSServers\": \"80.10.246.136,81.253.149.6\",\n            \"IPv6Address\": \"2a01:cb00:xyzt:abcd:1:2:3:4\",\n            \"IPv6DelegatedPrefix\": \"2a01:cb00:xyzt:abcd::/56\"\n        }\n    }\n}\n```\n\n[jq](https://stedolan.github.io/jq/) is a tool that allows, among other things, to\nreformat the JSON.\n\nNote: This request does not require authentication, unlike the time request.\n\n### Examples with the script\n\n    # query similar to the curl example above\n    $ sysbus sysbus.NMC:getWANStatus\n\n    # passing parameters\n    $ sysbus sysbus.NMC.Wifi:set Enable=True Status=True\n\n### Where to find the requests?\n\nThe script has a `-scan` option that more or less lists the method calls that are used by the administration web interface. It uses for that the agglomeration of javascript scripts of the Livebox. On the other hand, it will be necessary to search to know the possible parameters.\n\nModern browser debuggers are also able to view sent queries and their results.\n\nAnother way is to use [wireshark](https://www.wireshark.org) or [tcpflow](https://github.com/simsong/tcpflow) and perform the actions that you wish to script, either via web interface, either via the mobile app if you know how to capture the Wi-Fi smartphone or tablet.\n\nFinally, the last source of information is the datamodel.\n\n## The datamodel\n\nThe sysbus interface has an interesting feature: that of being able to discover the datamodel.\n\nFor this, the HTTP request to make is a GET on the name of the object. The returned JSON describes the model.\n\n`sysbus` is able to make the return readable by detecting functions, parameters and object instances. Decoding, based solely on observation, may be incomplete.\n\n    # queries the datamodel of the NMC.Wifi object\n    $ sysbus NMC.Wifi -model\n\n    =========================================== level 0\n    OBJECT NAME: 'NMC.Wifi'  (name: Wifi)\n    function: startPairing (opt clientPIN)\n    function: stopPairing ()\n    function: startAutoChannelSelection ()\n    function: getStats (out RxBytes, out TxBytes)\n    function: get ()\n    function: set (opt parameters)\n    parameter:  Enable               : bool       = 'True'\n    parameter:  Status               : bool       = 'True'\n    parameter:  ConfigurationMode    : bool       = 'True'\n\nLaunched without an object name, the program displays the datamodel, with access restrictions. However, sub-objects can be accessible, such as NeMo.Intf.data, while neither NeMo nor NeMo.Intf are accessible. There are also the objects NeMo.MIB. * Name * (NeMo.MIB.alias for example), but forbidden access.\n\nThe `-modeluml` option will create class diagrams with [plantuml](http://plantuml.com) (see example below).\n\nThe datamodel includes some elements of different TR of the Broadband Forum (see [TR-181](https://www.broadband-forum.org/cwmp/tr-181-2-10-0.html) for example). For example, the Device.Hosts object is very similar to the one found in the Livebox, plus extensions specific to Orange (X_ORANGE-COM_xxx).\n\nIn addition, the presence of a user 'cwmpd' (see the UserManagement object) with the unknown password tends to prove that the Livebox communicates using _CWMP_ (or [TR-069](https://en.wikipedia.org/wiki/TR-069)) with its management gateway on the Orange side.\n\n![Hosts class diagram](http://rene-d.github.io/sysbus/docs/Hosts.png)\n\n### New Livebox 4\n\nThe LB4's web interface is much more advanced. The datamodel is essentially the same, with more objects.\n\nThere is also a description of methods via Json queries:\n\n    curl -s http://livebox.home/sdkut/apis/pcb/Time/getTime.json | jq .\n\n\n## The NeMo.Intf graph\n\nThe interfaces and pseudo-interfaces are internally organized into graphs via _upper_ and _lower_ connections.\n\nThe `-graph` option in` sysbus` uses Graphviz to display the entire graph of the interfaces.\n\n    $ sysbus -graph\n\n![functional graph](http://rene-d.github.io/sysbus/docs/nemo_intf.png)\n\nIn grayed out, the blocks that are inaccessible (they are discovered only thanks to the links _upper_ and _lower_). And in ellipse, blocks disabled.\n\nThe graph is displayed in SVG, which is used to zoom without loss. It can only be modified in the source of the script (change 'svg' to 'png' for example).\n\nEach interface manages one or more MIBs. The list can be retrieved with the command:\n\n    $ sysbus -MIBs show\n\nThe MIBs (_Management Information Base_) are apparently close to SNMP MIBs, but they are not - or they are proprietary MIBs and can not be accessed in SNMP. This is the MIB named `base` which is exploited to build the graph.\n\n    $ sysbus NeMo.Intf.wl1:getMIBs mibs=base traverse=this\n    {'status': {'base': {'wl1': {'Enable': True,\n                                 'Flags': 'wlanvap penable netdev enabled '\n                                          'wlanvap-bound wlansta netdev-bound '\n                                          'inbridge netdev-up up',\n                                 'LLIntf': {'wifi1_ath': {'Name': 'wifi1_ath'}},\n                                 'Name': 'wl1',\n                                 'Status': True,\n                                 'ULIntf': {'bridge': {'Name': 'bridge'}}}}}}\n\nThe interpretation of the result of this query is:\n\n- the `wl1` object has the` base` MIB\n- the properties of the base MIB are: `Name`` LLIntf` `ULIntf`` Status` `Enable`` Flags`\n- this MIB describes the graph,`wl1` being connected by a _upper_ link to the` bridge` interface and a _lower_ link to `wifi1_ath`\n- the interface is activated (`Status`)\n\nThe command is also able to establish a cross-tab between MIBs and interface to find the use. See this [result](docs/MIBs.md) where X = used, 0 = referenced but empty.\n\n    $ sysbus -MIBs table [html]\n\n### Remarks\n\n- The graph is perhaps incomplete since we only know the connections accessible blocks: we can not know the connections between two inaccessible blocks.\n- By the way, the two blocks starting with `data` and` lan` seem separate, both being at the top of two separate graphs (at least if shared Wi-Fi is not enabled). Yet the flow of data necessarily passes from one graph to another. `data` is connected to` eth1` which the external connection, to the fiber box, `lan` is connected to Wi-Fi and` eth0` which represents the switch 4 ports of the local network.\n- It remains undoubtedly to discover other information disseminated in these MIBs.\n\n## The network topology\n\nThe Livebox is more or less able to display the [network topology](http://livebox.home/supportMapper.html) from its admin page. This information is stored in the datamodel, and it has more details than the web interface wants to display.\n\nIn particular, peripherals connected in Wi-Fi 2.4GHz (interface wl0) and those connected in 5GHz (interface wl1).\n\n`sysbus` must be started with the` -topo` option to get this graph. Depending on the number of devices, the graph is very big. Adding `simple` the program only displays the device names.\n\nWe also see USB ports and UPnP.\n\n    $ sysbus -topo simple\n\n![network topology](http://rene-d.github.io/sysbus/docs/devices.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frene-d%2Fsysbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frene-d%2Fsysbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frene-d%2Fsysbus/lists"}