# 보안

## 개요

Neotask는 보안 우선 아키텍처로 설계되었습니다. 게이트웨이는 기본적으로 localhost에 바인딩되며, 모든 민감한 데이터는 저장 시 암호화되고, 에이전트 실행은 격리된 컨테이너에서 샌드박싱될 수 있습니다.

## 네트워크 보안

### 기본 루프백

게이트웨이는 바인딩 모드를 명시적으로 변경하지 않는 한 `127.0.0.1`(localhost)에서만 수신합니다. 기본적으로 외부 네트워크에 노출되지 않습니다.

### 인증

모든 WebSocket 연결에는 인증이 필요합니다:

- **토큰 인증**, 베어러 토큰 (UUID 또는 커스텀 문자열)
- **비밀번호 인증**, Bcrypt 해시 비밀번호
- **신뢰할 수 있는 프록시**, 리버스 프록시의 사전 인증 헤더
- **로컬 신뢰**, 루프백 연결은 암묵적으로 신뢰됨

### 원격 접근 보안

원격 접근의 경우 권장되는 방법은 **Tailscale VPN** 또는 **SSH 터널링**입니다, 게이트웨이를 인터넷에 직접 노출하지 마세요.

## 기기 페어링

### 페어링 작동 방식

게이트웨이에 연결하는 모든 클라이언트는 페어링되어야 합니다:

1. 기기가 자신의 신원(지문 + 공개 키)을 제시합니다
2. 게이트웨이가 페어링 챌린지(논스)를 발급합니다
3. 기기가 개인 키로 논스에 서명합니다
4. UI를 통해 기기를 승인합니다
5. 게이트웨이가 향후 연결을 위한 기기 토큰을 발급합니다

### 신뢰 모델

- **로컬 기기** (루프백)는 편의를 위해 자동 승인됩니다
- **비로컬 기기**는 명시적인 승인이 필요합니다
- 기기 토큰은 로컬에 저장되며 재연결 시 재사용됩니다
- 기기는 언제든지 취소할 수 있습니다

## 암호화

### 저장 데이터

- **AES-256-GCM**, 모든 토큰, 비밀, API 키는 저장 시 암호화됩니다
- **기기 파생 키**, 기기 ID에서 scrypt를 통해 파생된 암호화 키
- **평문 저장 없음**, 토큰은 평문으로 저장되지 않습니다

### 전송 중 데이터

- **TLS**, API 통신을 위한 HTTPS
- **WSS**, 게이트웨이 연결을 위한 WebSocket Secure (Tailscale Serve 또는 리버스 프록시 사용 시)
- **HMAC 서명**, 논스 및 타임스탬프가 포함된 요청 무결성 검증

## 샌드박싱

### Docker 기반 격리

에이전트 명령 실행은 Docker 컨테이너에서 샌드박싱될 수 있습니다:

- **에이전트별 프로필**, 각 에이전트는 자체 샌드박스 구성을 가질 수 있습니다
- **리소스 제한**, 구성 가능한 CPU, 메모리, 타임아웃 제한
- **네트워크 격리**, 컨테이너를 네트워크 격리할 수 있습니다
- **파일시스템 제한**, 에이전트는 자신의 워크스페이스에만 접근합니다
- **커스텀 이미지**, 특정 도구가 설치된 사전 빌드된 이미지 사용 가능

### 샌드박스 범위

| 범위 | 설명 |
|------|------|
| **세션별** | 각 세션에 대한 새로운 컨테이너 |
| **에이전트별** | 에이전트당 영구 컨테이너 |
| **공유** | 에이전트 간 공유 컨테이너 |

### 워크스페이스 접근

샌드박싱된 에이전트는 자신의 워크스페이스 디렉토리(컨테이너에 마운트됨)에 접근할 수 있지만 워크스페이스 외부의 호스트 파일시스템에는 접근할 수 없습니다.

## 실행 승인

노드와 게이트웨이 호스트에서 에이전트가 실행할 수 있는 명령을 제어합니다:

### 모드

| 모드 | 설명 |
|------|------|
| **허용 목록** | 사전 승인된 명령만 실행 |
| **요청** | 알 수 없는 명령은 사용자 승인 프롬프트 표시 |
| **전체** | 제한 없음 (주의하여 사용) |

### 노드별 구성

각 노드(macOS, 헤드리스 호스트)는 로컬에 저장된 자체 실행 승인 구성을 가집니다. 특정 바이너리(예: `/usr/bin/docker`, `/usr/local/bin/terraform`)를 허용하고 다른 것은 차단할 수 있습니다.

## 상승 모드

일부 작업은 (샌드박스가 아닌) 게이트웨이 호스트에서 직접 실행해야 합니다. 상승 모드는:

- 에이전트 구성의 명시적인 권한에 의해 제한됩니다
- 게이트웨이 호스트에서만 사용 가능합니다
- 기본적으로 비활성화되어 있습니다
- 로깅을 통해 감사 가능합니다

## 보안 감사

내장 보안 감사는 다음을 확인합니다:

- 구성 파일 권한 (600이어야 함)
- 세션 파일 권한
- Node.js 버전 (보안 패치)
- 평문 비밀 감지
- 플러그인 허용 목록 유효성 검사
- 열린 네트워크 인터페이스 감사
- 인증 구성 완전성

감사는 권한이 주어지면 많은 문제를 자동으로 수정할 수 있습니다.

## 모범 사례

1. **게이트웨이를 루프백으로 유지**, 원격 접근에는 Tailscale 또는 SSH 사용
2. **샌드박싱 활성화**, Docker 컨테이너에서 에이전트 명령 실행
3. **실행 허용 목록 사용**, 에이전트가 노드에서 실행할 수 있는 명령 제한
4. **인증 토큰 설정**, 루프백에서도 항상 토큰 인증 구성
5. **에이전트 권한 검토**, 가능한 경우 최소 도구 프로필 사용
6. **Neotask 최신 상태 유지**, 업데이트에 보안 패치 포함
7. **정기적으로 감사**, 보안 감사를 실행하여 잘못된 구성 감지
8. **플러그인 로딩 제한**, 신뢰할 수 있는 플러그인만 설치