Tutorial H5GG Full Tutorial [Offset Patching + Hooking] for Non-Jailbroken/Jailbreak Devices !

lxdx · May 7, 2023

Hello Hello,

Here is finally a tutorial to patch or even hook on Non-JB/JB.

This tutorial will cover the non-JB way because that's what's interesting :happydance: , but this way can work on JB.

We will see the complete installation of H5GG, and an example of offset patching, and another with hooking. The source code will also be provided. Nothing better to feel in paradise.

Requirements:
- PC (or a way of managing iPA files)
- Sideloadly
- 3u Tools to view the app documents
- Subway Surfer

1)

Since Critical Strike has serious issues with their games, I can't base my tutorial on this game. So let's go on a new one : Subway Surfer

First, download the Subway Surfer iPA : HERE

Then we will need 3 other files specific to H5GG for offset patching / hooking:

Simply see the instruction : HERE

You can delete the "hookme.test.dylib" cuz we don't need it.

You should have this :

Now, simply extract the iPA, copy the 3 files and move to the .app folder and paste it there. It should look like this :

Now simply ZIP the Payload, and rename it To WhatEver.ipa

Now we need to download the .deb that we gonna inject to the iPA : HERE

Now, we gonna need to Sideload the iPA WITH these settings :

We will need to use File Sharing later in the tutorial, so enable it. Don't forget to inject the H5GG.deb file.

We did like 50% of the work now hehe

2)

Now, we gonna code (or Ctrl+C, Ctrl+V) :

I use EasyHTML app on the AppStore to code it.

Offset Patching/Hooking on H5GG is done by injecting a .js script so, let's write it. you have a sample: HERE

Below is an edited version to work on Subway Surfer 3.6.0.

Offset Patching code :

h5gg.require(7.9); 
var h5frida=h5gg.loadPlugin("h5frida", "h5frida-15.1.24.dylib");
if(!h5frida) throw "Failed to load h5frida plugin";

function ActiveCodePatch(fpath, vaddr, bytes) {
    if(!h5frida.ActiveCodePatch(fpath, vaddr, bytes)) {
        var result = h5frida.ApplyCodePatch(fpath, vaddr, bytes);
        alert(fpath+":0x"+vaddr.toString(16)+"-修改失败!\n" + fpath+":0x"+vaddr.toString(16)+"-PatchFailed!\n" + result);return false;
    } return true;
}
function DeactiveCodePatch(fpath, vaddr, bytes) {
    return h5frida.DeactiveCodePatch(fpath, vaddr, bytes);
}

/*HERE IS OUR OFFSET PATCHING CODE*/

//public bool get_CanJump() -> 0x1B39598
//Enable a hack at 0x1B39598 with HEX : 200080D2C0035FD6
ActiveCodePatch("Frameworks/UnityFramework.framework/UnityFramework", 0x1B39598, "200080D2C0035FD6");

Well here we arn't using a template, we just want to patch our offset so we will enable it by default.

If you are using a template, just make a if statement, and use this code to disable the Offset Patching :

//this is just a POC
if (switch_Jump) {
    ActiveCodePatch("Frameworks/UnityFramework.framework/UnityFramework", 0x1B39598, "200080D2C0035FD6");
} else {
    //when you desactivate a patch, it need to be the same HEX that you use to enable the hack.
    DeactiveCodePatch("Frameworks/UnityFramework.framework/UnityFramework", 0x1B39598, "200080D2C0035FD6");
}

Now, inject the script with H5GG by clicking the "Scripts" button, and select the JavaScript file from there.

Information

The first JS run is just to prepare the Framework file and get a new one. This step is mandatory.

More details under.

Once this done, you should see this "error" (my offset is not the same on the picture, its normal i was testing another one. Ignore it):

A big alert for just telling us to overwrite a file , dont panic haha we gonna fix it !

If you want to replace the file without PC :

In theory, just change the UnityFramework given by H5GG with the old one. detailed step :

So this is where we need 3uTools. Go to the applications on your phone using 3utools, and select subway surfer then "view" (because you normally activated File Sharing). you should be able to see this :

Navigate to the directory until you find the UnityFramework file. then copy it, and replace it with the one of the Playload folder of the iPA. like this :

We don't see it on the pic, but the file patch is :

Payload\SubwaySurf.app\Frameworks\UnityFramework.framework

Ofc, delete the old one. i kept it & renamed just for demonstration.

Then, simply delete the app on your device, repack the new Payload folder and again Sideload the new iPA with the edited UnityFramework. you don't need to enable file sharing exept if you want to patch a new offset. but no need if you follow the tutorial

