Telepathy: An OSINT toolkit for investigating Telegram chats. Developed by Jordan Wildon. Version 2.3.2.
1
2
3
+
Telepathy has been described as the "swiss army knife of Telegram tools," allowing OSINT analysts, researchers and digital investigators to archive Telegram chats (including replies, media content, comments and reactions), gather memberlists, lookup users by given location, analyze top posters in a chat, map forwarded messages, and more.
2
4
3
-
Telepathy: An OSINT toolkit for investigating Telegram chats. Developed by Jordan Wildon. Version 2.2.58.
5
+
The toolkit has already seen a wide variety of use cases, including but not limited to: in investigative and data journalism, by academic and research institutions, and for intelligence gathering and analysis.
6
+
7
+
8
+
## !! IMPORTANT:
9
+
With the update to 2.3.0, you will need to delete your login.txt file to prevent errors if using the alternative login feature. Upon first use, Telepathy will guide you through setup of the details once again. To work around this, instead of deleting and recreating the file, you can add a newline character to the end of your current API details to ensure Telepathy scans the file correctly.
10
+
11
+
A note on unique identifiers per account: You will notice that depending on which alternative account you use, the access hash will vary. The same will happen with User IDs, which are unique to each Telegram account accessing them. For deeper data analysis based on user IDs, this is important to bare in mind as users will have as many unique IDs as accounts you've used to access information. In future, Telepathy may include a feature to assign unique identifier per account found based on a hash of the available information, regardless of which account accessed the data.
4
12
5
13
14
+
6
15
## Installation
7
16
8
17
### Pip install (recommended)
skipped 26 lines
35
44
Options:
36
45
- **'--target', '-t' [CHAT]**
37
46
38
-
this option will identify the target of the scan. The specified chat must be public. To get the chat name, look for the 't.me/chatname' link, and subtract the 't.me/'.
47
+
this option will identify the target of the scan. The specified chat must be publicorhaveaprivatelink. To get the chat name, look for the 't.me/chatname' link, and subtract the 't.me/'.
39
48
40
49
For example:
41
50
skipped 6 lines
48
57
49
58
- **'--comprehensive', '-c'**
50
59
51
-
A comprehensive scan will offer the same information as the basic scan, but will also archive a chat's message history.
60
+
A comprehensive scan will offer the same information as the basic scan, but will also archive a chat's message history,gatherthenumberofreactions,archivehowmanytimesamessagehasbeenforwarded,thenumberofrepliestoeachmessage,andmore.
61
+
62
+
Reaction lists are included in the archive file, including basic calculations of engagement rate. Only the most-common reactions are listed, with the total including all possible reactions. Currently, Telepathy calculates engagement rates based on forwards, comments and reactions seperately, with a calculation based on post views and one based on chat participant count. In future, Telepathy may include deeper analytics which can be cross-compared between chats based on a combination of these metrics, fixing for when comments, reactions or forwards are allowed or disallowed in a given chat.
52
63
53
64
For example:
54
65
skipped 4 lines
59
70
60
71
- **'--forwards', '-f'**
61
72
62
-
This flag will create an edgelist based on messages forwarded into a chat. It can be used alongside either a default or comprehensive scan.
73
+
This flag will create an edgelist based on messages forwarded into a chat. It can be used alongside either a default or comprehensive scan.Since2.3.0,TelepathynowformatstheseedgeliststomaximizecompatabilitywithGephi.
63
74
64
75
For example:
65
76
66
77
```
67
78
$ telepathy -t durov -f
79
+
80
+
$ telepathy -t durov -c -f
68
81
```
69
82
70
83
skipped 1 lines
72
85
73
86
Use this flag to include media archiving alongside a comprehensive scan. This makes the process take significantly longer and should also be used with caution: you'll download all media content from the target chat, and it's up to you to not store illegal files on your system.
74
87
75
-
Since 2.2.0, downloading all media files will also generate a CSV file listing the files' metadata.
76
-
77
-
For example, this will run a comprehensive scan, including media archiving:
88
+
To archive media, you must run a comprehensive scan:
78
89
79
90
```
80
91
$ telepathy -t durov -c -m
81
92
```
82
93
94
+
Once files have downloaded, you can run exiftool on the associated media directory to gather deeper insights on the files, their metadata, and in some cases attribute who might be behind an anonymous channel. Further details are in the "bonus investigations tips" section of this README.
83
95
84
-
- **'--user', '-u' [USER]**
85
96
86
-
Looks up a specified user ID. This will only work if your account has "encountered" the user before (for example, after archiving a group), you can specify User ID or @nickname
97
+
- **'--user', '-u'**
98
+
99
+
Looks up a specified user. This will only work if your account has "encountered" the user before (for example, after archiving a group), you can specify User ID or @nickname. If looking up by username, it's not always necessary for your account to have already seen the user.
87
100
88
101
```
89
102
$ telepathy -t 0123456789 -u
skipped 2 lines
92
105
```
93
106
94
107
95
-
- **'--location', '-l'[COORDINATES]**
108
+
- **'--location', '-l']**
96
109
97
-
Finds users near to specified coordinates. Input should be longitude followed by latitude, seperated by a comma. This feature only works if your Telegram account has a profile image which is set to publicly viewable.
110
+
Finds users near to specified coordinates. Input should be longitude followed by latitude, seperated by a comma. This feature only works if your Telegram account has a profile image which is set to bepublicly viewable.
111
+
112
+
While searches for multiple locations at once may work in some cases, Telegram appears to have a limit on how quickly an account can cycle through locations. At the time of writing, this appears to be at least ten minutes. Further location scanning support while using multiple accounts is being explored for a future release.
98
113
99
114
```
100
115
$ telepathy -t 51.5032973,-0.1217424 -l
101
116
```
102
117
103
118
104
-
- **'--alt', '-a'**
119
+
- **'--alt', '-a'[NUMBER]**
105
120
106
-
Flag for running Telepathy from an alternative number. You can use the same API key and Hash but authenticate with a different phone number. Allows for running multiple scans at the same time.
121
+
Flag for running Telepathy from an alternative numberorAPIdetails. You can use the same API key and Hash but authenticate with a different phone number. Thisallows for running multiple scans at the same time.Telepathywilldefaulttothefirstdetailsyouoffer,anduptofourotherscanbeadded.PleaseseethenotesatthetopofthisREADMEforinformationregardinglimitationswithuserIDsusingthismethod.
107
122
108
123
```
109
-
$ telepathy -t Durov -c -a
124
+
$ telepathy -t Durov -c -a1
110
125
```
111
126
112
127
113
128
- **'--export', '-e'**
114
129
115
-
Exports all chats your account is part of to a CSV file. In a future release, this may assist with settingupmultiple accounts following the same groups.
130
+
Exports all chats your account is part of to a CSV file. In a future release, this may assist with provisioningnew accounts toautomaticallyfollowing the listed groups.
116
131
117
132
```
118
133
$ telepathy -e
skipped 2 lines
121
136
122
137
- **'--reply', '-r'**
123
138
124
-
Flag for enable the reply in the channel, it will map users who replied in the channel and it will dump the full conversation chain
139
+
Flag for enabling channel reply retrieval, this will archive replies and list users who replied to messages in the target channel.
125
140
126
141
```
127
142
$ telepathy -t [CHANNEL] -c -r
128
143
```
129
144
130
145
146
+
- **'--translate', '-tr'**
147
+
148
+
Flag for enabling auotmatic translation (currently only into English) during message retrieval.
149
+
150
+
```
151
+
$ telepathy -t [CHANNEL] -c -tr
152
+
```
153
+
154
+
131
155
## Bonus investigations tips:
132
156
133
157
- Navigating to a media archive directory and running Exiftool may give you a whole host of useful information for further investigation. Telegram doesn't currently scrub metadata from PDF, DOCX, XLSX, MP4, MOV and some other filetypes, which offer creation and edit time metadata, often timezones, sometimes authors, and general technical information about the perosn or people who created a media file.
skipped 1 lines
135
159
$ cd ./telepathy/telepathy_files/CHATNAME/media
136
160
$ exiftool * > metadata.txt
137
161
```
138
-
- Group and inferred channel memberlists offer a point of further investigation for usernames found. By using Maigret, you can look up where else a username has been used. While this is not accurate in all cases, it's been proven to be useful for handlesthatareoften reused. In this case, remember to verify your findings to avoid false positives.
162
+
- Group and inferred channel memberlists offer a point of further investigation for usernames found. By using [Maigret](https://github.com/soxoj/maigret), you can look up where else a username has been usedonline. While this is not accurate in all cases, it's been proven to be helpful for identifyingwhereapersonhas reusedhandlesacrossplatforms. In this case, remember to verify your findings to avoid false positives.
139
163
140
164
141
165
## A note on how Telegram works
142
166
143
-
Telegram chats are organised into three key types: Channels, Megagroups/Supergroups and Gigagroups. Each module works slightly differently depending on the chat type. Channels can have seemingly unlimited subscribers and are where an admin will broadcast messages to an audience, Megagroups can have up to 200,000 members, each of whom can participate (if not restricted), and Gigagroups sit somewhere between the two.
167
+
Telegram chats are organised into three key types: Channels, Megagroups/Supergroups and Gigagroups. Each option works slightly differently depending on the chat type. Channels can have seemingly unlimited subscribers and are where an admin will broadcast messages to an audience, Megagroups can have up to 200,000 members, each of whom can participate (if not restricted), and Gigagroups sit somewhere between the two.
144
168
145
169
146
170
## Upcoming changes
skipped 2 lines
149
173
Upcoming features include:
150
174
151
175
- [ ] Adding a time specification flag to set archiving for specific period.
152
-
- [] The ability to gather the number of reactions to messages, including statistics on engagement rate.
176
+
- [x] The ability to gather the number of reactions to messages, including statistics on engagement rate.
153
177
- [ ] Finding a method to once again gather complete memberlists (currently restricted by the API).
154
178
- [ ] Improved statistics: including timestamp analysis for channels.
155
179
- [ ] Generating an entirely automated complete report, including visualisation for some statistics.
156
180
- [ ] Hate speech analytics.
157
-
- [x] Maximise compatibility of edgelists with Gephi.
158
181
- [ ] Include sockpuppet account provisioning (creation of accounts from previous exported lists).
159
182
- [ ] Listing who has group admin rights in memberlists.
160
-
- [ ] Media downloaded in the background to increase efficiency.
161
-
- [] When media archiving is flagged, the location of downloaded content will be added to the archive file.
162
-
- [ ] Exploring, and potentially integrating, media crosschecks based on https://github.com/conflict-investigations/media-search-engine.
183
+
- [ ] Media downloaded in the background to increase efficiencyorprogressbarsformediadownloadstogiveabetterestimationofruntime.
184
+
- [x] When media archiving is flagged, the location of downloaded content will be added to the archive file.
185
+
- [ ] Exploring, and potentially integrating, media cross-checks based on https://github.com/conflict-investigations/media-search-engine.
Telepathy: An OSINT toolkit for investigating Telegram chats. Developed by Jordan Wildon. Version 2.3.2.
12
13
14
+
Telepathy has been described as the "swiss army knife of Telegram tools," allowing OSINT analysts, researchers and digital investigators to archive Telegram chats (including replies, media content, comments and reactions), gather memberlists, lookup users by given location, analyze top posters in a chat, map forwarded messages, and more.
15
+
16
+
The toolkit has already seen a wide variety of use cases, including but not limited to: in investigative and data journalism, by academic and research institutions, and for intelligence gathering and analysis.
13
17
14
-
Telepathy: An OSINT toolkit for investigating Telegram chats. Developed by Jordan Wildon. Version 2.2.58.
18
+
19
+
## !! IMPORTANT:
20
+
With the update to 2.3.0, you will need to delete your login.txt file to prevent errors if using the alternative login feature. Upon first use, Telepathy will guide you through setup of the details once again. To work around this, instead of deleting and recreating the file, you can add a newline character to the end of your current API details to ensure Telepathy scans the file correctly.
21
+
22
+
A note on unique identifiers per account: You will notice that depending on which alternative account you use, the access hash will vary. The same will happen with User IDs, which are unique to each Telegram account accessing them. For deeper data analysis based on user IDs, this is important to bare in mind as users will have as many unique IDs as accounts you've used to access information. In future, Telepathy may include a feature to assign unique identifier per account found based on a hash of the available information, regardless of which account accessed the data.
23
+
15
24
16
25
17
26
## Installation
skipped 28 lines
46
55
Options:
47
56
- **'--target', '-t' [CHAT]**
48
57
49
-
this option will identify the target of the scan. The specified chat must be public. To get the chat name, look for the 't.me/chatname' link, and subtract the 't.me/'.
58
+
this option will identify the target of the scan. The specified chat must be publicorhaveaprivatelink. To get the chat name, look for the 't.me/chatname' link, and subtract the 't.me/'.
50
59
51
60
For example:
52
61
skipped 6 lines
59
68
60
69
- **'--comprehensive', '-c'**
61
70
62
-
A comprehensive scan will offer the same information as the basic scan, but will also archive a chat's message history.
71
+
A comprehensive scan will offer the same information as the basic scan, but will also archive a chat's message history,gatherthenumberofreactions,archivehowmanytimesamessagehasbeenforwarded,thenumberofrepliestoeachmessage,andmore.
72
+
73
+
Reaction lists are included in the archive file, including basic calculations of engagement rate. Only the most-common reactions are listed, with the total including all possible reactions. Currently, Telepathy calculates engagement rates based on forwards, comments and reactions seperately, with a calculation based on post views and one based on chat participant count. In future, Telepathy may include deeper analytics which can be cross-compared between chats based on a combination of these metrics, fixing for when comments, reactions or forwards are allowed or disallowed in a given chat.
63
74
64
75
For example:
65
76
skipped 4 lines
70
81
71
82
- **'--forwards', '-f'**
72
83
73
-
This flag will create an edgelist based on messages forwarded into a chat. It can be used alongside either a default or comprehensive scan.
84
+
This flag will create an edgelist based on messages forwarded into a chat. It can be used alongside either a default or comprehensive scan.Since2.3.0,TelepathynowformatstheseedgeliststomaximizecompatabilitywithGephi.
74
85
75
86
For example:
76
87
77
88
```
78
89
$ telepathy -t durov -f
90
+
91
+
$ telepathy -t durov -c -f
79
92
```
80
93
81
94
skipped 1 lines
83
96
84
97
Use this flag to include media archiving alongside a comprehensive scan. This makes the process take significantly longer and should also be used with caution: you'll download all media content from the target chat, and it's up to you to not store illegal files on your system.
85
98
86
-
Since 2.2.0, downloading all media files will also generate a CSV file listing the files' metadata.
87
-
88
-
For example, this will run a comprehensive scan, including media archiving:
99
+
To archive media, you must run a comprehensive scan:
89
100
90
101
```
91
102
$ telepathy -t durov -c -m
92
103
```
93
104
105
+
Once files have downloaded, you can run exiftool on the associated media directory to gather deeper insights on the files, their metadata, and in some cases attribute who might be behind an anonymous channel. Further details are in the "bonus investigations tips" section of this README.
94
106
95
-
- **'--user', '-u' [USER]**
107
+
108
+
- **'--user', '-u'**
96
109
97
-
Looks up a specified userID. This will only work if your account has "encountered" the user before (for example, after archiving a group).
110
+
Looks up a specified user. This will only work if your account has "encountered" the user before (for example, after archiving a group),youcanspecifyUserIDor@nickname.Iflookingupbyusername,it'snotalwaysnecessaryforyouraccounttohavealreadyseentheuser.
98
111
99
112
```
100
113
$ telepathy -t 0123456789 -u
114
+
115
+
$ telepathy -t @test_user -u
101
116
```
102
117
103
118
104
-
- **'--location', '-l'[COORDINATES]**
119
+
- **'--location', '-l']**
105
120
106
-
Finds users near to specified coordinates. Input should be longitude followed by latitude, seperated by a comma. This feature only works if your Telegram account has a profile image which is set to publicly viewable.
121
+
Finds users near to specified coordinates. Input should be longitude followed by latitude, seperated by a comma. This feature only works if your Telegram account has a profile image which is set to bepublicly viewable.
122
+
123
+
While searches for multiple locations at once may work in some cases, Telegram appears to have a limit on how quickly an account can cycle through locations. At the time of writing, this appears to be at least ten minutes. Further location scanning support while using multiple accounts is being explored for a future release.
107
124
108
125
```
109
126
$ telepathy -t 51.5032973,-0.1217424 -l
110
127
```
111
128
112
129
113
-
- **'--alt', '-a'**
130
+
- **'--alt', '-a'[NUMBER]**
114
131
115
-
Flag for running Telepathy from an alternative number. You can use the same API key and Hash but authenticate with a different phone number. Allows for running multiple scans at the same time.
132
+
Flag for running Telepathy from an alternative numberorAPIdetails. You can use the same API key and Hash but authenticate with a different phone number. Thisallows for running multiple scans at the same time.Telepathywilldefaulttothefirstdetailsyouoffer,anduptofourotherscanbeadded.PleaseseethenotesatthetopofthisREADMEforinformationregardinglimitationswithuserIDsusingthismethod.
116
133
117
134
```
118
-
$ telepathy -t Durov -c -a
135
+
$ telepathy -t Durov -c -a1
119
136
```
120
137
121
138
122
139
- **'--export', '-e'**
123
140
124
-
Exports all chats your account is part of to a CSV file. In a future release, this may assist with settingupmultiple accounts following the same groups.
141
+
Exports all chats your account is part of to a CSV file. In a future release, this may assist with provisioningnew accounts toautomaticallyfollowing the listed groups.
125
142
126
143
```
127
144
$ telepathy -e
skipped 2 lines
130
147
131
148
- **'--reply', '-r'**
132
149
133
-
Flag for enable the reply in the channel, it will map users who replied in the channel and it will dump the full conversation chain
150
+
Flag for enabling channel reply retrieval, this will archive replies and list users who replied to messages in the target channel.
134
151
135
152
```
136
153
$ telepathy -t [CHANNEL] -c -r
137
154
```
138
155
139
156
157
+
- **'--translate', '-tr'**
158
+
159
+
Flag for enabling auotmatic translation (currently only into English) during message retrieval.
160
+
161
+
```
162
+
$ telepathy -t [CHANNEL] -c -tr
163
+
```
164
+
165
+
140
166
## Bonus investigations tips:
141
167
142
168
- Navigating to a media archive directory and running Exiftool may give you a whole host of useful information for further investigation. Telegram doesn't currently scrub metadata from PDF, DOCX, XLSX, MP4, MOV and some other filetypes, which offer creation and edit time metadata, often timezones, sometimes authors, and general technical information about the perosn or people who created a media file.
skipped 1 lines
144
170
$ cd ./telepathy/telepathy_files/CHATNAME/media
145
171
$ exiftool * > metadata.txt
146
172
```
147
-
- Group and inferred channel memberlists offer a point of further investigation for usernames found. By using Maigret, you can look up where else a username has been used. While this is not accurate in all cases, it's been proven to be useful for handlesthatareoften reused. In this case, remember to verify your findings to avoid false positives.
173
+
- Group and inferred channel memberlists offer a point of further investigation for usernames found. By using [Maigret](https://github.com/soxoj/maigret), you can look up where else a username has been usedonline. While this is not accurate in all cases, it's been proven to be helpful for identifyingwhereapersonhas reusedhandlesacrossplatforms. In this case, remember to verify your findings to avoid false positives.
148
174
149
175
150
176
## A note on how Telegram works
151
177
152
-
Telegram chats are organised into three key types: Channels, Megagroups/Supergroups and Gigagroups. Each module works slightly differently depending on the chat type. Channels can have seemingly unlimited subscribers and are where an admin will broadcast messages to an audience, Megagroups can have up to 200,000 members, each of whom can participate (if not restricted), and Gigagroups sit somewhere between the two.
178
+
Telegram chats are organised into three key types: Channels, Megagroups/Supergroups and Gigagroups. Each option works slightly differently depending on the chat type. Channels can have seemingly unlimited subscribers and are where an admin will broadcast messages to an audience, Megagroups can have up to 200,000 members, each of whom can participate (if not restricted), and Gigagroups sit somewhere between the two.
153
179
154
180
155
181
## Upcoming changes
skipped 2 lines
158
184
Upcoming features include:
159
185
160
186
- [ ] Adding a time specification flag to set archiving for specific period.
161
-
- [] The ability to gather the number of reactions to messages, including statistics on engagement rate.
187
+
- [x] The ability to gather the number of reactions to messages, including statistics on engagement rate.
162
188
- [ ] Finding a method to once again gather complete memberlists (currently restricted by the API).
163
189
- [ ] Improved statistics: including timestamp analysis for channels.
164
190
- [ ] Generating an entirely automated complete report, including visualisation for some statistics.
165
191
- [ ] Hate speech analytics.
166
-
- [x] Maximise compatibility of edgelists with Gephi.
167
192
- [ ] Include sockpuppet account provisioning (creation of accounts from previous exported lists).
168
193
- [ ] Listing who has group admin rights in memberlists.
169
-
- [ ] Media downloaded in the background to increase efficiency.
170
-
- [] When media archiving is flagged, the location of downloaded content will be added to the archive file.
171
-
- [ ] Exploring, and potentially integrating, media crosschecks based on https://github.com/conflict-investigations/media-search-engine.
194
+
- [ ] Media downloaded in the background to increase efficiencyorprogressbarsformediadownloadstogiveabetterestimationofruntime.
195
+
- [x] When media archiving is flagged, the location of downloaded content will be added to the archive file.
196
+
- [ ] Exploring, and potentially integrating, media cross-checks based on https://github.com/conflict-investigations/media-search-engine.
Jordan Wildon
committed
with
GitHub
2 years ago
1 parent 7b92c963