# Telegram · 접근 및 권한

Canonical page: https://phishdestroy.io/tgwitness/ko/docs/reference/access/

계정 및 채팅에 대한 접근 권한을 제한하고, 권한을 선택하며, 세션 및 IP 주소를 제한하고, 접근 권한을 철회할 수 있습니다.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/ko/llms.txt)

계정 및 채팅에 대한 접근 권한을 제한하고, 권한을 선택하며, 세션 및 IP 주소를 제한하고, 접근 권한을 철회할 수 있습니다.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [문서](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [시작하기](https://phishdestroy.io/tgwitness/ko/docs/reference/quickstart/)

![시작하기](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

검토자에게는 하나의 채팅에 대한 접근 권한을, 분석가에게는 사건 내역 내보내기 권한을, 운영자에게는 선택된 계정에 대한 관리 권한을 부여할 수 있습니다. 각 사용자는 고유한 토큰을 부여받습니다. 메인 패널 토큰은 관리자가 보유합니다.

[계정 설정](https://phishdestroy.io/tgwitness/ko/docs/reference/accounts/) · [연결 경로](https://phishdestroy.io/tgwitness/ko/docs/reference/connection/) · [보안 모델](https://phishdestroy.io/tgwitness/ko/docs/reference/security/)

## 두 가지 범위, 두 가지 서로 다른 업무

**수집 범위에** 따라 계정이 기록하는 대상(선택한 채팅, 텔레그램 폴더 또는 전체 계정)이 결정됩니다. **접근 범위에** 따라 다른 사람이 기록된 계정 및 채팅 중 어떤 것을 보고 사용할 수 있는지가 결정됩니다. 접근 권한을 부여한다고 해서 텔레그램 채팅에 참여하거나, 수집이 시작되거나, 텔레그램 계정 권한이 부여되는 것은 아닙니다.

접근 권한을 통해 선택한 워크스페이스, 그 안의 선택한 채팅, 모든 워크스페이스, 또는 [계정](https://phishdestroy.io/tgwitness/ko/docs/reference/accounts/#bulk-import-and-account-groups)그룹의 모든 계정에 접근할 수 있습니다. **모든 워크스페이스( 나중에 추가된 워크스페이스 포함)**는 향후 추가될 계정도 포함합니다. 그룹 접근 권한 또한 나중에 해당 그룹에 추가되는 계정을 포함합니다. 케이스를 특정 워크스페이스로만 제한해야 할 경우에는 해당 워크스페이스를 명시적으로 선택하십시오.

## 사용자 접근 권한 부여

1. 주 관리자로 로그인한 후 **‘추가 도구’ → ‘액세스’를** 엽니다.
2. **'사용자 접근 권한 부여**' 항목에서 로그에서 쉽게 알아볼 수 있는 이름을 입력하세요.
3. 작업 공간을 선택하고, 필요한 경우 개별 채팅방을 선택하십시오.
4. 이 사람이 수행할 수 있는 작업을 선택하십시오. **‘보기’는** 항상 포함됩니다.
5. 필요에 따라 만료 기간, 로그인/세션 제한 및 허용된 주소를 설정하십시오.
6. **'생성'을** 클릭하여 **액세스 권한을 생성하세요**. 토큰을 지금 복사하세요: 토큰은 한 번만 표시됩니다.
7. 패널 주소와 토큰을 비공개로 전송하십시오. 수신자는 일반 로그인 페이지에서 해당 토큰을 입력하면 되며, 귀하의 메인 패널 토큰이나 텔레그램 세션은 필요하지 않습니다.

발급된 토큰이 포함된 패널을 별도의 브라우저 세션에서 열고, 전달하기 전에 표시된 채팅과 허용된 작업을 확인하십시오.

액세스 이름은 암호화된 로컬 스토리지에 남아 있으며 관리자 패널을 통해 확인됩니다. 새로운 액세스 및 작업 공간 생성 감사 기록에서는 이름이 생략되며, 기존 서명된 기록은 원래 필드를 유지합니다.

## 권한 선택

텍스트 전용 공개 데모를 진행하려면 일반 리뷰어 액세스 대신 **‘공개 쇼케이스’를** 사용하십시오. 이 기능은 명시적으로 선택된 공개 채널, 보존된 수정 및 삭제 내역, 서명된 통계를 표시하며, 작성자 필드는 가려지고 파일은 API 경계에서 차단됩니다. [쇼케이스를 생성하고 확인하십시오](https://phishdestroy.io/tgwitness/ko/docs/reference/showcase/).

| 사용 권한 | 이 도구의 기능 |
| --- | --- |
| `view` | 허용된 채팅, 캡처된 메시지, 프로필, 파일 및 필터링된 기록부를 확인할 수 있습니다. 항상 포함되어 있습니다. |
| `export` | 허용된 채팅 기록 및 자료 모음을 내보낼 수 있습니다. 전체 작업 공간의 증거 자료를 내보내려면 해당 작업 공간 전체에 대한 접근 권한이 필요합니다. |
| `sources` | 소스, 스냅샷 및 프로필 캡처를 관리합니다. 채팅 제한 액세스는 허용된 채팅에서만 작동하며, 계정 전체의 소스 검색 및 범위 설정은 비활성화된 상태로 유지됩니다. |
| `collect` | 수집기를 시작하거나 중지합니다. 수집 작업이 계정에 영향을 미치므로 전체 작업 공간에 대한 접근 권한이 필요합니다. |
| `interact` | 접근 권한 범위 내에서 지원되는 텔레그램 상호작용을 수행하십시오. 채팅 제한 접근 권한의 경우 계정 전체 링크 미리보기를 사용할 수 없습니다. |
| `settings` | 수집 설정, 타임스탬프, 알림, 외부 백업 및 매개변수를 변경할 수 있습니다. 전체 워크스페이스에 대한 접근 권한이 필요합니다. |
| `account` | 텔레그램에 로그인하거나 로그아웃하고 연결 경로를 관리할 수 있습니다. 전체 작업 공간에 대한 접근 권한이 필요합니다. |
| `board.read` | 허용된 작업 공간 및 채팅 내에서만 케이스 보드 메모를 읽으십시오. |
| `board.write` | 북마크, 하이라이트, 슬라이스, 주석 및 열기/검토 상태를 추가할 수 있습니다. 또한 ``board.read``가 필요합니다. |
| `board.manage` | 컬렉션, 최종 팀 상태 및 다른 참가자의 카드를 관리합니다. 또한 보드에 대한 읽기/쓰기 권한이 필요합니다. |

주 관리자만이 오프사이트 복제본 복구 키를 다운로드할 수 있습니다. 위임된 `settings` 또는 `account` 접근 권한으로는 해당 키를 얻을 수 없습니다.

권한과 적용 범위는 함께 확인됩니다. 특정 권한을 선택한다고 해서 다른 채팅이 열리거나, 채팅 제한형 액세스 권한에 대해 워크스페이스 전체에 적용되는 작업이 활성화되지는 않습니다. 병렬 내보내기의 경우, 선택한 모든 계정에서 내보내려는 채팅에 대한 접근 권한이 포함되어야 합니다. 부여된 접근 권한으로는 새로운 접근 권한을 생성하거나, 타인의 세션을 관리하거나, 관리자 콘솔을 열 수 없습니다.

### 세 가지 유용한 설정 방법

| 인물 | 범위 | 권한 |
| --- | --- | --- |
| 검토자 | 한 사례의 기록된 채팅 내용 | `view` |
| 업무 인계를 준비 중인 분석가 | 조사 및 내보내기 대상 채팅 | `view`, `export`; 텔레그램을 통해 조치를 취해야 하는 경우에만 `interact`를 추가하십시오. |
| 수집 운영자 | 선별된 전체 작업 공간 | `view`, `sources`, `collect`; 필요한 경우에만 `settings` 또는 `account`를 추가하십시오. |

Access 양식의 초기 사전 설정에는 케이스 보드도 포함됩니다: 검토자는 읽기 권한, 분석가는 읽기 및 쓰기 권한, 운영자는 관리 권한을 가집니다. 사전 설정은 계속 편집 가능하며, 기존 권한은 자동으로 확장되지 않습니다. 상속된 채팅 범위 및 내보내기 개인정보 보호 설정에 대해서는 [케이스 보드를](https://phishdestroy.io/tgwitness/ko/docs/reference/case-board/) 참조하십시오.

## 제한 사항 및 세션

| 설정 | 작동 원리 |
| --- | --- |
| 병행 세션 | 동시 세션 수를 1~100개로 제한합니다. 한도에 도달하면 다음 로그인을 거부하거나 가장 오래된 세션을 종료합니다. |
| 로그인 허용 | 세션 시작을 위한 토큰의 사용 횟수를 제한합니다. 허용된 마지막 로그인이 사용되었다고 해서 기존 세션이 종료되지는 않습니다. |
| 유효 기간: | 접근 권한에 대한 절대 만료일이 적용됩니다. 만료된 접근 권한으로는 로그인하거나 요청을 계속할 수 없습니다. |
| 활동이 없는 시간 | 세션 비활성 타임아웃은 5분에서 30일까지 설정 가능합니다. 요청이 성공하면 타임아웃 시간이 연장되며, 열려 있는 패널은 폴링을 통해 활성 상태를 유지할 수 있습니다. |
| 허용된 주소 | 특정 IP 주소 또는 CIDR 서브넷을 허용합니다. 첫 로그인 바인딩이 활성화되지 않은 경우, 빈 상태로 두면 모든 주소를 허용합니다. |
| 첫 로그인 시 연결 | 첫 번째 성공적인 로그인 시 해당 접속에 허용된 주소가 확정됩니다. |

IP는 애플리케이션이 인식하는 클라이언트 주소입니다. 리버스 프록시나 터널을 사용하는 경우, IP 규칙을 적용하기 전에 **‘열린**세션’에 표시된 주소를 확인하십시오. 그렇지 않으면 여러 사용자가 프록시의 주소를 공유하는 것처럼 보일 수 있습니다.

## 변경 또는 접근 권한 철회

**'접근 권한 부여**' 항목에서 항목을 편집하여 적용 범위, 권한 또는 제한 사항을 변경할 수 있습니다. 적용 범위 및 권한 변경 사항은 이후 요청 시 확인되며, 여기에는 이미 열려 있는 세션에서 발생하는 요청도 포함됩니다. 접근 권한을 취소하면 해당 세션이 종료되고 발급된 토큰은 더 이상 사용할 수 없게 됩니다. 또한 관리자는 **'열린 세션' 기능을** 통해 전체 접근 권한을 취소하지 않고도 개별 세션을 종료할 수 있습니다.

저장된 내보내기 사본은 작성자, 작업 공간, 채팅 범위 및 필요한 권한 정보를 유지합니다. 부여된 접근 권한은 해당 권한이 유효한 기간 동안에만 자신의 사본을 열람하거나 다운로드할 수 있습니다. 케이스 보드가 포함된 사본의 경우 다음 사항도 필요합니다 `board.read`. 관리자는 모든 사본을 검색할 수 있습니다. 이 메타데이터와 그룹 번들이 포함되지 않은 오래된 사본은 관리자만 접근할 수 있습니다. 다운로드 티켓 및 준비된 파일 응답은 파일을 준비한 후, 데이터를 전송하기 전에 접근 권한을 재확인합니다. 관리자를 포함한 각 사용자는 작업 공간당 10개의 보류 중인 다운로드 티켓을 보유할 수 있으며; 작업 공간 전체 한도는 1,000개입니다. 티켓은 120초 후에 만료되며 1회용입니다.

권한 취소 기능으로는 사용자가 이미 다운로드한 파일을 복구할 수 없습니다. 로그아웃, 패널 잠금 또는 세션 종료는 실행 중인 수집기를 중지시키지 않습니다.

## 관리자가 확인할 수 있는 내용

검토자와 분석가는 프록시 엔드포인트, 풀 진단 정보, 서버 경로 또는 원시 연결 오류가 포함되지 않은 수집 진행 상황을 수신합니다. 연결 진단 기능을 사용하려면 전체 작업 공간에 대한 `account` 권한이 필요합니다. 알림 읽기, 오프사이트 복사 및 매개변수 설정에는 `settings` 권한이 필요합니다.

브라우저의 전체 User-Agent 문자열은 액세스 세션에 보존되지 않습니다. 또한 업그레이드 시 변경 가능한 세션 캐시에서도 해당 문자열이 제거됩니다. 패널 프로세스 로그는 IP 리터럴, URL 자격 증명 및 라벨이 지정된 비밀 정보를 가립니다. 로컬 서비스 로그와 이전에 서명된 저널 기록은 재작성되지 않습니다. 액세스 규칙 및 서명된 로그인 기록은 여전히 클라이언트 주소를 사용합니다.

### 주 키를 교체하십시오

**‘도구 더 보기 → 액세스 → 내 제한 사항 → 관리자 키 재발급’을** 사용하거나, 패널이 실행 중인 동안 관리형 설치 환경에서 `tgwitness token rotate`를 실행하십시오. 동료 토큰으로 열린 세션을 포함하여 모든 기존 브라우저 세션이 종료됩니다. 요청한 브라우저는 새로운 세션을 받게 되며, 새로운 관리자 키를 숨기기 전에 저장하십시오. 발급된 동료 토큰은 별도로 취소될 때까지 유효합니다. `TGWITNESS_TOKEN`를 사용하는 설치 환경은 해당 환경 설정을 변경하고 다시 시작해야 합니다.

### 요청 및 프록시 경계

이 API는 클라이언트 및 인증 정보 그룹(패널, 아카이브/MCP 또는 위트니스)당 분당 최대 600건의 요청을 허용합니다. 인증 대기 시간은 각 그룹별로 별도로 적용됩니다. 1분 이내에 인증이 10회 거부되면 1초부터 최대 5분까지의 지수적 대기 시간이 시작됩니다. 대기 시간 이후 인증 시도가 실패하면 대기 시간이 연장되며, 10분 동안 실패한 시도가 없으면 대기 시간 연장이 초기화됩니다. 인증 거부 시 HTTP 429가 반환되며 `Retry-After`. 제한은 메모리 내에 저장되며, 하나의 패널 프로세스 내 워크스페이스 간에 공유됩니다. 프로세스를 재시작하면 제한이 초기화됩니다. 라이브 스트림은 베어러 토큰당 4개, 패널 프로세스당 32개로 제한됩니다. 스트림을 열면 API 요청 할당량도 소모됩니다.

요청 본문의 수신 마감 시간은 60초이며, 로그인, 데모 액세스, 아카이브 API 및 witness-head 경로의 경우 10초로, MCP 전송의 경우 8초로 단축됩니다. 각 애플리케이션은 클라이언트 주소당 4개의 미완성 본문을 허용하며, 전체 예약된 경로 허용량은 32 및 64 MiB로 제한됩니다. 본문이 없는 요청은 이러한 슬롯을 소모하지 않습니다. 크기 제한을 초과한 본문은 413을 반환하고, 시간 초과된 본문은 408을 반환하며, 클라이언트 용량 초과 시 429를 반환하며 `Retry-After: 1`. 전체 본문 용량이 소진된 경우 503을 반환하며 `Retry-After`.

실제 TCP 피어가 `TGWITNESS_TRUSTED_PROXIES`(쉼표로 구분된 IP 또는 CIDR)에 속하지 않는 한, 전달된 IP 헤더는 무시됩니다. `TGWITNESS_PROXY_HEADER`를 `x-forwarded-for` 또는 `cf-connecting-ip`로 설정하십시오. XFF는 가장 가까운 프록시에서 첫 번째 신뢰할 수 없는 피어 방향으로 추적됩니다. 형식이 잘못되었거나 중복된 신뢰할 수 있는 주소 메타데이터는 거부되므로, 허용 목록에 등록된 프록시 주소를 상속받을 수 없습니다. 관리형 퀵 터널은 로컬 Cloudflare 커넥터를 신뢰하며, 자체 도메인 설정은 로컬 Caddy를 신뢰합니다. 직접 배포 환경은 기본적으로 프록시를 신뢰하지 않습니다. Uvicorn을 직접 실행하는 경우, 이 경계가 실제 피어를 수신할 수 있도록 Uvicorn의 프록시 헤더 처리를 비활성화하십시오.

`TGWITNESS_PANEL_ALLOWED_IPS`는 관리자를 포함한 모든 패널 액세스를 나열된 IP 또는 CIDR로 제한합니다. 설치 프로그램의 라우팅 식별 프로브는 공개 상태로 유지되며 계정 데이터를 반환하지 않습니다. 허용 목록을 활성화하기 전에 필요한 로컬 관리 경로를 포함하십시오. 관리형 설치의 **START-HERE** 가이드에는 서비스 구성 및 복구 지침이 포함되어 있습니다.

API `ws` 쿼리 선택자는 요청 경로에서 작업 공간을 식별해야 하며, 알 수 없거나 일치하지 않거나 중복된 선택자는 404 오류로 거부됩니다.

패널 스크립트와 스타일에는 SHA-384 무결성 메타데이터가 포함됩니다. 임포트 맵은 또한 import-map 무결성을 지원하는 브라우저에서 로컬로 임포트된 JS 모듈도 포함합니다. 동적으로 생성된 언어 응답은 별도로 처리됩니다. 이러한 검사는 전송된 페이지에 대한 자산 대체 여부를 감지합니다. 페이지 자체와 해당 해시는 패널 서버에서 제공되므로, 해당 서버와 전송 경로를 보호해야 합니다.

**시작 시점부터 기록된** 로그에는 모든 워크스페이스의 프로세스 로그와 저널 활동(로그인, 거부, 경로 변경 및 운영자 조치 등)이 결합되어 있습니다. 이는 현재 프로세스에 대한 인메모리 콘솔이며, 모든 메시지의 영구적인 사본은 아닙니다. 빈번하게 발생하는 메시지 이벤트는 콘솔을 채우지 않고 저널에 남게 됩니다.

접근 권한의 발급, 변경 및 취소, 세션 시작 또는 종료 시에도 서명된 `access.*` 저널 기록이 생성됩니다. 토큰은 해당 기록에 포함되지 않습니다. 발급된 토큰과 세션 인증 정보는 암호화된 볼트에 해시 형태로 보관됩니다.

보류 중인 QR 로그인은 이를 시작한 패널 세션에 속합니다. 해당 세션을 종료하거나 취소하거나, 메인 패널 토큰을 회전시키면 서버에서 보류 중인 QR 클라이언트가 취소됩니다. 이는 브라우저가 자체 취소 요청을 보낼 수 없는 경우에도 적용됩니다. 토큰 회전 시 메인 패널 토큰으로 직접 시작된 QR 로그인도 취소됩니다. 다른 작업을 대기 중인 QR 요청은 시작 전에 다시 한 번 액세스 권한을 확인합니다. 완료된 텔레그램 인증 및 다른 패널 세션에서 시작된 보류 중인 로그인은 유지됩니다.

****주 관리자 및 신뢰 경계****

메인 패널 토큰에는 제한이 없습니다. 이 토큰을 사용하여 브라우저에 로그인하면 관리자가 설정한 세션 제한에 따라 세션이 생성됩니다. 메인 토큰을 직접 전송하는 스크립트는 전체 액세스 권한을 유지하며 브라우저 세션으로 집계되지 않습니다.

이는 단일 설치 환경 내의 애플리케이션 수준 접근 제어입니다. 모든 작업 공간은 서버 프로세스를 공유하며, 이는 호스트 관리자로부터의 격리를 의미하지 않습니다. 메인 토큰, 텔레그램 세션, 서명 키 및 데이터 디렉터리는 비공개로 유지하십시오. 위트니스 토큰은 패널 액세스 토큰이 아닌, 별도의 체크포인트/상태 인증 정보입니다.
