Exiting the Matrix: Introducing Metasploit's Hardware Bridge

Metasploit is an amazing tool. You can use it to maneuver through vast networks, pivoting through servers and even embedded OSes.  Having a single interface for your team and yourself to control a web of servers and networks is extremely powerful.  But sometimes you want to do more than control the virtual world. You want to control the physical world. You need to exit the Matrix.

We recently announced a new addition to Metasploit to help you do exactly that: the Hardware Bridge API. The Hardware Bridge API extends Metasploit’s capabilities into the physical world of hardware devices. Much in the same way that the Metasploit framework helped unify tools and exploits for networks and software, the Hardware Bridge looks to do the same for all types of hardware. From within Metasploit you can now branch out into a Metasploit compatible hardware device to remotely control and use it for your penetration testing needs.

How does it work?

There are two ways to connect a physical device to Metasploit:

1. Build support directly into your firmware to make your device Metasploit compatible, or
2. Create a relay service.

A relay service is required if your device does not have a way to naturally communicate on Ethernet. Many useful hardware tools such as Software Defined Radio (SDR) devices are controlled solely through a USB port. In order to connect an SDR device like this to Metaslpoit then the machine that SDR is connected to would run a relay service. This uses a REST API, the details of which can be found here: Metasploit Hardware Bridge API.

Why REST?

There are trade-offs with any solution. Embedded systems typically don't support REST because that would require they run some types of mini-web server. Newer embedded systems, especially IoT devices, have no problem running web servers locally but if you have hardware that doesn't have WiFi or Ethernet capabilities we make it easy to create relays for your device. We will provide several examples in the Metasploit tools section demonstrating how to leverage the Metasploit framework to handle all of your http/web needs so you can focus on serial, usb, or whatever communication channel your device uses. We also plan on providing libraries for common microcontrollers and embedded systems to quickly allow your device to support Metasploit.

So what can the Hardware Bridge do?

Technically, anything. The API provides some core functionality that you *should* support, although most of commands are optional. These core features mainly watch power, and get versioning information and the devices capabilities. There are certain "specialties" the device can support that will trigger extra capabilities on the Metasploit end. At launch, this will include the Automotive extension.

Getting out of your dreams, getting into your car

If your device supports CAN, Metasploit will automatically provide several interactive vehicle-related commands. This will also mark your Hardware Bridge (HWBridge) session as an Automotive session that can be viewed in your session list or via modules that are designed to work only on automotive systems. This allows exploit developers to focus on writing automotive tools without having to worry about the attached hardware. It also provides internal Metasploit APIs to make common automotive calls easier, such as getting the vehicle speed or requesting a security access token from the Engine Control Unit (ECU).

Hardware devices can teach Metasploit new tricks! You don't have to wait for Metasploit updates or specific support for your new device. Hardware devices can expose any functionality they have to the Metasploit Framework. This is typically something that is unique to your hardware device. It could be as simple as exposing the LEDs, or as complicated as a series of commands that run on MIL-STD-1553 bus systems. When functionality is taught via the API to Metasploit, they show up as interactive commands in the HWBridge session. This allows for support of specific hardware support without forcing the developer to the strict rules of an API, and these commands can also be used by post exploitation modules.

How can I use it?

If you have read this far I can assume you are ready to take the red pill. This first release comes with support for SocketCAN. If you have a Linux system and a CAN bus sniffer that support SocketCAN you can get started without anything else. The local_hwbridge module is provided as an example of a simple relay system. You can run the relay locally or on a remote machine.

msf > use auxiliary/server/local_hwbridge

msf auxiliary(local_hwbridge) > run

[*] Auxiliary module execution completed

[*] Using URL: http://0.0.0.0:8080/6xOv7GqFs3YTeIE

[*] Local IP: http://10.1.10.21:8080/6xOv7GqFs3YTeIE

[*] Server started.

msf auxiliary(local_hwbridge) >

The local_hwbridge defaults will automatically detect any SocketCAN interfaces you have and should just work without having to type in any options. A relay service does not have to run within Metasploit but can be its own service, or if the REST API is supported by the hardware itself, you can skip this step. Next you need to connect to a relay or a supported piece of hardware to establish a HWBridge session.

msf > use auxiliary/client/hwbridge/connect

msf auxiliary(connect) > set rhost 10.1.10.21

rhost => 10.1.10.21

msf auxiliary(connect) > set targeturi 6xOv7GqFs3YTeIE

targeturi => 6xOv7GqFs3YTeIE

msf auxiliary(connect) > run

[*] Attempting to connect to 10.1.10.21...

[*] Hardware bridge interface session 1 opened (127.0.0.1 -> 127.0.0.1) at 2017-01-17 11:02:34 -0800

[+] HWBridge session established

[*] HW Specialty: {"automotive"=>true}  Capabilities: {"can"=>true, "custom_methods"=>true}

[!] NOTICE:  You are about to leave the matrix.  All actions performed on this hardware bridge

[!]          could have real world consequences.  Use this module in a controlled testing

[!]          environment and with equipment you are authorized to perform testing on.

[*] Auxiliary module execution completed

msf auxiliary(connect) > sessions

Active sessions

===============

Id  Type                   Information  Connection

--  ----                   -----------  ----------

1   hwbridge cmd/hardware  automotive   127.0.0.1 -> 127.0.0.1 (10.1.10.21)

Once connected, a HWBridge session will be established. If you are familiar with using meterpreter you will feel very at home using a hwbridge. Jumping on a session you can see a list of commands by typing help or run a post module such as the supplied getvinfo (Get Vehicle Info) module.

msf auxiliary(connect) > sess 1

[*] Starting interaction with 1...

hwbridge > supported_buses

Available buses

can0, can1, can2

hwbridge > run post/hardware/automotive/getvinfo CANBUS=can2

[*] Available PIDS for pulling realtime data: 46 pids

[*]   [1, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16, 17, 19, 20, 21, 24, 25, 28, 31, 32, 32, 33, 44, 45, 46, 47, 48, 49, 50, 51, 60, 61, 64, 65, 66, 67, 68, 69, 70, 71, 73, 74, 76]

[*]   MIL (Engine Light) : OFF

[*]   Number of DTCs: 0

[*]   Engine Temp: 48 °C / 118 °F

[*]   RPMS: 0

[*]   Speed: 0 km/h  /  0.0 mph

[*] Supported OBD Standards: OBD and OBD-II

[*] Mode $09 Vehicle Info Supported PIDS: [2, 4, 6, 8]

[*] VIN: 1G1ZT53826F109149

[*] Calibration ID: UDS ERR: {"RCRRP"=>"Request Correctly Received, but Response is Pending"}

[*] PID 6 Response: ["00", "00", "C4", "E9", "00", "00", "17", "33", "00", "00", "00", "00"]

[*] PID 8 Response: ["00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00"]

Feel free to look at the source to post/hardware/automotive/getvinfo.rb to see how to use Metasploit's Unified Diagnostic Service (UDS) API to make modules like these very simple. There are a lot more automotive modules and other services coming.

How can I help?

This is the initial release of the HWBridge. We are looking for feedback from both hardware developers and exploit writers. If there are automotive features you would like to see, let us know. If you’re a hardware developer who wants to be Metasploit compatible, let us know how we can help you.

Metasploit condensed a slew of independent software exploits and tools into one framework and now we want to do the same for hardware. As you exit the Matrix, please watch your step!