One-stop TLS traffic inspection and manipulation using dynamic instrumentation

Related tags

Database hallucinate
Overview

hallucinate

Author: Moritz Bechler [email protected]
Project Repository: https://github.com/SySS-Research/hallucinate
License: MIT

Originally inspired by Echo Mirage Intercept clear-text TLS network traffic by instrumenting the target process. Binary instrumentation based on Frida, Java integration on a custom agent.

Intercepted traffic can be:

  • logged, also in PCAP format for convenient protocol analysis
  • edited interactively or programmatically using external tools
  • analyzed/modified using python scripts

Supported Libraries/APIs:

  • Native network IO (POSIX/BSD/Winsock) - disabled by default
  • OpenSSL
  • GnuTLS
  • SChannel
  • low-level Windows NCrypt APIs (SslEncryptPacket/SslDecryptPacket) - disabled by default
  • Java JSSE
  • NSS

Ideas for future integration:

  • Java +BouncyCastle, RSA
  • BoringSSL
  • Mobile Platforms: Android, iOS

BUILD/INSTALL

Using setuptools

#> python setup.py install

Java/Maven is required to build the Java Agent JAR file required to attach to Java Applications. It is recommended to choose the oldest targeted Java version SDK. The Java Agent may also be version dependent and should be built with a JDK version similar to the targeted applications JVM.

USAGE

usage: hallucinate [-h] [--verbose] [--process PROCESS] [--disable DISABLE]
                   [--enable ENABLE] [--dump-script DUMPSCRIPT]
                   [--mapfile MAPFILE] [--force-replace-buffer] [--log]
                   [--pcap PCAP] [--editor EDITOR] [--script SCRIPT]
                   [--java-vm JAVAVM] [--agent-jar AGENTJAR]
                   [--inject-agent-startup] [--java-server-host JAVAAGENTHOST]
                   [--java-server-port JAVAAGENTPORT]
                   [--java-server-key JAVAAGENTKEY]
                   [cmd [cmd ...]]

Instrument processes to intercept (encrypted) network communication

positional arguments:
  cmd                   Command to execute

optional arguments:
  -h, --help            show this help message and exit
  --verbose, -v
  --process PROCESS, -p PROCESS
                        Attach to existing process (by name or PID)
  --disable DISABLE, -d DISABLE
                        Disable default module (gnutls.js, java.js, nss.js,
                        openssl.js, schannel.js)
  --enable ENABLE, -e ENABLE
                        Enable optional module (raw.js, ncrypt.js)
  --dump-script DUMPSCRIPT
                        Dump complete frida script to file for debugging
  --mapfile MAPFILE     JSON configuration to manually override library names
                        and function addresses
  --force-replace-buffer
                        Replace application buffers, even if this likely
                        breaks the application (SChannel only)

handlers:
  Options for processing the intercepted traffic

  --log                 Log clear-text packet data
  --pcap PCAP           Write clear-text communication to a dump file in PCAP
                        format
  --editor EDITOR       Specify a system command to edit individual packet
                        data,{in} and {out} are replaced with temporary
                        files,if only {in} is specified in-place editing is
                        expected
  --script SCRIPT       Python script to load, functions recv/send(data,props)
                        will be called

java:
  Options relating to the Java agent, re(attaching) to a Java process
  multiple times is unreliable

  --java-vm JAVAVM      Java binary to use when injecting the agent. This
                        should match the target application's Java version
  --agent-jar AGENTJAR  Override agent JAR file to inject (typically bundled
                        with hallucinate)
  --inject-agent-startup
                        Inject Java agent via VM argument. Not usable when
                        attaching to a running process
  --java-server-host JAVAAGENTHOST
                        Bind address for Java agent server
  --java-server-port JAVAAGENTPORT
                        Port for Java agent server (random by default)
  --java-server-key JAVAAGENTKEY
                        Secret authentication key for Java agent server
                        connection (random by default)

Usage Examples

Launch the target process through the script

#> hallucinate  --log -- /usr/bin/curl -k https://localhost

Different options for logging, interactive or automated modification of the intercepted traffic are available, see the application help.

For example the clear-text HTTP request/response of a CURL call could be modified in an editor of your choice:

#> hallucinate --disable raw.js  --editor '/usr/bin/gedit {in}' -- /usr/bin/curl -k https://localhost

Or, attach to a running process by specify it's PID, or, if unique, process name

#> hallucinate --log -p <pid|procname>

Java Usage

Java processes are automatically detected by hallucinate when attaching. However, as an agent is injected into these processes and no reloading is supported, (re-)attaching multiple times to the same process is unreliable (there may be room for future improvement). Also, make sure to specify a Java runtime version compatible with the target application as --java-vm.

An alternative is to inject the agent during VM startup by specifying the full Java command line for the target program, e.g. java -cp myjar.jar my.Application as the command to run and the --inject-agent-startup option. This automatically adds the necessary agent parameters to the VM invocation.

