PhishSnitch is a real-time email security tool that monitors your Gmail inbox and performs deep URL analysis to detect phishing links. It utilizes Gmail API, URLScan.io, SSL verification, domain reputation checks, and more to provide comprehensive alerting and logging.
- ✅ Real-time Gmail monitoring (secure OAuth2)
- 🔗 Automated URL extraction from HTML & plain text
- 🔁 Shortened URL resolution & redirect tracing
- 🛡️ URLScan.io integration for advanced analysis
- 🔍 SSL certificate & domain reputation validation
⚠️ Risk scoring system (Low → Critical)- 🔔 Native desktop notifications
- 🧾 Persistent alert logging
git clone https://github.com/ShivKushDev/PhishSnitch.git
cd PhishSnitch
pip install -r requirements.txt- macOS:
brew install terminal-notifier - Linux:
sudo apt-get install libnotify-bin
- Visit Google Cloud Console
- Create a project and enable the Gmail API
- Generate OAuth 2.0 Client ID (Desktop App)
- Download
credentials.jsonand move it into:
mkdir config
mv credentials.json config/- Sign up at urlscan.io
- Copy your API key
Create config/config.yaml:
gmail:
credentials_path: config/credentials.json
check_interval: 300
urlscan:
api_key: "your-urlscan-api-key"
cache_duration: 3600
security:
whitelist: []
blacklist: []
risk_threshold: 70
alerts:
history_path: data/alert_history.json
desktop_notifications: truepython src/app.py- Browser opens on first run to authorize Gmail access
- Logs saved in
logs/app.log - Alerts stored in
data/alert_history.json
Note: If Ctrl+C doesn't stop the application, use PowerShell command:
Get-Process python | Stop-ProcessThis will forcefully terminate all Python processes.
| Level | Score Range | Indicators |
|---|---|---|
| CRITICAL | 80–100 | Malicious domains, credential theft |
| HIGH | 60–79 | Redirect chains, no SSL, fresh domain |
| MEDIUM | 40–59 | Obfuscation, suspicious URLs |
| LOW | 20–39 | New domains, URL shorteners |
http://example.comhttps://test-phish.example.comhttp://bit.ly/test123
Subject: Reset your password
From: [email protected]
Link: http://bit.ly/fake-login
python src/app.py
# Then send a test email and check logs/notificationsexport PYTHONPATH=$PWD
python -m pytest -v tests/
python -m pytest --cov=src tests/
Desktop notifications for immediate threat awareness
Detailed analysis of critical security threats
High risk threat detection with detailed scoring
Medium risk assessment with comprehensive analysis
Real-time threat detection and analysis in action
black src/
mypy src/- Fork this repo
- Create a new branch:
git checkout -b feature-name - Make your changes and commit
- Run tests & format code
- Submit a pull request 🎉
Licensed under the MIT License.