Skip to content

Commit 23c2787

Browse files
pbarry-r7pbarry-r7
committed
Land rapid7#7795, Hardware Bridge API.
Initial bridge API that supports the HW rest protocol.
2 parents 6522c0d + c7e6d1a commit 23c2787

File tree

32 files changed

+4160
-0
lines changed

32 files changed

+4160
-0
lines changed

‎documentation/modules/auxiliary/client/hwbridge/connect.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
## Overview
2+
3+
This module connects to any Hardware device that supports the HWBridge API. For details
4+
on the HWBridge API see [API Reference](http://opengarages.org/hwbridge). On successful connection to a HWBridge a
5+
HWBridge session will be established.
6+
7+
## Devices
8+
9+
When run on linux you can use the auxiliary/server/local_hwbridge to talk to any device supported by SocketCAN.
10+
It will work with natively supported devices (can), serial devices (slcan) and even virtual devices (vcan). For
11+
a list of supported SocketCAN hardware see the [eLinux website](http://elinux.org/CAN_Bus).
12+
13+
Any ELM327 or STN1100 interface will work with the HWBridge. If you pick up any device that uses either of
14+
these chipsets can can connect via serial (USB or Bluetooth) it will work. These are popular and inexpensive
15+
devices. They are not as fast as some of the native CAN devices but they are plentiful and cheap.
16+
17+
This module was also tested with the [Particle](https://Particle.io) Photon board. To utilize a Particle.io Photon board you
18+
will want to add the spark-msf-relay library to your project. See the library examples for details on
19+
how to extend your project to integrate it with Metasploit. If you are building an automotive project
20+
and you are using the [Carloop](https://carloop.io) then the spark-msf-relay library also includes an example app for carloop
21+
that you can simply flash to the device for full support.
22+
23+
2. Generic ELM327: [ebay](http://www.ebay.com/itm/like/221821719820)
24+
25+
## Bluetooth Adapter Connection
26+
27+
Bluetooth HWBridge adapters, depending on the Operating System, may take several additional steps to establish a connection and communications bus.
28+
The following steps were [recorded during the testing of this module](https://github.com/rapid7/metasploit-framework/pull/7795#issuecomment-274302326)
29+
on setting up the [BAFX 34t5](https://bafxpro.com/products/obdreader) with Kali Linux 2016.2 (rolling).
30+
31+
1. Ensure no locks on the Bluetooth device via: `rfkill list` (and subsequent `unblock` commands)
32+
2. Make sure Bluetooth service is started: `/etc/init.d/bluetooth start`, or `bluetoothd`
33+
3. Start bluetoothctl: `bluetoothctl`
34+
4. Turn on scanning: `scan on`
35+
5. Turn on agent: `agent on`
36+
6. Make sure we can see OBDII: `devices`
37+
7. Attempt to pair: `[bluetooth]# pair 00:0D:18:AA:AA:AA`
38+
39+
```
40+
Attempting to pair with 00:0D:18:AA:AA:AA
41+
[CHG] Device 00:0D:18:AA:AA:AA Connected: yes
42+
```
43+
9. If prompted for pin: `1234`
44+
10. Trust the device in order to not put in the pin again: `trust 00:0D:18:AA:AA:AA`
45+
11. 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"`
46+
47+
## Options
48+
49+
**TARGETURI**
50+
51+
Specifies the base target URI to communicate to the HWBridge API. By default this is '/' but it
52+
could be things such as '/api' or the randomly generated URI from the local_hwbridge module
53+
54+
**DEBUGJSON**
55+
56+
Prints out all the JSON packets that come from the HWBridge API. Useful for troubleshooting
57+
a device.
58+
59+
This module also supports all the other HTTP Client options typical to Metaplsoit.
60+
61+
## Sample Connection
62+
63+
For an example, lets say we connect to a HW Bridge that is designed for automotive use
64+
and has support for multiple CAN buses. The remote device in our example is called 'carhax'
65+
66+
```
67+
msf > use auxiliary/client/hwbridge/connect
68+
msf auxiliary(connect) > set rhost carhax
69+
rhost => carhax
70+
msf auxiliary(connect) > run
71+
72+
[*] Attempting to connect to carhax...
73+
[*] Hardware bridge interface session 1 opened (127.0.0.1 -> 127.0.0.1) at 2016-12-29 13:49:55 -0800
74+
[+] HWBridge session established
75+
[*] HW Specialty: {"automotive"=>true} Capabilities: {"can"=>true, "custom_methods"=>true}
76+
[!] NOTICE: You are about to leave the matrix. All actions performed on this hardware bridge
77+
[!] could have real world consequences. Use this module in a controlled testing
78+
[!] environment and with equipment you are authorized to perform testing on.
79+
[*] Auxiliary module execution completed
80+
```
81+
82+
On successful connection to a Hardware device you will be prompted with a special notice to
83+
remind you that any action you take on the HWBridge could have physical affects and consequences.
84+
Our lawyers asked us to put that there. You can verify the session was created by type 'sessions'
85+
86+
```
87+
msf auxiliary(connect) > sessions
88+
89+
Active sessions
90+
===============
91+
92+
Id Type Information Connection
93+
-- ---- ----------- ----------
94+
1 hwbridge cmd/hardware automotive 127.0.0.1 -> 127.0.0.1 (10.1.10.21)
95+
96+
```
97+
## Automotive Extension
98+
99+
If a device specifies a hw_specialty then it can load custom extensions. For instance, if
100+
a defice defines its specialty is automotive then Metasploit will load a custom automotive
101+
extension that gives you a few generic commands you can use on autotive systems such as the
102+
ability to send arbitrary CAN packets down the bus. It also allows you to run any
103+
post/hardware/automotive modules.
104+
105+
For instance you can run post/hardware/automtive/getvinfo to retrieve vehicle information
106+
via UDS Mode $9 commands.
107+
108+
```
109+
hwbridge > run post/hardware/automotive/getvinfo CANBUS=can2
110+
111+
[*] Supported PIDS: [2, 4, 6, 8]
112+
[*] VIN: 1G1ZT53826F109149
113+
[*] Calibration ID: x
114+
[*] PID 6 Response: ["00", "00", "C4", "E9", "00", "00", "17", "33", "00", "00", "00", "00"]
115+
[*] PID 8 Response: ["00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00"]
116+
```
117+
run 'supported_buses' for a list of available buses provided by your hardware. And as always you can
118+
type 'help' for a list of available commands and each command should support '-h' to additional
119+
argument help.
120+
121+
## Custom Method Extension
122+
123+
It is possible for the hardware device to report functionality that Metasploit has no knowledge
124+
of. For instance, perhaps the device has a unique capability that isn't standard or can be done
125+
100% in hardware. In order to utilize that functionality the HW device can report that it has
126+
custom_methods as a capability. At which point Metasploit will then query the custom methods
127+
and their argument syntax. These methods will become available as command line options
128+
within the hardware bridge.
129+
130+
For a simple example of a custom method see auxiliary/server/local_hwbridge for a more complete
131+
list on how to define custom methods see the [API Reference](http://opengarages.org/hwbridge).

‎documentation/modules/auxiliary/server/local_hwbridge.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## Overview
2+
3+
This is a sample hardware bridge that demonstrates how to connect the HWBridge API to metasploit.
4+
It demonstrates some bare minimum capabilities to report back to the hardware connector and
5+
establish a hwbridge session. This module provides an example on how to connect any hardware
6+
component to Metasploit. It is also a fully functional interface to SocketCAN and will work
7+
to create an automotive HW Bridge.
8+
9+
## Setup a Test
10+
11+
To experimient with using Metasploit to send automtovie CAN bus packets you can use
12+
the SocketCAN capabilities of Linux to create a virtual CAN device. NOTE: If you have a
13+
supported CAN sniffer you could also use a real can device.
14+
15+
In order for the local_hwbridge to inteface with SocketCAN you will need:
16+
17+
* can-utils
18+
19+
Once those are installed you can setup a virtual CAN inteface using:
20+
21+
```
22+
sudo modprobe can
23+
sudo modprobe vcan
24+
sudo ip link add dev vcan0 type vcan
25+
sudo ip link set up vcan0
26+
```
27+
28+
Once that is setup you can simply launch the module and it should auto detect any
29+
CAN intefaces you have active on the system.
30+
31+
```
32+
msf > use auxiliary/server/local_hwbridge
33+
msf auxiliary(local_hwbridge) > run
34+
[*] Auxiliary module execution completed
35+
36+
[*] Using URL: http://0.0.0.0:8080/xaUKu68Va
37+
[*] Local IP: http://10.1.10.21:8080/xaUKu68Va
38+
[*] Server started.
39+
```
40+
By default it will create a random URI, in this case it's xaUKu68Va.
41+
42+
## Connecting to the HWBridge
43+
44+
You will need to use the auxiliary/client/hwbridge/connect to connect
45+
to the local_hwbridge. You can either use the same machine or another machine to
46+
connect to your local_hwbridge. Just make sure the TARGETURI matches the randomly
47+
generated URI
48+
49+
```
50+
set TARGETURI xaUKu68Va
51+
```
52+
Then simply type run and you should connect to the HW bridge and a hwbridge session
53+
should be established. You can switch to the hwbridge session to interact with
54+
this module.
55+
56+
See the documentation for auxiliary/client/hwbridge/connect for more information on
57+
the hwbridge sessions.
58+

‎documentation/modules/post/hardware/automotive/getvinfo.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
Gathers several pieces of information from the vehicle. First it reports
2+
the available PIDS for pulling realtime current_data from Mode $01. If some of
3+
the common PIDs are returned it will print those as well, such as Engine Temp and
4+
Vehicle speed. If there are any Diagnostic Trouble Codes (DTCs) it will list those.
5+
The DTCs and Engine Light can be cleared by setting the optional CLEAR_DTC to true.
6+
Finally it gathers Vehicle information via UDS Mode $09 requests. The module
7+
first probes Mode $09 PID $00 to determine what all PIDs are supported then
8+
iterates through them and prints the response. The module will format known
9+
PIDs to ASCII.
10+
11+
## Options ##
12+
13+
**SRCID**
14+
15+
This is the SRC CAN ID for the ISO-TP connection. Default is 0x7E0.
16+
17+
**DSTID**
18+
19+
This is the CAN ID of the expected response. Default is 0x7E8.
20+
21+
**CANBUS**
22+
23+
Determines which CAN bus to communicate on. Type 'supported_buses' for valid options.
24+
25+
**CLEAR_DTCS***
26+
27+
If any Diagnostic Trouble Codes (DTCs) are present it will clear those and reset the MIL (Enginge Light)
28+
29+
## Scenarios
30+
31+
Given a standard vehicle ECU that is connected to can2 of the HWBridge device:
32+
33+
```
34+
hwbridge > run post/hardware/automotive/getvinfo CANBUS=can2
35+
36+
[*] Avaiable PIDS for pulling realitme data: 46 pids
37+
[*] [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]
38+
[*] MIL (Engine Light) : OFF
39+
[*] Number of DTCs: 0
40+
[*] Engine Temp: 140 °C / 284 °F
41+
[*] RPMS: 0
42+
[*] Speed: 0 km/h / 0.0 mph
43+
[*] Supported OBD Standards: OBD and OBD-II
44+
[*] Mode $09 Vehicle Info Supported PIDS: [2, 4, 6, 8]
45+
[*] VIN: 1G1ZT53826F109149
46+
[*] Calibration ID: UDS ERR: {"RCRRP"=>"Request Correctly Received, but Response is Pending"}
47+
[*] PID 6 Response: ["00", "00", "C4", "E9", "00", "00", "17", "33", "00", "00", "00", "00"]
48+
[*] PID 8 Response: ["00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00", "00"]
49+
```

‎documentation/modules/post/hardware/automotive/identifymodules.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Scans the CANBUS for devices responding to UDS DSC queries. By trying to set
2+
the Diagnostic Session Control (DSC) devices that support UDS will typically respond
3+
with an error or an acknowldegment. We use this information to map out modules in a vehicle.
4+
5+
## Options
6+
7+
**STARTID**
8+
9+
The CAN ID to start your scan from.
10+
11+
**ENDID**
12+
13+
The CAN ID to stop the CAN scan.
14+
15+
**CANBUS**
16+
17+
The bus to scan. See 'supported_buses' for a list of available buses
18+
19+
## Scenarios
20+
21+
A Quick scan of buses from 0x600 to 0x7FF
22+
23+
```
24+
hwbridge > run post/hardware/automotive/identifymodules CANBUS=can2 STARTID=0x600
25+
26+
Starting scan...
27+
[*] Identified module 7e0
28+
Scanned 504 IDs and found 1 modules that responded
29+
7e0
30+
```

0 commit comments

Comments
 (0)