연결, 프록시 및 데이터 보호

이 문서는 TgWitness 0.7.0의 동작 방식과 그 한계를 설명합니다. 인증, 소스 액세스, 네트워크 연결 및 캡처 완전성은 각각 별개의 상태입니다. 로그인 절차, 파일 형식 및 다중 계정에 대해서는 ‘계정 및 세션 형식’ 섹션부터 확인하십시오. 이벤트 정책 및 재시작 동작에 대해서는 ‘수집 방식’ 섹션을 참조하십시오.

인증 방법#

API ID와 API 해시는 애플리케이션을 식별하는 용도로 사용되며, 계정 로그인을 대체하지 않습니다. TgWitness에서는 이 정보들이 선택 사항입니다. 우선순위는 다음과 같습니다: 양식에 입력된 쌍, 가져온 계정 JSON의 쌍, 작업 공간에 저장된 쌍, 내장된 50개의 공개 쌍 풀에서 무작위 순서로 시도되며, 텔레그램에서 거부될 경우 자동으로 순환됩니다. 오직 텔레그램 데스크톱 쌍(2040)만이 일치하는 텔레그램 데스크톱 클라이언트 설명과 함께 전송됩니다. my.telegram. org의 API 개발 도구에서 생성한 본인 소유의 쌍은 모든 계정에 사용할 수 있으며, 각 계정은 여전히 고유한 인증 정보를 유지합니다.

텔레그램은 코드 전송 방식을 선택하며, SMS 전송은 보장되지 않습니다. API 해시는 취소된 세션을 복구하거나 잊어버린 2단계 인증(2FA) 비밀번호를 대체할 수 없습니다. TgWitness는 로그인 코드나 텔레그램 2단계 인증(2FA) 비밀번호를 디스크에 저장하지 않습니다.

비공개 소스의 경우, 해당 계정은 이미 접근 권한을 가지고 있어야 합니다. 그룹 사용자 이름은 필요하지 않습니다. 프록시 또는 세션 가져오기를 통해서는 회원 자격이나 관리자 권한이 부여되지 않습니다. 현재 회원 자격이 있다고 해서 가입 전 기록에 대한 접근이 보장되는 것은 아닙니다.

Telethon 세션 파일 가져오기#

Telethon SQLite, Pyrogram SQLite 및 Telegram Desktop TData는 서로 다른 형식을 사용합니다. 이 패널은 지원되는 구조를 감지하여 변환하며, 파일 이름 변경은 변환으로 간주되지 않습니다. ‘파일(Files)’에서 하나의 세션과 해당 JSON 파일을 선택한 다음, ‘계정 연결(Connect account)’을 누르십시오. 최대 4개의 일치하는 파일과 총 8 MiB까지 허용됩니다. TData/JSON에 대한 자세한 내용은 형식 제한 사항을 참조하십시오. 비밀번호 복구 기능은 없습니다. 전화/2단계 인증(2FA) 또는 QR 로그인을 통해 별도의 인증이 생성됩니다.

선택 사항인 Telethon 전용 명령줄 경로는 계속 사용할 수 있습니다:

1. 원본 세션을 사용하는 클라이언트를 중지하고 일관된 복사본을 생성하십시오. 변환기는 WAL/저널이 완료되지 않은 파일을 거부합니다. 검사를 우회하기 위해 해당 파일을 삭제하는 대신, 원본 클라이언트를 올바르게 종료하십시오.
2. TgWitness 환경에서 다음 명령을 실행하십시오:

python -m tgwitness.sessions account.session --out account.tgwitness-session

3. '계정 추가' → '파일'에서 결과 파일을 불러오거나 해당 문자열을 붙여넣은 후 다음 단계로 진행하십시오.
4. 표시된 숫자형 계정 ID를 확인하고, 소스를 선택한 후 관찰을 시작하십시오.

이 변환기는 SQLite를 읽기 전용 모드로 열고, 스키마 업그레이드나 네트워크 요청을 수행하지 않으며, 세션을 출력하지 않습니다. 스키마 버전, 테이블 유형, 단일 세션 행, IP/포트/데이터 센터 및 키 길이를 확인합니다. CLI 입력은 64 MiB로 제한되며, StringSession 텍스트는 4 KiB로 제한됩니다. 패널 변환은 파일을 인증된 TgWitness 서버에 업로드하고, 메모리 내에서 처리한 후, 업로드된 원본 파일을 저장하지 않고 정규화된 자격 증명을 해당 브라우저로 반환합니다. 원격 서버의 경우 HTTPS를 사용하십시오.

