Understanding an application’s network communication is commonly one of the major tasks when performing grey or black box application security analyses. To make this process as efficient and convenient as possible, we developed hallucinate, a dynamic binary instrumentation tool to inspect and manipulate application TLS traffic in clear-text form.
SySS just released hallucinate as an open source project, so that other security researchers may benefit from it as well.
With the wide-spread use of SSL/TLS protected network protocols, application communication can no longer be easily inspected or manipulated on the network layer. When operating on the network layer, the SSL/TLS security has to be broken first to gain access to the actual clear-text data. If implemented correctly, this requires modification of the system or application security configuration or even of the application code itself. The required changes may not be obvious and require some analysis first.
Another approach, which is taken by hallucinate, is to perform the traffic inspection or manipulation before it is encrypted and after it is decrypted. Thereby, the potential complexity of the network level approach can be avoided. To get in the position to do so, modification of the application code, also known as dynamic instrumentation, is required to inspect application data at certain points during program execution. Frida offers a powerful and stable toolkit to perform this dynamic instrumentation, even across multiple operating systems.
Tools with similar features have existed for a long time, for example Echo Mirage on the Windows platform, and also published Frida scripts covering some of the APIs used. We found that these typically are unmaintained and/or lack necessary features.
Therefore, hallucinate aims to offer a one-stop cross-platform solution. It already includes out-of-the-box support for the following commonly encountered TLS libraries:
- Windows Schannel
- Windows NCrypt APIs
- OpenSSL
- GnuTLS
- Mozilla Network Security Services (NSS)
- Java Secure Socket Extension (JSSE)
Additional libraries and APIs may be added in the future. Contrary to the remaining libraries, Java support is not implemented using Frida scripts as it’s support for JVM instrumentation is/was still incomplete, but through a custom Java agent.
Once the clear-text application data has been intercepted using dynamic instrumentation, it is forwarded to the hallucinate Python wrapper. This enables various options to work with the transmitted or received data:
- Simple logging, or logging to a PCAP file, e.g. for convenient protocol analysis in Wireshark.
- Automated or manual manipulation using external programs
- Processing with a Python script, harnessing Python’s full power
Modified data is then transferred back to the target process and transmitted in place of the original data. Depending on the used API, there may be some length restrictions regarding replaced data. Often the replaced data cannot be larger than the original one due to technical limitations.
Usage example
Leveraging hallucinate’s Python scripting support, sent and received data is processed using the following Python script.
The script drops the Accept-Encoding header from the request to avoid getting a compressed response, and replaces
some data within the returned HTML document.
1
2
3
4
5
6
7
8
9
10
11
12
def send(data,p):
if b'Accept-Encoding:' in data:
start = data.index(b'Accept-Encoding:')
end = data.index(b'\r\n', start+1)
return data[0:start] + data[end:]
def recv(data,p):
if b'<nav' in data:
start = data.index(b'<a href="/leistungen/')
end = data.index(b'</a>', start+1)
return data[0:start] + b'<h3 style="margin-right: 2em">Greetings from hallucinate</h3>' + data[end:]
Now hallucinate can be started and attached to a running Firefox instance. This enables instrumentation for
the Mozilla Network Security Services (NSS) library used by Firefox for HTTPS/TLS communication, and the
defined python functions send and recv will be called when the application transmits or receives data.
#> hallucinate --script test.py -p <firefox-PID>
Visiting the SySS homepage, the changed HTTP Response/HTML document can be observed. The message
Greetings from hallucinate is included in the web site.
Firefox showing manipulated web site contents
While this example shows the manipulation of HTTPS traffic and a generic web browser for graphic demonstration purposes, hallucinate is not limited to specific application layer protocols like HTTPS, but can handle any TLS-protected traffic (if a supported library/API is used), and any type of application, for example network services.
You can find the hallucinate source code on our GitHub site.