Hardware Bridge Session Connector - Metasploit
This page contains detailed information about how to use the auxiliary/client/hwbridge/connect metasploit module. For list of all metasploit modules, visit the Metasploit Module Library.
Module Overview
Name: Hardware Bridge Session Connector
Module: auxiliary/client/hwbridge/connect
Source code: modules/auxiliary/client/hwbridge/connect.rb
Disclosure date: -
Last modification time: 2021-01-05 14:59:46 +0000
Supported architecture(s): -
Supported platform(s): -
Target service / protocol: http, https
Target network port(s): 80, 443, 3000, 8000, 8008, 8080, 8443, 8880, 8888
List of CVEs: -
The Hardware Bridge (HWBridge) is a standardized method for Metasploit to interact with Hardware Devices. This extends the normal exploit capabilities to the non-ethernet realm and enables direct hardware and alternative bus manipulations. You must have compatible bridging hardware attached to this machine or reachable on your network to use any HWBridge exploits. Use this exploit module to connect the physical HWBridge which will start an interactive hwbridge session. You can launch a hwbridge server locally by using compliant hardware and executing the local_hwbridge module. After that module has started, pass the HWBRIDGE_BASE_URL options to this connector module.
Module Ranking and Traits
Module Ranking:
- normal: The exploit is otherwise reliable, but depends on a specific version and can't (or doesn't) reliably autodetect. More information about ranking can be found here.
Basic Usage
msf > use auxiliary/client/hwbridge/connect
msf auxiliary(connect) > show targets
... a list of targets ...
msf auxiliary(connect) > set TARGET target-id
msf auxiliary(connect) > show options
... show and set options ...
msf auxiliary(connect) > exploit
Knowledge Base
Overview
This module connects to any Hardware device that supports the HWBridge API. For details on the HWBridge API see API Reference. On successful connection to a HWBridge a HWBridge session will be established.
Devices
When run on linux you can use the auxiliary/server/local_hwbridge to talk to any device supported by SocketCAN. It will work with natively supported devices (can), serial devices (slcan) and even virtual devices (vcan). For a list of supported SocketCAN hardware see the eLinux website.
Any ELM327 or STN1100 interface will work with the HWBridge. If you pick up any device that uses either of these chipsets can can connect via serial (USB or Bluetooth) it will work. These are popular and inexpensive devices. They are not as fast as some of the native CAN devices but they are plentiful and cheap.
This module was also tested with the Particle Photon board. To utilize a Particle.io Photon board you will want to add the spark-msf-relay library to your project. See the library examples for details on how to extend your project to integrate it with Metasploit. If you are building an automotive project and you are using the Carloop then the spark-msf-relay library also includes an example app for carloop that you can simply flash to the device for full support.
- Generic ELM327: ebay
Bluetooth Adapter Connection
Bluetooth HWBridge adapters, depending on the Operating System, may take several additional steps to establish a connection and communications bus. The following steps were recorded during the testing of this module on setting up the BAFX 34t5 with Kali Linux 2016.2 (rolling).
- Most Bluetooth HWBridge adapters, speak serial. So you will need to get the ruby gem "serialport":
gem install serialport
- Ensure no locks on the Bluetooth device via:
rfkill list
(and subsequentunblock
commands) - Make sure Bluetooth service is started:
/etc/init.d/bluetooth start
, orbluetoothd
- Start bluetoothctl:
bluetoothctl
- Turn on scanning:
scan on
- Turn on agent:
agent on
- Make sure we can see OBDII:
devices
- Attempt to pair:
[bluetooth]# pair 00:0D:18:AA:AA:AA
Attempting to pair with 00:0D:18:AA:AA:AA
[CHG] Device 00:0D:18:AA:AA:AA Connected: yes
- If prompted for pin:
1234
- Trust the device in order to not put in the pin again:
trust 00:0D:18:AA:AA:AA
- Use rfcomm to make the connection and serial interface in a different window (not bluetoothctl):
rfcomm connect /dev/rfcomm1 "00:0D:18:AA:AA:AA"
Options
TARGETURI
Specifies the base target URI to communicate to the HWBridge API. By default this is '/' but it could be things such as '/api' or the randomly generated URI from the local_hwbridge module
DEBUGJSON
Prints out all the JSON packets that come from the HWBridge API. Useful for troubleshooting a device.
This module also supports all the other HTTP Client options typical to Metaplsoit.
Sample Connection
For an example, lets say we connect to a HW Bridge that is designed for automotive use and has support for multiple CAN buses. The remote device in our example is called 'carhax'
msf > use auxiliary/client/hwbridge/connect
msf auxiliary(connect) > set rhost carhax
rhost => carhax
msf auxiliary(connect) > run
[*] Attempting to connect to carhax...
[*] Hardware bridge interface session 1 opened (127.0.0.1 -> 127.0.0.1) at 2016-12-29 13:49:55 -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
On successful connection to a Hardware device you will be prompted with a special notice to remind you that any action you take on the HWBridge could have physical affects and consequences. Our lawyers asked us to put that there. You can verify the session was created by type 'sessions'
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)
Automotive Extension
If a device specifies a hw_specialty then it can load custom extensions. For instance, if a defice defines its specialty is automotive then Metasploit will load a custom automotive extension that gives you a few generic commands you can use on autotive systems such as the ability to send arbitrary CAN packets down the bus. It also allows you to run any post/hardware/automotive modules.
For instance you can run post/hardware/automtive/getvinfo to retrieve vehicle information via UDS Mode $9 commands.
hwbridge > run post/hardware/automotive/getvinfo CANBUS=can2
[*] Supported PIDS: [2, 4, 6, 8]
[*] VIN: 1G1ZT53826F109149
[*] Calibration ID: x
[*] 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"]
run 'supported_buses' for a list of available buses provided by your hardware. And as always you can type 'help' for a list of available commands and each command should support '-h' to additional argument help.
Custom Method Extension
It is possible for the hardware device to report functionality that Metasploit has no knowledge of. For instance, perhaps the device has a unique capability that isn't standard or can be done 100% in hardware. In order to utilize that functionality the HW device can report that it has custom_methods as a capability. At which point Metasploit will then query the custom methods and their argument syntax. These methods will become available as command line options within the hardware bridge.
For a simple example of a custom method see auxiliary/server/local_hwbridge for a more complete list on how to define custom methods see the API Reference.
Go back to menu.
Msfconsole Usage
Here is how the client/hwbridge/connect auxiliary module looks in the msfconsole:
msf6 > use auxiliary/client/hwbridge/connect
msf6 auxiliary(client/hwbridge/connect) > show info
Name: Hardware Bridge Session Connector
Module: auxiliary/client/hwbridge/connect
License: Metasploit Framework License (BSD)
Rank: Normal
Provided by:
Craig Smith
Check supported:
No
Basic options:
Name Current Setting Required Description
---- --------------- -------- -----------
DEBUGJSON false no Additional debugging out for JSON requests to HW Bridge
Proxies no A proxy chain of format type:host:port[,type:host:port][...]
RHOSTS 127.0.0.1 yes The target host(s), range CIDR identifier, or hosts file with syntax 'file:<path>'
RPORT 8080 yes The target port (TCP)
SSL false no Negotiate SSL/TLS for outgoing connections
TARGETURI / yes The path to the hwbridge API
VHOST no HTTP server virtual host
Description:
The Hardware Bridge (HWBridge) is a standardized method for
Metasploit to interact with Hardware Devices. This extends the
normal exploit capabilities to the non-ethernet realm and enables
direct hardware and alternative bus manipulations. You must have
compatible bridging hardware attached to this machine or reachable
on your network to use any HWBridge exploits. Use this exploit
module to connect the physical HWBridge which will start an
interactive hwbridge session. You can launch a hwbridge server
locally by using compliant hardware and executing the local_hwbridge
module. After that module has started, pass the HWBRIDGE_BASE_URL
options to this connector module.
References:
http://opengarages.org/hwbridge
Module Options
This is a complete list of options available in the client/hwbridge/connect auxiliary module:
msf6 auxiliary(client/hwbridge/connect) > show options
Module options (auxiliary/client/hwbridge/connect):
Name Current Setting Required Description
---- --------------- -------- -----------
DEBUGJSON false no Additional debugging out for JSON requests to HW Bridge
Proxies no A proxy chain of format type:host:port[,type:host:port][...]
RHOSTS 127.0.0.1 yes The target host(s), range CIDR identifier, or hosts file with syntax 'file:<path>'
RPORT 8080 yes The target port (TCP)
SSL false no Negotiate SSL/TLS for outgoing connections
TARGETURI / yes The path to the hwbridge API
VHOST no HTTP server virtual host
Advanced Options
Here is a complete list of advanced options supported by the client/hwbridge/connect auxiliary module:
msf6 auxiliary(client/hwbridge/connect) > show advanced
Module advanced options (auxiliary/client/hwbridge/connect):
Name Current Setting Required Description
---- --------------- -------- -----------
DOMAIN WORKSTATION yes The domain to use for Windows authentication
DigestAuthIIS true no Conform to IIS, should work for most servers. Only set to false for non-IIS servers
FingerprintCheck true no Conduct a pre-exploit fingerprint verification
HttpClientTimeout no HTTP connection and receive timeout
HttpPassword no The HTTP password to specify for authentication
HttpRawHeaders no Path to ERB-templatized raw headers to append to existing headers
HttpTrace false no Show the raw HTTP requests and responses
HttpTraceColors red/blu no HTTP request and response colors for HttpTrace (unset to disable)
HttpTraceHeadersOnly false no Show HTTP headers only in HttpTrace
HttpUsername no The HTTP username to specify for authentication
SSLVersion Auto yes Specify the version of SSL/TLS to be used (Auto, TLS and SSL23 are auto-negotiate) (Accepted: Auto, TLS, SSL23, SSL3, TLS1, TLS1.1, TLS1.2)
UserAgent Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1) no The User-Agent header to use for all requests
VERBOSE false no Enable detailed status messages
WORKSPACE no Specify the workspace for this module
Auxiliary Actions
This is a list of all auxiliary actions that the client/hwbridge/connect module can do:
msf6 auxiliary(client/hwbridge/connect) > show actions
Auxiliary actions:
Name Description
---- -----------
Evasion Options
Here is the full list of possible evasion options supported by the client/hwbridge/connect auxiliary module in order to evade defenses (e.g. Antivirus, EDR, Firewall, NIDS etc.):
msf6 auxiliary(client/hwbridge/connect) > show evasion
Module evasion options:
Name Current Setting Required Description
---- --------------- -------- -----------
HTTP::header_folding false no Enable folding of HTTP headers
HTTP::method_random_case false no Use random casing for the HTTP method
HTTP::method_random_invalid false no Use a random invalid, HTTP method for request
HTTP::method_random_valid false no Use a random, but valid, HTTP method for request
HTTP::pad_fake_headers false no Insert random, fake headers into the HTTP request
HTTP::pad_fake_headers_count 0 no How many fake headers to insert into the HTTP request
HTTP::pad_get_params false no Insert random, fake query string variables into the request
HTTP::pad_get_params_count 16 no How many fake query string variables to insert into the request
HTTP::pad_method_uri_count 1 no How many whitespace characters to use between the method and uri
HTTP::pad_method_uri_type space no What type of whitespace to use between the method and uri (Accepted: space, tab, apache)
HTTP::pad_post_params false no Insert random, fake post variables into the request
HTTP::pad_post_params_count 16 no How many fake post variables to insert into the request
HTTP::pad_uri_version_count 1 no How many whitespace characters to use between the uri and version
HTTP::pad_uri_version_type space no What type of whitespace to use between the uri and version (Accepted: space, tab, apache)
HTTP::uri_dir_fake_relative false no Insert fake relative directories into the uri
HTTP::uri_dir_self_reference false no Insert self-referential directories into the uri
HTTP::uri_encode_mode hex-normal no Enable URI encoding (Accepted: none, hex-normal, hex-noslashes, hex-random, hex-all, u-normal, u-all, u-random)
HTTP::uri_fake_end false no Add a fake end of URI (eg: /%20HTTP/1.0/../../)
HTTP::uri_fake_params_start false no Add a fake start of params to the URI (eg: /%3fa=b/../)
HTTP::uri_full_url false no Use the full URL for all HTTP requests
HTTP::uri_use_backslashes false no Use back slashes instead of forward slashes in the uri
HTTP::version_random_invalid false no Use a random invalid, HTTP version for request
HTTP::version_random_valid false no Use a random, but valid, HTTP version for request
Go back to menu.
Error Messages
This module may fail with the following error messages:
- Access Denied: <RES.BODY>
- SSL error
- Unable to Connect
- Timeout error
- 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.
- Could not connect to API
Check for the possible causes from the code snippets below found in the module source code. This can often times help in identifying the root cause of the problem.
Access Denied: <RES.BODY>
Here is a relevant code snippet related to the "Access Denied: <RES.BODY>" error message:
63: return nil if !res || !res.body || !res.code
64: if res.code == 200
65: print_status res.body if datastore['DEBUGJSON'] == true
66: return JSON.parse(res.body)
67: elsif res.code == 401
68: print_error "Access Denied: #{res.body}"
69: end
70: return nil
71:
72: rescue OpenSSL::SSL::SSLError
73: vprint_error("SSL error")
SSL error
Here is a relevant code snippet related to the "SSL error" error message:
68: print_error "Access Denied: #{res.body}"
69: end
70: return nil
71:
72: rescue OpenSSL::SSL::SSLError
73: vprint_error("SSL error")
74: return nil
75: rescue Errno::ENOPROTOOPT, Errno::ECONNRESET, ::Rex::ConnectionRefused, ::Rex::HostUnreachable, ::Rex::ConnectionTimeout, ::ArgumentError
76: vprint_error("Unable to Connect")
77: return nil
78: rescue ::Timeout::Error, ::Errno::EPIPE
Unable to Connect
Here is a relevant code snippet related to the "Unable to Connect" error message:
71:
72: rescue OpenSSL::SSL::SSLError
73: vprint_error("SSL error")
74: return nil
75: rescue Errno::ENOPROTOOPT, Errno::ECONNRESET, ::Rex::ConnectionRefused, ::Rex::HostUnreachable, ::Rex::ConnectionTimeout, ::ArgumentError
76: vprint_error("Unable to Connect")
77: return nil
78: rescue ::Timeout::Error, ::Errno::EPIPE
79: vprint_error("Timeout error")
80: return nil
81:
Timeout error
Here is a relevant code snippet related to the "Timeout error" error message:
74: return nil
75: rescue Errno::ENOPROTOOPT, Errno::ECONNRESET, ::Rex::ConnectionRefused, ::Rex::HostUnreachable, ::Rex::ConnectionTimeout, ::ArgumentError
76: vprint_error("Unable to Connect")
77: return nil
78: rescue ::Timeout::Error, ::Errno::EPIPE
79: vprint_error("Timeout error")
80: return nil
81:
82: end
83:
84: #
NOTICE: You are about to leave the matrix. All actions performed on this hardware bridge
Here is a relevant code snippet related to the "NOTICE: You are about to leave the matrix. All actions performed on this hardware bridge" error message:
83:
84: #
85: # Disclaimer for legal and those without common sense...
86: #
87: def print_disclaimer
88: print_warning("NOTICE: You are about to leave the matrix. All actions performed on this hardware bridge")
89: print_warning(" could have real world consequences. Use this module in a controlled testing")
90: print_warning(" environment and with equipment you are authorized to perform testing on.")
91: end
92:
93: #
could have real world consequences. Use this module in a controlled testing
Here is a relevant code snippet related to the "could have real world consequences. Use this module in a controlled testing" error message:
84: #
85: # Disclaimer for legal and those without common sense...
86: #
87: def print_disclaimer
88: print_warning("NOTICE: You are about to leave the matrix. All actions performed on this hardware bridge")
89: print_warning(" could have real world consequences. Use this module in a controlled testing")
90: print_warning(" environment and with equipment you are authorized to perform testing on.")
91: end
92:
93: #
94: # Uses status information to automatically load proper extensions
environment and with equipment you are authorized to perform testing on.
Here is a relevant code snippet related to the "environment and with equipment you are authorized to perform testing on." error message:
85: # Disclaimer for legal and those without common sense...
86: #
87: def print_disclaimer
88: print_warning("NOTICE: You are about to leave the matrix. All actions performed on this hardware bridge")
89: print_warning(" could have real world consequences. Use this module in a controlled testing")
90: print_warning(" environment and with equipment you are authorized to perform testing on.")
91: end
92:
93: #
94: # Uses status information to automatically load proper extensions
95: #
Could not connect to API
Here is a relevant code snippet related to the "Could not connect to API" error message:
160: autoload_extensions(sess)
161: load_custom_methods(sess)
162: print_status "HW Specialty: #{self.hw_specialty} Capabilities: #{self.hw_capabilities}"
163: print_disclaimer
164: else
165: print_error "Could not connect to API"
166: end
167: end
168:
169: attr_reader :hw_specialty
170: attr_reader :hw_capabilities
Go back to menu.
Related Pull Requests
- #14584 Merged Pull Request: Implement the zeitwerk autoloader within lib/msf/base
- #8951 Merged Pull Request: Hwbridge auto padding fix and flowcontrol
- #8888 Merged Pull Request: spelling/grammar fixes part 1
- #8716 Merged Pull Request: Print_Status -> Print_Good (And OCD bits 'n bobs)
- #8338 Merged Pull Request: Fix msf/core and self.class msftidy warnings
- #8155 Merged Pull Request: Style fixes for HWBridge RF and a couple small bug fixes
- #7935 Merged Pull Request: HWBridge RF transceiver extension
- #7967 Merged Pull Request: DTC Improvements and Fixes
- #8065 Merged Pull Request: Zigbee Hardware Bridge Extension
- #7795 Merged Pull Request: Hardware Bridge API. Initial bridge API that supports the HW rest pr…
References
See Also
Check also the following modules related to this module:
- exploit/linux/http/atlassian_confluence_webwork_ognl_injection
- exploit/multi/http/atlassian_confluence_webwork_ognl_injection
- exploit/linux/http/trendmicro_imsva_widget_exec
- exploit/multi/http/totaljs_cms_widget_exec
- exploit/multi/http/vbulletin_widgetconfig_rce
- exploit/multi/http/vbulletin_widget_template_rce
- exploit/windows/http/trendmicro_officescan_widget_exec
- exploit/unix/webapp/elfinder_php_connector_exiftran_cmd_injection
- auxiliary/fuzzers/smb/smb_tree_connect
- auxiliary/fuzzers/smb/smb_tree_connect_corrupt
- auxiliary/scanner/mqtt/connect
- exploit/linux/misc/ib_inet_connect
- exploit/multi/browser/adobe_flash_net_connection_confusion
- exploit/multi/browser/java_rmi_connection_impl
- exploit/multi/http/confluence_widget_connector
- exploit/unix/webapp/openview_connectednodes_exec
- exploit/unix/webapp/spip_connect_exec
- exploit/windows/browser/orbit_connecting
- exploit/windows/browser/synactis_connecttosynactis_bof
- exploit/windows/http/manageengine_connectionid_write
- exploit/windows/http/sws_connection_bof
- exploit/windows/mmsp/ms10_025_wmss_connect_funnel
- post/linux/busybox/enum_connections
- post/windows/wlan/wlan_current_connection
- exploit/windows/browser/cisco_anyconnect_exec
- exploit/windows/local/anyconnect_lpe
- post/windows/wlan/wlan_disconnect
- auxiliary/client/iec104/iec104
- auxiliary/client/mms/send_mms
- auxiliary/client/sms/send_text
- auxiliary/client/smtp/emailer
- auxiliary/client/telegram/send_message
- auxiliary/server/local_hwbridge
Authors
- Craig Smith
Version
This page has been produced using Metasploit Framework version 6.1.27-dev. For more modules, visit the Metasploit Module Library.
Go back to menu.