Oblivion-1 ~ A Simple E-mail Tracker
π―οΈ Oblivion-Inverse is a simple e-mail tracking solution which based on the usage of web beacons or tracking pixels.
π’ New Upgrade is Now Available!
π We have moved onto Render
platform + Databases, Authentication is now handled using Firebase
! This branch (main
) contains the code for the latest stable release of this project now.
π» You can also use the initial version from v1 branch which is ready to be deployed on Heroku Cloud Platform or on a self hosted environment.
π΄ Several sections in this README needs to be updated with the new changes.
π Here we have a list of features that need to be implemented to enhance the overall experience. If you are willing to contribute, you can check available open issues or open new issues.
Feature | Task | Status |
---|---|
π Authentication handling - Firebase Auth | β |
π Better database handling - Firebase Realtime DB | β |
π Migration to Render | β |
πΆοΈ Theme Management (UI) | π§ |
π Tracking link Search functionality | π§ |
π» PWA functionality | π§ |
π Update Docs & Readme | π§ |
- What can I achieve using this?
- Setup & Usage
- Steps to create a tracking link for your email
- How to use a Geo Location API
- Special note about G-Mail
- Why not using cookies for tracking?
- Contributing
- License & Copyrights
- Disclaimer
What is a web beacon?
A web beacon (web bug) is a technique used on web pages and emails to unobtrusively (usually invisibly) allow checking that a user has accessed some content. Web beacons are typically used by third parties to monitor the activity of users at a website for the purpose of web analytics or page tagging. They can also be used for email tracking. - Wikipedia
What can I achieve using this?
Basically using this pixel tracking method you can obtain vast amount of information about the targets. But, when it comes to emails there are few restrictions. For an instance, JavaScripts are not generally allowed in email clients.
-
β IP address of the recipient's device (or the proxy)
-
β οΈ Request Header - User-Agent (Browser, Operating System, Device information)
Ex:Mozilla/5.0 (Linux; Android 11; Nokia G10) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.88 Mobile Safari/537.36
-
β οΈ Additionally, you can use a Geo Location API to obtain information such as approximate location, country, ISP ( Internet Service Provider), whether the user is using a VPN/Tor and so on... ) Read how to use a Geo Location API section
Screenshots
Desktop View | Mobile View |
---|---|
Dashboard | Tracking Data |
---|---|
Setup & Usage
Basic Requirements
-
Python3 and Pip
-
Git
-
Heroku Account & Heroku CLI (or suitable platform)
If you're willing to use Heroku, here they have explained all the steps for getting started with python apps. -
Code Editor (such as VS Code)
Installation
-
First clone or download this repository as a Zip file to your local machine.
-
Navigate to the directory.
cd Oblivion-Inverse
-
Create a virtual environment.
python3 -m venv venv
-
Activate virtual environment.
Linux:
source venv/bin/activate
Windows:
venv\Scripts\activate
-
Install dependencies.
pip install -r requirements.txt
-
Change the time zone used in
routes.py
: (Default value isAsia/Colombo
)# Line 38 TIMEZONE = "Your-Timezone"
To choose the correct time zone, you can query all the supported time zones like this; open a separate python shell and run the following code.
import pytz pytz.all_timezones
-
As we use Firebase Realtime Database and Firebase Authentication, you have to create a Firebase project and obtain the credentials. Visit Firebase Console and create a new project.
Then go to the project settings and click on theService Accounts
tab. Then click on theGenerate New Private Key
button. This will download a JSON file containing the credentials. Rename the file tocredentials.json
and place it in the root directory of the project. -
Now you have to create a new Firebase Authentication user. To do that, you have to go to the
Authentication
tab in the Firebase Console. Then click on theSet up sign-in method
button. Then click on theEmail/Password
tab and enable it. Then click on theUsers
tab and click on theAdd User
button. Enter the email and password of the user account you want to create. Then click on theAdd User
button. -
Now you have to create a new Firebase Realtime Database. To do that, you have to go to the
Database
tab in the Firebase Console. Then click on theCreate Database
button. Then select the database location and click on theNext
button. Then change the rules as follows and click on theEnable
button:{ "rules": { "MailTrackData": { "Users": { "$uid": { ".read": "auth !== null && auth.uid === $uid", ".write": "auth !== null && auth.uid === $uid" } }, "LinkHits": { ".read": false, ".write": true } } } }
-
Now go to project settings again and under the General tab you can find the
Web API Key
. And also,you are able to find theDatabase URL
under the SDK setup and configuration tab there.
(Ex:databaseURL: "https://your-app-default-rtdb.asia-southeast1.firebasedatabase.app"
)
Take a note of both of them since we will need them on the next step.
After that you can either test the application in your local machine or setup your selected platform, as you wish.
Testing/Using on your Local Machine | Network
First you have to set the following environment variables. Create a new file named .env
in the root directory of the project and add the following lines to it. Replace the values with your own values.
FIREBASE_API_KEY=Your-Firebase-API-Key
FIREBASE_DB_URL=Your-Firebase-Database-URL
SECRET_KEY=replace-this-text-with-a-suitable-key
FLASK_ENV=development
Then run the application using the following command:
flask run
If another program is already utilizing port 5000 (default port), Address already in use
error will be displayed.
If that happens you can specify a different port like this:
flask run --port 5001
Navigate to localhost:<port_number>
(default: http://localhost:5000) in your browser.
A login page will be displayed.
Input your newly created account's email & password and that's it!
Deploying to Render
Instructions will be added soon.
Like to complete this section? Open an issue...
Steps to create a tracking link for your email.
- Visit the homepage of the app and sign into your account.
Login Screen |
---|
- First add a suitable title for your message. You can add the subject of the specific email which will make it easier to identified at later times.
Create Entry |
---|
-
Then click 'Generate'
-
Then, you can drag & drop the tracking image to the end of your message body. (DO NOT copy & paste the image since it will insert your image as a base64 image to the email body) Otherwise, you can manipulate the content of the email body using Developer Tools in browser.
-
Everything's done! Now send your email and wait for the results to appear. (you need to refresh your browser to load new entries)
How to use a Geo Location API
Using a Geo Location API, you can collect additional information about the recipient such as;
- Approximate location
- Country
- ISP ( Internet Service Provider)
- VPN/Tor Usage ...
In routes.py
line 70 to 75 contains a simple API usage that can be altered according to your opinions. Please note that ipwhois service has certain limitations (like amount of requests) which may eventually cause errors. So, you can choose a better API which fit into your needs.
Special note about G-Mail
Since Google uses a special technique, "Image Proxies" to deliver images; this pixel based tracking method is not suitable to gather additional information about the recipients who use G-Mail. Instead of recipient's IP address and User-Agent, you will receive Google Image Proxyβs UA (User-Agent) and IP address which looks like this:
Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
But, on the bright side, you can still get the resource accessed date and time!
Why not using cookies for tracking?
Yes, you can set cookies for additional/accurate data collection. But they represent as third party cookies within devices. Most of the web browsers/platforms block such cookies by default. [maybe not Chrome yet π] So, it's the death of 3rd party cookies.
Update: Since some browsers/platforms allow 3rd party cookies, we are going to implement a cookie based tracking method in the future.
Contributing
Got an idea? Found a bug? Feel free to open an issue or submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us. You can also check CODE_OF_CONDUCT.md for more information.
License & Copyrights
The MIT License
This program is free software: you can redistribute it and/or modify it under the terms of the MIT License
Refer to the LICENSE file for more details.
Heroku, GMail, ipwhois, VS Code, Chrome are copyrights and/or trademarks of their respective owners.
Disclaimer
Tracking other users actions across any platform may considered as violation of their privacy. So, kindly use this in a responsible manner.