MacSubstrate is a platform tool for interprocess code injection on macOS, with the similar function to Cydia Substrate on iOS. Using macSubstrate, you can inject your plugins (.bundle or .framework) into a mac app (including sandboxed apps) to tweak it in the runtime.

  • All you need is to get or create plugins for your target app.
  • No trouble with modification and codesign for the original target app.
  • No more work after the target app is updated.
  • Super easy to install or uninstall a plugin.
  • Loading plugins automatically whenever the target app is relaunched.
  • Providing a GUI app to make injection much easier.

Also Read IDB – Tool To Simplify Some Common Tasks For iOS Pentesting & Research

MacSubstrate Usage

  • Download, put into /Applications and launch it.
  • Grant authorization if needed.
  • Install a plugin by importing or dragging into macSubstrate.
  • Launch the target app.

step 3 and step 4 can be switched

Once a plugin is installed by macSubstrate, it will take effect immediately. But if you want it to work whenever the target app is relaunched or macOS is restarted, you need to keep it running and allow it to automatically launch at login.

  • Uninstall a plugin when you do not need it anymore.


It supports plugins of .bundle or .framework, so you just need to create a valid .bundle or .framework file. The most important thing is to add a key macSubstratePlugin into the info.plist, with the dictionary value:

Key Value
TargetAppBundleID the target app’s CFBundleIdentifier, this tells it which app to inject.
Description brief description of the plugin
AuthorName author name of the plugin
AuthorEmail author email of the plugin

Please check the demo plugins demo.bundle and demo.framework for details.

Xcode Templates

macSubstrate also provides Xcode Templates to help you create plugins conveniently:

  • ln -fhs ./macSubstratePluginTemplate ~/Library/Developer/Xcode/Templates/macSubstrate\ Plugin
  • Launch Xcode, and there will be 2 new plugin templates for you.
My Plugins
  • Send you a notification when you receive a HongBao message.
  • Send you a notification when you receive a message containing customized keywords.
  • Anti-recall message and send you a notification.

Welcome pull requests of your own plugins to Plugins.


  1. SIP is a new security policy on macOS, which will help to keep you away from potential security risk. Disable it means you will lose the protection from SIP.
  2. If you install a plugin from a developer, you should be responsible for the security of the plugin. If you do not trust it, please do not install it. macSubstrate will help to verify the code signature of a plugin, and I suggest you to scan it using VirusTotal. Anyway, macSubstrate is just a tool, and it is your choice to decide what plugin to install.