when running friTap as a module you can now work with your own message handler

Author: monkeywave

INTEGRATION.md

@@ -11,6 +11,9 @@ The following example demonstrates how to use `friTap` to hook into an applicati
 ### **Code Example**
 
 ```python
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
 from friTap import SSL_Logger
 import sys
 
@@ -26,7 +29,7 @@ try:
         app_package,
         verbose=True,            # Enable verbose output
         mobile=True,             # Indicate that the target app is running on a mobile device
-        keylog="keylogtest3.log", # Path to save SSL key log
+        keylog="keylogtest.log", # Path to save SSL key log
         debug_output=True        # Enable debug output
     )
 
@@ -68,17 +71,160 @@ except KeyboardInterrupt:
 | `payload_modification` | `bool`  | `False`      | Enable payload modification during traffic capture.                        |
 | `enable_default_fd`    | `bool`  | `False`      | Enable default file descriptor handling.                                   |
 | `patterns`             | `list`  | `None`       | List of patterns to match during traffic capture.                          |
-| `custom_hook_script`   | `str`   | `None`       | Path to a custom Frida hook script to be executed during the session.      |
+| `custom_hook_script`   | `str`   | `None`       | Path to a custom Frida hook script to be executed during the session. These hooks are installed prior to the installation of friTap hooks.     |
 
 ---
 
+## Advanced Usage: Integrating friTap with Custom Handler
+
+If you'd like to integrate friTap into your project but prefer to manage Frida yourself, friTap offers advanced flexibility. With this approach, you can either:
+
+- Retrieve the friTap script Path: Use `ssl_log.get_fritap_frida_script_path()` to obtain the path to the friTap Frida script. You can then manually load the script into your target process.
+- Use the Advanced API: Utilize the `start_fritap_session_instrumentation(own_message_handler, process)` API to integrate friTap while managing Frida yourself.
+    - `on_message_handler`: Your custom handler function to process messages between the script and your Python code.
+    - `process`: The Frida process object you manage, which can be created by spawning or attaching to the target application.
+
+This API gives you full control over when the friTap script is loaded into the target process. It returns the script object, allowing you to load the script at your preferred time. Below is an example of how to use this API:
+
+```python
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from friTap import SSL_Logger
+import sys
+import frida
+
+#global variable
+script = None
+
+# Custom message handler function
+def myAwesomeHandler(message, data):
+    global script
+
+    # Pass options to friTap hooks (mandotory)
+    if message['payload'] == 'experimental':
+        script.post({'type':'experimental', 'payload': False})
+        return
+
+    if message['payload'] == 'defaultFD':
+        script.post({'type':'defaultFD', 'payload': False})
+        return
+
+    if message['payload'] == 'pattern_hooking':
+        script.post({'type':'pattern_hooking', 'payload': False})
+        return
+
+    if message['payload'] == 'offset_hooking':
+        script.post({'type':'offset_hooking', 'payload': False})
+        return
+    
+    if message['payload'] == 'anti':
+        script.post({'type':'antiroot', 'payload': False})
+        return
+
+
+    print(f"Message from Frida: {message}")
+    if data:
+        print(f"Data: {data}")
+
+
+
+def getFridaProcess(target_app):
+    device = frida.get_usb_device()
+    process = device.attach(int(target_app) if target_app.isnumeric() else target_app)
+    return process, device
+
+
+
+try:
+    print("Starting friTap logging...")
+    print("Press Ctrl+C to stop logging.")
+
+    # Specify the target app package
+    app_package = "YouTube"
+
+    # Create or attach a Frida process (replace with your implementation)
+    process, device = getFridaProcess(app_package)  # Your code for creating or attaching to a Frida process.
+
+    # Initialize SSL_Logger with optional arguments
+    ssl_log = SSL_Logger(
+        app_package,
+        verbose=True,             # Enable detailed output
+        keylog="keylogtest.log" # Path to save the SSL key log
+    )
+    
+    # Hook friTap into the target process without immediately loading the script
+    script = ssl_log.start_fritap_session_instrumentation(myAwesomeHandler, process)
+
+    # Manually load the friTap script into the target process
+    script.load()
+
+    # Wait for the user to interrupt
+    sys.stdin.read()
+
+except KeyboardInterrupt:
+    # Detach the process when interrupted
+    process.detach()
+    print("friTap logging stopped.")
+
+```
+
+Key Notes about this approach:
+
+- Script Loading: The `start_fritap_session_instrumentation` API provides the script object but does not automatically load it. This gives you full control over when the friTap hooks are injected.
+- Custom Message Handler: Your on_message_handler function allows you to handle Frida messages and data flexibly. When managing the handler yourself, it is mandatory to ensure that certain internal friTap variables are correctly communicated with the Frida script. Failing to do so will halt the installation of the friTap hooks, as they depend on values from the Python environment to determine how certain hooks should be applied. 
+- Full Control: This approach is ideal for advanced use cases where you want precise management of Frida processes and script lifecycle.
+
+### Understanding Frida Messages in friTap
+
+In friTap, the `on_fritap_message(self, job, message, data)` handler processes messages sent from the Frida script. These messages contain important information about the operation of friTap. The key fields in the message are:
+
+- **`payload`**: This field contains a structured dictionary with a `contentType` key that determines the type of the message. The specific `contentType` dictates how the remaining fields in the `payload` are interpreted. The structure looks like this `'payload': {'contentType': '<content type>', '<content key>': <content value>}`
+- **`data`**: This field contains the decrypted TLS payload when the `contentType` is `datalog`. In other cases, the `data` field is typically unused and the focus remains on the `payload` field.
+
+Here are the different `contentType` values and their meanings:
+
+| **Content Type**     | **Description**                                                                                          | **Access Key**      |
+|-----------------------|----------------------------------------------------------------------------------------------------------|---------------------|
+| `datalog`            | Contains decrypted TLS payload data and associated socket information. Useful for analyzing TLS traffic. | `datalog`          |
+| `console_dev`        | Debug output intended for development and troubleshooting, such as scanning logs or fallback patterns.   | `console_dev`      |
+| `console_error`      | Error messages encountered during the operation of friTap.                                               | `console_error`    |
+| `console`            | Standard output messages visible to the user when running friTap.                                        | `console`          |
+| `keylog`             | Extracted TLS key material from the target application.                                                  | `keylog`           |
+
+**Key Details**:
+
+1. **Decrypted TLS Data**: 
+   - When `contentType` is `datalog`, the `data` field contains the decrypted TLS payload (if available), along with associated socket information.
+
+2. **Development Logs**:
+   - `console_dev` messages provide insights into debug operations, which are helpful during development or when fixing bugs.
+
+3. **Error Handling**:
+   - Error messages (`console_error`) help identify problems within friTap’s execution.
+
+4. **User Output**:
+   - `console` messages are meant for the user and reflect key operational statuses.
+
+5. **TLS Key Extraction**:
+   - `keylog` messages provide extracted key material for analyzing the cryptographic state of the target application.
+
+By using the `contentType` as the key, you can access specific fields in the `payload` to analyze the messages accordingly.
+
+
+
+By using this API, you can seamlessly integrate friTap while maintaining complete control over Frida's operation in your application.
+
 ## Advanced Usage: Using friTap as a Job in AndroidFridaManager
 
 friTap can also be used as a job within the `AndroidFridaManager` framework. This allows you to manage friTap sessions as part of a larger job workflow.
 
 ### **Code Example**
 
 ```python
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
 from friTap import SSL_Logger
 from AndroidFridaManager import JobManager
 import sys