Then run the script again on the new sideloaded iPA, and you should be able to Jump every time due to the Offset Patching :happydance: .

Now, lets go to Hooking !

I will make a new script with this content (an edited version of the github one) :

h5gg.require(7.9); //设定最低需求的H5GG版本号//min version support for H5GG
var h5frida=h5gg.loadPlugin("h5frida", "h5frida-15.1.24.dylib");
if(!h5frida) throw "加载h5frida插件失败\n\nFailed to load h5frida plugin";
if(!h5frida.loadGadget("frida-gadget-15.1.24.dylib"))
    throw "加载frida-gadget守护模块失败\n\nFailed to load frida-gadget daemon module";
var procs = h5frida.enumerate_processes();
if(!procs || !procs.length) throw "frida无法获取进程列表\n\nfrida can't get process list";
var pid = -1; //pid=-1, 使用自身进程来调用OC/C/C++函数, 也可以附加到其他APP进程来调用
var found = false;
for(var i=0;i<procs.length;i++) {
    if(procs[i].pid==pid) {
        if(procs[i].name!='Gadget') throw "免越狱测试请卸载frida-server的deb然后重启当前APP\nFor non-jailbreak tests, please uninstall the frida-server deb and restart the current APP";
        found = true;
    }
}
if(!found) throw "frida无法找到目标进程\n\nfrida cannot find the target process";
var session = h5frida.attach(pid);
if(!session) throw "frida附加进程失败\n\nfrida attach process failed";

//监听frida目标进程连接状态, 比如异常退出
session.on("detached", function(reason) {
    alert("frida目标进程会话已终止(frida target process session terminated):\n"+reason);
});

var frida_script_line = frida_script("getline"); //safari console will auto add 2 line
var frida_script_code = "("+frida_script.toString()+")()"; //将frida脚本转换成字符串
var script = session.create_script(frida_script_code); //注入frida的js脚本代码

if(!script) throw "frida注入脚本失败\n\nfrida inject script failed!";
script.on('message', function(msg) {
    if(msg.type=='error') {
        script.unload(); //如果脚本发生错误就停止frida脚本
        try {if(msg.fileName=="/frida_script.js") msg.lineNumber += frida_script_line-1;} catch(e) {}
        if(Array.isArray(msg.info)) msg.info.map(function(item){ try { if(item.fileName=="/frida_script.js")
            item.lineNumber += frida_script_line-1;} catch(e) {}; return item;});
        var errmsg = JSON.stringify(msg,null,1).replace(/\/frida_script\.js\:(\d+)/gm,
            function(m,c,o,a){return "/frida_script.js:"+(Number(c)+frida_script_line-1);});
        alert("frida(脚本错误)script error:\n"+errmsg.replaceAll("\\n","\n"));
    }
    
    if(msg.type=='send')
        alert("frida(脚本消息)srcipt msg:\n"+JSON.stringify(msg.payload,null,1));
    if(msg.type=='log')
        alert("frida(脚本日志)script log:\n"+msg.payload);
});

if(!script.load()) throw "frida启动脚本失败\n\nfrida load script failed"; //启动脚本
function frida_script() { if(arguments.length) return new Error().line; 
                         
                         
            /*HERE IS OUR HOOKING*/
                         
                         
var Jump = h5frida.StaticInlineHookFunction("Frameworks/UnityFramework.framework/UnityFramework",
    0x1B39598,
    "bool",
    ["pointer"],
    function(instance) {
        //return 1 for true, 0 for false
        return 1;
    }
);
                        
   
}

You can hook any function type, just change the return type of the function.

//public float get_SpeedModifier() -> 0x1234567
var Speed = h5frida.StaticInlineHookFunction("Frameworks/UnityFramework.framework/UnityFramework",
    0x1234567,
    "float",
    ["pointer"],
    function(instance) {
        return 9999;
    }

);

Well, that's all hehe, hope you could achieve your goals !

Usefull

To "Enable" all your offset at once, you can just call the ActiveCodePatch function as much as u need on the script. it will proceed each offset at once, so that u need to replace the UnityFramework file once only

ActiveCodePatch("Frameworks/UnityFramework.framework/UnityFramework", 0x1212121, "YOUR HEX");
ActiveCodePatch("Frameworks/UnityFramework.framework/UnityFramework", 0x8989898, "YOUR HEX");
ActiveCodePatch("Frameworks/UnityFramework.framework/UnityFramework", 0x6565656, "YOUR HEX");

Usefull

Better would be to make a full working mod menu on JB, and convert it to H5GG after, cuz its a pain to test offset with H5GG lol

Credits :

@tuancc H5GG tool

- Me for the tuto

Feel free to ask questions about it if its related to the topic

