TgWitness / Documentación

Lo que se ha probado →

Referencia / Configuración

Telegram · Inicio rápido

Todas las formas de instalar y poner en marcha TgWitness: paquete para Windows, Python, Docker y la demostración sintética, con las primeras comprobaciones.

TgWitness / Documentación

Primeros pasos

Inglés · Русский · Ucraniano · Español · Portugués (Brasil) · Türkçe · العربية · فارسی · Urdu · Hindi · Bahasa Indonesia · Tiếng Việt · Chino simplificado

TgWitness es una aplicación independiente para supervisar los grupos y canales de Telegram a los que tienen acceso sus cuentas. Se ejecuta localmente con su propio directorio de datos.

¿Es tu primera visita? Explora la demo antes de vincular una cuenta. Elige una guía sobre proxies, testigos, exportaciones o configuración del servidor. GitHub Actions capture (vista previa) ejecuta una captura en tu propia bifurcación de GitHub en lugar de en una instalación local.

Instalación y puesta en marcha#

El instalador guiado incluye su propio Python y comprueba los hash de los paquetes y las firmas de la versión antes de la instalación. Al ejecutarlo de nuevo, se actualiza una instalación existente.

Linux / macOS:

curl -fsSL https://get.destroy.tools/install.sh | bash

Windows (PowerShell o Símbolo del sistema):

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"

En un servidor Ubuntu, ejecútalo como root para instalar un servicio en segundo plano; en un ordenador de sobremesa, ejecútalo como usuario normal. En Ubuntu, el instalador muestra la dirección del panel y la clave de acceso; en macOS y Windows, el panel local se abre en tu navegador. Continúa en Conectar Telegram más abajo. Instalar, verificar y actualizar abarca las opciones de acceso al servidor, la comprobación del script antes de ejecutarlo, las actualizaciones y la desinstalación.

Otros métodos#

Las versiones de GitHub, el código fuente y Docker son alternativas al instalador. Las descargas portátiles están disponibles una vez publicada la versión:

Alojamiento No es necesario instalar nada Fuente: Python 3.11+ Docker: Engine/Desktop con Compose 2.20 o superior
Windows Extraiga «TgWitness-<version>-windows-amd64-portable.zip» de las versiones de GitHub y haga doble clic en «TgWitness.cmd» Haga doble clic en Start.cmd Haga doble clic en scripts\Docker.cmd
Linux / macOS — sh start.sh sh scripts/docker-start.sh

Para los métodos desde el código fuente, descargue y extraiga la rama main actual o clone el repositorio:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

Start.cmd ofrece instalar Python 3.12 para su usuario de Windows si no se encuentra un Python adecuado (mediante winget o el instalador firmado de python.org). start.sh muestra el comando de instalación exacto para su distribución de Linux o macOS si falta Python. El primer inicio desde el código fuente crea .venv e instala las dependencias automáticamente.

Docker compila la aplicación y la inicia en segundo plano; no es necesario un servidor Python. scripts\Docker.cmd y scripts/docker-start.sh muestran la dirección del panel y el token cuando el contenedor funciona correctamente. Los comandos de Docker equivalentes en todos los hosts compatibles son:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

Abra http://127.0.0.1:8787. Utilice el token generado por el asistente de Docker o el segundo comando de Docker, o consulte el archivo data/live/panel-token.txt si se trata de una instalación portátil o desde el código fuente. Continúe en «Conectar Telegram» más abajo. Las instalaciones nativas y de Docker utilizan un almacenamiento independiente; al iniciar Docker no se importa ningún registro nativo existente.

En el caso de un servidor, la implementación incluye HTTPS automático, reinicio, imágenes publicadas, actualizaciones y copias de seguridad.

Explore la interfaz#

  1. Ejecute «TgWitness-Demo.cmd» en el paquete portátil, «scripts\Demo.cmd» en una carpeta de origen de Windows o «sh start.sh --demo » en Linux/macOS. Al ejecutarlo desde la fuente, primero se crea «.venv » y se instalan las dependencias.
  2. Open http://127.0.0.1:8787.
  3. La demostración local abre automáticamente el registro de muestra. No se necesita ningún código de acceso para el acceso local directo.

Los mensajes de demostración son ficticios. El modo de demostración no permite conectarse a una cuenta real de Telegram.

Conectarse a Telegram#

