# 보안 개요 > Clawdbot의 보안 모델과 샌드박스 시스템 설명 --- ## 🔒 보안 아키텍처 ```javascript ┌─────────────────────────────────────────────────────────────────────┐ │ 외부 위협 │ │ (악의적 프롬프트) │ └─────────────┬───────────────────────────────────────────────────┘ │ ▼ ┌────────────────┐ │ 보안 계층 │ └────┬────┬─────┘ │ │ ┌────┴────┐ ┌──────┴──────────┐ │ DM 페어링 │ │ 샌드박스 │ │ 정책 │ │ (Docker) │ └──────────┘ └─────┬──────────┘ │ ▼ ┌──────────────────────┐ │ 권한 시스템 │ └────────┬───────────┘ │ ┌───────────┼──────────┐ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │ 브라우저│ │ Canvas │ │ 노드 │ │ 자동화 │ │ A2UI │ │ 제어 │ └────────┘ └────────┘ └────────┘ ``` --- ## 🔑 보안 레이어 ### 1. 네트워크 계층 | 위협 | 방어 기법 | 구현 | | --- | --- | --- | | **중간자 공격** | TLS 암호화 | `gateway.tls.enabled` | | **DNS 스푸핑** | Tailscale 통합 | `gateway.tailscale` | | **비인가 접속** | 인증 (password/token) | `gateway.auth.mode` | | **원격 접속** | SSH 터널, 포트 제한 | `gateway.port`, `gateway.bind` | ### 2. 애플리케이션 계층 | 위협 | 방어 기법 | 구현 | | --- | --- | --- | | **악의적 메시지** | DM 페어링 | `channels.*.dmPolicy` | | **그룹 스팸** | 멘션 모드 | `channels.*.groupPolicy.mode` | | **코드 실행 공격** | 샌드박스 격리 | `sandbox.mode` | | **권한 에스컬레이션** | 도구 권한 시스템 | `sandbox.allowlist/denylist` | ### 3. 데이터 계층 | 위협 | 방어 기법 | 구현 | | --- | --- | --- | | **데이터 유출** | 로컬 저장 우선 | 기본 동작 | | **중간 서버 노출** | 직접 LLM 통신 | 기본 동작 | | **메모리 유출** | 세션 격리 | `agents.bindings` | --- ## 🎫 DM 페어링 (Pairing) ### 개요 새로운 DM 발신자를 승인하는 메커니즘입니다. ### 작동 방식 ```javascript 1. 알 수 없는 발신자가 메시지 전송 2. Gateway가 짧은 페어링 코드 생성 예: "pairing-code-ABC123" 3. 발신자에게 코드가 포함된 응답 전송 "알 수 없는 발신자입니다. 페어링 코드: pairing-code-ABC123" 4. 사용자가 CLI에서 승인 clawdbot pairing approve whatsapp pairing-code-ABC123 5. 발신자가 로컬 allowlist에 추가 .clawdbot/channels/whatsapp/allowlist.json: ["+9876543210"] 6. 이후 메시지가 정상 처리됨 ``` ### 설정 ```javascript { channels: { whatsapp: { dmPolicy: "pairing", // 또는 "open" allowFrom: ["+1234567890", "*"] // "*": 모든 연결 허용 }, discord: { dm: { policy: "pairing", allowFrom: ["1234567890123456789", "*"] } } } } ``` ### 장점 - ✅ 알 수 없는 발신자를 방지 - ✅ 페어링 코드로 1회 승인 - ✅ allowlist 관리로 쉬운 접근 제어 - ✅ 여러 발신자 동시 승인 가능 --- ## 🐳 Docker 샌드박스 ### 개요 비-main 세션(그룹, 공개 DM)에서 잠재적인 코드 실행을 방지하기 위해 Docker 컨테이너를 사용합니다. ### 샌드박스 모드 | 모드 | 설명 | 대상 세션 | | --- | --- | --- | | `none` | 샌드박스 비활성화 | 모든 세션 | | `non-main` | 비-main 세션만 샌드박스 | 그룹, 공개 DM | | `all` | 모든 세션 샌드박스 | 모든 세션 | ### 설정 ```javascript { sandbox: { mode: "non-main", allowlist: [ "bash", // 쉘 명령 실행 "process", // 프로세스 정보 "read", // 파일 읽기 "write", // 파일 쓰기 "edit", // 파일 편집 "sessions_list", // 세션 목록 조회 "sessions_history" // 세션 기록 조회 ], denylist: [ "browser", // 브라우저 자동화 "canvas", // 캔버스 제어 "nodes", // 디바이스 노드 "cron", // 크론 작업 "discord", // Discord 액션 "slack", // Slack 액션 "gateway" // Gateway 제어 ] } } ``` ### 샌드박스 동작 ```javascript // 샌드박스 실행 로직 async function runInSandbox(tool: string, params: any, session: Session) { if (session.isMain) { // main 세션은 호스트에서 직접 실행 return await executeTool(tool, params); } // 비-main 세션은 Docker 컨테이너에서 실행 if (!sandbox.allowlist.includes(tool)) { throw new Error(`Tool ${tool} not in allowlist`); } if (sandbox.denylist.includes(tool)) { throw new Error(`Tool ${tool} in denylist`); } // Docker 컨테이너 실행 return await executeInDocker(tool, params, session.workspace); } ``` ### Docker 이미지 ```javascript # 샌드박스 Docker 이미지 (개념) FROM node:22-alpine # 필요한 의존성만 설치 RUN apk add --no-cache git curl bash # 작업 디렉토리 WORKDIR /workspace # 샌드박스 실행 ENTRYPOINT ["node", "/usr/local/bin/clawdbot-sandbox"] ``` ### 장점 - ✅ 호스트 파일 시스템 격리 - ✅ 악의적 코드 실행 방지 - ✅ 리소스 사용 제한 - ✅ 세션별 격리 --- ## 🔐 인증 및 권한 ### Gateway 인증 | 모드 | 설명 | 설정 | | --- | --- | --- | | **password** | 비밀번호 기반 인증 | `gateway.auth.password` | | **token** | 토큰 기반 인증 | `gateway.auth.token` | | **none** | 인증 비활성화 (로컬 전용) | `gateway.auth.mode = "none"` | ### 인증 예시 ```javascript { gateway: { auth: { mode: "password", // 또는 "token", "none" password: "secure-password" // mode="password" 시 필요 // 또는 // token: "auth-token-xyz123" // mode="token" 시 필요 } } } ``` ### TLS 설정 ```javascript { gateway: { tls: { enabled: true, certPath: "~/.clawdbot/gateway/cert.pem", keyPath: "~/.clawdbot/gateway/key.pem", caPath: "~/.clawdbot/gateway/ca.pem", // 선택적 autoGenerate: true // 자체 서명 인증서 자동 생성 } } } ``` ### Tailscale 통합 ```javascript { gateway: { tailscale: { enabled: true, allowTailscale: true // Tailscale IP 자동 인증 허용 } } } ``` --- ## 🔒 권한 시스템 ### 도구 권한 ```javascript // 도구 권한 체크 interface ToolPermission { tool: string; allowed: boolean; reason?: string; } // 권한 검사 로직 function checkPermission(tool: string, session: Session): boolean { if (session.isMain) { return true; // main 세션은 모든 도구 허용 } if (sandbox.mode === 'non-main') { return sandbox.allowlist.includes(tool); } return false; } ``` ### 권한 그룹 | 그룹 | 포함 도구 | 비-Main 허용 | | --- | --- | --- | | **파일** | `read`, `write`, `edit`, `list`, `delete` | ✅ | | **프로세스** | `process`, `bash` | ✅ | | **세션** | `sessions_list`, `sessions_history` | ✅ | | **브라우저** | `browser.*` | ❌ | | **Canvas** | `canvas.*` | ❌ | | **노드** | `camera.*`, `screen.*`, `location.*` | ❌ | | **자동화** | `cron.*`, `webhook.*` | ❌ | | **Gateway** | `gateway.*` | ❌ | | **채널** | `discord.*`, `slack.*` | ❌ | --- ## 🛡 보안 베스트 프랙티스 ### 1. 권장 설정 ```javascript { // Gateway 보안 gateway: { auth: { mode: "password" // 비밀번호 인증 권장 }, tls: { enabled: true, // TLS 활성화 권장 autoGenerate: true }, bind: "loopback" // 루프백만 바인드 권장 }, // 채널 DM 정책 channels: { whatsapp: { dmPolicy: "pairing", // 페어링 권장 groupPolicy: { mode: "mention" // 멘션 모드 권장 } } }, // 샌드박스 sandbox: { mode: "non-main", // 비-main 세션만 샌드박스 denylist: [ // 위험한 도구는 비-Main에서 거부 "browser", "canvas", "nodes", "cron", "discord", "slack", "gateway" ] } } ``` ### 2. 보안 체크리스트 - ✅ [ ] Gateway 인증 활성화되어 있는가? - ✅ [ ] TLS가 활성화되어 있는가? - ✅ [ ] DM 정책이 `pairing`으로 설정되어 있는가? - ✅ [ ] 샌드박스가 활성화되어 있는가? - ✅ [ ] 위험한 도구가 denylist에 있는가? - ✅ [ ] 로그 파일 권한이 제한되어 있는가? ### 3. 정기적 보안 점검 ```javascript # 보안 설정 확인 clawdbot config get gateway.auth.mode clawdbot config get gateway.tls.enabled clawdbot config get channels.*.dmPolicy clawdbot config get sandbox.mode # 로그 검사 clawdbot logs gateway --follow | grep -i "auth\|denied\|error" ``` --- ## 🔗 관련 문서 - [DM 정책 상세](https://dm-policy.md) - [Docker 샌드박스 상세](https://sandbox.md) - [인증 및 권한 상세](https://auth-permissions.md) - [트러블슈팅](https://../usage/troubleshooting.md) For the site tree, see the [root Markdown](https://slashpage.com/techkwon.md).