보안 — 실행 전 필독 사항

Collie는 구조상 머신에 대한 원격 셸 접근을 제공합니다. 단 한 번의 Collie API 호출로 임의의 키 입력을 활성 터미널 창에 직접 보냅니다. 해당 URL에 네트워크로 접근할 수 있는 사용자라면 누구나 모든 창(소스 코드, 시크릿, 환경 변수, 에이전트 출력)을 읽고 사용자 권한으로 명령어를 실행할 수 있습니다.

샌드박스나 명령어 허용 목록은 존재하지 않습니다. 명령어를 필터링하면 이 도구의 목적에 맞지 않기 때문입니다. 해당 URL을 루트 로그인처럼 취급하십시오.

위험 모델

주요 보안 경계 및 위험 요인:

• —
  사용자 권한으로 실행됩니다. Collie는 ~/.ssh, git push --force, rm -rf, sudo을 포함한 사용자의 모든 접근 권한을 그대로 상속받습니다.
• —
  인증은 사람이 아닌 기기를 식별합니다. Tailscale은 기기를 사용하는 사람이 아니라 하드웨어 엔드포인트 자체를 검증합니다. 별도의 비밀번호나 사용자 세션이 없으므로, 잠금 해제된 휴대폰이나 도난당한 휴대폰은 열려 있는 셸과 같습니다. 기기를 페어링하여 이 위험을 완화할 수 있습니다(아래). 기본 내장된 유휴 잠금 기능은 방치된 화면을 가릴 뿐 실제 보안 경계를 제공하지는 않습니다(ADR 0007).
• —
  모든 로컬 시스템 사용자가 해당 포트에 접근할 수 있습니다. 표준 터미널 멀티플렉서 소켓(tmux, zellij, herdr)은 파일 시스템 권한을 사용하여 다른 로컬 사용자의 접근을 차단합니다. Collie는 로컬 TCP 포트에서 수신 대기하므로 모든 로컬 UID에 노출됩니다. 페어링이나 기기별 게이트를 통해 쓰기 권한을 제한할 수 있지만, 모든 로컬 사용자가 읽기 작업을 수행할 수 있는 상태로 남습니다. 이는 실행 위험은 줄이지만 데이터 유출은 방지하지 못합니다(ARCHITECTURE.md §6).
• —
  단일 인스턴스가 모든 세션을 노출합니다. 기본적으로 하나의 Collie 프로세스가 샌드박스 세션(다중 세션)을 포함하여 Herdr의 설정 루트 아래에서 검색된 모든 멀티플렉서 세션을 전면에 둡니다.
• —
  쓰기 작업은 <state-dir>/audit.log에 기록됩니다.이며, COLLIE_STATE_DIR이(가) 이를 이동하지 않는 한 ~/.local/state/collie/audit.log에 위치합니다. 서버는 들어오는 모든 키 입력, 응답, 파일 업로드, 창/탭 수명 주기 이벤트를 기록합니다. 감사 로그는 접근 제어가 아니라 사후 가시성을 제공한다는 점에 유의하십시오(ARCHITECTURE.md §6).
• —
  기본 방어 제어. Collie는 엄격하게 루프백 인터페이스에만 바인딩되며, 트래픽을 tailscale serve 또는 이에 상응하는 역방향 프록시를 통해서만 라우팅하고, 엄격한 CSP 규칙, 동일 출처 검사 및 호스트 헤더 유효성 검사를 적용합니다. 창 출력은 innerHTML 대신 React 텍스트 노드로 렌더링됩니다. tailscale funnel을(를) 사용하거나 원시 포트를 외부에 노출하지 마십시오. 특정 하드웨어를 승인하려면 페어링을(를) 직접 사용하거나, 프록시가 기기 ID를 삽입하는 경우 아래 두 개의 COLLIE_DEVICE_* 변수를 사용하십시오.

🚫 Collie와 함께 tailscale funnel을 절대 사용하지 마십시오. Funnel은 트래픽을 공용 인터넷으로 라우팅하는 반면, tailscale serve은 비공개 tailnet으로 접근을 제한합니다. Collie를 Funnel을 통해 실행하는 사용 사례는 지원되지 않습니다.

Tailscale ACL 및 COLLIE_TRUSTED_USER을(를) 사용하여 접근을 추가로 제한하십시오. 어떠한 보증도 없이 있는 그대로 제공됩니다.

머신 외부로 전송되는 데이터

기본적으로 정책상 아무것도 전송되지 않습니다. Collie는 설치 이벤트, 사용 통계, 충돌 보고서, 분석 데이터를 전송하지 않습니다. 이를 활성화하는 플래그도 없습니다.

유일하게 요청 없이 발생하는 아웃바운드 호출은 업데이트 확인입니다. 사용자의 버전과 최신 태그를 비교하는 GitHub 공개 태그 API(bridge/update.ts)로의 익명 HTTPS GET 호출입니다. 사용자나 머신에 대한 데이터는 전송되지 않으며, 정적 사용자 에이전트인 collie-update-check만 포함됩니다.

데이터 수집이 추가되더라도 명시적인 옵트인이 최대 한도입니다. 기본적으로 꺼져 있고, 눈에 띄는 질문으로 확인하며, 플래그나 기본값으로 처리되지 않습니다. 이 약속을 제거하는 것은 주요 변경 사항(ADR 0034)에 해당합니다.

디바이스 페어링: 쓰기 자격 증명

bin/collie pair          # on the host — prints an 8-character code and a QR code, good for 10 minutes

휴대폰에서 Collie를 열고 Settings → Paired devices로 이동한 다음 기기 라벨과 함께 코드를 입력하거나, 명령어로 출력된 QR 코드를 스캔하여 코드가 이미 입력된 해당 화면을 바로 엽니다. 휴대폰에 반환된 토큰이 저장됩니다. Collie는 해시만 보관하며 토큰은 한 번만 표시됩니다. 프로세스를 다시 시작할 필요는 없습니다. 실행 중인 데몬이 다음 요청 시 페어링 및 철회를 바로 적용합니다.

두 가지 디바이스 게이트는 서로 다른 질문을 다루며, 하나만 사용하거나 둘 다 사용하거나 둘 다 사용하지 않을 수 있습니다.

페어링에는 추가 인프라가 필요하지 않습니다. 헤더를 삽입할 프록시가 없는 직접 tailscale serve 설정에 적합합니다.

두 옵션 모두 쓰기 접근만 제한합니다. 동일 출처 확인(same-origin check)을 통과하는 대상에는 읽기 요청이 계속 열려 있습니다.

bin/collie devices list             # what holds a credential, and when each was last seen
bin/collie devices revoke old-phone # effective immediately, no restart

쓰기 제한은 하나 이상의 기기가 페어링되어 있을 때만 활성화됩니다. collie pair을(를) 실행하기 전까지는 페어링된 기기가 없으므로, 그전까지는 읽기 및 쓰기 작업이 기존과 동일하게 작동합니다. 먼저 현재 사용하는 스마트폰을 페어링하십시오. 마지막 기기의 등록을 취소하면 잠금 상태가 되는 것을 방지하기 위해 제한이 다시 비활성화됩니다.

코드를 5회 잘못 입력하면 코드가 무효화되며, collie pair을(를) 다시 실행해야 합니다.

여러 인스턴스를 실행하는 호스트에서는 명령어 앞에 COLLIE_INSTANCE=<name>을 붙이고 휴대폰에서 해당 인스턴스 URL을 여십시오 (단일 호스트에서의 다중 Collie 인스턴스).