Despite the wide spread use of the Universal Plug-N-Play protocol in applications, operating systems and embedded devices, few tools exist that allow simple discovery and interaction with UPNP-enabled devices. Further, of the tools that do exist, most or all are closed-source Windows binaries. Miranda is a Python-based UPNP client application designed to discover, query and interact with UPNP devices, particularly Internet Gateway Devices (aka, routers).
Miranda was built on and for a Linux system and has been tested on a Linux 2.6 kernel with Python 2.5. However, since it is written in Python, most functionality *should* be available for any Python-supported platform.
Miranda has been tested against IGDs from various vendors, including Linksys, D-Link, and ActionTec. All Python modules came installed by default on a Linux Mint 5 (Ubuntu 8.04) test system.
./miranda.py [OPTIONS] -s <struct file> Load previous host data from struct file -l <log file> Log user-supplied commands to log file -i <interface> Specify the name of the interface to use (Linux only, requires root) -u Disable show-uniq-hosts-only option -v Enable verbose mode -d Enable debug mode -h Show command line help If run with no options, you will be dropped into the interactive shell with the default settings.
| msearch | Actively locate UPNP hosts |
| pcap | Passively listen for UPNP hosts |
| host | View host list and host information |
| save | Save current host data to file |
| load | Restore previous host data from file |
| log | Logs user-supplied commands to a log file |
| head | Show/define HTTP headers |
| seti | Show/define application settings |
| help | Show program help |
| quit | Exit the shell |
| exit | Exit the shell |
Many of the shell commands support various sub-commands. Miranda is designed to be as self-documenting as possible, so use '<command> help' for specific command usage, descriptions and examples.
While this tutorial will not cover every command and option available in Miranda, it will walk you through the basic usage and demonstrate the tool's major capabilities.
Upon running Miranda, you will be greeted with a 'upnp>' prompt. You will likely wish to discover all UPNP hosts on your network first; this can be done with the msearch or pcap commands. The difference is that pcap will passively listen for SSDP notification messages sent out by UPNP hosts, while msearch will actively query the network for UPNP hosts. In this example, we will use the msearch command:
upnp> msearch Entering dicovery mode for 'upnp:rootdevice', Ctl+C to stop... **************************************************************** SSDP reply message from 192.168.1.1:2869 XML file is located at http://192.168.1.1:2869/IGatewayDeviceDescDoc Device is running VxWorks/5.4.2 UPnP/1.0 iGateway/1.1 **************************************************************** Discover mode halted...
Here you can see that we found one host on the network (in this case, the network's Linksys router). When run without any arguments, the msearch command will query the network for all UPNP root devices. However, if we had only been interested in UPNP hosts that are of a certian device type, or that offer a particular service, we could have queried the network for only hosts matching our criteria. For example, to search only for WANDevice UPNP devices, we could have run:
upnp> msearch device WANDevice
Likewise, if we only wanted to find hosts that support the WANIPConnection service, we could have run:
upnp> msearch service WANIPConnection
The 'host list' command will display all discovered hosts along with their host index number:
upnp> host list [0] 192.168.1.1:2869
Since the Linksys router was the first (and in this case, only) host discovered, it has a host index number of 0. This index number will be used to reference this particular host in subsequent commands.
Before moving on, let's look at a few other host commands that we can run. At this point it is important to note that all of the 'host' commands feature full tab completion; if you're unsure of what options are available to you, or what values are in a particular piece of the host data structure, pressing TAB twice will show you.
The first command we will look at is 'host summary'; this command will display a summary of the host, along with the host's device type(s) and device info. Since we haven't enumerated any of the device types and services supported by the Linksys router, this command will only display a couple lines of information that identify the host and the location of the host's main UPNP XML file:
upnp> host summary 0 Host: 192.168.1.1:2869 XML File: http://192.168.1.1:2869/IGatewayDeviceDescDoc
Next, there is the 'host info' command that lets you walk through the entire data structure that holds information about the hosts that we've discovered. Running 'host info 0' shows the following:
upnp> host info 0
xmlFile : http://192.168.1.1:2869/IGatewayDeviceDescDoc
name : 192.168.1.1:2869
proto : http://
serverType : None
upnpServer : VxWorks/5.4.2 UPnP/1.0 iGateway/1.1
dataComplete : False
deviceList : {}
You can see that the dataComplete field is set to false, indicating that we have not enumerated any detailed information about this host. However, we do know a little bit about the host just from the results of running the msearch command, including the HTTP Server header that it is using, as indicated by the upnpServer field. Note thate the value of the deviceList field is '{}'. Any field with this value indicates that it contains data sub-sets which can be further displayed with the 'host info' command like so:
upnp> host info 0 deviceList
Because we have not discovered what type of UPNP device the Linksys router is, this command will return no data at this time.
There is also the 'host details' command that will display all devices, services, actions, arguments, etc, related to a particular host. Again, we have not discovered this information yet, and the 'host details' command tells us so:
upnp> host details 0 Can't show host info because I don't have it. Please run 'host get 0'
We'll take the 'host details' suggestion and run the 'host get' command. This command will request and parse all device and service XML files that are advertised by the host, and place the extracted data into the host data structure so that we can view it using the previously mentioned host commands:
upnp> host get 0 Requesting device and service info for 192.168.1.1:2869 (this could take a few seconds)... Host data enumeration complete!
Now, let's try running the 'host summary' command again and see what it reports:
upnp> host summary 0 Host: 192.168.1.1:2869 XML File: http://192.168.1.1:2869/IGatewayDeviceDescDoc WANConnectionDevice manufacturerURL: http://www.linksys.com/ modelName: WTR54AG UPC: IGateway-01 modelNumber: WTR54AG-01 presentationURL: None fullName: urn:schemas-upnp-org:device:WANConnectionDevice:1 friendlyName: WANConnectionDevice1 modelURL: http://www.linksys.com/ modelDescription: WTR54AG UDN: uuid:34bc065f-e59a-1612-9be5-c67e816b4bfb manufacturer: Linksys WANDevice manufacturerURL: http://www.linksys.com/ modelName: WRT54G UPC: IGateway-01 modelNumber: WRT54G-01 presentationURL: None fullName: urn:schemas-upnp-org:device:WANDevice:1 friendlyName: WANDevice modelURL: http://www.linksys.com/ modelDescription: WRT54G UDN: uuid:28f8f50a-e59a-1612-9be4-c67e816b4bfb manufacturer: Linksys InternetGatewayDevice manufacturerURL: http://www.linksys.com/ modelName: WRT54G UPC: IGateway-01 modelNumber: WRT54G-01 presentationURL: http://192.168.1.1:80/ fullName : urn:schemas-upnp-org:device:InternetGatewayDevice:1 friendlyName: WRT54G modelURL: http://www.linksys.com/ modelDescription: WRT54G UDN: uuid:13814000-4ff1-11f2-9be3-c67e816b4bfb manufacturer: Linksys
If we hadn't known that this was a Linksys device before, we do now! The router is actually advertising itself as three UPNP devices: a WANConnectionDevice, a WANDevice, and an InternetGatewayDevice.
You can also try re-running the 'host details 0' command; for clarity and brevity, the output will not be shown here as this command will spit out everything it knows about the host and its devices/services, which at this point is quite a bit. You will probably want to save this output to disk in order to view it more easily; this can be done with the 'save info' command:
upnp> save info 0 wrt54g Host info for '192.168.1.1:2869' saved to 'info_wrt54g.mir'
The 'wrt54g' file name is an optional argument; if it had not been supplied, then the host index number would have been used ('info_0.mir').
If you wish to save your data to share with others or to view at a later date, you can use the 'save data' command. This will save the entire host structure that contains all the information about all of the UPNP hosts that you have discovered and enumerated during your session:
upnp> save data wrt54g Host data saved to 'struct_wrt54g.mir'
This data can later be imported back into Miranda using the 'load' command:
upnp> load struct_wrt54g.mir Host data restored: [0] 192.168.1.1:2869
Because this data structure is saved using Python's pickle module, any other Python script can load the file for analysis using pickle.
Let's now see if we can view the deviceList values with the 'host info' command that we tried earlier:
upnp> host info 0 deviceList
WANConnectionDevice : {}
WANDevice : {}
InternetGatewayDevice : {}
The three device types are listed here, and they have additional information that can be enumerated. You can explore the various fields and options as you like, but for brevity, we will examine only a couple of the most interesting; the first of these is the 'services' field which exists for each device listed in the deviceList. Taking a look at the services field for the WANConnectionDevice shows that it offers two services, WANIPConnection and WANEthernetLinkConfig:
upnp> host info 0 deviceList WANConnectionDevice services
WANIPConnection : {}
WANEthernetLinkConfig : {}
Each service also contains several sub-fields, but the one that we are most concerned with is the 'actions' field which shows the actions that each service supports (if this command looks too long to type, don't worry; use the tab completion!):
upnp> host info 0 deviceList WANConnectionDevice services WANIPConnection actions
AddPortMapping : {}
GetWarnDisconnectDelay : {}
GetGenericPortMappingEntry : {}
GetSpecificPortMappingEntry : {}
RequestTermination : {}
ForceTermination : {}
GetExternalIPAddress : {}
GetConnectionTypeInfo : {}
GetIdleDisconnectTime : {}
GetStatusInfo : {}
SetConnectionType : {}
DeletePortMapping : {}
GetAutoDisconnectTime : {}
RequestConnection : {}
GetNATRSIPStatus : {}
Now that we know what devices, services, and actions exist, we can start sending UPNP commands to the Linksys router. We will try running the GetExternalIPAddress action that is supported by the WANIPConnection service offered by the WANConnectionDevice device. To send commands to a UPNP host, use the 'host send' command; you must specify the host index number, the device name, the service name, and the action name, in that order. If the action requires any input values, you will be prompted for them automatically, as well as being informed of those value's type, allowed use, and default values/ranges, if any. The GetExternalIPAddress does not require any input, so it runs immediately:
upnp> host send 0 WANConnectionDevice WANIPConnection GetExternalIPAddress NewExternalIPAddress : 69.123.45.678
The NewExternalIPAddress is the name of the output service state variable associated with the GetExternalIPAddress (some actions have several variables associated with them, but in this case there is only one), and 69.123.45.678 is the value that the UPNP host returned for that variable, which in this case is the IP address of the WAN interface.
Now let's look at a more complex request; we will attempt to forward data from port 8080 of the external WAN interface to port 80 of the router via the AddPortMapping action, essentially enabling remote administration for the router:
upnp> host send 0 WANConnectionDevice WANIPConnection AddPortMapping Required argument: Argument Name: NewPortMappingDescription Data Type: string Allowed Values: [] Set NewPortMappingDescription value to: Test Description Required argument: Argument Name: NewLeaseDuration Data Type: ui4 Allowed Values: [] Set NewLeaseDuration value to: 0 Required argument: Argument Name: NewInternalClient Data Type: string Allowed Values: [] Set NewInternalClient value to: 192.168.1.1 Required argument: Argument Name: NewEnabled Data Type: boolean Allowed Values: [] Set NewEnabled value to: 1 Required argument: Argument Name: NewExternalPort Data Type: ui2 Allowed Values: [] Set NewExternalPort value to: 8080 Required argument: Argument Name: NewRemoteHost Data Type: string Allowed Values: [] Set NewRemoteHost value to: Required argument: Argument Name: NewProtocol Data Type: string Allowed Values: ['TCP', 'UDP'] Set NewProtocol value to: TCP Required argument: Argument Name: NewInternalPort Data Type: ui2 Allowed Values: [] Set NewInternalPort value to: 80
Note that several values were required to run this action, and that we were prompted for each one. Note that boolean values are either '1' (true) or '0' (false). By leaving the NewRemoteHost value blank, we allow any remote host to use this port mapping. Since this action does not return any values, there is no output (no news is good news).
We can verify that the port mapping was successful by invoking the GetSpecificPortMappingEntry action; this action requires that we input the external port number, external host, and protocol type of the port mapping entry we are interested in:
upnp> host send 0 WANConnectionDevice WANIPConnection GetSpecificPortMappingEntry Required argument: Argument Name: NewExternalPort Data Type: ui2 Allowed Values: [] Set NewExternalPort value to: 8080 Required argument: Argument Name: NewRemoteHost Data Type: string Allowed Values: [] Set NewRemoteHost value to: Required argument: Argument Name: NewProtocol Data Type: string Allowed Values: ['TCP', 'UDP'] Set NewProtocol value to: TCP NewPortMappingDescription : Test Description NewLeaseDuration : 0 NewInternalClient : 192.168.1.1 NewEnabled : 1 NewInternalPort : 80
Finally, we can delete this port mapping entry using the DeletePortMapping action, which requires the same input parameters as the GetSpecificPortMappingEntry action did:
upnp> host send 0 WANConnectionDevice WANIPConnection DeletePortMapping Required argument: Argument Name: NewProtocol Data Type: string Allowed Values: ['TCP', 'UDP'] Set NewProtocol value to: TCP Required argument: Argument Name: NewExternalPort Data Type: ui2 Allowed Values: [] Set NewExternalPort value to: 8080 Required argument: Argument Name: NewRemoteHost Data Type: string Allowed Values: [] Set NewRemoteHost value to:
Again, no news is good news, and if we try to run GetSpecificPortMappingEntry after deleting the port mapping, we get an error indicating that the port mapping no longer exists:
upnp> host send 0 WANConnectionDevice WANIPConnection GetSpecificPortMappingEntry Required argument: Argument Name: NewExternalPort Data Type: ui2 Allowed Values: [] Set NewExternalPort value to: 8080 Required argument: Argument Name: NewRemoteHost Data Type: string Allowed Values: [] Set NewRemoteHost value to: Required argument: Argument Name: NewProtocol Data Type: string Allowed Values: ['TCP', 'UDP'] Set NewProtocol value to: TCP Request for 'http://192.168.1.1:2869/WANIPConnCtrlUrl' failed with error code: 500 SOAP error message: NoSuchEntryInArray
Miranda has many other features, and is designed to be self-documenting; all of the shell commands have their own help information that detail usage and sub-commands, and provide descriptions and examples. However, the above command set comprises 99% of what you will probably want to use Miranda for, and details the steps to discover and interact with UPNP devices on your network.
Send all comments/suggestions/bugs/etc to Craig Heffner, dev [at] sourcesec.com.