Skip to content

Commit 0dfe9a1

Browse files
caikeluncaikelun
committed
first commit
0 parents  commit 0dfe9a1

File tree

89 files changed

+9504
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

89 files changed

+9504
-0
lines changed

‎.gitignore

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.DS_Store
2+
3+
build/
4+
.cxx/
5+
.gradle/
6+
.idea/
7+
*.iml
8+
*.log
9+
*.so
10+
wrap.sh
11+
local.properties

‎CONTRIBUTING.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Contributing to bhook
2+
3+
Welcome to the bhook project. Read on to learn more about our development process and how to propose bug fixes and improvements.
4+
5+
## Issues
6+
7+
We use GitHub issues to track public bugs and feature requests. Before creating an issue, please note the following:
8+
9+
1. Please search existing issues before creating a new one.
10+
2. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue. The more information the better.
11+
12+
13+
## Branch Management
14+
15+
There are 2 main branches:
16+
17+
1. `main` branch
18+
19+
* It's the latest (pre-)release branch. We use `main` for tags.
20+
* **Please do NOT submit any PR on `main` branch.**
21+
22+
2. `dev` branch
23+
24+
* It's our stable developing branch.
25+
* Once `dev` has passed our internal tests, it will be merged to `main` branch for the next release.
26+
* **Please always submit PR on `dev` branch.**
27+
28+
29+
## Pull Requests
30+
31+
Please make sure the following is done when submitting a pull request:
32+
33+
1. Fork the repo and create your branch from `main`.
34+
2. Add the copyright notice to the top of any new files you've added.
35+
3. Try your best to test your code.
36+
4. Squash all of your commits into one meaningful commit.
37+
38+
39+
## Code Style Guide
40+
41+
1. 4 spaces for indentation rather than tabs.
42+
2. Follow the C code style already in place.
43+
44+
45+
## License
46+
47+
By contributing to bhook, you agree that your contributions will be licensed under its [MIT LICENSE](LICENSE).

‎LICENSE

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
Copyright (c) 2020-present, ByteDance, Inc.
2+
3+
Most source code in bhook are MIT licensed. Some other source code
4+
have BSD-style licenses.
5+
6+
A copy of the MIT License is included in this file.
7+
8+
9+
10+
Source code Licensed under the BSD 2-Clause License
11+
===================================================
12+
13+
tree.h
14+
15+
Copyright 2002 Niels Provos <[email protected]>
16+
All rights reserved.
17+
18+
Redistribution and use in source and binary forms, with or without
19+
modification, are permitted provided that the following conditions
20+
are met:
21+
1. Redistributions of source code must retain the above copyright
22+
notice, this list of conditions and the following disclaimer.
23+
2. Redistributions in binary form must reproduce the above copyright
24+
notice, this list of conditions and the following disclaimer in the
25+
documentation and/or other materials provided with the distribution.
26+
27+
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
28+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29+
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
30+
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
31+
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
32+
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33+
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34+
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
36+
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37+
38+
39+
40+
Source code Licensed under the BSD 3-Clause License
41+
===================================================
42+
43+
queue.h
44+
45+
Copyright (c) 1991, 1993 The Regents of the University of California.
46+
All rights reserved.
47+
48+
Redistribution and use in source and binary forms, with or without
49+
modification, are permitted provided that the following conditions
50+
are met:
51+
1. Redistributions of source code must retain the above copyright
52+
notice, this list of conditions and the following disclaimer.
53+
2. Redistributions in binary form must reproduce the above copyright
54+
notice, this list of conditions and the following disclaimer in the
55+
documentation and/or other materials provided with the distribution.
56+
3. Neither the name of the University nor the names of its contributors
57+
may be used to endorse or promote products derived from this software
58+
without specific prior written permission.
59+
60+
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
61+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
62+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
63+
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
64+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
65+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
66+
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
67+
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
68+
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
69+
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
70+
SUCH DAMAGE.
71+
72+
73+
74+
Terms of the MIT License
75+
========================
76+
77+
Permission is hereby granted, free of charge, to any person obtaining a copy
78+
of this software and associated documentation files (the "Software"), to deal
79+
in the Software without restriction, including without limitation the rights
80+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
81+
copies of the Software, and to permit persons to whom the Software is
82+
furnished to do so, subject to the following conditions:
83+
84+
The above copyright notice and this permission notice shall be included in all
85+
copies or substantial portions of the Software.
86+
87+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
88+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
89+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
90+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
91+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
92+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
93+
SOFTWARE.