변환된 파일은 암호화되지 않은 계정 접근 비밀번호입니다. 이 정보를 안전한 저장소에 보관하고, 절대로 커밋하거나 제3자 변환 서비스로 전송하지 마십시오. TgWitness는 인증된 세션을 암호화된 볼트에 저장합니다. 세션을 복사한다고 해서 별도의 인증이 생성되는 것은 아닙니다. 복제된 인증 키로 클라이언트를 동시에 실행하여 독립적인 업데이트 전달이 이루어진다고 가정하지 마십시오.

변환 작업은 원본 메시지, 엔티티 캐시 또는 영구적인 업데이트 커서가 아닌 권한을 전달합니다. 또한 프로세스 재시작 시 업데이트 복구 기능을 보장하지 않습니다.

MTProto, Telethon 및 프록시#

MTProto는 텔레그램의 프로토콜입니다. Telethon은 TgWitness가 사용하는 파이썬 클라이언트 라이브러리입니다. MTProxy는 텔레그램 전송 프록시이며, SOCKS5 및 HTTP CONNECT는 일반적인 터널을 제공합니다. 이 중 어느 것도 계정 인증을 대체하지는 않습니다.

로그인하기 전에 ‘계정 → 설정 → 연결 설정 → 연결 경로 변경’에서 각 작업 공간의 경로를 저장하십시오. 새 작업 공간은 기본적으로 ‘자동 MTProxy’ 모드로 설정되며, IP 숨기기 기능이 적용된 공개 목록으로 구성됩니다. ‘직접 연결(Direct)’을 명시적으로 사용했던 기존 작업 공간은 이를 허용하는 모드를 유지합니다.

IP 모드#

경로에 따라 연결 방식이 결정됩니다. IP 모드는 서버 주소가 노출될 수 있는 시점을 결정합니다. 이러한 제어 기능은 VPN을 설치하거나 기기의 모든 트래픽을 라우팅하지 않습니다.

터널/VPN 모드는 사용자가 해당 네트워크를 별도로 관리한다고 가정합니다. 정상적으로 작동하는 터널이 없으면, 대상 측에서 서버의 실제 주소를 확인할 수 있습니다. 옵션의 이름이 아닌 실제 네트워크 환경에 따라 모드를 선택하십시오.

경로 선택#

가짜 TLS ee 비밀키는 거부됩니다. Telethon 1.45의 정규화 기능은 접두사 및 도메인을 제거할 수 있지만, 이는 가짜 TLS를 구현하는 것은 아닙니다. tg://proxy?server=…&port=…&secret=… 또는 https://t.me/proxy?server=…&port=…&secret=…를 붙여넣고 ‘링크에서 필드 채우기’를 선택하십시오. 이렇게 하면 연결하거나 저장하지 않고도 필드가 유효성 검사되고 채워집니다. 경로를 별도로 검토하고 저장하십시오. 수동 입력 필드는 계속 사용할 수 있습니다. 텔레그램 프록시 링크를 참조하십시오.

설치를 통해 제공되는 공개 프록시#

내장된 목록은 SoliSpirit/mtproto, zakky8/mtproto-proxy-pro, kort0881/telegram-proxy-collector 및 3yed-61/MTP-Collector 등 네 가지 소스를 결합한 것입니다. 번들로 제공되는 스냅샷에는 엔드포인트 정보, 출처 출처 및 다운로드 날짜가 포함되어 있습니다. 제공업체가 목록에 포함되어 있다고 해서 해당 프록시가 정상적으로 작동하거나 모든 텔레그램 업데이트를 전달한다는 증거는 아닙니다.

자동 MTProxy는 텔레그램 전송 연결 상태를 확인하고, 정상 작동하는 프록시를 유지하며 오류가 발생하면 다른 프록시로 전환합니다. 워크스페이스는 사용 가능한 정상 작동 프록시 항목이 충분할 경우 서로 다른 프록시를 선호하며, 고유한 출구 주소는 보장되지 않습니다. 작동하지 않는 프록시는 다음 시도를 위해 잠시 대기합니다. 작동하는 프록시가 없는 경우, IP 모드가 수집을 대기해야 하는지 아니면 직접 연결을 사용할 수 있는지를 결정합니다. 프록시를 변경해도 계정이 변경되거나 저널이 삭제되지는 않습니다. 경로 선택 및 변경 사항은 서명된 저널에 기록됩니다.