@@ -97,7 +243,7 @@ try:
     ssl_log = SSL_Logger(
         app_package,
         verbose=True,             # Enable verbose output
-        keylog="keylogtest3.log", # Path to save SSL key log
+        keylog="keylogjobtest.log", # Path to save SSL key log
         debug_output=True         # Enable debug output
     )
 

friTap/about.py

@@ -2,5 +2,5 @@
 # -*- coding: utf-8 -*-
 
 __author__ = "Daniel Baier, Francois Egner, Max Ufer"
-__version__ = "1.2.4.0"
+__version__ = "1.2.4.3"
 debug = False # are we running in debug mode?

friTap/ssl_logger.py

@@ -139,7 +139,7 @@ def on_fritap_message(self,job, message, data):
         Args:
         message: A dictionary containing the message "type" and other fields
             dependent on message type.
-        data: The string of captured decrypted data.
+        data: The string of captured decrypted data or the caputured decryption keys
         """
 
 
@@ -272,7 +272,7 @@ def on_spawn_added(self, spawn):
         self.device.resume(spawn.pid)
 
 
-    def instrument(self, process):
+    def instrument(self, process, own_message_handler):
         runtime="qjs"
         debug_port = 1337
         if self.debug:
@@ -311,7 +311,12 @@ def instrument(self, process):
 
         if self.debug and frida.__version__ >= "16":
             self.script.enable_debugger(debug_port)
-        self.script.on("message", self.internal_callback_wrapper())
+
+        if own_message_handler != None:
+            self.script.on("message", self._provide_custom_hooking_handler(own_message_handler))
+            return self.script
+        else:
+            self.script.on("message", self._internal_callback_wrapper())
         self.script.load()
 
 
@@ -370,8 +375,13 @@ def load_patterns(self):
             print(f"[-] Pattern file {self.patterns} does not exist.")
 
 
+    def start_fritap_session_instrumentation(self, own_message_handler, process):
+        self.process = process
+        script = self.instrument(self.process, own_message_handler)
+        return script
+
 
-    def start_fritap_session(self):
+    def start_fritap_session(self, own_message_handler=None):
 
         if self.mobile:
             self.device = frida.get_usb_device()
@@ -380,34 +390,13 @@ def start_fritap_session(self):
         else:
             self.device = frida.get_local_device()
 
-        """
-        if self.offsets is not None:
-            if os.path.exists(self.offsets):
-                offset_file = open(self.offsets, "r")
-                self.offsets_data = offset_file.read()
-                offset_file.close()
-            else:
-                try:
-                    json.load(self.offsets)
-                    self.offsets_data = self.offsets
-                except ValueError as e:
-                    print(f"Log error, defaulting to auto-detection: {e}")
-
-        if self.patterns is not None:
-            self.load_patterns()
-        """
-
-
         self.device.on("child_added", self.on_child_added)
         if self.enable_spawn_gating:
             self.device.enable_spawn_gating()
             self.device.on("spawn_added", self.on_spawn_added)
         if self.spawn:
             print("spawning "+ self.target_app)
 
-            #if self.pcap_name:
-            #    self.pcap_obj =  PCAP(self.pcap_name,SSL_READ,SSL_WRITE,self.full_capture, self.mobile,self.debug)
-                
             if self.mobile or self.host:
                 pid = self.device.spawn(self.target_app)
             else:
@@ -420,29 +409,10 @@ def start_fritap_session(self):
                 time.sleep(1) # without it Java.perform silently fails
             self.process = self.device.attach(pid)
         else:
-            #if self.pcap_name:
-            #    self.pcap_obj =  PCAP(self.pcap_name,SSL_READ,SSL_WRITE,self.full_capture, self.mobile,self.debug)
             self.process = self.device.attach(int(self.target_app) if self.target_app.isnumeric() else self.target_app)
 
-        """
-        if self.live:
-            if self.pcap_name:
-                print("[*] YOU ARE TRYING TO WRITE A PCAP AND HAVING A LIVE VIEW\nTHIS IS NOT SUPPORTED!\nWHEN YOU DO A LIVE VIEW YOU CAN SAFE YOUR CAPUTRE WITH WIRESHARK.")
-            fifo_file = self.temp_fifo()
-            print(f'[*] friTap live view on Wireshark')
-            print(f'[*] Created named pipe for Wireshark live view to {fifo_file}')
-            print(
-                f'[*] Now open this named pipe with Wireshark in another terminal: sudo wireshark -k -i {fifo_file}')
-            print(f'[*] friTap will continue after the named pipe is ready....\n')
-            self.pcap_obj =  PCAP(fifo_file,SSL_READ,SSL_WRITE,self.full_capture, self.mobile,self.debug)
-            
-
-        if self.keylog:
-            self.keylog_file = open(self.keylog, "w")
-        """
-
 
-        self.instrument(self.process)
+        script = self.instrument(self.process, own_message_handler)
 
 
 
@@ -458,15 +428,22 @@ def start_fritap_session(self):
         if self.spawn:
             self.device.resume(pid)
 
-        return self.process
+        return self.process, script
 
 
     def finish_fritap(self):
         if self.script:
             self.script.unload()
 
 
-    def internal_callback_wrapper(self):
+    def _provide_custom_hooking_handler(self, handler):
+        def wrapped_handler(message, data):
+            handler(message, data)
+
+        return wrapped_handler
+
+
+    def _internal_callback_wrapper(self):
         def wrapped_handler(message, data):
             self.on_fritap_message(None, message, data)
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "friTap",
-    "version": "1.2.4.0",
+    "version": "1.2.4.3",
     "description": "Frida agent for logging SSL traffic as plaintext and extracting SSL keys",
     "private": true,
     "main": "agent/ssl_log.ts",