Référence / Configuration
Telegram · Mise en route rapide
Toutes les méthodes d'installation et de lancement de TgWitness : package Windows, Python, Docker et la démo synthétique, avec les premières vérifications.
Anglais · Русский · Ukrainien · Español · Portugais (Brésil) · Türkçe · العربية · فارسی · Urdu · हिन्दी · Bahasa Indonesia · Tiếng Việt · Chinois simplifié
TgWitness est une application autonome permettant de surveiller les groupes et les chaînes Telegram auxquels vos comptes ont accès. Elle fonctionne en local avec son propre répertoire de données.
Première visite ? Découvrez la démo avant de connecter un compte. Choisissez un guide pour les proxys, les témoins, les exportations ou la configuration du serveur. GitHub Actions capture (aperçu) exécute une capture dans votre propre fork GitHub plutôt que via une installation locale.
Installation et mise en route#
Le programme d’installation guidé inclut son propre Python et vérifie les hachages des paquets ainsi que les signatures de version avant l’installation. Le relancer met à jour une installation existante.
Linux / macOS :
curl -fsSL https://get.destroy.tools/install.sh | bash
Windows (PowerShell ou Invite de commandes) :
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"
Sur un serveur Ubuntu, exécutez en tant qu’administrateur pour installer un service en arrière-plan ; sur un ordinateur de bureau, exécutez en tant qu’utilisateur standard. Sous Ubuntu, le programme d’installation affiche l’adresse du panneau et la clé d’accès ; sous macOS et Windows, le panneau local s’ouvre dans votre navigateur. Passez à la section Se connecter à Telegram ci-dessous. La section Installer, vérifier et mettre à jour couvre les options d’accès au serveur, la vérification du script avant son exécution, les mises à jour et la désinstallation.
Autres méthodes#
Les versions GitHub, le code source et Docker constituent des alternatives au programme d’installation. Les téléchargements portables deviennent disponibles après la publication d’une version :
| Hébergeur | Aucune installation requise | Source : Python 3.11+ | Docker : Engine/Desktop avec Compose 2.20 ou version ultérieure |
|---|---|---|---|
| Windows | Extrayez « TgWitness-<version>-windows-amd64-portable.zip » des versions GitHub, puis double-cliquez sur « TgWitness.cmd » |
Double-cliquez sur Start.cmd |
Double-cliquez sur scripts\Docker.cmd |
| Linux / macOS | — | sh start.sh |
sh scripts/docker-start.sh |
Pour les méthodes depuis les sources, téléchargez et extrayez la branche main actuelle
ou clonez le dépôt :
git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness
Start.cmd propose d'installer Python 3.12 pour votre utilisateur Windows si aucune
version appropriée de Python n'est trouvée (via winget ou l'installateur signé de python.org). start.sh affiche
la commande d'installation exacte pour votre distribution Linux ou macOS si Python est manquant.
Le premier lancement depuis les sources crée .venv et installe les dépendances automatiquement.
Docker compile l’application et la lance en arrière-plan ; l’utilisation de Python sur l’hôte n’est
pas nécessaire. Les commandes « scripts\Docker.cmd » et « scripts/docker-start.sh » affichent l’adresse du panneau et le jeton lorsque
le conteneur fonctionne correctement. Les commandes Docker équivalentes sur chaque hôte pris en charge sont les suivantes :
docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt
http://127.0.0.1:8787 ouverte. Utilisez le jeton généré par l’assistant Docker ou la deuxième commande Docker, ou consultez le fichier data/live/panel-token.txt pour une installation portable ou à partir du code source. Poursuivez à la section « Connecter Telegram » ci-dessous. Les installations natives et Docker utilisent des espaces de stockage distincts ; le démarrage de Docker n’importe pas un journal natif existant.
Pour un serveur, le déploiement inclut la configuration automatique du protocole HTTPS, le redémarrage, la publication d’images, les mises à jour et les sauvegardes.
Découvrez l'interface#
- Exécutez TgWitness-Demo.cmd
dans le package portable, scripts\Demo.cmd
dans un dossier source Windows
ou
sh start.sh --demosous Linux/macOS. Un lancement depuis le dossier source crée d'abord.venvet installe les dépendances. - http://127.0.0.1:8787 ouvert.
- La démo locale ouvre automatiquement le journal d'exemple. Aucune copie du jeton n'est nécessaire pour un accès local direct.
Les messages de démonstration sont fictifs. Le mode démo ne permet pas de se connecter à un véritable compte Telegram.
Se connecter à Telegram#
[!AVERTISSEMENT] Utilisez des comptes dédiés. Telegram peut restreindre ou bannir définitivement les comptes en cas de volumes de requêtes jugés excessifs, quel que soit le client. Connectez des comptes prévus pour l’ observation plutôt que des comptes personnels ou précieux, et créez un identifiant API / hachage sur un compte dédié.
- Si la démo native est en cours d'exécution, arrêtez-la et exécutez Start.cmd ou
sh start.sh. Sinon, laissez l'installation en direct lancée ci-dessus en cours d'exécution. - Utilisez le jeton du panneau pour vous connecter. Un nouvel espace de travail s’ouvre lors de la première configuration. Choisissez Juste télécharger, Suivre les discussions ou Preuves pour un dossier.
- Vérifiez la connexion. Configurez votre propre proxy si nécessaire ; les paramètres de connexion restent disponibles après la configuration.
- Dans Connect Telegram, choisissez un numéro de téléphone, un code QR, des fichiers de compte (TData,
.session, StringSession, JSON de compte) ou une clé d’autorisation complète. Remplissez la confirmation Telegram, le code et le mot de passe de l’authentification en deux étapes lorsque cela vous est demandé. - Vérifiez le compte affiché, sélectionnez les discussions et passez en revue vos paramètres. Terminez depuis l’écran final. Pour l’option Juste télécharger, Démarrer l’exportation lance une exportation ponctuelle et ouvre la fenêtre Exportations pour afficher sa progression ; cela n’active pas l’observation continue.
Après la configuration, Chats → Choisir modifie les chats sélectionnés. Les paramètres contrôlent la collecte et les fichiers ; Plus d’outils → Sources fournit la liste détaillée des sources au niveau Standard ou Expert. Le guide du panneau décrit les six principales sections et leurs commandes contextuelles.
L’ID API + le hachage sont facultatifs : l’espace de travail utilise la paire enregistrée ou importée,
ou une paire fonctionnelle issue du pool intégré. Pour utiliser votre propre application, collez une
paire API ID:API Hash dans le champ API ID. Pour la clé d’authentification, collez les 512 caractères hexadécimaux
et sélectionnez l’ID DC fourni. L’ID utilisateur est facultatif et est validé s’il est saisi.
Les identifiants API permettent d’identifier votre application ; ils n’autorisent pas en soi l’accès à un compte. Les groupes privés ne nécessitent pas de nom d’utilisateur public, mais votre compte doit disposer d’un accès.
Pour les comptes existants, consultez les formats de comptes et de sessions : le panneau prend en charge Telethon StringSession, Telethon/Pyrogram SQLite, les fichiers ZIP TData à compte unique et les fichiers JSON de compte pris en charge. Sélectionnez une session et le fichier JSON correspondant, cliquez sur Vérifier les fichiers, puis sur Se connecter au compte. La connexion par code QR est également disponible avec les mêmes paramètres API facultatifs. TDLib, les sessions de bot et les inventaires de comptes au format CSV/JSON ne sont pas pris en charge.
Pour plusieurs comptes, utilisez Comptes → Importer des comptes et sélectionnez leurs fichiers de session pris en charge. Les fichiers JSON associés sont appariés selon leur nom de base ; chaque compte importé obtient son propre espace de travail. Consultez importation en masse et groupes de comptes.
Pour ajouter un autre compte, appuyez sur le signe + à côté du sélecteur de compte ou utilisez Comptes → Ajouter un compte. Les espaces de travail disposent de sessions, de journaux, de clés, de sources et de files d’attente distincts. Le changement de vue ne met pas fin à l’exécution des autres collecteurs. Un même compte Telegram ne peut pas être attribué à deux espaces de travail dans cette installation. Il n’y a pas de nombre fixe d’espaces de travail ; ceux-ci partagent un seul processus, leur capacité dépend donc de la machine.
Le jeton de panel en direct protège l’accès à vos autorisations Telegram et à vos
données enregistrées ; il est distinct des identifiants de l’API Telegram. Seule une démo locale explicitement lancée et
à laquelle on accède directement bénéficie d’une connexion automatique. Une démo à distance ou via un proxy utilise toujours
data/demo/panel-token.txt.
Vérification et exportation#
- Journal : recherchez et filtrez les observations par source et par type d'événement.
- Sélectionnez un événement pour consulter son enregistrement d'origine, ses informations d'attribution et ses versions sauvegardées.
- Les détails de modification indiquent le contenu disponible avant et après la modification. Les détails de suppression indiquent le dernier contenu capturé, le cas échéant ; un acteur inconnu reste inconnu.
- Formats d'exportation : ZIP signé, JSONL, CSV et HTML hors ligne.
- Exportation complète d’une conversation (Conversations → Exporter une conversation, ou Exportations → Capturer ou exporter une
conversation) : téléchargez l’historique visible complet d’une conversation
sous la forme d’un ensemble signé comprenant
chat.json(au format d’exportation Telegram) et un fichier lisiblechat.html. Les conversations privées fonctionnent lorsque le compte est membre. Il s’agit d’un instantané actuel, et non d’une reconstruction de messages supprimés ou modifiés précédemment. Vérifiez une copie à l’aide depython verify.py chat-export.zip --fingerprint TRUSTED_SHA256. - Point de contrôle à retenir : veillez à ce que les limites du journal signé ne soient pas incluses dans le collecteur.
- Télécharger le reçu d'exécution signé : conservez l'historique du programme et de la version du collecteur.
- Préparer une demande d’horodatage : préparez une demande hors ligne auprès d’une autorité d’horodatage ; suivez les instructions du fichier TIMESTAMP.md pour obtenir et vérifier une réponse.
- Vérification du journal : vérifiez les signatures des événements et les liens de la chaîne. L'exportation au format ZIP permet également de vérifier les fichiers multimédias.
Les navigateurs pris en charge enregistrent les exportations volumineuses directement dans le fichier de votre choix. Les autres navigateurs mettent en mémoire tampon au maximum 128 MiB. Lorsque le serveur est en cours d’exécution, l’interface CLI de streaming prend en charge des téléchargements plus volumineux sans mettre en mémoire tampon l’intégralité de la réponse :
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
Pour un autre espace de travail, ajoutez --profile ID à l’aide de Exports → Workspace ID.
Pour un serveur distant, ajoutez --url https://your-server. La limite de transfert par défaut est de
5 GiB ; --max-mib permet de la modifier. Le contenu ZIP signé dispose d’une limite de vérification distincte de 4 Gio non compressés
par défaut (Plus d’outils → Paramètres permet de l’augmenter ; vérifiez ces archives avec
verify.py --max-gib N). Vérifiez l’archive à l’aide d’une copie fiable du vérificateur, d’une
empreinte de clé conservée de manière indépendante et, au minimum à des fins de preuve, du certificat racine de l’autorité
d’horodatage (--tsa-ca).
Consultez la procédure d'installation#
python start.py --setup-only
python start.py --check
python start.py --check --json
--check vérifie les dépendances locales, la prise en charge de la signature, le stockage, la configuration des clés et
l’adresse d’écoute. Il n’installe rien et ne se connecte pas à Telegram. Un port
occupé peut signifier qu’une autre instance est en cours d’exécution. Utilisez un autre --port ou arrêtez-le d’abord.
Le programme de lancement s'installe dans .venv. Les commandes auxiliaires python -m tgwitness... doivent
utiliser .venv\Scripts\python.exe sous Windows ou .venv/bin/python sous Linux/macOS,
à moins que cet environnement ne soit déjà activé.
Sessions, protection et fonctionnement#
Une session Telethon SQLite fermée et cohérente .session peut être convertie localement à l’aide de
python -m tgwitness.sessions account.session --out account.tgwitness-session, puis
chargée dans Plus d’outils → Compte → Fichiers. L’importation directe de fichiers et la connexion via QR code sont également disponibles. Consultez
CONNECTION-SECURITY.md pour connaître les formats de connexion, SOCKS5,
HTTP CONNECT, MTProxy et les clés principales externes.
La mise en pause de la surveillance interrompt la collecte. Le verrouillage ne fait que fermer l’accès au navigateur. La fermeture d’un onglet laisse le processus de collecte en cours d’exécution. L’arrêt du processus interrompt la collecte ; un instantané de l’historique ne permet pas de reconstituer toutes les modifications ou suppressions manquées. Découvrez le fonctionnement de la collecte en ce qui concerne les règles d’événements, les files d’attente de pièces jointes, l’isolation des comptes et le comportement en cas de redémarrage.
Les sessions et les secrets sont chiffrés. Le contenu des messages, les médias et les exportations nécessitent un disque ou un volume chiffré. Vérifier les signatures du journal à l’aide d’une clé de confiance et conserver les points de contrôle séparément. Examiner les enregistrements de capture, les justificatifs horaires externes et les attestations d’environnement pour le mode de collecte sélectionné.
Consultez le fichier OPERATIONS.md pour la sauvegarde et la restauration, DEPLOYMENT.md
pour l’hébergement, et la page deploy/ pour des exemples d’utilisation. Le panneau d’installation
comprend également un guide de configuration hors ligne à l’adresse /guide.html.
Les vérifications effectuées et les limites restantes sont consignées dans les fichiers VERIFICATION.md et READINESS.md.