자동 경로가 활성화된 상태에서는 목록이 매시간 갱신되며, 전송 확인은 기본적으로 10분마다 실행됩니다. 이러한 간격은 설정에서 조정할 수 있습니다. 공개 목록을 업데이트하면 갱신이 요청되며, 목록을 조회하는 것만으로는 저장된 수동 경로가 변경되지 않습니다.

각 피드 응답은 1 MiB로 제한되며, 요청 타임아웃은 8초, 전체 다운로드 마감 시간은 20초입니다. 리디렉션은 거부됩니다. 소스당 최대 64개의 호환 가능한 항목이 보관되며 중복 제거됩니다. 파서는 지원되는 16진수 및 base64url 비밀값과 JSON 피드를 수용합니다. 가짜 TLSee, 유효하지 않은 링크, 사설/예약 IP 리터럴 및 로컬 호스트명은 건너뜁니다. 호스트명은 사용 전에 확인 및 검증되며, 선택된 IP는 해당 연결에 대해 고정됩니다. 자동 재획득 시 호스트명이 다시 확인되며, 수동 항목을 재적용하여 다시 확인해야 합니다.

피드 응답이 실패하거나, 비어 있거나, 호환되지 않는 경우 이전 소스 스냅샷이 유지됩니다. 업데이트는 원자적이며, 직렬화되며, 워크스페이스당 분당 한 번으로 제한됩니다. 전송 프로브가 성공하면 연결이 확립된 것이지, 익명성이나 캡처의 완전성이 보장되는 것은 아닙니다.

텔레그램 트래픽과 HTTPS 요청은 서로 다른 경로를 사용합니다. 목록 다운로드는 별도의 HTTPS 연결과 제공된 외부 요청 경로를 사용합니다. 'TGWITNESS_PROXY_FEED_PROXY'는 HTTP/SOCKS5 프록시를 통해 해당 경로를 명시적으로 재정의하며, 두 가지 'Compose' 수집기 변형 모두 이를 전달합니다. 백그라운드 풀은 메인 작업 공간을 따릅니다. 텔레그램 세션, API 인증 정보, 패널 토큰 또는 봇 토큰은 피드 제공자에게 전송되지 않습니다. 제공자 이름, 스냅샷 날짜 및 다운로드 경로는 ‘목록 출처’ 항목 아래에 표시됩니다.

MTProxy는 텔레그램 트래픽만 전달합니다. 타임스탬프, 알림, 외부 복사본 및 소스 확인과 같은 워크스페이스 HTTP 작업은 구성된 경우 별도의 SOCKS5/HTTP 프록시를 사용하며, 그렇지 않은 경우 계정의 SOCKS5/HTTP 경로를 사용합니다. 둘 중 하나도 설정되지 않은 경우, Hide IP는 요청을 거부하며, 다른 모드에서는 Direct를 허용합니다. 외부 요청은 비활성화할 수 있습니다. 명시적으로 구성된 피드 다운로드 프록시는 별도의 운영자 오버라이드로 유지됩니다. 독립적인 증인 서비스는 자체 경로를 유지합니다.

자동 풀 매개변수

**매개변수 → 자동 MTProxy**에서 오류 임계값, 대기 시간, 계획된 로테이션, 프록시 공유 및 허용되는 폴백 지연 시간을 구성합니다. | 제어 항목 | 기본값 | | --- | --- | | 교체 전 연결 끊김 횟수 | 10분 이내 3회 | | 연결 시도당 프록시 시도 횟수 | 3 | | 오류 발생 후 첫 번째/최대 대기 시간 | 10분 / 6시간 | | 계획된 로테이션 | 비활성화; 실패 시 전환 | | 프록시당 계정 수 | 0: 별도의 항목을 우선적으로 사용하며, 필요할 때 공유합니다. 독점 항목을 기다리려면 1로 설정하세요. | | 허용된 Direct 폴백 전 지연 시간 | 10분; Hide IP는 여전히 Direct를 거부합니다 | | 피드 새로고침 / 전송 확인 | 60 / 10분; 메인 작업 공간의 값이 공유 풀에 적용됨 | 프로xy가 다르다고 해서 출구 주소가 달라지는 것은 아닙니다. 이 설정들은 Telegram의 제한을 무효화하지 않으며 익명성을 보장하지도 않습니다.

