Skip to content

OS X Platform for loading C function or Objective-C method hooks from plists.

License

Notifications You must be signed in to change notification settings

ParasiteTeam/crucible

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

40 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Crucible

Crucible is a platform for loading C function or Objective-C method hooks from plists.

Installation

Crucible comes bundled with Parasite on installation.

Folder Structure

Place Crucible plist files in /Library/Parasite/Crucible. You can name them using the following options:

  • File has the name class_<CLASSNAME> where CLASSNAME is whatever class you want to trigger the loading of the plist if it is present in the target process.
  • File has the same name as the bundle identifier it is targeting.
  • File has any name, inside of folder with any of the above mentioned filters.

Format

Crucible files are just in a certain plist file format. Here is the general structure you want and an explanation of the keys.

| Root (plist root)
|––––| Hooks (array)
|––––|––––| Index 0 (dictionary)
|––––|––––|––––| Key: Class (string): "NSColor"
|––––|––––|––––| Key: Methods (array)
|––––|––––|––––|––––| Index 0 (array)
|––––|––––|––––|––––|––––| Index 0 (string): colorWithSRGBRed:green:blue:alpha:
|––––|––––|––––|––––|––––| Index 1 (any): dictionary
|––––|––––|––––|––––|––––|––––| Key: Value (value element): "#FFF"
|––––|––––|––––|––––|––––|––––| Key: Transform (string): "color"
|––––|––––|––––|––––| Index 1 (array)
|––––|––––|––––|––––|––––| Index 0 (string): "+description"
|––––|––––|––––|––––|––––| Index 1 (any): "Hello, Class Description"
|––––|––––|––––|––––| Index 2 (array)
|––––|––––|––––|––––|––––| Index 0 (string): "-description"
|––––|––––|––––|––––|––––| Index 1 (any): "Hello, Instance Description"
|––––|––––| Index 1 (dictionary)
|––––|––––|––––| Key: MinBundleVersion (number): 0
|––––|––––|––––| Key: MaxBundleVersion (number): 999
|––––|––––|––––| Key: Symbol (string): "_NSUserName"
|––––|––––|––––| Key: Image (string): "identifier:com.apple.AppKit"
|––––|––––|––––| Key: Returns (string): "@"
|––––|––––|––––| Key: Value (value/value dict): "Bill Nye"
|––––|––––| Index 2 (dictionary)
|––––|––––|––––| Key: Symbol (string): "_test"
|––––|––––|––––| Key: Image (string): "@executable_path"
|––––|––––|––––| Key: Returns (string): "v"
|––––|––––|––––| Key: Value (value/value dict): ""

Description

Name Type Description
Hooks array of Hook Elements The root key that contains all of your hooks
Hook Element dictionary Contains a class hook or a function hook
MinBundleVersion number Minimum Bundle Version to use this Hook Element on. The version is derived from whatever filter you used to load this Crucible plist.
MaxBundleVersion number Maximum Bundle Version to use this Hook Element on.
Class string For a class hook, specifies which class the Methods key will hook
Methods array of Method Elements For a class hook, contains a list of all the methods in the class to hook and which values to return.
Method Element array For a class hook, describes a method to hook and the return value. The first value is the selector of the method to replace; you can optionally prefix with +/- to disambiguate class and instance methods, but leaving it off lets Crucible check both. The second element is a Value Element of the return value to use.
Symbol string For a function hook, Public/Private symbol name that you would like to hook
Image string For a function hook, Path to a binary where we can find your function. You can prefix this with identifier: to have Crucible dynamically find the executable given a bundle identifier, or you can write @executable_path to specify the Application binary path.
Returns string For a function hook, a type encoding of the return type of the function you are hooking. More Information
Value value element Value to return
Value Element dictionary/any Anywhere you are writing something as a return value, whether inside a function hook or the method hook, your objects will be recursively sanitized. This is just a fancy word we used to say that whenever I see a dictionary with the key Value Crucible will treat that sub-element as another Value Element and collapse the original one into just the smaller one. Why would you do this? So you can also have a Transform key and apply transforms to values in dictionaries and arrays.

Transforms

Transforms take whatever value you entered and does some pre-processing at runtime to make make it a different value.

Parasite extensions can add more Transforms into whatever they are loaded into by defining a category on NSObject and naming functions with a _crucible_ prefix such as -(id)_crucible_url for the url transform. NOTE: Transforms are affected by any hooks specified in parasite or Crucible, so be wary of infinite loops with things like for example; when hooking colorWithRed:green:blue:alpha: and supplying an argument that would trigger an invocation of that function because you will be stuck in an infinite loop.

Here is a list of the default available transforms:

Name Return Type Argument Type Description
url NSURL string Transforms a string into an NSURL using URLWithString:
file_url NSURL string Transforms a string into a file path URL using fileURLWithPath:
now NSDate ignored Returns [NSDate date]
color NSColor string/number Transforms a string or a number into an NSColor. Accepts the common CSS styles like hsl/hsla, hsb, rgb, gray, hex.
alloc_init any class string Calls +alloc and then -init on a given class name.

About

OS X Platform for loading C function or Objective-C method hooks from plists.

Resources

License

Stars

Watchers

Forks

Packages

No packages published