[!ADVERTENCIA] Utiliza cuentas específicas. Telegram puede restringir o bloquear permanentemente cuentas por volúmenes de solicitudes que considere excesivos, independientemente del cliente. Conecta cuentas preparadas para la observación en lugar de cuentas personales o valiosas, y crea un ID de API / hash en una cuenta específica.

  1. Si la demostración nativa está en ejecución, deténgala y ejecute «Start.cmd» o «sh start.sh». De lo contrario, mantenga en ejecución la instalación en vivo iniciada anteriormente.
  2. Utiliza el token del panel para iniciar sesión. Se abrirá un nuevo espacio de trabajo para la configuración inicial. Elige Solo descargar, Seguir chats o Pruebas para un caso.
  3. Revisa la comprobación de conexión. Configura tu propio proxy si es necesario; los ajustes de conexión siguen estando disponibles tras la configuración.
  4. En Connect Telegram, elija un número de teléfono, un código QR, archivos de cuenta (TData, .session, StringSession, JSON de la cuenta) o una clave de autorización completa. Complete la confirmación de Telegram, el código y la contraseña de dos pasos cuando se le solicite.
  5. Comprueba la cuenta mostrada, selecciona los chats y revisa tu configuración. Finaliza desde la pantalla final. En el caso de Solo descargar, Iniciar exportación inicia una exportación única y abre Exportaciones para mostrar su progreso; no habilita la observación continua.

Tras la configuración, Chats → Elegir cambia los chats seleccionados. Configuración controla la recopilación y los archivos; Más herramientas → Fuentes proporciona la lista detallada de fuentes en nivel Estándar o Experto. La guía del panel describe las seis secciones principales y sus controles contextuales.

El ID de API + Hash es opcional: el espacio de trabajo utiliza su par guardado o importado, o un par válido del conjunto integrado. Para utilizar tu propia aplicación, pega un par API ID:API Hash en el campo API ID. Para la clave de autenticación, pega los 512 caracteres hexadecimales y selecciona el DC ID proporcionado. El ID de usuario es opcional y se comprueba si se introduce.

Las credenciales de la API identifican su aplicación; por sí solas, no autorizan una cuenta. Los grupos privados no necesitan un nombre de usuario público, pero su cuenta debe tener acceso.

Para las cuentas existentes, consulta los formatos de cuentas y sesiones: el panel admite Telethon StringSession, Telethon/Pyrogram SQLite, TData ZIP de una sola cuenta y JSON de cuentas compatibles. Selecciona una sesión y su archivo JSON correspondiente a la vez, pulsa Comprobar archivos y, a continuación, Conectar cuenta. El inicio de sesión mediante código QR también está disponible con la misma configuración opcional de la API. No se admiten TDLib, sesiones de bots ni inventarios de cuentas en formato CSV/JSON .

Para varias cuentas, use Cuentas → Importar cuentas y seleccione sus archivos de sesión compatibles. Los archivos JSON complementarios se emparejan por su nombre base; cada cuenta importada obtiene su propio espacio de trabajo. Consulte importación masiva y grupos de cuentas.

Para añadir otra cuenta, pulsa el signo + junto al selector de cuentas o utiliza Cuentas → Añadir cuenta. Los espacios de trabajo tienen sesiones, diarios, claves, fuentes y colas independientes. Al cambiar de vista, los demás colectores siguen en funcionamiento. En esta instalación, no se puede asignar la misma cuenta de Telegram a dos espacios de trabajo. No hay un número fijo de espacios de trabajo; comparten un mismo proceso, por lo que la capacidad depende del equipo.

El token del panel en tiempo real protege el acceso a sus autorizaciones de Telegram y al material guardado; es independiente de las credenciales de la API de Telegram. Solo una demostración local iniciada explícitamente y a la que se acceda directamente obtiene acceso automático. Una demostración remota o a través de un proxy sigue utilizando data/demo/panel-token.txt.

