How ethanarbuckle/objsee-ios works
Project type and purpose
• This is a combined command-line tool and dynamic library (libobjsee) whose job is to hook into the Objective-C runtime (objc_msgSend), collect method-call events, format/filter them, and emit them via multiple transport mechanisms (stdout, file, socket, custom handlers).
• It also offers a TUI mode for live, per-thread display and a C API for embedding in other tools.
File structure
Top-level items:
• control, Makefile, deploy_to_device.py, objsee.xcodeproj – build & deploy scripts for device vs simulator
• dependencies/ – third-party headers & static libs (capstone, json-c, ncursesw, plus a small ‘kat’ syntax module)
• src/libobjsee/ – core library, split into subpackages:
– config (encode/decode JSON config)
– injection (loader.m)
– interception (arg capture, selector deny lists, rebind vs MSHookFunction, msgSend_hook)
– tracing (core tracer logic, guarding signals)
– transport (stdout, file, socket, custom handlers)
– type_decoding (block & encoding introspection)
• src/objsee-cli/ – CLI binary
– main entry, CLI arg parser, app/simulator launching, dylib injector, trace server, TUI renderer
• src/libobjseeTests/ – unit tests for decoding, filters, selectors
• testapp/ – sample iOS app to demonstrate injection
README for architectural insights
• The README emphasizes two “fronts”:
1. CLI/TUI front-end that launches or attaches to a process and loads libobjsee.
2. Library API that user code can embed.
• It documents the tracer pipeline: config → hook installation → event capture → formatting → transport → output (console, JSON, TUI).
Main components & their interactions
a. CLI Front-End (src/objsee-cli)
• Parses command-line options
• Chooses target (bundle-id vs PID)
• Launches app in device or simulator (uses deploy_to_device.py or Xcode project)
• Injects libobjsee.dylib into target process via a small loader
• Hosts a trace server (for TUI or socket output)
b. Injected Library (libobjsee)
• Interception Layer: hooks objc_msgSend or uses symbol rebind (rebind.c / msgSend_hook.c)
• Tracing Core: collects call context (thread, depth, class, selector)
• Type-Decoding: inspects block arguments, objects, SELs
• Configuration Module: applies include/exclude filters for class, method, image
• Transport Layer: routes events to stdout, file, socket, or custom handler
c. External Dependencies
• Static libraries (capstone for disassembly, json-c for JSON output, ncursesw for TUI)
• Build scripts (Makefile, Xcode project for device embedding)
d. Test Harness & Example App
• Unit tests validate decoding and filtering
• testapp/ demonstrates injection and runtime tracing
Architectural patterns & design principles
• Layered Pipeline: interception → capture → decode → format → transport
• Plugin-like Transport: pluggable output handlers allow stdout, file, socket, or user-provided callback
• Separation of Concerns: each subsystem lives in its own directory (config vs formatting vs tracing vs transport)
• Cross-process Communication: CLI ↔ injected library via IPC socket or stdout/stderr