Scripting

hallucinate allows python scripting to process/analyze/modify the intercepted traffic. A python script can be specified using the --script parameter. From this file the functions send and recv will be called on each intercepted send/recv. If these functions return data the sent/received data is be replaced, otherwise it passes as-is.

Example: test.py

def send(data,p):
    if b'HTTP/1.1' in data:
        print("Replacing HTTP version")
        return data.replace(b'HTTP/1.1', b'HTTP/1.0')
    print("Not touching: " + repr(data))

def recv(data,p):
    print("Not touching: " + repr(data))
#> hallucinate -d raw.js --script test.py -- /usr/bin/curl -s -o /dev/null -k https://localhost
INFO:root:Starting ['/usr/bin/curl', '-s', '-o', '/dev/null', '-k', 'https://localhost']
INFO:root:Injected script, resuming execution of 22096
Replacing HTTP version
Not touching: b'HTTP/1.1 200 OK

Mapfile

A mapfile can be used to manually override the hooked target module and function addresses, e.g. statically linked library copies. It is a JSON formatted nested dictionary, lookup is based on the module name on the first nesting level, function name on the second. The special name @lib can be used to specify/override the target module name.

Example: test.json

{
        "openssl":{
                "@lib" : "test.so",
                "SSL_read_ex" : "0x24235235"
        }
}

KNOWN LIMITATIONS

  • Receive calls generally must use the application allocated buffers, therefore modified data cannot exceed the length of the buffers provided by the application.
  • The same is true for SChannel send calls, therefore the length is limited in this case as well. The option --force-replace-buffer to replace the buffers nevertheless is provided, but must be expected to break most applications.
  • Statically linked (without symbols)/inlined library instances won't be detected, hooking may be possible using manually identified function addresses and a mapfile.
  • No connection/address information is available for SChannel
  • Hooking of calls in runtime loaded libraries may not be working properly (room for future improvement?)
  • Hooking may not cover all relevant APIs of the respective libraries (let me know)
  • Attaching to processes may be limited on Linux, either launch the target process as a child or set sys.kernel.yama.ptrace_scope=0
You might also like...

Bulk follow GitHub users using a NodeJS script.

Github bulk follow Getting Started Prerequisites Clone the project to your local environment: git clone [email protected]:farid-ouachrar/github-bulk-

Sep 27, 2021

Auth model created by Using nodeJs for backend & reactJs for frontend with the help of TailwindCss in styling

Auth model created by Using nodeJs for backend & reactJs for frontend with the help of TailwindCss in styling

The Universal Auth System Using The MERN Stack Including Mysql -- The project is divded to two separte projects 1- The Client side - containing the

Aug 22, 2022

This library helps implement caching using Cloudflare Workers KV

With a few lines of code, you can control the execution of functions that you want to cache for speed, store them in the cache, and skip execution of the function if the cache exists.

Oct 20, 2022

A web SQL interface to your Stripe account using Datasette.

Datasette, Stripe and tdog Or: Stripe Sigma Alternative Datasette is a web GUI for exploring SQLite datasets. Stripe handles online payments. Sigma is

Nov 27, 2022

Repository with various templates using nest ( express )

A progressive Node.js framework for building efficient and scalable server-side applications. Description Nest framework TypeScript starter repository

Nov 27, 2022

AlaSQL.js - JavaScript SQL database for browser and Node.js. Handles both traditional relational tables and nested JSON data (NoSQL). Export, store, and import data from localStorage, IndexedDB, or Excel.

AlaSQL.js - JavaScript SQL database for browser and Node.js. Handles both traditional relational tables and nested JSON data (NoSQL). Export, store, and import data from localStorage, IndexedDB, or Excel.

Please use version 1.x as prior versions has a security flaw if you use user generated data to concat your SQL strings instead of providing them as a

Jan 9, 2023

ORM for TypeScript and JavaScript (ES7, ES6, ES5). Supports MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, SAP Hana, WebSQL databases. Works in NodeJS, Browser, Ionic, Cordova and Electron platforms.

ORM for TypeScript and JavaScript (ES7, ES6, ES5). Supports MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, SAP Hana, WebSQL databases. Works in NodeJS, Browser, Ionic, Cordova and Electron platforms.

TypeORM is an ORM that can run in NodeJS, Browser, Cordova, PhoneGap, Ionic, React Native, NativeScript, Expo, and Electron platforms and can be used

Jan 3, 2023

A query builder for PostgreSQL, MySQL and SQLite3, designed to be flexible, portable, and fun to use.

