Merge branch 'main' of github.com:christoftorres/Web3-Privacy

README.md

@@ -1,10 +1,10 @@
 <div align="center">
-  <img src="architecture.png" width="300"/>
+  <img src="architecture.png" width="800"/>
 </div>
 
 <h1 align="center">Is Your Wallet Snitching On You?</h1>
 
-A framework to quantify Web3 privacy violations such as web3-based browser fingerprinting and wallet address leakage to third-parties by DApps and wallet extensions. Our paper can be found
+A framework to quantify Web3 privacy violations such as Web3-based browser fingerprinting and wallet address leakage to third-parties by DApps and wallet extensions. Our paper can be found
 [here](https://arxiv.org/pdf/2306.08170.pdf).
 
 ## Installation Instructions
@@ -18,38 +18,130 @@ brew tap mongodb/brew
 brew install [email protected]
 ```
 
+##### Linux
+
+``` shell
+wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | apt-key add && echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.4 multiverse" | tee /etc/apt/sources.list.d/mongodb-org-4.4.list && apt-get update && apt-get install -y mongodb-org
+```
+
 For other operating systems follow the installation instructions on [mongodb.com](https://docs.mongodb.com/manual/installation/).
 
-### 2. Install Python dependencies
+### 2. Install Python and its dependencies
+
+##### MacOS
+
+``` shell
+python3 -m pip install -r requirements.txt
+```
+
+##### Linux
 
 ``` shell
+apt-get update -q && apt-get install -y wget curl unzip software-properties-common python3-distutils python3-pip python3-apt python3-dev
 python3 -m pip install -r requirements.txt
 ```
 
-### 3. Install Node.js
+### 3. Install Node.js and its dependencies
 
 ##### MacOS
 
 ``` shell
 brew install node
+cd framework/tracker-radar-collector && npm install
+cd framework/request-interceptor && npm install
+```
+
+##### Linux
+
+``` shell
+curl -sL https://deb.nodesource.com/setup_18.x | bash -
+apt-get update -q && apt-get install -y nodejs
+cd framework/tracker-radar-collector && npm install
+cd framework/request-interceptor && npm install
 ```
 
 For other operating systems follow the installation instructions on [nodejs.org](https://nodejs.org/en/download/package-manager/).
 
-## Analysis
+## Download datasets and results
 
-You can either run the data collection scripts or download our data from Google drive:
+``` shell
+wget https://zenodo.org/record/8071006/files/browser-fingerprinting-datasets.zip
+unzip browser-fingerprinting-datasets.zip
+mv datasets browser-fingerprinting/
+rm browser-fingerprinting-datasets.zip
+```
 
 ``` shell
-cd data-collection
-./download_and_import_data.sh
+wget https://zenodo.org/record/8071006/files/browser-fingerprinting-results.zip
+unzip browser-fingerprinting-results.zip
+mv results browser-fingerprinting/
+rm browser-fingerprinting-results.zip
+```
 
+``` shell
+wget https://zenodo.org/record/8071006/files/wallet-address-leakage-datasets.zip
+unzip wallet-address-leakage-datasets.zip
+mv datasets wallet-address-leakage/
+rm wallet-address-leakage-datasets.zip
 ```
 
-The bulk of the analysis was done in Jupyter notebooks, which can be opened by running:
+``` shell
+wget https://zenodo.org/record/8071006/files/wallet-address-leakage-results.zip
+unzip wallet-address-leakage-results.zip
+mv results wallet-address-leakage/
+rm wallet-address-leakage-results.zip
+```
+
+## Running Instructions
+
+### Detect Web3-based browser fingerprinting
+
+To detect for example if ```nytimes.com``` tries to access wallet information such as ```window.ethereum```, run the following commands:
+
+``` shell
+cd framework/tracker-radar-collector
+npm run crawl -- -u "https://www.nytimes.com" -o ./data/ -f -v -d "requests,targets,apis,screenshots"
+cat data/www.nytimes.com_89db.json | grep ethereum -C 10
+```
+
+The terminal should display ```window.ethereum``` along with other JavaScript properties.
+
+### Analyze Web3-based browser fingerprinting
+
+To analyze Web3-based browser fingerprinting and reproduce the results in our paper, run the following commands:
+
+``` shell
+cd browser-fingerprinting/results
+mkdir db
+mongod --dbpath db
+mongoimport --uri="mongodb://localhost:27017/web3_privacy" --collection fingerprinting_results --type json --file fingerprinting_results.json
+```
+
+``` shell
+cd browser-fingerprinting/analysis
+python3 analyze_detected_fingerprinting.py
+```
+
+### Detect wallet address leakage
+
+To detect for example if ```notional.finance``` is leaking your wallet address to a third-party, run the following commands:
 
 ``` shell
-cd analysis
-jupyter notebook
+cd framework/request-interceptor
+node run --interactive -u https://notional.finance/portfolio --debug verbose -w metamask-chrome-10.22.2 -t 30
+cat notional.finance.json | grep 7e4abd63a7c8314cc28d388303472353d884f292
 ```
-and selecting the notebook of choice.
+
+The terminal should display several entries which highlight that the wallet address is being leaked by the DApp to third-parties.
+
+### Analyze wallet address leakage
+
+To analyze wallet address leakage and reproduce the results in our paper, run the following commands:
+
+``` shell
+cd wallet-address-leakage/analysis
+python3 find-leaks-and-scripts-winter-et-al.py ../results/whats_in_your_wallet/crawl ../datasets/whats_in_your_wallet
+python3 find-leaks-and-scripts-dapps.py
+python3 find-leaks-and-scripts-wallet-extensions.py
+```
+