공개 목록을 자체 운영자 카탈로그로 대체하려면 아래의 오버라이드 설정을 구성하십시오. 이 설정은 proxies 배열이 비어 있는 경우를 포함하여 외부 구독을 완전히 비활성화합니다.

빈 카탈로그를 proxy-config/proxies.json 로 복사하고 배포된 공개 엔드포인트를 추가하십시오:

{"format": "tgwitness-proxy-catalog-v1", "proxies": [
  {"id": "project-eu", "label": "Project EU",
   "link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}

예시 값은 반드시 교체해야 합니다. 최대 32개의 고유 항목을 입력할 수 있습니다. 인증된 목록은 공유 비밀번호 없이 레이블/호스트/포트를 반환하며, 하나를 선택하면 해당 자격 증명이 워크스페이스 볼트에 저장됩니다. 명시적인 전송 테스트가 이루어질 때까지 가용성은 검증되지 않은 상태입니다. 형식이 잘못된 카탈로그의 경우 수동 구성이 가능합니다.

네이티브 실행: TGWITNESS_PROXY_CATALOG를 로컬 JSON 경로로 설정합니다. Docker:

docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build

오버레이는 proxy-config를 읽기 전용으로 마운트하며, 파일은 컨테이너 UID 10001이 읽을 수 있어야 합니다. 해당 디렉터리는 Git, Docker 빌드 컨텍스트 및 소스 아카이브에서 제외됩니다. 이 카탈로그는 수집 계정을 구성하며, 위트니스 봇은 MTProxy가 아닌 자체 HTTP/SOCKS5 경로를 사용합니다.

직접 대체 경로는 위의 IP 모드에 따라 결정됩니다. 경로를 변경하기 전에 관찰을 일시 중지하십시오. 저장 시 기존 클라이언트 연결이 끊기고 진행 중이던 로그인이 취소되며, 새 클라이언트는 저장된 경로를 사용합니다. 계정의 저널/세션 바인딩은 유지됩니다. 설정을 변경하면 이전 경로가 대체되므로, 편집 시 프록시 자격 증명을 다시 입력해야 합니다.

인증 정보는 network.enc로 암호화됩니다. API는 사용자 이름, 비밀번호 또는 비밀 키를 반환하지 않습니다. 서명된 기록에는 경로 유형과 인증 정보의 유무가 포함되지만, 엔드포인트와 비밀 키는 제외됩니다. 운영자는 패널에서 엔드포인트를 확인할 수 있습니다. 비밀 키 필드는 저장, 잠금 또는 작업 공간 전환 후 삭제됩니다.

‘텔레그램 연결 테스트’ 기능은 로그인 전에도 이용 가능하며, 해당 경로를 통해 일시적인 비승인 텔레그램 연결을 열고 닫습니다. 이 기능은 IP 확인 웹사이트에 접속하지 않습니다. 테스트 성공 시 전송 연결이 확립된 것일 뿐, 그룹 접근 권한, 완전한 전달 또는 익명성이 보장되는 것은 아닙니다.

이 프록시는 텔레그램 DC 미디어 다운로드를 포함하여 텔레그램 클라이언트의 연결에 적용됩니다. 브라우저, pip, SSH 및 수동으로 실행되는 TSA 도구는 별도의 경로를 따릅니다. 프록시 호스트명은 로컬에서 확인될 수 있습니다. rdns는 대상 호스트명에 영향을 미치며, 텔레그램은 종종 숫자로 된 DC IP를 제공합니다.

SOCKS5 및 일반 HTTP CONNECT는 프록시 인증 정보나 클라이언트-프록시 터널 자체를 암호화하지 않습니다. MTProto는 텔레그램 트래픽을 별도로 보호합니다. 신뢰할 수 없는 네트워크에서는 프록시로 연결되는 적절한 보안 채널을 사용하십시오. 비공개 그룹은 클라우드 채팅이며, MTProto는 이를 종단 간 암호화된 비밀 채팅으로 변환하지 않습니다.

암호화 및 서명#

계정의 ‘저장소 보호’ 항목에는 이러한 상태가 표시됩니다. 패널 토큰은 암호화 비밀번호가 아닌 액세스 시크릿입니다. 이 토큰은 관리자 권한을 부여하며, 발행된 토큰의 적용 범위는 계정 및 채팅으로 제한될 수 있습니다. 워크스페이스는 호스트 프로세스를 공유하며, 독립된 테넌트가 아닙니다.

명시적으로 시작된 격리된 합성 데모는 직접적인 루프백 연결을 통해 자동으로 열릴 수 있습니다. 이는 별도의 프로세스 수명 주기 기능을 사용하며, 구성된 패널 토큰을 노출하지도 않고 실제 작업 공간에 대한 액세스 권한을 부여하지도 않습니다. 원격, 프록시 또는 크로스 오리진 요청은 이 자동 진입 기능을 획득하거나 사용할 수 없습니다. 이러한 편의 기능은 실제 계정 데이터에 대한 인증 경계를 제거하지 않습니다.

BitLocker, LUKS, FileVault 또는 관리형 암호화 볼륨은 각각의 위협 모델에 따라 저장 장치를 보호할 수 있습니다. 잠금 해제된 상태에서 실행 중인 시스템의 관리자는 여전히 데이터를 읽을 수 있습니다. 저장소 계획 시 SQLite WAL/SHM, 미디어, 임시 내보내기 파일, 스왑, 백업 및 브라우저 다운로드 파일을 포함하십시오. Docker 볼륨은 단순히 볼륨이라는 이유만으로 암호화되는 것은 아닙니다. TgWitness는 SQLCipher나 객체 암호화를 구현하지 않습니다.

외부 마스터 키#

새로 설치할 경우, 마스터 키를 데이터 디렉터리 외부에 배치하십시오. 이렇게 해도 기존 로컬 키 볼트가 자동으로 마이그레이션되지는 않습니다. 서비스 ID만 접근할 수 있는 키 디렉터리를 준비한 다음, 다음 명령을 실행하십시오:

python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case

설치된 프로젝트 환경을 사용하는 PowerShell:

python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case

Docker에서 파일을 /data 외부(예: /run/secrets/tgwitness-master.key)에 읽기 전용으로 마운트하고, 환경 변수를 해당 경로로 설정하십시오. 서비스 UID는 해당 파일을 읽을 수 있어야 합니다. 키 바이트가 아닌 경로를 환경/구성 파일을 통해 전달하십시오.

각 워크스페이스에는 무작위로 생성된 공개 솔트(salt)와 HKDF-SHA256을 통해 파생된 고유한 Fernet 키가 할당됩니다. vault.external.json는 마스터 키가 아닌 파생 메타데이터를 저장합니다. 키가 없거나 잘못된 경우, 키를 자동으로 대체하지 않고 시작에 실패합니다. 복구를 위해 솔트 메타데이터와 마스터 키를 모두 보관하십시오.

모든 작업 공간은 동일한 마스터 키에서 파생되며, 이 키가 유출될 경우 전체 설치에 영향을 미칩니다. 실행 중인 프로세스는 비밀 정보를 복호화할 수 있습니다. 이는 HSM이나 암호 KDF가 아닙니다. 무작위 키 대신 임의의 사용자 지정 비밀번호는 허용되지 않습니다.

의도적인 마이그레이션이 구현되고 검증될 때까지는 기존 설치 환경에 대한 기존 키를 유지하십시오. vault.key를 삭제하거나 마스터 키를 교체하면 세션/서명 키에 대한 접근 권한이 상실될 수 있습니다. 암호화된 백업과 키를 별도로 보관하고 격리된 인스턴스에서 복구 테스트를 수행하십시오.

출처 및 검증 범위#

2026년 10월 26일 검토:

• https://core.telegram.org/api/auth
• https://core.telegram.org/api/obtaining_api_id
• https://docs.telethon.dev/en/stable/basic/signing-in.html
• https://docs.telethon.dev/en/stable/concepts/sessions.html
• https://core.telegram.org/mtproto/mtproto-transports
• https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/SourceFiles/storage/storage_account.cpp
• Telethon 1.45.0: SQLiteSession, StringSession, Connection._proxy_connect, TcpMTProxy.normalize_secret 및 다운로드 방법.

현지 테스트에는 루프백 SOCKS5/HTTP CONNECT 피처, 합성 SQLite 세션, 경로 격리, 비밀 정보 제외 및 키 누락 시 거부 기능이 포함됩니다. 이러한 테스트는 실제 텔레그램/프록시 상호 운용성이나 MTProxy의 실제 동작을 검증하지는 않습니다. VERIFICATION.md 및 LIVE_ACCEPTANCE.md를 참조하십시오.