TgWitness참고 문헌 / 보안 및 프로젝트
아키텍처
컬렉터, 패널, 저널, 워커 및 위트니스의 구성 요소와 이들 간에 데이터가 어떻게 이동하는지 설명합니다.
단일 Python 프로세스가 FastAPI 패널과 여러 개의 분리된 작업 공간을 호스팅하며, 각 작업 공간에는 Telethon 사용자 계정 클라이언트가 포함됩니다. SQLite는 추가 전용 서명된 이벤트 저널과 변경 가능한 운영 설정을 저장합니다. 암호화된 볼트에는 API 자격 증명, StringSession 및 서명 키가 저장됩니다. 프론트엔드는 단순한 번들형 HTML/CSS/JavaScript로 구성되어 있어, Node 빌드, CDN 또는 런타임 프론트엔드 다운로드가 필요하지 않습니다.
| 모듈 | 책임 |
|---|---|
| collector.py | 권한 부여, 대화 선택, 업데이트, 스냅샷, 미디어 대기열, 연결 모니터링 |
| interactions.py / telegram_client.py | 명시적인 패널 동작, 서명된 수신 확인, 영구적인 요청 ID 및 작업별 콜백/참가 재시도 정책 |
| message_content.py | 전송 액세스 메타데이터를 제외한 메시지 비교 기능 |
| workers.py | 취소 정리 작업을 수행하기 전에 파일 내보내기 작업이 완료될 때까지 대기 |
| store.py | WAL 트랜잭션, 순차적 이벤트 체인, 쿼리 필터, 운영 설정 |
| security.py | 비공개 파일 생성, 암호화된 보관소, Ed25519 서명, 단일 프로세스 잠금 |
| evidence.py | 전체 기록부 내보내기, 파생 파일, 체크포인트, 첨부 파일 검증 |
| verify.py | 독립형, 읽기 전용 검증 도구(표준 라이브러리 + 암호학): 아카이브, 커버리지, 위트니스 저널 및 채널 게시물, 프로필 파일 |
| app.py | 인증된 API, 라이프사이클, 요청 유효성 검사, 정적 패널 |
| profiles.py | 다중 계정 수집기, 공유 액세스 제어기, 워크스페이스별 라이프사이클 |
| access.py | 범위 지정된 권한 부여, 권한 확인, IP 제한, 세션 제한 및 관리자 콘솔 |
| proxy_catalog.py | 공개 피드 스냅샷, 전송 상태 확인, 공유 프록시 풀 및 상태 기반 선택 |
| provenance.py | 서명된 수집 실행 식별 정보, 코드 및 종속성 측정값 |
| network.py | 워크스페이스별 검증된 경로; 편집된 상태 및 증거; 텔레톤 전송 옵션 |
| sessions.py | 검토된 Telethon SQLite 스키마의 오프라인 읽기 전용 변환 |
| account_import.py | 지원되는 계정 파일 및 JSON에 대한 인메모리 탐지 및 정규화 |
| tdata.py | 경계가 명확한 최신 TData ZIP 리더, 체크섬/복호화 유효성 검사, 압축 해제 없음 |
| doctor.py | 데이터 수집, 로그인 또는 패키지 설치 없이 수행되는 로컬 준비 상태 확인 |
| download.py | 읽기 횟수가 제한되고 덮어쓰기가 없는 인증된 스트리밍 내보내기 다운로드 |
| monitoring.py | 워크스페이스별 이벤트 정책 및 유형별 첨부 파일 규칙이 검증되었으며, 핸들러, 상태 및 서명된 수신 확인서를 통해 공유됩니다. |
| scope.py | 모니터링 범위(선택한 채팅, 텔레그램 폴더, 전체 계정), 소스 유형, 제외 항목, 재확인 단계 |
| dossier.py | 저장된 기록을 바탕으로 채팅별 사용자 프로필 생성: 기록 참조 정보가 포함된 사실 정보, 아바타 SHA-256/pHash, 멘션 추출 |
| witness_api.py | 읽기 전용 위트니스 토큰 및 이를 통해 가져올 수 있는 서명된 저널 헤더 |
| witness.py | 독립적인 증빙 절차: 자체 키 및 기록부, 헤드 체크, 서명된 채널 게시물, 내보내기 |
| alerts.py | 알림 및 패널의 알림 목록 |
| logging_config.py | 창이 표시되지 않는 방식으로 실행할 때의 콘솔 로깅 및 순환 서버 진단 |
| static/ | 반응형 인터페이스, 로컬 액세스 게이트, 필터, 상세 정보, 내보내기, 계정 설정 |
| demo.py | 실제 수집 데이터와 분리되어 있으며, ‘합성 기록부’로 명확히 표기됨 |
관찰 핸들러는 연결 전에 등록됩니다. 실시간 수집은 활성 클라이언트 ID, 명시적인 실행 상태, 활성화된 소스 또는 관찰 범위(폴더 또는 전체 계정 모드는 첫 번째 업데이트 시 새로운 채팅을 소스로 추가함), 그리고 이벤트 정책에 따라 제어됩니다. 거부되거나 대체된 클라이언트는 실시간 업데이트를 제공할 수 없습니다. 원시 반응 및 멤버십 업데이트는 가시성 제한을 유지합니다. 수신 메시지 콘텐츠와 해당 영구 미디어 작업은 함께 커밋됩니다. 작업은 원본 TL 설명자를 보존하고 그 해시를 서명된 메시지 관찰에 바인딩합니다. 발신자/편집자/삭제자의 의미론은 분리됩니다.
각 워크스페이스는 하나의 계정만 허용하며, 고유한 디렉터리와 서명 식별자를 갖습니다. 호환성을 위해 메인 워크스페이스는 루트에 위치하며, 추가 워크스페이스는 profiles/<id>/에 위치합니다. 하나의 베어러 토큰이 전체 설치를 제어하며, 워크스페이스는 별도의 인증 테넌트가 아닙니다. 프로세스 잠금이 디렉터리를 보호하며, 데이터베이스 잠금은 이벤트 삽입을 순차적으로 처리합니다. 각 추가 작업은 FULL 동기 모드를 사용하여 SQLite WAL에 동기식으로 커밋됩니다. 이벤트 업데이트/삭제 트리거는 일반적인 애플리케이션 수정을 방지하며, 파일 시스템 관리자는 신뢰 경계 내에 머무릅니다.
API 인증은 베어러 토큰 방식입니다. 로그인 작업은 직렬화되며 시간 제한이 적용됩니다. 계정 업로드는 인코딩된 본문 12 MiB, 디코딩된 파일 8 MiB의 전용 제한을 적용하며, 일반 API 요청은 16 KiB 제한을 유지합니다. 변환은 워커 스레드에서 실행되며, 업로드 데이터를 메모리에 보관하고 인증된 브라우저에 정규화된 입력값을 반환합니다. QR 로그인은 워크스페이스별 후보, 단기 유효 식별자, 대기 작업, 및 명시적 취소 기능을 갖추고 있습니다. 승인된 인증만 활성 클라이언트가 됩니다. Telegram FloodWait는 Retry-After 값과 함께 반환되며, 자격 증명 및 원시 RPC 오류 메시지는 API 오류에 노출되지 않습니다. 내보내기 작업은 비동기 이벤트 루프 외부에서 실행되며 워크스페이스별로 직렬화됩니다. 이 작업은 안정적인 읽기 스냅샷을 스트리밍하며, 진행 중인 WAL 쓰기 작업과 공존할 수 있습니다. 워크스페이스 수집기는 프로세스/이벤트 루프를 공유합니다.
현재의 기록 스냅샷과 실시간 업데이트가 중복될 수 있습니다. 두 가지 모두 별도의 관측값으로, 출처별로 라벨이 지정되며, 중복 항목은 자동으로 접히지 않습니다. 누락된 ID, 조작된 삭제된 텍스트, 강제 회원 열거, 또는 자동 그룹 가입에 따른 추론 기능은 구현되지 않았습니다.
운영자용 설명은 수집 방식 및 계정 및 세션 형식을 참조하십시오.
네트워크 구성 정보는 암호화된 볼트에 저장됩니다. 경로를 적용하면 기존 클라이언트가 종료되고 진행 중이던 로그인이 취소되며, 이후 연결에서는 해당 경로를 사용하며 직접적인 대체 경로는 제공되지 않습니다. 새로운 외부 키 설치 시, 마스터 키 파일과 저장된 임의의 솔트(salt)를 사용하여 HKDF-SHA256을 통해 각 작업 공간의 Fernet 키를 생성합니다. 이를 통해 비밀 정보는 데이터 디렉터리에서 별도로 보호되며, 저널/미디어 콘텐츠는 평문으로 저장되지 않습니다.
로컬 데모 항목은 별도로 생성된 프로세스 기능을 사용하며, 설정된 패널 토큰은 절대 사용하지 않습니다. 발급 및 수락에는 명시적인 데모 모드, 추가 작업 공간이 없는 합성 루트 또는 승인된 세션, 루프백 피어/호스트, 프록시 전달 헤더 없음, 크로스 오리진 브라우저 요청 없음이 필요합니다. 실시간 API는 베어러 인증 방식을 유지하며, 데모 모드에서는 수집 변경 사항을 거부합니다.