# 보안 정책

## 지원 범위

보안 수정은 최신 릴리스에만 적용합니다. `0.y.z` 단계이므로 마이너 릴리스에서도 동작이 바뀔 수 있습니다.

| 버전 | 지원 |
|---|---|
| 0.1.x | ✅ |
| 그 이전 | ❌ |

## 취약점 신고

**공개 이슈로 신고하지 마세요.** GitHub 저장소의 **Security → Report a vulnerability**(비공개 취약점 신고)를 사용해 주세요.

가능하면 다음을 포함해 주세요.

- 영향받는 버전과 플랫폼
- 재현 절차 또는 최소 재현 예시
- 원격 실행·경로 매핑·설정 파싱 중 어느 경계가 깨졌는지
- 비밀값은 마스킹하고 실제 토큰·키는 붙이지 않기

48시간 안에 접수 확인, 수정 일정은 심각도에 따라 회신합니다. 수정 전 공개는 삼가 주세요.

## 이 패키지의 위협 모델

이 확장은 **원격 장비에서 셸 명령을 실행**합니다. 따라서 다음을 설계상의 경계로 두고, 그 경계를 깨는 입력은 취약점으로 취급합니다.

- **원격 변경은 2단계 옵트인**: 호스트 설정의 `allowMutating: true` **그리고** 호출의 `allowMutating: true`가 모두 필요합니다. 위험도 분류는 `pi-helper-core`의 `classifyCommand`가 명령 텍스트로 판정합니다.
- **경로 매핑은 fail-closed**: 로컬 cwd가 매핑 루트 밖이면 명령을 실행하지 않고 실패합니다. 엉뚱한 디렉터리에서의 빌드·테스트를 막기 위한 것이므로, 이 검사를 우회하는 경로를 찾으면 취약점입니다.
- **인용**: 모든 경로·인자는 POSIX `sh` 기준으로 인용됩니다(`src/ssh/quote.ts`). 인용을 통과해 셸이 실행되는 입력은 취약점입니다. 단 `ssh_exec`의 `command`는 **사용자가 준 셸 한 줄**이므로 그 자체는 인용 대상이 아닙니다.
- **컨테이너 실행**: `container`가 설정되면 모든 명령이 `docker exec`로 그 컨테이너 안에서 실행됩니다. 이는 원격 사용자의 docker 권한(사실상 root 동등)을 그대로 사용하는 것이므로, 컨테이너 이름은 정규식으로 검증하고 `-w` 경로는 절대 경로만 허용합니다. 컨테이너를 지정하지 않으면 호스트에서 실행됩니다(`ssh_exec` 기본값).
- **비대화형**: `BatchMode=yes`로 비밀번호·호스트키 프롬프트를 즉시 실패시킵니다. 인증은 키/agent에 위임합니다.
- **환경 미전달**: 호출별 overlay만 원격으로 보냅니다(로컬 `PATH` 등은 전달하지 않음).
- **출력 상한**: stdout/stderr는 100KB, 모델 전달은 16KB에서 잘립니다.
- **설정 파일**: `~/.pi/agent/ssh-helper.json`은 사용자 소유 파일이며, 알 수 없는 키와 잘못된 타입은 거부합니다. 특히 `allowMutating: "yes"` 같은 truthy 문자열은 거부합니다.

## 비밀값 취급

- 이 저장소에는 토큰·키·비밀번호를 커밋하지 않습니다. CI는 OIDC(Trusted Publishing)만 사용하며 저장소 시크릿이 필요 없습니다.
- SSH 키 경로(`identityFile`)를 설정에 적을 수는 있지만, **키 내용**은 어디에도 저장하지 않습니다.
- 도구 출력에는 원격 명령의 stdout/stderr가 포함됩니다. 원격에서 비밀을 출력하는 명령을 실행하면 그 값이 모델 컨텍스트로 전달됩니다 — 필요한 경우 원격 측에서 마스킹하세요.