# 기능 및 제한 사항

Canonical page: https://phishdestroy.github.io/TgWitness/ko/docs/reference/features/

TgWitness가 현재 구현하고 있는 기능, 텔레그램 플랫폼이 제한하는 사항, 그리고 향후 개선이 필요한 부분.

디자인 참조: 2026년 10월 26일. 주요 사용 사례는 연결된 계정이 접근할 수 있는 비공개 텔레그램 그룹 및 채널입니다. 이 문서는 구현된 동작, 플랫폼의 한계 및 향후 작업 사항을 구분하여 설명합니다. 목표 아키텍처 항목은 해당 기능이 이미 존재한다는 주장을 의미하지 않습니다.

## 독립형 애플리케이션

TgWitness는 자체 설치 절차, 데이터 디렉터리 및 릴리스 라이프사이클을 갖추고 있습니다. 번들로 제공되는 웹 인터페이스를 통해 설정 및 검토가 가능하며, 내보낸 기록은 독립적으로 사용할 수 있습니다.

운영자는 계정을 연결하고, 각 계정이 볼 수 있는 소스를 선택한 후, 저장된 관찰 일지를 확보합니다. 패널에는 콘텐츠, 저장된 변경 사항, 관찰 출처 및 알려진 누락 사항이 표시됩니다. 다른 조사관은 내보낸 자료를 검증할 수 있습니다.

네 가지 뚜렷한 상태가 중요합니다: 계정 인증, 소스에 대한 접근 권한, 정상적으로 작동하는 수집기, 그리고 전달 완결성이 어느 정도 확립되었는지 여부입니다. 처음 세 가지 중 어느 것도 네 번째를 자동으로 입증하지는 않습니다. 활동이 없는 그룹이 반드시 수집기 오류인 것은 아닙니다.

## 공동 수사

