You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/instructions/mastg-frida-scripts.instructions.md
+28-22Lines changed: 28 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,10 +7,6 @@ This guide defines how to write and use Frida scripts in MASTG demos. Scripts li
7
7
8
8
**Note:** Prefer Frooky hooks over Frida scripts where possible, as they require less code. See `mastg-frooky-scripts.instructions.md` for details.
9
9
10
-
Version requirement
11
-
12
-
- Use Frida 17 or later. See @MASTG-TOOL-0031 ([Frida 17](https://mas.owasp.org/MASTG/tools/generic/MASTG-TOOL-0031/#frida-17)
13
-
14
10
## Location and naming
15
11
16
12
- Place scripts inside the demo folder and name them `script.js` unless multiple scripts are needed.
@@ -36,6 +32,34 @@ Examples:
36
32
- Backtraces: use `DebugSymbol.fromAddress` and cap lines.
37
33
- In `onEnter/onLeave`, capture context first (for example, `const ctx = this.context;`) before using nested arrow functions.
38
34
35
+
## Use and Validation of Frida APIs
36
+
37
+
When writing new Frida scripts for MASTG demos, always validate against the latest [frida-gum typings](https://raw.githubusercontent.com/DefinitelyTyped/DefinitelyTyped/refs/heads/master/types/frida-gum/index.d.ts) (human-readable version: [JavaScript API](https://frida.re/docs/javascript-api/)).
38
+
39
+
Consider the following key changes introduced in Frida 17 and if you encounter any of the old APIs in existing scripts, update them accordingly:
40
+
41
+
| Area | Before Frida 17 | Frida 17 and later | Notes |
| Global exports |`Module.getExportByName(null, "open")` and `Module.findExportByName(null, "open")`|`Module.getGlobalExportByName("open")` and `Module.findGlobalExportByName("open")`| Global lookups are now explicit. `get*` throws if missing, `find*` returns null. |
44
+
| Global symbol special case |`Module.getSymbolByName(null, "open")`|`Module.getGlobalExportByName("open")`| Only the null module symbol case maps to global exports. Not a general symbol replacement. |
45
+
| Module exports |`Module.getExportByName("libc.so", "open")` and `Module.findExportByName("libc.so", "open")`|`Process.getModuleByName("libc.so").getExportByName("open")` and `Process.getModuleByName("libc.so").findExportByName("open")`| Static helpers removed. Use a `Module` instance. `get*` throws, `find*` returns null. |
46
+
| Module symbols |`Module.getSymbolByName("libart.so", "ExecuteNterpImpl")`|`Process.getModuleByName("libart.so").getSymbolByName("ExecuteNterpImpl")`| Symbol lookup still exists but only on `Module` instances, not statically and not on pointers. |
47
+
| Module base |`Module.getBaseAddress("libc.so")`|`Process.getModuleByName("libc.so").base`| Base address helpers removed. Base is a property of a `Module` instance. |
48
+
| Module initialization |`Module.ensureInitialized("libobjc.A.dylib")`|`Process.getModuleByName("libobjc.A.dylib").ensureInitialized()`| Static initializer removed. Instance method ensures initializers have run for that module. |
49
+
| Enumeration |`Process.enumerateModules({ onMatch, onComplete })`|`Process.enumerateModules()`| Callback based enumeration removed. Now returns arrays. Same model for threads and ranges. |
50
+
| Memory access |`Memory.read*`, `Memory.write*`, `Memory.readUtf8String`, `Memory.writeUtf8String`, `Memory.readByteArray`, `Memory.writeByteArray`|`ptr.read*`, `ptr.write*`, `ptr.readUtf8String()`, `ptr.writeUtf8String()`, `ptr.readByteArray()`, `ptr.writeByteArray()`| All memory read and write helpers moved onto `NativePointer` instances, including numeric reads and writes, strings, and byte arrays. The `Memory.*` forms are replaced by instance methods on the pointer you want to access. |
51
+
52
+
Here's one example of updating code for Frida 17 that can serve as a reference: <https://patch-diff.githubusercontent.com/raw/AloneMonkey/frida-ios-dump/pull/200.diff>.
53
+
54
+
**Using ObjC and Java runtime bridges in Frida 17+:**
55
+
56
+
The Frida scripts we're creating for MASTG demos are meant to be run with the Frida CLI, so you can keep using the `ObjC` and `Java` runtime bridges as before. However, be aware that starting with Frida 17, these APIs are no longer part of the [frida-gum typings](https://raw.githubusercontent.com/DefinitelyTyped/DefinitelyTyped/refs/heads/master/types/frida-gum/index.d.ts). The Frida CLI pre-bundles these runtime bridges for you.
- Don't reinvent the wheel when something already exists. Use existing open-source sources when available, for example, <https://codeshare.frida.re/browse>.
Frida 17 removes the bundled [runtime bridges](https://frida.re/docs/bridges/) (`frida-{objc,swift,java}-bridge`) within Frida's GumJS runtime. When you use the commands `frida` and `frida-trace`, this doesn't have any noticeable impact, as they come with the Java, Objective-C, and Swift bridges pre-bundled, so you can still use them as before.
56
+
Frida 17 removes the bundled [runtime bridges](https://frida.re/docs/bridges/) (`frida-{objc,swift,java}-bridge`) within Frida's GumJS runtime. When you use CLI tools such as `frida`, `frida-trace` or @MASTG-TOOL-0145, this doesn't have any noticeable impact, as they come with the Java, Objective-C, and Swift bridges pre-bundled, so you can still use them as before.
57
57
58
58
However, if you are writing your own custom Frida-based tooling or scripts that depend on these bridges, you will now need to install them separately via `frida-pm`, Frida's package manager. For example, to install the Java bridge, run:
Frida has made changes to its native APIs. While these changes may break some of your existing scripts, they encourage you to write more readable and performant code. For instance, now, `Process.enumerateModules()` returns an array of `Module` objects, allowing you to work with them directly.
79
+
Frida has made changes to its native APIs. While these changes may break some of your existing scripts, they encourage you to write more readable and performant code. See a full overview in the [MASTG Frida scripts writing guide](https://mas.owasp.org/contributing/writing-content/mastg-frida-scripts.instructions#use-and-validation-of-frida-apis).
80
+
81
+
For instance, now, `Process.enumerateModules()` returns an array of `Module` objects, allowing you to work with them directly.
0 commit comments