Revisión y exportación#

  • Registro: busque y filtre las observaciones por fuente y tipo de evento.
  • Seleccione un evento para examinar su registro original, su atribución y las versiones guardadas.
  • Los detalles de la edición muestran el contenido disponible antes y después. Los detalles de la eliminación muestran el último contenido capturado, si lo hubiera; un actor desconocido sigue sin identificarse.
  • Formatos de exportación: ZIP firmado, JSONL, CSV y HTML sin conexión.
  • Exportación completa del chat (Chats → Exportar chat, o Exportaciones → Capturar o exportar un chat): descarga todo el historial visible de un chat como un paquete firmado con chat.json (estilo de exportación de Telegram) y un archivo legible chat.html. Los chats privados funcionan cuando la cuenta es miembro. Se trata de una instantánea actual, no de una reconstrucción de mensajes eliminados o editados previamente. Verifica una copia con python verify.py chat-export.zip --fingerprint TRUSTED_SHA256.
  • Punto de control: mantenga los límites del registro firmado fuera del recopilador.
  • Descargar el recibo de ejecución firmado: conserve el registro del programa y la versión del recopilador.
  • Preparar una solicitud de marca de tiempo: prepare una solicitud fuera de línea dirigida a una autoridad de marcas de tiempo; siga las instrucciones de TIMESTAMP.md para obtener y verificar una respuesta.
  • Verificar el registro: compruebe las firmas de los eventos y los eslabones de la cadena. La exportación en formato ZIP también comprueba los archivos multimedia.

Los navegadores compatibles guardan exportaciones de gran tamaño directamente en el archivo elegido. Otros navegadores almacenan en el búfer un máximo de 128 MiB. Mientras el servidor está en funcionamiento, la CLI de transmisión admite descargas de mayor tamaño sin necesidad de almacenar en el búfer la respuesta completa:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

Para otro espacio de trabajo, añade --profile ID utilizando Exportaciones → ID del espacio de trabajo. Para un servidor remoto, añade --url https://your-server. El límite de transferencia predeterminado es de 5 GiB; --max-mib lo modifica. El contenido ZIP firmado tiene un límite de verificación independiente de 4 GiB sin comprimir por defecto (Más herramientas → Parámetros lo aumenta; verifica dichos archivos con verify.py --max-gib N). Verifica el archivo utilizando una copia fiable del verificador, una huella digital de la clave conservada de forma independiente y, como mínimo para servir de prueba, el certificado raíz de la autoridad de marcas de tiempo (--tsa-ca).

Consulte la instalación#

python start.py --setup-only
python start.py --check
python start.py --check --json

--check comprueba las dependencias locales, la compatibilidad con la firma, el almacenamiento, la configuración de claves y la dirección de escucha. No instala nada ni se conecta a Telegram. Si un puerto está ocupado, puede significar que hay otra instancia en ejecución. Utilice un --port diferente o deténgala primero.

El lanzador se instala en .venv. Los comandos auxiliares de python -m tgwitness... deben utilizar .venv\Scripts\python.exe en Windows o .venv/bin/python en Linux/macOS, a menos que dicho entorno ya esté activado.

Sesiones, protección y funcionamiento#

Un .session de Telethon SQLite cerrado y coherente se puede convertir localmente con python -m tgwitness.sessions account.session --out account.tgwitness-session y, a continuación, cargarlo en Más herramientas → Cuenta → Archivos. También están disponibles la importación directa de archivos y el inicio de sesión mediante código QR. Consulta CONNECTION-SECURITY.md para conocer los formatos de inicio de sesión, SOCKS5, HTTP CONNECT, MTProxy y las claves maestras externas.

La función «Pausar observación» detiene la recopilación. La opción «Bloquear» solo cierra el acceso al navegador. Al cerrar una pestaña, el proceso de recopilación sigue en ejecución. Detener el proceso interrumpe la recopilación; una instantánea del historial no puede reconstruir todas las modificaciones o eliminaciones que se hayan perdido. Consulte cómo funciona la recopilación en relación con las políticas de eventos, las colas de archivos adjuntos, el aislamiento de cuentas y el comportamiento al reiniciar.

Las sesiones y los secretos están cifrados. El contenido de los mensajes, los archivos multimedia y las exportaciones requieren un disco o volumen cifrado. Verifica las firmas del diario con una clave de confianza y conserva los puntos de control por separado. Revisa los registros de captura, los recibos de tiempo externos y las certificaciones del entorno para el modo de recopilación seleccionado.

Consulte el archivo OPERATIONS.md para obtener información sobre copias de seguridad y restauración, DEPLOYMENT.md para el alojamiento, y deploy/ para ver ejemplos de uso del servicio. El panel instalado también incluye una guía de configuración sin conexión en /guide.html.

La verificación real y las limitaciones existentes se recogen en los archivos VERIFICATION.md y READINESS.md.