관리자는 워크스페이스 및 개별 채팅에 적용되는 [액세스 토큰을](https://phishdestroy.github.io/TgWitness/ko/docs/reference/access/) 발급할 수 있으며, 여기에는 7가지 권한, IP 제한, 유효 기간, 로그인 횟수 제한 및 세션 제어 기능이 포함됩니다. 읽기 전용 검토자는 텔레그램 인증이나 메인 패널 키를 받지 않고도 사건을 검토할 수 있습니다. 채팅 단위의 제한된 접근 권한은 계정 전체 설정 및 전체 기록부 내보내기 기능과는 별도로 관리됩니다.

자동 MTProxy는 4개의 공개 소스 또는 운영자 카탈로그에서 텔레그램 경로를 지속적으로 유지 관리합니다. [IP 모드에](https://phishdestroy.github.io/TgWitness/ko/docs/reference/connection/#ip-modes) 따라 오류 발생 시 다른 프록시를 기다려야 하는지, 아니면 명시적으로 허용된 직접 경로를 사용할 수 있는지가 결정됩니다. 외부 HTTP 요청에는 별도의 경로와 비활성화 스위치가 있습니다.

## 아카이브 도구

현재 `main` 버전에서는 [기록 수집](https://phishdestroy.github.io/TgWitness/ko/docs/reference/history/), [아카이브 검색 및 분석](https://phishdestroy.github.io/TgWitness/ko/docs/reference/analysis/), [읽기 전용 MCP](https://phishdestroy.github.io/TgWitness/ko/docs/reference/mcp/), [로컬 OCR/전사 기능](https://phishdestroy.github.io/TgWitness/ko/docs/reference/media-analysis/) 및 [발신 웹훅](https://phishdestroy.github.io/TgWitness/ko/docs/reference/webhooks/) 기능이 추가되었습니다. 이는 0.7.0 휴대용 미리보기 버전 이후에 추가된 소스 체크아웃 기능입니다. 분석 보고서와 인식된 텍스트는 캡처된 이벤트와 별도로 관리됩니다.

## 선택적 추가 기능

기본 설정 순서는 계정 → 소스 → 관찰입니다. **‘추가 기능’은** 텔레그램 위트니스 봇과 GitHub 캡처 미리보기가 포함된 별도의 목적지입니다. 각 항목은 설정을 표시하기 전에 사용 가능 여부와 요구 사항을 안내합니다. 카드를 선택하면 지침이 열리지만, 서비스가 등록되거나 시작되지는 않습니다.

봇 설정은 읽기 전용 액세스 생성, 게시 설정 선택, 위트니스 호스트에서 실행하는 세 단계로 이루어집니다. 네트워크 및 게시 옵션, 기존 연결 정보, 검증 명령어는 요청 시 제공됩니다. 다운로드된 구성 파일은 실행 중인 위트니스와 별개입니다. 추가 기능을 전환해도 초안은 유지되지만, 계정 변경 및 잠금 시에는 임시 토큰과 양식이 삭제됩니다. 내장된 가이드에는 실행 지침이 포함되어 있습니다. [GitHub Actions는](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) 사용자의 포크에서 고정된 수집기를 실행하여, 하나의 채팅 내용을 캡처하고 워크플로 출처 정보가 포함된 암호화된 전달 데이터를 생성합니다.

## 프로토콜 및 비공개 출처

**MTProto는 텔레그램의 프로토콜이며, Telethon은 TgWitness가 MTProto와 통신하기 위해 사용하는 파이썬 라이브러리입니다.** 이 둘은 서로 다른 연결 방식이 아닙니다. 수집 기능은 MTProto를 사용하며, 선택 사항인 ‘witness’는 봇 API를 통해 서명된 확인 내역을 게시합니다.

각 작업 공간에는 고유한 인증된 클라이언트와 계정 업데이트 스트림이 있습니다. TgWitness는 구성된 소스에서 관측 데이터를 선별하고, 기록 스냅샷 및 미디어 다운로드와 같은 기능에 대해 별도의 명시적 요청을 수행합니다.

비공개 정보원은 공개 사용자 이름이 필요하지 않습니다. 텔레그램 피어 유형과 숫자 ID가 식별자이며, 제목과 사용자 이름은 변경될 수 있습니다. 접근 권한은 기존 회원 자격 및 권한에 따라 결정됩니다. TgWitness는 정보원에 자동으로 가입하거나 가입 승인을 우회하지 않습니다. 다른 계정에서 발급된 접근 해시는 범용 접근 토큰이 아닙니다.

수집 모델은 가입 전 숨겨진 기록, 참가자/관리자 역할, 세션 취소, 권한 제거 또는 변경, 그룹에서 슈퍼그룹으로의 이전, 주제/포럼, 연결된 토론, 채널 신원 및 이용 불가능한 첨부 파일을 모두 고려해야 합니다. 모든 조합이 실제 환경에서 검증된 것은 아닙니다.

출처 가시성은 수집기 시작 시점에 확인됩니다. 제한된 대화 결과에서 출처가 누락된 경우, 이는 **접근이 확인되지 않았음을** 의미하며, 삭제된 것이 입증된 것은 아닙니다. 하나의 출처가 사용 불가능하더라도 다른 접근 가능한 출처를 관찰하는 데는 지장이 없습니다. 공개된 고정 데이터에 초대 링크나 실제 세션 정보를 절대 포함하지 마십시오.

## 여러 계정

이 패널은 여러 개의 **워크스페이스를** 지원하며, 각 워크스페이스마다 다음과 같은 기능을 갖추고 있습니다:

- 인증, 암호화 저장소 및 연결 경로.
- SQLite 저널 및 Ed25519 서명 식별자.
- 선택된 소스, 미디어 대기열 및 캡처 설정.
- 모니터링 상태, 오류, 체크포인트 및 내보내기 기능.

표시된 작업 공간을 전환하더라도 다른 수집기는 중단되지 않습니다. 작업 공간 간 중복 계정 인증은 허용되지 않습니다. 이미 하나의 텔레그램 계정에 바인딩된 저널은 다른 계정으로 재할당할 수 없으나, 동일한 계정을 다시 연결하는 것은 허용됩니다. 이를 통해 계정 식별 정보와 관련 메시지 ID 범위가 유지됩니다.

고정된 수량이나 측정된 처리량 보장은 없습니다. 워크스페이스는 하나의 Python 프로세스와 이벤트 루프를 공유합니다. 별도의 계정 워커 구현은 향후 작업으로 남아 있습니다. 현재 프로세스 격리를 위해서는 별도의 설치, 포트 및 데이터 디렉터리를 사용하십시오.

각 계정에 접근 가능한 소스를 할당하십시오. 서로 다른 계정이 동일한 그룹을 관찰할 수는 있지만, 각 계정의 관찰 기록은 별도로 유지되며 출처가 명확하게 표시됩니다. 한 명의 운영자가 제어하는 단일 기기에서 실행되는 두 계정은 두 개의 독립적인 증인이 아닙니다. 내보내기 기능은 작업 공간별로 제공되며, 통합된 사건 패키지나 전체 텔레그램 타임라인 기능은 구현되어 있지 않습니다.

## 캡처 및 출처 표기

'소스(Sources)'는 새 메시지, 수정, 삭제, 반응 및 멤버십에 대해 계정별 설정을 제공합니다. 사전 설정은 모든 범주를 유지하거나 메시지/수정/삭제 중 하나를 선택합니다. 이 정책은 워크스페이스에서 선택한 그룹에 적용되며, 재시작 후에도 유지되고, 변경 전후의 서명이 포함됩니다. 기본값은 모든 범주를 보존합니다. 카테고리를 비활성화해도 기존 기록은 삭제되지 않으며, 다시 활성화하더라도 누락된 이벤트는 복원되지 않습니다. 운영 기록, 기타 그룹 서비스 이벤트 및 명시적인 기록 스냅샷은 별도로 관리됩니다. 캡처된 텔레그램 객체는 별도의 업데이트 설정과 관계없이 내장된 메타데이터를 유지할 수 있습니다. 아직 그룹별 카테고리 재정의 기능은 제공되지 않습니다.

| 자료 | 지금 캡처됨 | 경계 |
| --- | --- | --- |
| 메시지 | 텍스트, 피어/메시지 ID, 발신자 메타데이터, 답장 및 원본 업데이트 엔벨로프 | 해당 메시지에 대해 공개적으로 검증 가능한 텔레그램 서명이 없습니다. |
| 편집 | 새로 확인된 버전 및 이전에 저장된 모든 버전 | 서비스 중단 기간 중 이루어진 중간 편집 내용은 손실될 수 있으며, 발신자가 반드시 편집자인 것은 아닙니다. |
| 삭제 | 알림 및 이전에 캡처된 콘텐츠(있는 경우) | 일반적으로 삭제자나 정확한 조치 시간은 표시되지 않음 |
| 범위 미지정 삭제 | 상대방을 추측하지 않은 원본 계정 수준의 알림 | 이전에 저장된 계정 단위 ID와의 엄격한 상관관계 확립은 향후 과제입니다. |
| 반응 | 집계된 카운터 및 최근 신원 정보 표시 | 이용 가능한 리액터 전체 목록을 확인하려면 별도의 조회가 필요하며, 채널은 신원을 숨길 수 있습니다. |
| 회원 가입 | 서비스 공지 및 참가자 업데이트 전달 | 표시 여부는 역할 및 채팅 유형에 따라 다르며, 이벤트가 누락되었다고 해서 해당 이벤트가 존재하지 않는 것은 아닙니다. |
| 관리자 작업 | 관련된 업데이트만 제공 | 별도의 관리자 로그 폴링 기능은 구현되어 있지 않습니다. |
| 첨부 파일 | 원본 버전 설명자, 다운로드된 바이트 수/SHA-256 및 시도 결과 | 삭제된 파일은 복구할 수 없을 수도 있으며, 최신 버전이 이를 대체하지 않습니다. |
| 연혁 | 현재 표시된 메시지의 명확한 스냅샷 | 모든 수정 내역이나 삭제된 콘텐츠를 재구성하지는 않습니다. |
| 수집 프로세스 | 시작/중지, 하트비트, 오류, 설정, 범위 및 프로그램 수신 | 자체 보고이며, 독립적인 프로세스 인증이 아님 |

특정 행동은 출처가 해당 행위자를 실제로 명시한 경우에만 해당 인물에게 귀속됩니다. 그렇지 않은 경우, 인터페이스는 귀속 정보가 누락되었음을 알립니다. 사용자 이름과 실명은 관찰된 속성일 뿐, 실제 신원을 증명하는 것은 아닙니다.

## 용량 및 텔레그램 제한 사항

품질 보장이 가능한 채팅 모니터링에 대한 보편적인 수치는 없습니다. 처리 용량은 초당 최대 이벤트 수, 첨부 파일의 양과 크기, 추가 RPC, 활성 계정 수, 디스크 지연 시간/여유 공간, 네트워크 상태, 텔레그램 제한, 허용 가능한 지연 시간 및 대기열 깊이에 따라 달라집니다.

텔레그램은 수동 전달과 능동적 단기 폴링을 구분합니다. 텔레그램의 업데이트 문서에는 공개 채널/슈퍼그룹에 대한 추가적인 `updates.getChannelDifference` 호출이 설명되어 있으며, **동시에 단기 폴링되는 소스는** 최대 10개까지로 제한할 것을 권장합니다. 이는 선택된 그룹이 10개에 국한된다는 의미도, 완전성을 보장한다는 의미도 아닙니다.

| 모드 | 목적 | 상태 |
| --- | --- | --- |
| 표준 관찰 사항 | 선택한 출처에서 전달된 업데이트 기록 | 구현됨 |
| 우선순위 관찰 | 제한된 소스 집합에 대한 추가 차이점 확인 | 사용자 모드로는 구현되지 않음 |

FloodWait를 무시하거나 추가 계정을 통한 선형 용량을 가정하는 임의의 고주파수 폴링은 유효한 용량 산정 모델이 아닙니다. 기본 제한은 나열된 대화 중 처음 1,000개, 기록 스냅샷당 최대 500개의 메시지, 유형별 수집 파일당 1~2,000 MiB, 압축되지 않은 서명된 ZIP 콘텐츠 4 GiB이며, 각 **한도는 ‘매개변수’에서** 작업 공간별로 변경할 수 있습니다. 내보내기에는 고정된 이벤트 수 제한이 없습니다. 브라우저 폴백은 기본적으로 128 MiB로 제한되며, 스트리밍 CLI는 구성 가능한 전송 제한을 가지며, 기본값은 5 GiB입니다.

`tools/check_capacity.py`는 로컬 합성 데이터의 수집 및 내보내기를 측정합니다. 이 결과는 텔레그램 전송량 측정값이나 실제 채팅 횟수를 보장하는 것이 아닙니다. 측정된 버전 및 워크로드는 [VERIFICATION.md를](https://phishdestroy.github.io/TgWitness/ko/docs/reference/verification/) 참조하십시오.

## 신뢰성 및 복구

구현된 기능으로는 SQLite WAL/동기식 트랜잭션, 원자적 메시지 및 미디어 작업 쓰기, 지속적 작업 및 재시도 지연, 원본 버전 설명자, 제한된 재시도; 지속화된 미디어 FloodWait; 텍스트 이벤트의 네트워크 대기 시간 외 미디어 다운로드; 후속 쓰기 작업이 진행되는 동안의 안정된 접두사 내보내기; 원자적 설정 및 감사 기록; 대체 로그인 실패 후 유효한 인증 정보 보존; 손상된 추가 작업 공간의 격리; 명시적인 재연결 시도; 명확한 권한 상실 보고; 단조로운 시계를 사용한 실제 시간 변경 감지 등이 포함됩니다.

계정 및 채널의 pts/qts/seq는 재시작 후에도 저장 및 복원되며, 모니터링 중인 채팅은 주기적으로 재확인됩니다. [증거 형식을](https://phishdestroy.github.io/TgWitness/ko/docs/reference/evidence/#durable-collection-and-process-receipts-02) 참조하십시오. 위치를 주기적으로 저장하는 것은 저널 수락에 대한 원자적이고 무손실적인 확인을 의미하지는 않습니다.

모든 프로세스 시작 시 이전 헤드와 오프라인 경계가 기록됩니다. 현재 기록은 공백 보충으로 간주되지 않습니다. 텔레그램의 차이값 보존 용량은 유한하므로, `differenceTooLong`는 사라진 모든 콘텐츠를 복원할 수 없습니다. 복구 불가능한 공백은 후속 기록 스냅샷이 성공하더라도 명시적으로 남아 있어야 합니다.

## 증거 모델

각 이벤트에는 시퀀스, 현지 UTC 관측 시간, 제공된 경우 소스 시간, 유형, 소스, 제공된 경우 행위자, 원본 페이로드, 이전 해시 및 서명이 기록됩니다. 메시지 관측 기록에는 수집자 계정/실행 컨텍스트도 함께 저장됩니다.

서명된 처리 기록에는 무작위 실행 ID, TgWitness/Python/OS/의존성 버전, 소스 파일의 SHA-256 값 및 집계 지문, 초기 계정, 범위 및 설정, UTC/단조 증가 값, 그리고 이전 저널 헤더가 포함됩니다. 설정 변경, 시작/중지 및 오류는 동일한 기록부에 기록됩니다. 체크포인트는 시작 시, 관찰 중 5분마다(변경 가능), 그리고 정상적인 중지 시에 보관됩니다. 보관된 로컬 체크포인트를 통해 이전 기록부 접두사로의 롤백을 감지할 수 있습니다.

| 작동 원리 | 이 도구가 제공하는 기능 |
| --- | --- |
| 파일 SHA-256 | 바이트가 알려진 다이제스트와 일치합니다. |
| 이벤트 해시 체인 | 알려진 경계를 기준으로 기록의 정렬/연결 |
| Ed25519 | 특정 키로 서명 |
| 독립적으로 유지되는 체크포인트 | 후속 자료는 유지된 경계와 일치합니다. |
| 프로그램 파일 크기 측정 | 측정된 파일에 대한 수집기 자체 보고서 |
| 유효한 독립적인 TSA 응답 | 명시적인 신뢰 가정 하에서 TSA 시간을 기준으로 한 특정 바이트의 존재 여부 |

RFC 3161 요청 준비 및 OpenSSL 응답 검증 기능이 구현되었습니다. 자동 제출 기능은 구현되지 않았습니다. 요청이나 로컬 서명에 포함된 시스템 시간은 독립적인 타임스탬프가 아닙니다. [TIMESTAMP.md를](https://phishdestroy.github.io/TgWitness/ko/docs/reference/timestamp/) 참조하십시오.

수집기 및 서명 키를 관리하는 운영자는 새로운 서명된 관측 기록을 조작할 수 있습니다. 서명은 텔레그램의 출처, 진실성 또는 자동적인 법적 증거 능력을 입증하지 않습니다. 보다 강력한 증거 보관을 위해서는 독립적인 점검점/시간 저장소, 키 접근 제어, 전송 기록 및 신뢰할 수 있는 소프트웨어를 통한 검증이 필요합니다.

## 내보내기, 배포 및 인계

서명된 ZIP 파일에는 원본 JSONL, CSV, HTML, 보존된 첨부 파일, 해시, 서명된 매니페스트 및 편의를 위한 검증 도구가 포함되어 있습니다. 이는 하나의 워크스페이스와 고정된 전체 저널 접두사를 다룹니다. 패널 검색 필터는 기록을 무작정 제거하지 않습니다. 비밀 키, 토큰 및 텔레그램 세션은 제외되며, 원본 관측 데이터에는 여전히 개인 정보 및 텔레그램 메타데이터가 포함될 수 있습니다.

ZIP 다이제스트, 신뢰할 수 있는 지문, 체크포인트, 처리 영수증 및 인계 기록을 별도로 보관하십시오. 검사 대상 ZIP 파일에 포함되어 있다는 이유만으로 실행 코드를 무조건 신뢰하기보다는, 신뢰할 수 있는 설치 환경에서 제공된 검증 도구를 사용하십시오.

브라우저 인터페이스는 Node.js, CDN 또는 외부 폰트 없이 로컬에서 제공됩니다. 하나의 운영자 토큰으로 설치를 제어합니다. 원격 액세스를 위해서는 HTTPS 또는 SSH 터널이 필요합니다. 네이티브 파이썬 및 컨테이너 정의가 제공되며, [deploy/ 디렉토리](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) 아래에 서비스 예제가 포함되어 있습니다. 실행된 플랫폼 확인 항목은 별도로 나열되어 있습니다.

기본 작업 공간은 데이터 루트를 사용하며, 추가 작업 공간은 `profiles/<id>/`를 사용합니다. 백업을 수행하려면 프로세스를 중지하고 전체 데이터/키 세트가 필요합니다. 증거 ZIP 파일은 애플리케이션 백업이 아닙니다. 비밀 정보는 새로운 데이터 디렉터리에 대한 외부 마스터 키를 사용할 수 있으며, 저널/미디어 암호화는 운영자의 디스크/볼륨에서 제공됩니다. [CONNECTION-SECURITY.md](https://phishdestroy.github.io/TgWitness/ko/docs/reference/connection/) 및 [OPERATIONS.md](https://phishdestroy.github.io/TgWitness/ko/docs/reference/operations/)를 참조하십시오.

## 안정 버전 출시 기준

안정 버전이 출시되기 전에는 다음과 같이 명시하십시오:

1. 실제 비공개 그룹, 슈퍼그룹, 포럼 및 채널을 다루며, 회원/관리자 역할과 숨김/표시된 기록(로그인/2단계 인증, 권한 취소 및 접근 권한 상실 포함)을 포함합니다.
2. 알려진 활동과 대조하여 편집, 삭제, 반응, 회원 정보 및 미디어를 체계적으로 관리합니다.
3. 프로세스/호스트 중단, 디스크 장애/디스크 용량 부족, 만료된 파일 참조, FloodWait, 네트워크 연결 끊김, 파일 손상 및 데이터베이스 롤백.
4. 측정된 지연 시간, 대기열, 메모리 및 디스크 자원을 고려한 지속적인 다중 계정 사용으로, 조용한 소스와 소음이 많은 소스를 함께 포함합니다.
5. MTProto 상태 진행과 저널 수락 사이에 발생하는 중단.
6. 대상 OS/컨테이너 매트릭스에서의 클린 설치 및 검증된 백업 복원.
7. 보안, 서명 및 출처/증거 주장에 대한 독립적인 검토.

관리자 로그 폴링, 추가 리액터 목록, 우선순위 폴링, 별도의 워커, 애플리케이션 전체 암호화 기능은 향후 개발 과제입니다. 범위 지정 패널 액세스에 대한 설명은 ['액세스 및 권한'](https://phishdestroy.github.io/TgWitness/ko/docs/reference/access/) 섹션에 있습니다. 버전 0.6은 [ACCOUNTS.](https://phishdestroy.github.io/TgWitness/ko/docs/reference/accounts/)md에 설명된, 단일 계정에 제한된 TData 및 계정 파일 가져오기를 지원합니다. 게시 전에 텔레그램 API 이용 약관을 검토하십시오. 연구 참고 문헌 및 플랫폼 분석 결과는 [RESEARCH.md에](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/RESEARCH.md) 수록되어 있습니다.