Watch Dogs

A Python project to monitor torrent peers for Bulgarian IPs, collect threat intelligence, and visualize on a map.

IMPORTANT: This system is not implemented to be exposed on the internet. Use it for local, isolated access.

More information here: https://innerfirez.github.io/posts/watch-dogs-threat-intel-platform/

Features

• Monitors Kali Linux torrents for Bulgarian peers (24/7). Parrot OS torrents are not scraped (site doesn't provide direct .torrent links).
• Checks IPs with AbuseIPDB, IP-API, IPInfo.io, AlienVault OTX, Shodan (if abusive).
• Optional IPQualityScore scoring (fraud score + VPN/Proxy/Tor flags).
• Abstract IP Intelligence enrichment (full response stored; security flags shown in stats).
• C2 feed matching from C2-Tracker and C2IntelFeeds with daily syncs.
• Stores unique IP findings in SQLite (latest view only) with first/last seen metadata.
• Generates interactive Folium map with advanced search, quick filters, and SpiderFoot scan button.
• Optional real-time updates on the map HUD via WebSocket (Socket.IO) when full dependencies are installed.
• Exports findings to CSV, PDF
• Tracks the first torrent filename seen for each IP.
• Advanced analytics dashboards for trends, risk, and behavioral insights.

Setup

You can download new bg_only-ips-range.txt file from here: https://iptoasn.com/

1. Clone/copy the project to your Ubuntu server: /home/YOUR_USER/watch-dogs
2. Create venv: python3 -m venv watch_dogs_env
3. Activate: source watch_dogs_env/bin/activate
4. Install: pip install -r requirements.txt
   • Optional full install (tests + real-time + extras): pip install -r requirements_full.txt
5. Set API keys as environment variables (export in shell or add to .env):
   • ABUSEIPDB_API_KEY
   • SHODAN_API_KEY
   • GREYNOISE_API_KEY (GreyNoise Community)
   • IPQS_API_KEY (IPQualityScore)
   • ABSTRACT_API_KEY (Abstract IP Intelligence)
   • REGEN_MAP_TOKEN (optional, enables manual POST /regen_map)
   • EXPORT_TOKEN (optional, protects GET /export.csv)
   • SPIDERFOOT_URL (optional, default http://127.0.0.1:5001)
   • SPIDERFOOT_USER / SPIDERFOOT_PASS (optional, SpiderFoot auth)
   • SPIDERFOOT_USECASE (optional: all, investigate, passive, footprint)
6. C2 feed settings are static and configured in config.py (sync interval, feed URLs, file names).
7. Run manually: python main.py or setup as service (see below)

Setup as Systemd Service (Ubuntu)

1. Edit watch-dogs.service and replace YOUR_USER with your username
2. Update paths in the service file to match your installation directory
3. Copy service file: sudo cp watch-dogs.service /etc/systemd/system/
4. Reload systemd: sudo systemctl daemon-reload
5. Enable service: sudo systemctl enable watch-dogs
6. Start service: sudo systemctl start watch-dogs
7. Check status: sudo systemctl status watch-dogs
8. View logs: sudo journalctl -u watch-dogs -f
9. Stop service: sudo systemctl stop watch-dogs

Testing

1. Install full dependencies: pip install -r requirements_full.txt
2. Run tests: pytest

Files

• main.py: Entry point with scheduling.
• monitor.py: Torrent monitoring loop.
• asn_lookup.py: Bulgarian IP range checker.
• ip_checker.py: API integrations.
• database.py: SQLite storage.
• map_generator.py: Folium map creation.
• torrent_downloader.py: Weekly torrent updates.
• c2_feed_sync.py: Daily C2 feed downloader + matcher.
• analytics_dashboard.py: Advanced analytics engine.
• report_generator.py: PDF/HTML reporting.
• config.py: API keys and settings.
• templates/map_injection.html: Map UI template (HUD, filters, JS).
• maps/bulgaria_ips.html: Generated map.
• torrents/: Downloaded .torrent files.

Usage

• Run python main.py to start everything: monitoring, scheduling, and web server on http://0.0.0.0:3030
• Run python main.py --debug to enable Flask debug mode and console output for IPs/peers.
• Health endpoint: http://0.0.0.0:3030/health returns basic status and finding count.
• Open http://0.0.0.0:3030 for the interactive map (with Bulgaria border).
• Manual regeneration endpoint is disabled by default; set REGEN_MAP_TOKEN and send X-Auth-Token: <token> to POST /regen_map (the map Refresh button uses this token when set).
• CSV export: GET http://0.0.0.0:3030/export.csv (send X-Auth-Token: <token> if EXPORT_TOKEN is set).
• Existing IPs are rechecked every 7 days (adjust RECHECK_DAYS in config.py).
• C2 feed sync runs on app start and then every 24 hours. Run on demand: python c2_feed_sync.py.
• Advanced dashboards: http://0.0.0.0:3030/stats-enhanced and http://0.0.0.0:3030/analytics
• Reports: http://0.0.0.0:3030/report/html and http://0.0.0.0:3030/report/generate
• DB: watch_dogs.db for data (use SQLite browser to query).
• Logs: watch_dogs.log for detailed logs, including watched torrents.
• Monitor console (with --debug) for "Monitoring active" messages to confirm it's working.
• SpiderFoot integration: click the "Spider" button in a popup to start a scan in SpiderFoot and open the scan page (SpiderFoot must be running).

APIs Used

• AbuseIPDB: Abuse scores.
• IP-API: Geolocation, ISP, ASN.
• IPInfo.io: Additional ASN/ISP info.
• AlienVault OTX: Threat pulses.
• Shodan: Host details (only if abuse > 0).
• IPQualityScore: Risk score and VPN/Proxy/Tor flags.
• Abstract IP Intelligence: Security and hosting flags.
• C2 feeds: C2-Tracker and C2IntelFeeds.

Rate limits monitored; notifications on limits.

Endpoints

1. Main Map - http://localhost:3030
2. Classic Stats - http://localhost:3030/stats
3. Enhanced Stats - http://localhost:3030/stats-enhanced
4. Analytics - http://localhost:3030/analytics
5. IP Detail - http://localhost:3030/ip/
6. Heat Map - http://localhost:3030/heatmap
7. PDF Report - http://localhost:3030/report/generate
8. HTML Report - http://localhost:3030/report/html
9. CSV Export - http://localhost:3030/export.csv
10. Health Check - http://localhost:3030/health