Contrôle par script d'une Livebox 2, 3 et 4
🇫🇷 Original version in French 🇫🇷
WARNING: I am not the author of this translation. It may contain errors or typos (especially with spaces…).
WARNING: Some information may be out of date and irrelevant since Livebox software has been updated by Orange.
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.
There is - unfortunately - no crunchy hidden information to discover, or so I have not found anything. The Livebox is closed well enough.
The script is written in Python 3. It also requires requests which greatly simplifies HTTP requests. It may use Graphviz and one of its Python interface modules graphviz to draw graphs.
It will also install the Graphviz engine. On OSX we can use brew. On Linux, sudo apt-get install graphviz
or equivalent depending on the distribution.
This should work also with Windows. Refer to the sites of the various software for installation procedures.
This installs the latest stable, released version.
$ pip3 install sysbus
$ pip3 install -r requirements.txt
$ pip3 install .
$ pip3 install requests
$ cd src/sysbus
$ ./sysbus.py -h
In this case, replace sysbus
by ./sysbus.py
in the following commands.
Nota
The Python module manuf.py displays the OUI from MAC addresses. The database manuf
can be updated with sysbus --update-oui
.
Most requests require authentication. This is the user admin
and the admin password (by default the first 8 characters of the Wi-Fi key).
The 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.
The version of the livebox defaults to lb4
(Livebox 4) but can be replaced ( lb3
for example) after the -lversion
argument.
To configure, type the following command (assuming that the password is SECRET):
$ sysbus -config -password SECRET [-url http://192.168.1.1/] [-lversion lb4]
From now on, the script will use this login information each time. One can test by asking the time of the equipment:
$ sysbus
Livebox time: Sun, 14 Feb 2016 22:08:32 GMT + 0100
A 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.
The script is also able to send almost any request, provided that it is fully specified on the command line.
$ sysbus Time:getTime
Livebox time: Sun, 14 Feb 2016 22:13:30 GMT + 0100
The -h
or --help
option displays all the possible syntax.
By browsing the sources made available by Orange here, we can establish that the Liveboxes since version 2 use a middleware developed by SoftAtHome and a home datamodel engine named “pcb”.
Unfortunately 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.
This internal datamodel communicates with the outside via an HTTP interface and JSON named “sysbus”.
This interface is used by the administration interface [http: //livebox.home] or the apps iOS and Android.
The 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.
It 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.
API 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):
curl -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
API used on old Livebox and the mobile apps:
curl -s -X POST -H "Content-Type: application/json" -d '{"parameters":{}}' http://192.168.1.1/sysbus/NMC:getWANStatus | jq .
Result:
{
"result": {
"status": true,
"data": {
"LinkType": "ethernet",
"LinkState": "up",
"MACAddress": "3C:81:D8:xx:yy:zz",
"Protocol": "dhcp",
"ConnectionState": "Bound",
"LastConnectionError": "None",
"IPAddress": "aa.bb.cc.dd",
"RemoteGateway": "aa.bb.cc.dd",
"DNSServers": "80.10.246.136,81.253.149.6",
"IPv6Address": "2a01:cb00:xyzt:abcd:1:2:3:4",
"IPv6DelegatedPrefix": "2a01:cb00:xyzt:abcd::/56"
}
}
}
jq is a tool that allows, among other things, to reformat the JSON.
Note: This request does not require authentication, unlike the time request.
# query similar to the curl example above
$ sysbus sysbus.NMC:getWANStatus
# passing parameters
$ sysbus sysbus.NMC.Wifi:set Enable=True Status=True
The 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.
Modern browser debuggers are also able to view sent queries and their results.
Another way is to use wireshark or 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.
Finally, the last source of information is the datamodel.
The sysbus interface has an interesting feature: that of being able to discover the datamodel.
For this, the HTTP request to make is a GET on the name of the object. The returned JSON describes the model.
sysbus
is able to make the return readable by detecting functions, parameters and object instances. Decoding, based solely on observation, may be incomplete.
# queries the datamodel of the NMC.Wifi object
$ sysbus NMC.Wifi -model
=========================================== level 0
OBJECT NAME: 'NMC.Wifi' (name: Wifi)
function: startPairing (opt clientPIN)
function: stopPairing ()
function: startAutoChannelSelection ()
function: getStats (out RxBytes, out TxBytes)
function: get ()
function: set (opt parameters)
parameter: Enable : bool = 'True'
parameter: Status : bool = 'True'
parameter: ConfigurationMode : bool = 'True'
Launched 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.
The -modeluml
option will create class diagrams with plantuml (see example below).
The datamodel includes some elements of different TR of the Broadband Forum (see TR-181 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).
In 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) with its management gateway on the Orange side.
The LB4’s web interface is much more advanced. The datamodel is essentially the same, with more objects.
There is also a description of methods via Json queries:
curl -s http://livebox.home/sdkut/apis/pcb/Time/getTime.json | jq .
The interfaces and pseudo-interfaces are internally organized into graphs via upper and lower connections.
The -graph
option in sysbus
uses Graphviz to display the entire graph of the interfaces.
$ sysbus -graph
In grayed out, the blocks that are inaccessible (they are discovered only thanks to the links upper and lower). And in ellipse, blocks disabled.
The 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).
Each interface manages one or more MIBs. The list can be retrieved with the command:
$ sysbus -MIBs show
The 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.
$ sysbus NeMo.Intf.wl1:getMIBs mibs=base traverse=this
{'status': {'base': {'wl1': {'Enable': True,
'Flags': 'wlanvap penable netdev enabled '
'wlanvap-bound wlansta netdev-bound '
'inbridge netdev-up up',
'LLIntf': {'wifi1_ath': {'Name': 'wifi1_ath'}},
'Name': 'wl1',
'Status': True,
'ULIntf': {'bridge': {'Name': 'bridge'}}}}}}
The interpretation of the result of this query is:
wl1
object has the base
MIBName
LLIntf
ULIntf
Status
Enable
Flags
wl1
being connected by a upper link to the bridge
interface and a lower link to wifi1_ath
Status
)The command is also able to establish a cross-tab between MIBs and interface to find the use. See this result where X = used, 0 = referenced but empty.
$ sysbus -MIBs table [html]
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.The Livebox is more or less able to display the network topology from its admin page. This information is stored in the datamodel, and it has more details than the web interface wants to display.
In particular, peripherals connected in Wi-Fi 2.4GHz (interface wl0) and those connected in 5GHz (interface wl1).
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.
We also see USB ports and UPnP.
$ sysbus -topo simple