TgWitness / Dokumentasi

Apa yang telah diuji →

Referensi / Keamanan & proyek

Arsitektur

Komponen-komponen kolektor, panel, jurnal, pekerja, dan saksi, serta bagaimana data berpindah di antara komponen-komponen tersebut.

TgWitness / Dokumentasi

Pengembangan

Satu proses Python menjalankan panel FastAPI dan sejumlah ruang kerja yang terisolasi, masing-masing dilengkapi dengan klien akun pengguna Telethon. SQLite menyimpan jurnal peristiwa yang ditandatangani dan hanya dapat ditambahkan, serta pengaturan operasional yang dapat diubah. Sebuah brankas terenkripsi menyimpan kredensial API, StringSession, dan kunci penandatanganan. Frontend berupa paket HTML/CSS/JavaScript biasa: tidak diperlukan proses kompilasi Node, CDN, atau pengunduhan frontend saat runtime.

Perekam browser opsional dan AyuGram berjalan dalam proses atau kontainer terpisah. Paket tgwitness_capture paket ini memiliki format peristiwa, kunci, artefak, API checkpoint, saksi independen, dan verifikator mandiri sendiri. Paket ini disertakan dalam wheel utama dan juga dapat diinstal secara terpisah addons/capture, tanpa perlu mengimpor pengumpul. Panel utama capture_api.py dan capture_connections.py menyediakan kontrol khusus administrator, yang berlaku di ruang kerja, di bawah /api/capture; token koneksi disimpan di brankas terenkripsi. Tidak ada perekam atau permintaan keluar yang dimulai dari proses utama. Setiap perintah eksplisit memverifikasi tantangan baru terhadap kunci perekam yang disematkan. Ekspor diverifikasi sebelum diunduh dan mempertahankan tanda tangan aslinya; ekspor tersebut tidak menjadi peristiwa pesan Telegram. Sesi pengumpulan dan rute proxy tetap berada di masing-masing klien. Lihat panduan perekaman mandiri dalam bahasa Inggris untuk informasi mengenai penerapan dan batas kepercayaan.

Modul Tanggung Jawab
collector.py Otorisasi, pemilihan dialog, pembaruan, tangkapan layar, antrian media, pemantauan koneksi
interactions.py / telegram_client.py Tindakan panel yang eksplisit, tanda terima yang ditandatangani, ID permintaan yang tetap, serta kebijakan percobaan ulang panggilan balik/bergabung yang disesuaikan dengan tugas
message_content.py Perbandingan pesan yang dapat diamati, tidak termasuk metadata akses transportasi
workers.py Tunggu hingga proses ekspor file selesai sebelum melakukan pembersihan setelah pembatalan
distributed_export.py / distributed_pages.py Tugas obrolan bersamaan, reservasi per akun, titik pemeriksaan yang ditandatangani, dan pembersihan setelah verifikasi arsip
distributed_takeout.py / export_timing.py Sesi Takeout yang dapat dilanjutkan dan waktu untuk setiap awal atau kelanjutan
store.py Transaksi WAL, rantai peristiwa terurut, filter kueri, pengaturan operasional
fulltext.py Indeks teks lengkap yang dihasilkan (bentuk kata, BM25), terikat pada bagian awal jurnal yang ditandatangani; tidak pernah diekspor
security.py Pembuatan berkas pribadi, brankas terenkripsi, penandatanganan Ed25519, penguncian proses tunggal
evidence.py Ekspor jurnal lengkap, turunan, titik pemeriksaan, verifikasi lampiran
verify.py Verifikator mandiri dan hanya baca (perpustakaan standar + kriptografi): arsip, cakupan, jurnal saksi, dan posting saluran, serta berkas profil
app.py API terotentikasi, siklus hidup, validasi permintaan, panel statis
profiles.py Pengumpul akun ganda, pengontrol akses bersama, siklus hidup per ruang kerja
access.py Hibah yang dibatasi cakupannya, pemeriksaan izin, pembatasan IP, batas sesi, dan konsol administrator
proxy_catalog.py Cuplikan umpan publik, pemeriksaan transportasi, kumpulan proxy bersama, dan pemilihan berdasarkan kondisi kesehatan
provenance.py Pengukuran identitas, kode, dan ketergantungan yang ditandatangani selama proses akuisisi
network.py Rute yang telah divalidasi per ruang kerja; status dan bukti yang disunting; opsi pengiriman Telethon
sessions.py Konversi skema SQLite Telethon yang telah ditinjau menjadi format offline yang hanya dapat dibaca
account_import.py Deteksi dan normalisasi dalam memori terhadap berkas akun yang didukung dan JSON
tdata.py Pembaca ZIP TData modern yang terbatas, validasi checksum/dekripsi, tanpa ekstraksi
doctor.py Pemeriksaan kesiapan lokal tanpa pengumpulan data, login, atau instalasi paket
download.py Unduhan ekspor streaming terotentikasi dengan pembatasan pembacaan dan tanpa penimpaan
monitoring.py Kebijakan peristiwa yang divalidasi per ruang kerja dan aturan lampiran per jenis, dibagikan oleh pengelola, status, dan tanda terima yang ditandatangani
scope.py Cakupan pemantauan (obrolan yang dipilih, folder Telegram, seluruh akun), jenis sumber, pengecualian, tingkatan pemeriksaan ulang
dossier.py Profil pengguna per obrolan yang dibuat berdasarkan catatan yang disimpan: fakta dengan referensi catatan, SHA-256/pHash avatar, serta ekstraksi sebutan
witness_api.py Token saksi yang hanya dapat dibaca dan bagian awal jurnal yang telah ditandatangani yang dapat mereka ambil
witness.py Proses saksi independen: kunci dan jurnal milik sendiri, pemeriksaan kepala, posting saluran yang ditandatangani, ekspor
alerts.py Pemberitahuan Apprise dan daftar pemberitahuan panel
logging_config.py Pencatatan konsol dan diagnostik server bergilir untuk peluncuran tanpa jendela
static/ Antarmuka responsif, gerbang akses lokal, filter, detail, ekspor, pengaturan akun
demo.py Jurnal sintetis yang diberi label dengan jelas, terpisah dari data asli yang dikumpulkan