knex.js A SQL query builder that is flexible, portable, and fun to use! A batteries-included, multi-dialect (MSSQL, MySQL, PostgreSQL, SQLite3, Oracle

Jan 4, 2023
Comments
  • Added remote functionality via local port forward

    Added remote functionality via local port forward

    Added the ability to use Hallucinate against a remote system (when you have configured a local port forward for port 27042 to go to the system running the Frida server).

    opened by agreenbhm 0
  • Exception when doing pcap capture

    Exception when doing pcap capture

    I occasionally get the following traceback when capturing to pcap

    Traceback (most recent call last):
      File "C:\Users\copewin\AppData\Local\Programs\Python\Python39\lib\site-packages\frida\core.py", line 450, in _on_message
        callback(message, data)
      File "C:\Users\copewin\AppData\Local\Programs\Python\Python39\lib\site-packages\hallucinate-1.0.0-py3.9.egg\hallucinate\handler.py", line 75, in handle
        self.handle_payload(p, self.script.post)
      File "C:\Users\copewin\AppData\Local\Programs\Python\Python39\lib\site-packages\hallucinate-1.0.0-py3.9.egg\hallucinate\handler.py", line 50, in handle_payload
        self.process_shutdown(p, rhandle)
      File "C:\Users\copewin\AppData\Local\Programs\Python\Python39\lib\site-packages\hallucinate-1.0.0-py3.9.egg\hallucinate\handler.py", line 41, in process_shutdown
        self.handler.shutdown(p)
      File "C:\Users\copewin\AppData\Local\Programs\Python\Python39\lib\site-packages\hallucinate-1.0.0-py3.9.egg\hallucinate\handlers\multi.py", line 45, in shutdown
        handler.shutdown(p, d)
      File "C:\Users\copewin\AppData\Local\Programs\Python\Python39\lib\site-packages\hallucinate-1.0.0-py3.9.egg\hallucinate\handlers\pcap.py", line 37, in shutdown
        self.fp.write(c.shutdown(time.time_ns()))
    TypeError: a bytes-like object is required, not 'NoneType'
    

    It appears that TCPState.shtudown is being called on a TCPState that has never had send called on it. so TCPState.shutdown returns nothing

    https://github.com/SySS-Research/hallucinate/blob/main/hallucinate/pcap.py#L191

    In my instance this is not being called on the default TCPState object created at https://github.com/SySS-Research/hallucinate/blob/main/hallucinate/handlers/pcap.py#L23 but on a valid connection. The application I'm using is hooking OpenSSL.

    opened by jcopenha 0
Owner
SySS Research
Open source IT security software tools and information
SySS Research
A fast, synchronized and dynamic query builder package.

@ssibrahimbas/query A fast, synchronized and dynamic query builder package. What is? In short, the query builder. You can write complex and parameteri

Sami Salih İbrahimbaş 7 Jun 13, 2022
:rocket: One command to generate REST APIs for any MySql Database.

Xmysql : One command to generate REST APIs for any MySql database Why this ? Generating REST APIs for a MySql database which does not follow conventio

null 129 Dec 30, 2022
Burger builder project using React, Hooks and Context API.

Burger Builder In this project, I made a context-api project by creating hamburgers with 3 different materials. Project setup npm install Project star

Efecan Pınar 4 Jun 17, 2021
A simple url shorter API built with nodejs running on Kubernetes in Google Cloud, using PostgreSQL for storage and cloud sql proxy.

Simple URL Shorter - Google Cloud - Kubernetes A simple url shorter API built with nodejs running on Kubernetes in Google Cloud, using PostgreSQL for

null 3 Nov 25, 2021
A back-end server aplication created using node.js, express and mongodb.

Course Material and FAQ for my Complete Node.js, Express and MongoDB Bootcamp This repo contains starter files and the finished project files for all

Pablo César Jiménez villeda 1 Jan 4, 2022
Basic Dapp showing how a React Dapp can connect to Cronos using MetaMask and Crypto.com Defi Wallet

cronos-dapp-basic Basic Dapp showing how a React Dapp can connect to Cronos using MetaMask and Crypto.com Defi Wallet You need to have node version 14

Acclrate 1 Dec 31, 2021
API developed using NestJS, TypeORM, PgMem and concepts of Clean Architecture

The Powerful NestJS A progressive Node.js framework for building efficient and scalable server-side applications. Clean Architecture The project has b

Matheus Alexandre 20 Jan 2, 2023
An in-depth implementation of Clean Architecture using NestJS and type-script

Clean Architecture With NestJS Description It's been a while since my last article on how to implement clean architecture on Node.js applications, git

null 297 Dec 28, 2022
A Full Stack Amazon Clone which created using ReactJS with full E-Commerce Functionality!!

Amazon Clone with ReactJS A small web app that tries to imitate the desktop web version of amazon site, you can add items to the basket, delete them,

Özge Coşkun Gürsucu 50 Oct 3, 2022
A template for WebSockets powered Cloudflare Worker project using graphql-ws

?? graphql-ws on Cloudflare Workers A template for WebSockets powered Cloudflare Worker project using graphql-ws. The worker serves the following rout

Denis Badurina 26 Dec 18, 2022