‎README.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# bhook
2+
3+
![](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)
4+
![](https://img.shields.io/badge/release-1.0.0-red.svg?style=flat)
5+
![](https://img.shields.io/badge/Android-4.1%20--%2012-blue.svg?style=flat)
6+
![](https://img.shields.io/badge/arch-armeabi--v7a%20%7C%20arm64--v8a%20%7C%20x86%20%7C%20x86__64-blue.svg?style=flat)
7+
8+
bhook is a PLT hook framework for Android app.
9+
10+
[README 中文版](README.zh-CN.md)
11+
12+
13+
## Features
14+
15+
* Multiple hooks and unhooks for the same function do not conflict with each other.
16+
* Hook a single, partial or all of the dynamic libraries in the process.
17+
* Hook the newly loaded dynamic libraries automatically.
18+
* Avoid recursive-calls and circular-calls between proxy functions automatically.
19+
* Support unwinding backtrace in proxy function.
20+
* Support Android 4.1 - 12 (API level 16 - 31).
21+
* Support armeabi-v7a, arm64-v8a, x86 and x86_64.
22+
* MIT licensed.
23+
24+
25+
## Usage
26+
27+
### 1. Add dependency in build.gradle
28+
29+
bhook is published on [Maven Central](https://search.maven.org/), and uses [Prefab](https://google.github.io/prefab/) package format for [native dependencies](https://developer.android.com/studio/build/native-dependencies), which is supported by [Android Gradle Plugin 4.0+](https://developer.android.com/studio/releases/gradle-plugin?buildsystem=cmake#native-dependencies).
30+
31+
```Gradle
32+
allprojects {
33+
repositories {
34+
mavenCentral()
35+
}
36+
}
37+
```
38+
39+
```Gradle
40+
android {
41+
buildFeatures {
42+
prefab true
43+
}
44+
}
45+
46+
dependencies {
47+
implementation 'com.bytedance:bytehook:1.0.0'
48+
}
49+
```
50+
51+
### 2. Add dependency in CMakeLists.txt or Android.mk
52+
53+
> CMakeLists.txt
54+
55+
```CMake
56+
find_package(bytehook REQUIRED CONFIG)
57+
58+
add_library(mylib SHARED mylib.c)
59+
target_link_libraries(mylib bytehook::bytehook)
60+
```
61+
62+
> Android.mk
63+
64+
```
65+
include $(CLEAR_VARS)
66+
LOCAL_MODULE := mylib
67+
LOCAL_SRC_FILES := mylib.c
68+
LOCAL_SHARED_LIBRARIES += bytehook
69+
include $(BUILD_SHARED_LIBRARY)
70+
71+
$(call import-module,prefab/bytehook)
72+
```
73+
74+
### 3. Specify one or more ABI(s) you need
75+
76+
```Gradle
77+
android {
78+
defaultConfig {
79+
ndk {
80+
abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
81+
}
82+
}
83+
}
84+
```
85+
86+
### 4. Add packaging options
87+
88+
If you are using bhook in an SDK project, you may need to avoid packaging libbytehook.so into your AAR, so as not to encounter duplicate libbytehook.so file when packaging the app project.
89+
90+
```Gradle
91+
android {
92+
packagingOptions {
93+
exclude '**/libbytehook.so'
94+
}
95+
}
96+
```
97+
98+
On the other hand, if you are using bhook in an APP project, you may need to add some options to deal with conflicts caused by duplicate libbytehook.so file.
99+
100+
```Gradle
101+
android {
102+
packagingOptions {
103+
pickFirst '**/libbytehook.so'
104+
}
105+
}
106+
```
107+
108+
### 5. Initialize
109+
110+
```Java
111+
import com.bytedance.android.bytehook.ByteHook;
112+
113+
public class MySdk {
114+
public static synchronized void init() {
115+
ByteHook.init();
116+
}
117+
}
118+
```
119+
120+
### 6. Hook and Unhook
121+
122+
```C
123+
#include "bytehook.h"
124+
```
125+
126+
```C
127+
bytehook_stub_t bytehook_hook_single(
128+
const char *caller_path_name,
129+
const char *callee_path_name,
130+
const char *sym_name,
131+
void *new_func,
132+
bytehook_hooked_t hooked,
133+
void *hooked_arg);
134+
135+
bytehook_stub_t bytehook_hook_partial(
136+
bytehook_caller_allow_filter_t caller_allow_filter,
137+
void *caller_allow_filter_arg,
138+
const char *callee_path_name,
139+
const char *sym_name,
140+
void *new_func,
141+
bytehook_hooked_t hooked,
142+
void *hooked_arg);
143+
144+
bytehook_stub_t bytehook_hook_all(
145+
const char *callee_path_name,
146+
const char *sym_name,
147+
void *new_func,
148+
bytehook_hooked_t hooked,
149+
void *hooked_arg);
150+
151+
int bytehook_unhook(bytehook_stub_t stub);
152+
```
153+
154+
These three hook functions are used to hook single, partial, and all caller dynamic libraries in the process.
155+
156+
Notice:
157+
* If you need to call the original function in the proxy function, please always use the `BYTEHOOK_CALL_PREV()` macro.
158+
* Make sure to call `BYTEHOOK_POP_STACK()` macro before proxy function returning. In the CPP source file, you can also call `BYTEHOOK_STACK_SCOPE()` macro at the beginning of the proxy function instead.
159+
* bhook proxies `dlopen()` and `android_dlopen_ext()` internally, so please do not try to hook these two functions. If you want to monitor the loading of ELF, please use `bytehook_add_dlopen_callback()` and `bytehook_del_dlopen_callback()`.
160+
161+
There is a sample app in the [bytehook-sample](bytehook_sample) folder you can refer to.
162+
163+
164+
## Contributing
165+
166+
[Contributing Guide](CONTRIBUTING.md)
167+
168+
169+
## License
170+
171+
[MIT License](LICENSE)

0 commit comments

Comments
 (0)