Penanganan pengamatan didaftarkan sebelum terhubung. Pengumpulan data secara langsung dibatasi oleh identitas klien yang aktif, status berjalan yang eksplisit, sumber yang diaktifkan, atau cakupan pengamatan (mode folder atau seluruh akun menambahkan obrolan baru sebagai sumber pada pembaruan pertamanya), serta kebijakan peristiwa. Klien yang ditolak dan digantikan tidak dapat berkontribusi pada pembaruan langsung. Reaksi mentah dan pembaruan keanggotaan mempertahankan batasan visibilitas. Isi pesan masuk dan tugas media tahan lama-nya disimpan bersama-sama. Tugas-tugas tersebut mempertahankan deskriptor TL asli dan mengikat hash-nya ke pengamatan pesan yang ditandatangani. Semantik pengirim/editor/penghapus dipisahkan.

Setiap ruang kerja hanya menerima satu akun dan memiliki direktori serta identitas penandatanganan tersendiri. Ruang kerja utama tetap berada di direktori akar demi kompatibilitas; ruang kerja tambahan berada di profiles/<id>/. Satu token bearer mengendalikan seluruh instalasi; ruang kerja bukanlah entitas otorisasi yang terpisah. Kunci proses melindungi direktori; kunci basis data menserialisasikan penyisipan peristiwa. Setiap penambahan disimpan secara sinkron ke WAL SQLite dengan mode sinkron PENUH. Pemicu pembaruan/penghapusan peristiwa mencegah pengeditan aplikasi biasa; administrator sistem berkas tetap berada di dalam batas kepercayaan.

Otorisasi API menggunakan token bearer. Operasi login diserialisasikan dan dibatasi waktu. Unggahan akun menggunakan batas tubuh terenkripsi 12 MiB dan batas file terdekodasi 8 MiB; permintaan API biasa tetap menggunakan batas 16 KiB. Konversi berjalan di benang pekerja, menyimpan unggahan di memori, dan mengembalikan input yang dinormalisasi ke browser yang terotentikasi. Masuk melalui QR memiliki kandidat per ruang kerja, pengenal berumur pendek, tugas penunggu, dan pembatalan eksplisit. Hanya otorisasi yang diterima yang menjadi klien aktif. Telegram FloodWait dikembalikan dengan nilai Retry-After; kredensial dan pesan kesalahan RPC mentah tidak ditampilkan dalam kesalahan API. Ekspor jurnal berjalan di luar loop peristiwa asinkron dan diserialisasikan per ruang kerja. Ekspor ini mengalirkan snapshot baca yang stabil bersamaan dengan penulisan WAL yang terus berlanjut. Tugas akuisisi obrolan dapat berjalan secara bersamaan di akun yang terpisah; setiap akun tetap dicadangkan hingga tugasnya berhenti. Tugas yang dijeda atau gagal tetap mempertahankan titik periksa (checkpoint)-nya. Verifikasi arsip yang berhasil memungkinkan pembersihan file kerjanya, dengan menyisakan ZIP, rencana yang ditandatangani, dan status. Pengumpul ruang kerja berbagi proses/loop peristiwa.

Cuplikan riwayat terkini dan pembaruan langsung dapat tumpang tindih. Keduanya merupakan pengamatan terpisah, yang diberi label berdasarkan sumber; duplikat tidak disembunyikan secara otomatis. Tidak ada inferensi yang dilakukan berdasarkan ID yang hilang, teks terhapus yang dipalsukan, penghitungan anggota yang dipaksakan, atau bergabungnya ke grup secara otomatis yang diterapkan.

Untuk penjelasan yang ditujukan kepada operator, lihat cara kerja pengumpulan data serta format akun dan sesi.

Konfigurasi jaringan disimpan di dalam brankas terenkripsi. Menerapkan rute akan menutup klien lama dan membatalkan proses login yang belum selesai; koneksi selanjutnya menggunakan rute tersebut tanpa fallback langsung. Instalasi kunci eksternal baru menghasilkan kunci Fernet setiap ruang kerja dengan HKDF-SHA256 dari berkas kunci utama dan garam acak yang tersimpan. Hal ini melindungi rahasia secara terpisah dari direktori data, bukan isi jurnal/media dalam teks biasa.

Entri demo lokal menggunakan kemampuan proses yang dihasilkan secara terpisah, bukan token panel yang dikonfigurasi. Penerbitan dan penerimaan memerlukan mode demo eksplisit, root sintetis tanpa ruang kerja tambahan atau sesi yang diotorisasi, peer/Host loopback, tanpa header penerusan proxy, dan tanpa permintaan browser lintas asal. API langsung mempertahankan otentikasi pembawa dan menolak perubahan pengumpulan data dalam mode demo.