Skip to content

Commit f3c832c

Browse files
rev1si0nrev1si0n
committed
add README.en.md
1 parent 58b930c commit f3c832c

6 files changed

Lines changed: 2553 additions & 0 deletions

File tree

‎README.en.md‎

Lines changed: 1871 additions & 0 deletions
Large diffs are not rendered by default.

‎tools/README.en.md‎

Lines changed: 376 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,376 @@
1+
These tools normally only work on linux/mac systems and are a package of common personal functions, not specifically designed to be Windows compatible but that doesn't mean lamda doesn't support them. If you are using Windows, scripts ending in `.sh` should not work properly.
2+
3+
## Pre-requisites
4+
5+
Before you start, make sure that you have started the lamda server on your device.
6+
7+
**Note**: Some of the command documentation may be updated from time to time, so to avoid versioning issues, make sure you have the latest version of lamda and its Python libraries and dependencies installed on your device before continuing. Some functions require adb, so please ensure that you have the latest version of adb installed.
8+
9+
```bash
10+
# If you don't have it installed, please do your own search for how to install it, this is only basic advice
11+
# Windows
12+
https://developer.android.com/studio/releases/platform-tools
13+
# Mac
14+
brew install android-platform-tools
15+
# brew cask install android-platform-tools
16+
# Debian/Ubuntu
17+
apt install adb
18+
```
19+
20+
Clone the code locally
21+
22+
```bash
23+
git clone https://github.com/rev1si0n/lamda.git
24+
# If you don't know how to use git or don't have it installed, download this file locally and unpack it
25+
# https://github.com/rev1si0n/lamda/archive/refs/heads/master.zip
26+
```
27+
28+
Go to the tools directory and install the required dependencies
29+
```bash
30+
# Switch to the tools/ directory and execute
31+
pip3 install -r requirements.txt
32+
```
33+
34+
If you have enabled communication encryption (certificate) on the server side, you will need to set the environment variable ``CERTIFICATE`` before you can use it
35+
```bash
36+
# For linux / Mac
37+
export CERTIFICATE=/path/to/lamda.pem
38+
# For Windows (paths must not contain spaces)
39+
set CERTIFICATE=C:\Users\path\to\lamda.pem
40+
```
41+
42+
If you have changed lamda's default port 65000, you will also need to set the environment variable before using it
43+
44+
```bash
45+
# For linux / Mac
46+
export LAMDAPORT=8123
47+
# For Windows (path must not contain spaces)
48+
set LAMDAPORT=8123
49+
```
50+
51+
192.168.1.2 is the example IP, please get the actual IP address of the device yourself.
52+
53+
## cert.sh
54+
55+
Used to generate a certificate for transmission encryption
56+
```bash
57+
bash cert.sh
58+
```
59+
60+
If you need to generate a certificate for a specific CN
61+
```bash
62+
bash cert.sh device1.example.com
63+
```
64+
65+
The lamda.pem or device1.example.com.pem in the current directory will be the required certificate.
66+
After the certificate has been applied on the server side, the client must also use the certificate for remote calls and ssh connections.
67+
Once the certificate is applied, any operations performed through the client library will be encrypted and ssh will no longer use the default secret key.
68+
The web control page will also require a login (you can find this login password in the last line of the certificate).
69+
70+
If the operating system is not convenient for using this tool, a default SSL certificate is already available for you in the current directory
71+
72+
```bash
73+
test.pem # The certificate used to encrypt client-server communication
74+
```
75+
76+
## cert.py
77+
78+
Used to generate a certificate for transport encryption, equivalent to ``cert.sh`` except that this script can also be run on Windows and is used in the same way as cert.sh.
79+
80+
> Note: you may need to install the pyOpenSSL dependencies manually `pip install pyOpenSSL`
81+
82+
83+
## id_rsa
84+
85+
The default ssh private key used by lamda's built-in ssh, which is the same as the hard-coded private key in `ssh.sh`, `scp.sh`.
86+
87+
## startmitm.py
88+
89+
Start the man-in-the-middle, this will fully automate the global man-in-the-middle on the device and you will be able to intercept http/s traffic for your application, including of course DNS requests (globally).
90+
It is possible to apply and withdraw the man-in-the-middle automatically, and the device and network will be restored to its original state when you exit the script.
91+
92+
> Tip: Sometimes it is annoying to have all this stuff on Windows.
93+
> So specifically for Windows there is **startmitm.exe**, a **Windows command line program** that can be downloaded and placed in the system PATH or current directory and executed from the command line.
94+
> It has the same arguments as startmitm.py. You can do this without installing Python and any associated environment, but you will only be able to do basic man-in-the-middle operations. You can find it in every release. If not, you can look at older releases.
95+
> For Linux/Mac users, if you want to generate/use this standalone executable, package it yourself using the `pyinstaller startmitm.spec` command
96+
> (requires pyinstaller to be installed).
97+
98+
> If you need to intermediate the IAPP, go to **globalmitm**
99+
100+
First make sure that the current computer is on the same network segment as the device, 192.168.1.2 for the mobile device with lamda running.
101+
Secondly, make sure you have verified on the command line that mitmproxy has been installed successfully (type `mitmdump` on the command line to verify this).
102+
103+
Of course, you can also easily mitm if the computer is not on the same network segment as the device or if it is a remote device, please read on.
104+
105+
> Note: mitmweb is not suitable for long periods of multiple requests, the intercepted requests are stored in memory. So your memory will be eaten up if you use it for a long time (you can free it up from time to time by clicking on File->Clear All in the top left corner of the mitmweb interface).
106+
> For long man-in-the-middle operations, please use mitmdump instead, please find out how to use it yourself.
107+
108+
Execute
109+
```bash
110+
# Note that the device IP must be first in the argument
111+
python3 -u startmitm.py 192.168.1.2
112+
```
113+
That's all.
114+
115+
If you want to analyse with a LAN buddy
116+
117+
```bash
118+
python3 -u startmitm.py 192.168.1.2 --web-port 7890 --web-host 0.0.0.0
119+
# Then, have your little one open http://你的IP地址:7890 in their browser and voila!
120+
```
121+
122+
If you need to intercept application-specific traffic rather than global
123+
```bash
124+
# where com.some.package is the application ID
125+
python3 -u startmitm.py 192.168.1.2:com.some.package
126+
```
127+
That will work.
128+
129+
130+
If you want to use a specific DNS, or in some cases you may have DNS resolution errors/unresolvable (which may occur on some native systems), you can do this
131+
132+
```bash
133+
# Use mainland China DNS
134+
python3 -u startmitm.py 192.168.1.2 --nameserver 114.114.114.114
135+
```
136+
137+
If additional arguments need to be passed to mitmproxy, such as -s, then execute
138+
139+
> For information on how to write the `http_flow_hook.py` script, please refer to [docs.mitmproxy.org/stable/addons-examples](https://docs.mitmproxy.org/stable/addons-examples/) and [ mitmproxy/examples/contrib](https://github.com/mitmproxy/mitmproxy/tree/9.0.0/examples/contrib)
140+
141+
```bash
142+
# So you can modify the request or response in real time by writing http_flow_hook.py
143+
python3 -u startmitm.py 192.168.1.2 -s http_flow_hook.py
144+
```
145+
That's all.
146+
147+
The phone is not on the same network as the current computer, but you can physically touch the device, you can still do man-in-the-middle, but **you need to make sure the current device is connected to the **computer** via USB or ``adb connect`` and is ADB authorized.
148+
149+
```bash
150+
# localhost means using an adb device
151+
# Only one adb device is currently connected
152+
python3 -u startmitm.py localhost
153+
# The computer is connected to multiple adb devices, you need to specify adb serial
154+
# This serial can be found in the output of the command adb devices
155+
python3 -u startmitm.py localhost --serial bfde362
156+
```
157+
This will work.
158+
159+
The phone is not under the same network as the current computer and does not have physical access to the device, but as long as you have access to the lamda port you can also do man-in-the-middle.
160+
**This is usually the case** when you have forwarded lamda to a remote server using the built-in frp service, or when you have forwarded lamda's port 65000 somewhere on your own in some way (e.g. SSH, router port forwarding, etc. - **be aware of security issues**), in which case you and lamda
161+
**Only this port** is available for direct communication, the other ports are not accessible to each other. In this case, the phone cannot access any of the local ports, and the local phone can only access the lamda port of the phone (or the phone has a public IP, but the local phone is on a non-interoperable intranet), so that you need to go through the following. (Note that OpenVPN network interworking is not a case of this)
162+
163+
In this case, it needs to be done in a slightly more cumbersome combination, and here's how to do it.
164+
165+
First, install your own adb public key onto the device using `adb_pubkey.py` or by calling the interface yourself (search for it in this document).
166+
167+
Now execute the following command
168+
169+
```bash
170+
adb kill-server
171+
# If you are using the built-in frp or using ssh forwarding yourself
172+
# where x.x.x.x is usually 127.0.0.1, please change this to suit the facts
173+
# and 65000 here is not fixed, change it according to your actual destination forwarding port
174+
adb connect x.x.x.x:65000
175+
```
176+
177+
Finally, do the same as above via USB
178+
```bash
179+
# localhost means the adb device is being used
180+
# Only one adb device is currently connected
181+
python3 -u startmitm.py localhost
182+
# The computer is connected to multiple adb devices, you need to specify the adb serial
183+
python3 -u startmitm.py localhost --serial x.x.x.x:65000
184+
```
185+
186+
and that will do it.
187+
188+
Note: You may need to end the app completely and reopen it before the traffic data will be displayed.
189+
190+
Press `CONTROL` + `C` once to exit the script.
191+
192+
### Forwarding to upstream agents
193+
194+
startmitm itself will also start mitmproxy as a proxy service, by default traffic is sent from the local NIC by mitmproxy, if you need traffic to go through an upstream proxy instead of the local machine, you can specify an upstream proxy using the following, **only** **HTTP** is supported as an upstream proxy.
195+
196+
> DNS traffic will not go through the upstream proxy
197+
198+
```bash
199+
python3 -u startmitm.py 192.168.1.2 --mode upstream:http://example.com:8080
200+
# Omitting the http:// start is fine
201+
python3 -u startmitm.py 192.168.1.2 --mode upstream:example.com:8080
202+
```
203+
204+
If the upstream proxy requires login authentication
205+
206+
```bash
207+
python3 -u startmitm.py 192.168.1.2 --mode upstream:example.com:8080 --upstream-auth USER:PASSWORD
208+
```
209+
210+
These options are compatible with mitmproxy.
211+
212+
### DNS man-in-the-middle (DNS+HTTP/S)
213+
214+
Intercepting DNS requests requires that mitmproxy version >= 9.0.0 (and Python >= 3.9) and that the script is run as **administrator** or **root**.
215+
Some systems may have their own DNS service, so make sure that no other service is using port 53 before using this feature.
216+
217+
This option is different from `-nameserver` above, the `-dns` option refers to the dns intermediary
218+
219+
> DNS broker, default upstream DNS server is 1.1.1.1
220+
```bash
221+
python3 -u startmitm.py 192.168.1.2 --dns
222+
```
223+
224+
> Specify the upstream DNS as 114.114.114.114 (if in mainland China, we recommend using the following command to specify DNS)
225+
226+
```bash
227+
python3 -u startmitm.py 192.168.1.2 --dns 114.114.114.114
228+
```
229+
230+
> If the upstream DNS uses a non-standard port (e.g. 5353)
231+
232+
```bash
233+
python3 -u startmitm.py 192.168.1.2 --dns 192.168.0.100:5353
234+
```
235+
236+
There are some changes to the method name definitions in the hook script, `response()` for normal http requests, and `dns_response()` for intercepting DNS.
237+
238+
```python
239+
def response(flow):
240+
print (flow, type(flow))
241+
242+
def dns_response(flow):
243+
print (flow, type(flow))
244+
```
245+
246+
See the documentation for mitmproxy for details.
247+
248+
## adb_pubkey.py
249+
250+
A script to install the local adb pubkey to lamda, otherwise the adb connection will show unauthorized.
251+
252+
```bash
253+
## install adb pubkey
254+
python3 -u adb_pubkey.py install 192.168.1.2
255+
# Uninstall adb pubkey
256+
python3 -u adb_pubkey.py uninstall 192.168.1.2
257+
```
258+
259+
After installation, execute
260+
```bash
261+
adb kill-server
262+
adb connect 192.168.1.2:65000
263+
adb -s 192.168.1.2:65000 shell
264+
```
265+
to connect to the lamda adb.
266+
267+
## ssh.sh
268+
269+
Connect to the shell terminal on the phone.
270+
271+
Execute
272+
```bash
273+
bash ssh.sh 192.168.1.2
274+
```
275+
276+
and you're done.
277+
278+
## scp.sh
279+
280+
Use ``scp`` to copy the files on the device locally.
281+
282+
Copy the `/sdcard/DCIM` directory of 192.168.1.2 to the current directory
283+
284+
```bash
285+
bash scp.sh 192.168.1.2:/sdcard/DCIM .
286+
```
287+
288+
Copy the local directory/file `test/` to `/sdcard/` on device 192.168.1.2
289+
290+
```bash
291+
bash scp.sh test/ 192.168.1.2:/sdcard
292+
```
293+
294+
## discover.py
295+
296+
List all devices online in the **local network** (some devices may not be listed in some network situations, please try several times)
297+
298+
```bash
299+
python3 discover.py
300+
```
301+
302+
## fridarpc.py
303+
304+
A simple wrapper for the fridarpc function.
305+
306+
This function requires you to be proficient in writing frida scripts. Please refer to the test-fridarpc.js file for the script used in the example, and note in particular that the return value of the function defined by rpc.exports in the frida script can only be string/list/json or any js that can be serialised by json. Assume that the device IP is 192.168.0.2.
307+
308+
> Execute the following command to inject RPC into com.android.settings (watch for errors)
309+
310+
```bash
311+
python3 fridarpc.py -f test-fridarpc.js -a com.android.settings -d 192.168.0.2
312+
```
313+
314+
Now that you have the interface out, you can simply request `http://192.168.0.2:65000/fridarpc/myRpcName/getMyString?args=["A", "B"]` to get the results of the methods within the script, and the link can be opened with a browser. GET, and the parameter list can also use multiple parameters at the same time.
315+
316+
Note that the arguments are provided in **double quotes** and we recommend using json.dumps(["A", "B"])
317+
318+
> call with requests
319+
320+
```python
321+
import json
322+
import requests
323+
url = "http://192.168.0.2:65000/fridarpc/myRpcName/getMyString"
324+
data = requests.post(url, data={"args": json.dumps(["A", "B"])}).json()
325+
print (data["result"])
326+
327+
#* Status code 200 Everything is fine
328+
#* Status code 410 Script needs to be re-injected or script is not injected (automatic re-injection is not currently supported)
329+
#* Status code 500 Script or parameter exception
330+
#* Status code 400 Parameter error
331+
```
332+
333+
The format of the response result is fixed and can be opened in a browser for viewing.
334+
335+
## emu-install.sh
336+
337+
Server-side installation script for mainstream emulators only, requires device to be WIFI adb enabled, needs to be downloaded in advance
338+
The corresponding architecture server-side installation package to the current running directory.
339+
340+
```bash
341+
bash emu-install 192.168.1.2
342+
```
343+
344+
## statistics.sh
345+
346+
If you are unable to run LAMDA properly, you can use this script to generate an issue report by rebooting the device and ensuring that LAMDA has exited, pushing ``statistics.sh`` to /data/local/tmp using adb, and then executing it as root.
347+
348+
```bash
349+
# launch.sh is the path to the script that starts LAMDA
350+
sh /data/local/tmp/statistics.sh /data/local/tmp/arm64-v8a/bin/launch.sh
351+
# After execution, the file /sdcard/statistics.txt will be generated, just report this file
352+
```
353+
354+
## magisk
355+
356+
lamda's magisk module architecture
357+
358+
## Various service scripts (Docker)
359+
360+
> All images are for x86 platforms, you may have to make your own modifications and regenerate them for use on ARM processor Linux/Mac.
361+
362+
### openvpn
363+
364+
Out-of-the-box OpenVPN service
365+
366+
### globalmitm
367+
368+
Used to analyse traffic from foreign apps that require a proxy to connect
369+
370+
### frps
371+
372+
Out-of-the-box frp port forwarding
373+
374+
### socks5
375+
376+
Out-of-the-box socks5 proxy service

0 commit comments

Comments
 (0)