NetLogger Development Guide
This skill provides essential procedural knowledge and architecture overview for maintaining and developing the NetLogger jailbreak tweak.
Core Architecture
NetLogger is an in-process network interceptor (Tweak) for iOS (specifically Dopamine rootless). It intercepts network requests and responses directly within the target application's process.
Key Components
Core Hooking (
Tweak.x):- Hooks
NSURLSessionConfigurationto injectNLURLProtocol. - Hooks C-level SSL/TLS and POSIX socket functions (e.g.,
SSLWrite,SSLRead,send,recv) usingMSHookFunction. - Implements
applyMitmRules,applyMitmRequestRules,applyMitmResponseRulesto intercept and manipulate JSON/Headers via a JavaScriptCore Engine or key-path matching.
- Hooks
Preference Bundle (
netloggerprefs/):- iOS Settings app integration using PreferenceLoader.
- Important: Detail Controllers (like
NLBlacklistController,NLMitmRulesController,NLLogDetailViewController) MUST subclassPSViewController(notUIViewController), implementloadView, and avoid manual view initialization inviewDidLoadto preventdoesNotRecognizeSelector:SIGABRT crashes in the Settings app. - Localization (i18n): Supports English (
en.lproj) and Vietnamese (vi.lproj). Strings are managed viaLocalizable.stringsandRoot.stringsand accessed using theNLLocalizedStringmacro inNLLocalization.h.
Sileo Depiction (
docs/depictions/com.minh.netlogger.json):- Uses Sileo Native Depiction format.
minVersionmust be at least0.4to support Screenshots.
Build and Deployment Workflow
Always use the custom build script instead of manually running make package.
# Clean, compile (with DEBUG=0 FINALPACKAGE=1), package, and update apt repository hashes (MD5, SHA256)
./update_repo.sh
Git Workflow: After a successful build, always commit the changes and push to the remote repository (GitHub Pages acts as the APT repository).
git add .
git commit -m "feat/fix: Description"
git push
Best Practices & Guidelines
1. Handling Settings UI (PreferenceLoader)
- NEVER subclass
UIViewControllerdirectly for screens launched fromRoot.plistor other preference cells. Always use<Preferences/PSViewController.h>. - Keyboard Handling: For screens with text inputs at the bottom (e.g., MitM Rules), always implement
UIKeyboardWillShowNotificationandUIKeyboardWillHideNotificationto adjust thetableView.contentInset. - Background Colors: When highlighting table cells in iOS 13+, restore the color to
[UIColor secondarySystemGroupedBackgroundColor]instead ofnilto prevent transparency bugs in grouped tables.
2. JavaScriptCore Engine (MitM)
- The MitM engine uses
JSContextto evaluate user-provided JavaScript scripts. - The payload is injected as a global variable named
body(Object if JSON, String if text). - Always wrap JS evaluation in try-catch or use
JSContext.exceptionHandlerto prevent user-provided scripts from crashing the host app.
3. Localization
- When adding new UI text in
netloggerprefs/, wrap strings inNLLocalizedString(@"Key", @"Fallback"). - Update both
netloggerprefs/Resources/en.lproj/Localizable.stringsandnetloggerprefs/Resources/vi.lproj/Localizable.strings.
4. Debugging
- Use
NSLog(@"[NetLogger] ...")for logging inTweak.x. Use the Console app oroslogto view them. - Ensure
DEBUG = 0andFINALPACKAGE = 1are set in the rootMakefilebefore releasing to remove debug symbols and reduce.debsize.