If your app is crashing, you can see this

H5GG Discord : https://discord.gg/h5gg

H5GG Github : https://github.com/H5GG/H5GG

Maybe usefull :

Updated May 7, 2023 by 𓄼 . f v c k . 𓄹
made it cleaner

Rook · January 13, 2023

Your tutorials are so well written! ❤️

lxdx · January 13, 2023

29 minutes ago, Rook said:

Your tutorials are so well written! ❤️

:hug:

namcyeon · January 13, 2023

About the hooking, is it working on the no jailbreak?

lxdx · January 13, 2023

2 hours ago, namcyeon said:

About the hooking, is it working on the no jailbreak?

yes, it's the point of the tut

Happy Secret · January 14, 2023

This is brilliant. Let me follow exactly what you done here.

Not sure why my try with another game was not successful. The patched instruction is not the instruction I want. Odd.

let me follow yours and see how it works.

thanks again in creating this.

Happy Secret · January 14, 2023

Quick test result:

1. I also got the the UnityFramework patched by h5frida and stored inside static-inline-hook folder

2. With a detail look into it, the hex code of the instruction (patched) doesn't look right to me.

Orignal at 0x1B39598 is FD7BBFA9FD030091

- stp x29, x30, [sp, #-0x10]!
- mov x29, sp

After patch at 0x1B39598 is CF2A9914FD030091

- b #0x264ab4c
- mov x29, sp

What we are expecting at 0x1B39598 is 200080D2C0035FD6, Right??

- mov x0, #1
- ret

Tested in game, always Can Jump is not working. Same as my try in another game these few days.

I am using iPadOS 16.2 (non-jailbreak) with iPad Pro 2nd Gen.

Updated January 14, 2023 by Happy Secret

Happy Secret · January 14, 2023

Update on the hook:

Not sure why I got hook fail as well.

Index
frida(脚本日志）script log:
Frameworks/UnitFramework.frame-work/UnitvFramework:0x1b39598-
HOOK失敗！
Frameworks/UnityFramework.frame-work/UnityFramework:0x1b39598-HOOK-Failed!
未签名该地址，修补文件将生成在APP的
Documents/static-inline-hook目录中，请将该目录中所有文件替换到 ipa中的.app目录并重新签名安装！
The offset has not been patched, the patched file will be generated in the Documents/static-inline-hook directory of the APP, please replace all the files in this directory to the app directory in the ipa and re-sign and reinstall!

Issue for me is: The h5frida internal function find_hook_block always return NULL, and reporting “cannot parse hook info!” In NSLog.

This internal function is being use for ActiveCodePatch and StaticInlineHookFunction.

I don’t know how to debug further.

Updated January 14, 2023 by Happy Secret

lxdx · January 14, 2023

4 hours ago, Happy Secret said:

Quick test result:

1. I also got the the UnityFramework patched by h5frida and stored inside static-inline-hook folder

2. With a detail look into it, the hex code of the instruction (patched) doesn't look right to me.

Orignal at 0x1B39598 is FD7BBFA9FD030091

- stp x29, x30, [sp, #-0x10]!
- mov x29, sp

After patch at 0x1B39598 is CF2A9914FD030091

- b #0x264ab4c
- mov x29, sp

What we are expecting at 0x1B39598 is 200080D2C0035FD6, Right??

- mov x0, #1
- ret

Tested in game, always Can Jump is not working. Same as my try in another game these few days.

I am using iPadOS 16.2 (non-jailbreak) with iPad Pro 2nd Gen.

Mhh i did the tutorial on an A14, iOS 15.1 and the patch/hook worked well.

maybe H5GG doesn't support iOS 16 atm, but it's weard since we hook the app framework and not any device framework.

i don't understand how you got the bytes at 0x1B39598, i didn't used ida, i simply checked the function on dnSpy, patched it on JB with the LOP tool from iOSGods, it worked so i did it on H5GG, and it worked too

edit :

oh you mean the UnityFramework patched ? well i didn't looked at the data at the offset 0x1B...98, but it's seems normal to me that's it's not 2000...FD6, otherwise it will always be enable. i think that it creates another function on the UnityFramework (at another place) and at 0x1B...98, it calls it.

so if there is no script running, we shouldn't be able to jump always, but when we load our script, it probably jump to our created function in the UnityFramework, and so it return 2000..FD6 at our function (maybe at 0x264ab4c) and if we unload the script, the original bytes in the memory will load again making "normal jumps"

(this is my personal analysis, it may not be 100% right but this is how i visual it)

video : https://streamable.com/5g6nvz

Updated January 14, 2023 by ꞋꞌꞋꞌꞋꞌꞋꞌ