tgTrax - Telegram Activity Analyzer

tgTrax is a Python-based toolkit for tracking and analyzing Telegram user activity, designed for digital forensics and behavioral analysis.

Key Features

• Activity Tracking: Monitor online/offline status of Telegram users with configurable polling.
• Temporal Analysis: Calculate correlations (Spearman, Jaccard) and build user connection graphs.
• Community Detection: Identify user groups using Louvain method.
• Gantt Charts: Visualize activity timelines for forensic analysis.
• SQLite Backend: Store and query activity data efficiently.

Quick Start

1. Installation:

   git clone <repository-url>
   cd tgTrax
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

2. Configuration:

   • Create .env with TELEGRAM_API_ID and TELEGRAM_API_HASH.
   • Optionally edit tgTrax_config.json and TARGET_USERS env (comma-separated).

3. Usage:

   • Start tracking (foreground):

     TARGET_USERS="alice,bob" ./run.sh -v start

   • Start tracking (daemon):

     TARGET_USERS="alice,bob" ./run.sh start

   • Analysis API (Python):

     from core.tracker import CorrelationTracker
     from core.analysis import TemporalAnalyzer
     tracker = CorrelationTracker(["alice","bob"], db_path="tgTrax.db")
     df = tracker.get_activity_data()
     analyzer = TemporalAnalyzer(df, resample_period="1min")
     corr = analyzer.get_correlation_matrix()

Screenshots

User communities based on activity correlation.

Gantt chart of user online sessions.

License

MIT License. See LICENSE for details.