보안 개요

Clawdbot의 보안 모델과 샌드박스 시스템 설명

🔒 보안 아키텍처

┌─────────────────────────────────────────────────────────────────────┐
│                        외부 위협                            │
│                      (악의적 프롬프트)                   │
└─────────────┬───────────────────────────────────────────────────┘
              │
              ▼
     ┌────────────────┐
     │   보안 계층   │
     └────┬────┬─────┘
          │     │
     ┌────┴────┐  ┌──────┴──────────┐
     │ 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 발신자를 승인하는 메커니즘입니다.

작동 방식

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. 이후 메시지가 정상 처리됨

설정

{
  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	모든 세션 샌드박스	모든 세션

설정

{
  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 제어
    ]
  }
}

샌드박스 동작

// 샌드박스 실행 로직
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 이미지

# 샌드박스 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"

인증 예시

{
  gateway: {
    auth: {
      mode: "password",  // 또는 "token", "none"
      password: "secure-password"  // mode="password" 시 필요
      // 또는
      // token: "auth-token-xyz123"  // mode="token" 시 필요
    }
  }
}

TLS 설정

{
  gateway: {
    tls: {
      enabled: true,
      certPath: "~/.clawdbot/gateway/cert.pem",
      keyPath: "~/.clawdbot/gateway/key.pem",
      caPath: "~/.clawdbot/gateway/ca.pem",  // 선택적
      autoGenerate: true  // 자체 서명 인증서 자동 생성
    }
  }
}

Tailscale 통합

{
  gateway: {
    tailscale: {
      enabled: true,
      allowTailscale: true  // Tailscale IP 자동 인증 허용
    }
  }
}

🔒 권한 시스템

도구 권한

// 도구 권한 체크
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. 권장 설정

{
  // 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. 정기적 보안 점검

# 보안 설정 확인
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"

🔗 관련 문서

•

•

•

•