Skip to content

Commit cd269de

Browse files
MaxelwebMaxelweb
authored
Merge pull request #2 for release v1.0.0
Release version v1.0.0
2 parents 755d0c0 + dee299b commit cd269de

File tree

106 files changed

+9694
-5
lines changed

Some content is hidden

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

106 files changed

+9694
-5
lines changed

‎.gitignore

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
pip-wheel-metadata/
24+
share/python-wheels/
25+
*.egg-info/
26+
.installed.cfg
27+
*.egg
28+
MANIFEST
29+
30+
# PyInstaller
31+
# Usually these files are written by a python script from a template
32+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
33+
*.manifest
34+
*.spec
35+
36+
# Installer logs
37+
pip-log.txt
38+
pip-delete-this-directory.txt
39+
40+
# Unit test / coverage reports
41+
htmlcov/
42+
.tox/
43+
.nox/
44+
.coverage
45+
.coverage.*
46+
.cache
47+
nosetests.xml
48+
coverage.xml
49+
*.cover
50+
*.py,cover
51+
.hypothesis/
52+
.pytest_cache/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
target/
76+
77+
# Jupyter Notebook
78+
.ipynb_checkpoints
79+
80+
# IPython
81+
profile_default/
82+
ipython_config.py
83+
84+
# pyenv
85+
.python-version
86+
87+
# pipenv
88+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
89+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
90+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
91+
# install all needed dependencies.
92+
#Pipfile.lock
93+
94+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow
95+
__pypackages__/
96+
97+
# Celery stuff
98+
celerybeat-schedule
99+
celerybeat.pid
100+
101+
# SageMath parsed files
102+
*.sage.py
103+
104+
# Environments
105+
.env
106+
.venv
107+
env/
108+
venv/
109+
ENV/
110+
env.bak/
111+
venv.bak/
112+
113+
# Spyder project settings
114+
.spyderproject
115+
.spyproject
116+
117+
# Rope project settings
118+
.ropeproject
119+
120+
# mkdocs documentation
121+
/site
122+
123+
# mypy
124+
.mypy_cache/
125+
.dmypy.json
126+
dmypy.json
127+
128+
# Pyre type checker
129+
.pyre/
130+
.vscode/settings.json
131+
132+
# Extra
133+
*.zip
134+
135+
# Dependencies
136+
**/node_modules
137+
138+
# Log scripts
139+
**/log-qrgen**
140+
**/log-appium**
141+
142+
# QRCodeFuzzer
143+
tools/QRCodeFuzzer/data-tests/**
144+
!tools/QRCodeFuzzer/data-tests/app-example/

‎CHANGELOGS.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# QRFuzz Changelogs
2+
3+
**v1.0.0** (2023-03-12)
4+
5+
- Initial public release

‎LICENSE

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -631,8 +631,8 @@ to attach them to the start of each source file to most effectively
631631
state the exclusion of warranty; and each file should have at least
632632
the "copyright" line and a pointer to where the full notice is found.
633633

634-
<one line to give the program's name and a brief idea of what it does.>
635-
Copyright (C) <year> <name of author>
634+
QRFuzz - A fuzzing toolkit to test malicious QR Codes in Mobile Applications
635+
Copyright (C) 2023 Mariano Sciacco, Federico Carboni, Denis Donadel
636636

637637
This program is free software: you can redistribute it and/or modify
638638
it under the terms of the GNU General Public License as published by
@@ -652,7 +652,7 @@ Also add information on how to contact you by electronic and paper mail.
652652
If the program does terminal interaction, make it output a short
653653
notice like this when it starts in an interactive mode:
654654

655-
<program> Copyright (C) <year> <name of author>
655+
QRFuzz Copyright (C) 2023 Mariano Sciacco, Federico Carboni, Denis Donadel
656656
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
657657
This is free software, and you are welcome to redistribute it
658658
under certain conditions; type `show c' for details.

‎README.md

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,47 @@
1-
# FuzzQRTestingUNIPD
2-
Fuzz QR Testing multiple applications - UNIPD
1+
# QRFuzz
2+
3+
A fuzzing toolkit to test malicious QR Codes in mobile applications.
4+
5+
![QRFuzz banner](docs/images/qrfuzz-banner.png)
6+
7+
**Current release**: v1.0.0 (2023-03-12)
8+
9+
You can find toolkit updates in the [CHANGELOGS](CHANGELOGS.md) page.
10+
11+
## Installation
12+
13+
All the instructions to install the toolkit are inside the [docs / installation](docs/installation.md) page.
14+
15+
## Usage
16+
17+
All the instructions to use the toolkit are inside the [docs / usage](docs/usage.md) page.
18+
19+
## Quick Start
20+
21+
1. Connect an Android Smartphone to a PC and type `adb devices`
22+
- Save the `udid` (`device_id`) of the device
23+
2. Open a new terminal and start Appium
24+
- `appium -p 4723`
25+
3. Open a new terminal and start QRCodeGenerator
26+
- `cd tools/QRCodeGenerator`
27+
- `python main.py -a <app> -j <json_data_path> -p <position>`
28+
4. Open a new terminal and start QRCodeFuzzer
29+
- `cd tools/QRCodeFuzzer`
30+
- `node index.js <app> <data_path> <port> <device_id>`
31+
5. Once the tests are completed, check the results inside the test directory
32+
- `ls tools/QRCodeFuzzer/data-tests/<app_name>`
33+
34+
## Extend the tool
35+
36+
You can find example on how to extend the tool inside the folder of each tool.
37+
38+
- [QRCodeFuzzer](tools/QRCodeFuzzer/README.md)
39+
- [QRCodeGenerator](tools/QRCodeGenerator/README.md)
40+
41+
## Credits
42+
43+
This project has been developed by students from the University of Padua (UniPD, Italy).
44+
45+
- Federico Carboni
46+
- Denis Donadel
47+
- Mariano Sciacco

‎docs/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# QRFuzz Documentation
2+
3+
![QRFuzz banner](images/qrfuzz-banner.png)
4+
5+
## Installation
6+
7+
You can find installation instructions in [installation.md](installation.md).
8+
9+
## Usage
10+
11+
You can find usage instructions in [usage.md](installation.md).

‎docs/images/qrfuzz-banner.png

27.5 KB
Loading

‎docs/images/terminal-tmux-parallel.png

58.8 KB
Loading

‎docs/images/terminal-tmux-single.png

59.8 KB
Loading

‎docs/installation.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Test-bench Installation
2+
3+
![QRFuzz banner](images/qrfuzz-banner.png)
4+
5+
## Debian GNU/Linux installation
6+
7+
> This version has been tested with Debian 10 and 11, as well as RaspbianOS.
8+
9+
1. `cd scripts/debian-installer/`
10+
2. Execute `./pyhton-installer.sh`
11+
3. Execute `./appium-installer.sh`
12+
4. (OPTIONAL) Execute `./bash-variables-installer.sh`
13+
- **Note:** This will add ANDROID_HOME to bashrc and a global folder in `~/.npm-global`
14+
15+
## Generic installation for Windows, MacOS, Linux
16+
17+
### Requirements
18+
19+
Check if these programs are already installed in your OS (and install them, if not):
20+
21+
- Python (3.9+) with PIP
22+
- NodeJS (18.x+) with NPM
23+
24+
### QRCodeFuzzer Installation
25+
26+
1. Open the terminal inside `tools/QRCodeFuzzer`
27+
2. `npm install`
28+
29+
### QRCodeGenerator Installation
30+
31+
1. Open the terminal inside `tools/QRCodeGenerator`
32+
2. `pip install -r requirements.txt`
33+
34+
### Appium server
35+
36+
1. Follow the [instructions](https://appium.io/docs/en/about-appium/getting-started/?lang=en) from the official website.
37+

‎docs/usage.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Test-bench Setup & Execution
2+
3+
![QRFuzz banner](images/qrfuzz-banner.png)
4+
5+
To replicate the test-bench, you need a PC with a monitor and a smartphone.
6+
7+
> **Tip:** In order to have everything under control in just one screen, we recommend to use `tmux`.
8+
9+
## Automated Execution
10+
11+
In this approach, you can use scripts to simplify the interactions with the tools provided by the toolkit. These scripts are collected in the `scripts` folder under the name `scripts/test-*`.
12+
13+
### Automated Single Execution
14+
15+
![tmux-single-example](images/terminal-tmux-single.png)
16+
17+
1. Move inside `scripts/test-single`
18+
2. Open a terminal and configure `tmux` (or open multiple terminals) as shown in the image above (3 terminals).
19+
3. In the left terminal, execute `./qrgen-terminal.sh -p left -a <app_name> -s <optional:start_position>`.
20+
4. Position the smartphone so that the QR Code is fully framed by the camera.
21+
5. In the top right terminal, execute `adb devices` and take note of `device ID`.
22+
6. In the top right terminal, execute `appium` and take note of port.
23+
7. In the bottom right terminal, execute `./appium-terminal.sh -p <appium_port> -d <device_id> -a <app_name> -s <optional:start_position>`
24+
25+
If something fails (e.g. xpath / object ID changes in the app), you will receive a prompt from the bottom right terminal to put the app in the scan page and then press any key to continue.
26+
27+
If the app crashes, the QRCodeFuzzer will try to recover the previous test by re-opening the app.
28+
29+
> Tests are saved inside `tools/QRCodeFuzzer/data-tests/<app_name>`
30+
31+
### Automated Parallel Execution
32+
33+
![tmux-parallel-example](images/terminal-tmux-parallel.png)
34+
35+
1. Move inside `scripts/test-single`
36+
2. Open a terminal and configure `tmux` (or open multiple terminals) as shown in the image above (4 terminals).
37+
3. In the top left terminal, execute `./qrgen-terminal.sh -p left -a <app_name> -s <optional:start_position>`.
38+
4. In the top right terminal, execute `./qrgen-terminal.sh -p right -a <app_name> -s <optional:start_position>`.
39+
5. Position the smartphones so that the QR Code is fully framed by the cameras (one on the left, one on the right).
40+
6. In the bottom left (or right) terminal, execute `adb devices` and take note of `device ID` of both smartphones.
41+
7. In another workspace, or in a background window, open two new terminals and execute `appium -p <port_number>`.
42+
8. In the bottom left terminal, execute `./appium-terminal.sh -p <appium_port_1> -d <device_id_1> -a <app_name> -s <optional:start_position>`
43+
9. In the bottom right terminal, execute `./appium-terminal.sh -p <appium_port_2> -d <device_id_2> -a <app_name> -s <optional:start_position>`
44+
45+
If something fails (e.g. xpath / object ID changes in the app), you will receive a prompt from the bottom terminals to put the app in the scan page and then press any key to continue.
46+
47+
If the app crashes, the QRCodeFuzzer will try to recover the previous test by re-opening the app.
48+
49+
> Tests are saved inside `tools/QRCodeFuzzer/data-tests/<app_name>`
50+
51+
### Automated Sequential Execution (experimental)
52+
53+
Sequential execution can be useful to execute multiple applications tests.
54+
The setup is similar to single / parallel execution, with the only constraint that you can pass a `<app_lists_file>` instead of `<app_name>`.
55+
56+
Here's an example with parallel execution (single execution is straight forward):
57+
58+
1. Move inside `scripts/test-sequential`, and create two files `apps-phone-1.txt` and `apps-phone-2.txt`, each containing list of apps to test in new lines.
59+
2. Open a terminal and configure `tmux` (or open multiple terminals) as shown in the image above (4 terminals).
60+
3. In the top left terminal, execute `./qrgen-terminal.sh -p left -f <app_lists_file_1> -s <optional:start_position>`.
61+
4. In the top right terminal, execute `./qrgen-terminal.sh -p right -f <app_lists_file_2> -s <optional:start_position>`.
62+
5. Position the smartphones so that the QR Code is fully framed by the cameras (one on the left, one on the right).
63+
6. In the bottom left (or right) terminal, execute `adb devices` and take note of `device ID` of both smartphones.
64+
7. In another workspace, or in a background window, open two new terminals and execute `appium -p <port_number>`.
65+
8. In the bottom left terminal, execute `./appium-terminal.sh -p <appium_port_1> -d <device_id_1> -f <app_lists_file_1> -s <optional:start_position>`
66+
9. In the bottom right terminal, execute `./appium-terminal.sh -p <appium_port_2> -d <device_id_2> -f <app_lists_file_2> -s <optional:start_position>`
67+
68+
## Manual Execution
69+
70+
In this approach, you can directly employ each tool manually.
71+
72+
> **Tip:** Get the `udid` (`device_id`) using `adb devices`.
73+
74+
### Manual Single Execution
75+
76+
1. Start `appium -p 4723` in terminal (even in background)
77+
2. Start a bash script with `python main.py -a <app> -j <json_data_path> -p <left/right/center> -sf <optional:start_position>` in another terminal
78+
3. Start a bash script with `node index.js <app> <data_path> <port> <device_id> <optional:start_position>` in a third terminal
79+
80+
### Manual Parallel Execution
81+
82+
1. Start `appium -p 4723` in terminal A (even in background)
83+
2. Start `appium -p 4724` in terminal B (even in background)
84+
3. Start a bash script with `python main.py -a <app> -j <json_path>` for terminal 1
85+
4. Start a bash script with `python main.py -a <app> -j <json_path>` for terminal 2
86+
5. Start a bash script with `node index.js <app> <data_path> <port> <device_id>` for terminal 3 (same path as terminal 1)
87+
6. Start a bash script with `node index.js <app> <data_path> <port> <device_id>` for terminal 4 (same path as terminal 2)
88+
89+
## Extra
90+
91+
### Telegram Notifier
92+
93+
The Telegram notifier can be used to get notified about app status changes.
94+
95+
You can find installation and usage instructions in [scripts/telegram-notifier](../scripts/telegram-notifier/README.md) folder.

‎scripts/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# QRFuzz Scripts
2+
3+
![QRFuzz banner](images/qrfuzz-banner.png)
4+
5+
This folder contains the script for the installation and the execution of the toolkit.
6+
7+
Please, refer to the [complete documentation](../docs/README.md) before proceeding.

‎scripts/debian-installer/appium-installer.sh

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/bin/bash
2+
3+
# Appium and Android installer
4+
5+
echo "[QRFUZZ] Installing node, npm, openjdk, android-tools"
6+
sudo apt update -y
7+
sudo apt install -y nodejs npm openjdk-11-jre openjdk-11-jdk android-sdk-build-tools android-sdk
8+
9+
echo "[QRFUZZ] Installing appium globally and qr code fuzzer"
10+
npm install -g appium;
11+
(cd ../../tools/QRCodeFuzzer/ || exit; npm install)
12+
13+
echo "[QRFUZZ] APPIUM AND ANDROID INSTALLED"

0 commit comments

Comments
 (0)