Security on Yarang's Tech Lair

[MicroVM] Firecracker를 활용한 고립형 샌드박스 구축 가이드

Sat, 27 Jun 2026 09:01:26 +0900

[MicroVM] Firecracker를 활용한 고립형 샌드박스 구축 가이드

최근 MicroVM 기술이 주목받고 있습니다. 전통적인 컨테이너(Docker 등)는 커널을 호스트와 공유하기 때문에 보안 격리(Isolation) 측면에서 완벽하다고 할 수 없습니다. 반면, AWS의 Firecracker와 같은 MicroVM은 가벼운 가상머신을 제공하여 ‘컨테이너의 속도’와 ‘VM의 보안’을 동시에 잡을 수 있습니다.

이번 글에서는 Rust 기반 에이전트 런타임인 ZeroClaw의 통신 프로토콜 설계 과정에서 고려한 Firecracker MicroVM을 사용하여, 신뢰할 수 없는 코드를 안전하게 실행하는 방법을 실용적인 코드와 함께 소개합니다.

왜 MicroVM인가?

기존의 블로그 API 서버나 MCP(Model Context Protocol) 클라이언트 개발에서는 주로 컨테이너 환경을 사용했습니다. 하지만 멀티 에이전트 시스템이나 외부 코드를 실행해야 하는 환경에서는 보안이 더욱 중요해집니다.

단일 프로세스 격리: 각 MicroVM은 독립적인 커널 공간을 가집니다.
빠른 부팅: 밀리초 단위의 부팅 시간으로 컨테이너와 유사한 속도를 냅니다.
리소스 제한: CPU 및 메모리 사용량을 엄격하게 제한할 수 있습니다.

사전 준비 사항

이 가이드를 따라하려면 Linux 환경(KVM 활성화)과 Rust 툴체인이 필요합니다. Firecracker는 Linux KVM(Kernel-based Virtual Machine) 위에서 동작합니다.

# KVM 권한 확인
ls -la /dev/kvm
# 그룹에 추가 (권한이 없는 경우)
sudo usermod -aG kvm $USER

1. Firecracker 다운로드 및 준비

Firecracker는 단일 바이너리로 제공되어 배포가 매우 간편합니다.

cd /tmp
curl -L -o firecracker-v1.9.1 https://github.com/firecracker-microvm/firecracker/releases/download/v1.9.1/firecracker-v1.9.1-x86_64
chmod +x firecracker-v1.9.1
mv firecracker-v1.9.1 firecracker

2. MicroVM 부팅을 위한 루트 파일시스템 생성

MicroVM을 실행하려면 간단한 Linux 커널과 루트 파일시스템(이미지)이 필요합니다. 테스트를 위해 Ubuntu 이미지를 다운로드하겠습니다.

# 작업 디렉토리 생성
mkdir -p fc-demo
cd fc-demo

# Ubuntu 22.04 루트 파일시스템 다운로드
wget https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64-root.tar.xz

# 이미지 변환 (raw 형식)
xz -d ubuntu-22.04-server-cloudimg-amd64-root.tar.xz

3. Rust로 제어 로직 작성하기

이제 Rust를 사용하여 Firecracker 인스턴스를 구동하고, 네트워크를 설정하며, 요청을 보내보겠습니다. serde_json을 사용하여 설정을 JSON으로 전달하는 방식이 가장 일반적입니다.

Cargo.toml dependencies:

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
reqwest = { version = "0.12", features = ["blocking"] }

Rust 구현 코드 (main.rs):

use std::fs::{self, File};
use std::io::Write;
use std::process::{Command, Stdio};
use serde::Serialize;

// Firecracker 설정 구조체
#[derive(Serialize)]
struct BootSource {
 kernel_image_path: String,
 boot_args: String,
}

#[derive(Serialize)]
struct Drive {
 drive_id: String,
 path_on_host: String,
 is_root_device: bool,
 is_read_only: bool,
}

#[derive(Serialize)]
struct MachineConfig {
 vcpu_count: u8,
 mem_size_mib: u64,
 ht_enabled: bool,
}

#[derive(Serialize)]
struct NetworkInterface {
 if_id: String,
 guest_mac: String,
 host_dev_name: String,
}

fn main() {
 // 1. 작업 디렉토리 설정
 let vm_id = "my-first-microvm";
 fs::create_dir_all(format!("/tmp/fc-demo/{}", vm_id)).expect("Failed to create vm dir");

 // 2. Firecracker 프로세스 실행 (백그라운드)
 // 실제 환경에서는 데몬으로 관리하거나 API를 통해 소켓을 생성합니다.
 // 여기서는 간단히 API 서버를 소켓으로 실행한다고 가정하고 설정을 전송합니다.
 
 // 주의: 실제 실행하려면 커널 이미지(vmlinux)가 필요합니다. 
 // AWS Firecracker GitHub 릴리즈에서 다운로드 가능합니다.
 let kernel_path = "/tmp/fc-demo/vmlinux"; // 경로 확인 필요
 let rootfs_path = "/tmp/fc-demo/ubuntu-22.04-server-cloudimg-amd64-root.tar";

 // (실제 튜토리얼에서는 네트워크 설정이 복잡하므로 TAP 디바이스 생성 생략)
 // API 설정 생성 예시
 let boot_config = BootSource {
 kernel_image_path: kernel_path.to_string(),
 boot_args: "console=ttyS0 reboot=k panic=1 pci=off".to_string(),
 };

 let drive_config = Drive {
 drive_id: "rootfs".to_string(),
 path_on_host: rootfs_path.to_string(),
 is_root_device: true,
 is_read_only: false,
 };

 // JSON 파일로 설정 저장 (Firecracker는 HTTP API나 JSON 파일 입력을 받음)
 let config_json = serde_json::to_string_pretty(&vec![&boot_config, &drive_config]).unwrap();
 let mut file = File::create(format!("/tmp/fc-demo/{}/vm_config.json", vm_id)).unwrap();
 file.write_all(config_json.as_bytes()).unwrap();

 println!("MicroVM 설정 완료: {}", vm_id);
 println!("Firecracker는 보통 TAP 네트워크와 마운트 설정이 필요합니다.");
 println!("CLI 사용법 예시:");
 println!("./firecracker --api-sock /tmp/fc-demo/{}/api.sock", vm_id);
 println!("이후 curl을 통해 http://localhost/... 로 설정을 전송합니다.");
}

4. 실행 및 제어 (CLI 방식)

Rust 코드로 자동화하는 것이 이상적이지만, 개발 단계에서는 CLI로 직접 제어하며 동작을 확인하는 것이 좋습니다.

# 1. TAP 네트워크 인터페이스 생성 (호스트와 게스트 연결용)
sudo ip tuntap add tap0 mode tap
sudo ip addr add 169.254.0.1/30 dev tap0
sudo ip link set tap0 up

# 2. Firecracker 실행 (API 소켓 모드)
./firecracker --api-sock /tmp/fc-demo/my-api.sock &

# 3. 부팅 소스 설정 전송
curl --unix-socket /tmp/fc-demo/my-api.sock -i \
 -X PUT 'http://localhost/boot-source' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
 "kernel_image_path": "/path/to/vmlinux",
 "boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
 }'

# 4. 마운트 설정 전송
curl --unix-socket /tmp/fc-demo/my-api.sock -i \
 -X PUT 'http://localhost/drives/rootfs' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
 "drive_id": "rootfs",
 "path_on_host": "/path/to/rootfs.ext4",
 "is_root_device": true,
 "is_read_only": false
 }'
 
# 5. 인스턴스 시작
curl --unix-socket /tmp/fc-demo/my-api.sock -i \
 -X PUT 'http://localhost/actions' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{ "action_type": "InstanceStart" }'

결론 및 ZeroClaw 적용 계획

위에서 살펴본 것처럼 MicroVM은 강력한 격리성을 제공합니다. ZeroClaw 프로젝트의 ‘멀티 에이전트 아키텍처’에서 이 기술은 매우 유용합니다. 각 에이전트가 수행하는 작업(예: 파일 시스템 접근, 외부 네트워크 요청)을 독립된 Firecracker 인스턴스 내에서 실행하게 하여, 시스템 전체의 안정성을 해치지 않고 ‘신뢰할 수 없는 플러그인’을 실행할 수 있게 됩니다.

다음 포스트에서는 이 MicroVM 위에서 동작하는 에이전트 간의 통신을 어떻게 최적화할지에 대해 다루겠습니다.

참고자료

Firecracker GitHub
[MicroVMs: Run isolated sandboxes with full lifecycle control](Hacker News Link)
[ZeroClaw 아키텍처 설계문서](내부 블로그 링크)

Zero-Touch OAuth 구현을 위한 MCP 인증 아키텍처 설계

Fri, 19 Jun 2026 09:00:58 +0900

최근 ‘Zero-Touch OAuth for MCP’라는 흥미로운 기술 트렌드를 접했습니다. 우리가 개발 중인 ZeroClaw 런타임과 blog-api-server의 MCP(Model Context Protocol) 통합 과정에서, 사용자 경험을 저해하지 않으면서도 보안성을 확보하는 것은 필수적인 과제입니다. 이번 포스트에서는 별도의 복잡한 설정 없이 사용자가 MCP 클라이언트를 연결할 수 있도록 돕는 ‘Zero-Touch’ 인증 흐름을 설계하고, 이를 실제 코드로 구현하는 방법을 살펴보겠습니다.

왜 Zero-Touch인가?

기존의 OAuth 2.0 흐름은 사용자에게 ‘Client ID’와 ‘Client Secret’을 발급받아 설정 파일에 입력하도록 요구하곤 했습니다. 하지만 일반 사용자나 개발자에게 이는 큰 진입 장벽입니다. Zero-Touch OAuth는 클라이언트가 사전에 등록된 정보(Pre-registered metadata)를 통해 자동으로 인증을 시도하고, 사용자는 단순히 ‘허용’ 버튼만 누르면 되는 흐름을 지향합니다.

아키텍처 설계

우리는 blog-api-server를 MCP Provider로, Claude Code나 커스텀 클라이언트를 MCP Consumer로 구성합니다. 핵심은 PKCE (Proof Key for Code Exchange) 확장을 사용하여 Secret을 저장하지 않는 Public Client 환경을 구축하는 것입니다.

핵심 구성 요소:

MCP Client (Consumer): 사용자의 로컬 환경에서 실행되는 에이전트입니다.
Auth Server: blog-api-server 내에 구현된 OAuth2 인증 서버입니다.
Resource Server: 실제 블로그 API입니다.

구현 단계 1: 서버 사이드 (blog-api-server)

먼저, Rust 기반의 blog-api-server에 간단한 인증 엔드포인트를 추가해야 합니다. 이전 글인 *’[blog-api-server] MCP 블로그 클라이언트 언어 파라미터 추가’*에서 언급된 아키텍처를 확장하여 Auth 모듈을 독립시킵니다.

여기서는 핵심 로직인 코드 검증(Verification) 로직을 보여드리겠습니다. 클라이언트로부터 받은 code_verifier를 검증하는 과정입니다.

// blog-api-server/src/auth/handler.rs
use axum::{extract::State, Json};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use base64::Engine as _;

#[derive(Deserialize)]
pub struct TokenRequest {
 pub code: String,
 pub code_verifier: String, // PKCE를 통해 클라이언트가 생성한 난수
 pub redirect_uri: String,
}

#[derive(Serialize)]
pub struct TokenResponse {
 pub access_token: String,
 pub token_type: String,
 pub expires_in: u64,
}

pub async fn exchange_token(
 State(state): State<AppState>,
 Json(payload): Json<TokenRequest>,
) -> Result<Json<TokenResponse>, String> {
 // 1. DB에서 Authorization Code 조회
 let auth_record = state.db.get_auth_code(&payload.code)
 .await
 .map_err(|_| "Invalid code".to_string())?;

 // 2. PKCE Challenge 검증 (핵심 보안 로직)
 let mut hasher = Sha256::new();
 hasher.update(payload.code_verifier.as_bytes());
 let hashed_verifier = hasher.finalize();
 let encoded_verifier = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(hashed_verifier);

 if encoded_verifier != auth_record.code_challenge {
 return Err("Code verifier mismatch".to_string());
 }

 // 3. Access Token 발급
 let access_token = generate_jwt(&state.secrets, &auth_record.user_id);

 Ok(Json(TokenResponse {
 access_token,
 token_type: "Bearer".to_string(),
 expires_in: 3600,
 }))
}

이 코드는 클라이언트가 보내온 code_verifier를 해싱하여, 처음 인증 요청을 보낼 때 생성된 code_challenge와 일치하는지 확인합니다. 이 과정이 ‘Zero-Touch’를 보안적으로 가능하게 만드는 핵심입니다.

구현 단계 2: 클라이언트 사이드 (MCP Client)

이제 클라이언트는 사용자 개입 없이(혹은 최소한의 개입으로) 토큰을 발급받을 수 있습니다. Python을 사용한 MCP 클라이언트 예제를 작성해보겠습니다.

import hashlib
import base64
import requests
from urllib.parse import urlencode

# Zero-Touch 설정 (하드코딩 혹은 환경 변수)
CLIENT_ID = "zeroclaw-mcp-client"
AUTH_URL = "https://api.myblog.com/oauth/authorize"
TOKEN_URL = "https://api.myblog.com/oauth/token"
REDIRECT_URI = "http://localhost:3000/callback"

# PKCE Code Verifier 생성
random_bytes = os.urandom(32)
code_verifier = base64.urlsafe_b64encode(random_bytes).rstrip(b'=').decode('utf-8')

# Code Challenge 생성
challenge_digest = hashlib.sha256(code_verifier.encode('utf-8')).digest()
code_challenge = base64.urlsafe_b64encode(challenge_digest).rstrip(b'=').decode('utf-8')

def get_auth_url():
 params = {
 "response_type": "code",
 "client_id": CLIENT_ID,
 "redirect_uri": REDIRECT_URI,
 "scope": "mcp:read mcp:write",
 "code_challenge": code_challenge,
 "code_challenge_method": "S256"
 }
 return f"{AUTH_URL}?{urlencode(params)}"

def exchange_code_for_token(auth_code):
 data = {
 "grant_type": "authorization_code",
 "code": auth_code,
 "redirect_uri": REDIRECT_URI,
 "client_id": CLIENT_ID,
 "code_verifier": code_verifier # 서버로 전송하여 검증받음
 }
 response = requests.post(TOKEN_URL, data=data)
 return response.json()

# 사용 예시
# 1. 사용자가 get_auth_url()를 통해 브라우저에서 인증 (최초 1회)
# 2. 리다이렉션된 쿼리 파라미터에서 'code' 추출
# 3. token = exchange_code_for_token(code)

ZeroClaw 런타임 통합 고찰

지난 회고록인 *’[ZeroClaw] 2026 상반기 발전방향 회의록’*에서 언급했듯, 우리의 에이전트 런타임은 보안과 확장성을 최우선으로 고려해야 합니다. 위에서 구현한 OAuth 흐름을 ZeroClaw의 Multi-Agent 아키텍처에 통합한다면, 각 에이전트는 독립된 Identity를 가질 수 있습니다.

특히 *’[ZeroClaw] 멀티 에이전트 통신 프로토콜 설계’*에서 논의된 바와 같이, Agent 간 통신 시 이 Access Token을 사용하여 다른 에이전트의 리소스(API)에 안전하게 접근할 수 있는 기반을 마련하게 됩니다. 이는 단순한 블로그 자동화를 넘어, 에이전트가 에이전트를 신뢰하고 작업을 위임하는 분산 시스템의 첫걸음이 됩니다.

마치며

Zero-Touch OAuth는 사용자의 편의성과 보안이라는 두 마리 토끼를 잡는 훌륭한 접근 방식입니다. blog-api-server와 같은 작은 프로젝트부터 시작하여, 점차 ZeroClaw의 핵심 인증 모듈로 발전시켜 나갈 계획입니다. 위 코드는 기본적인 골격이므로, 실제 운영 환경에서는 State 검증, Refresh Token Rotation 등의 로직을 추가해야 합니다.

다음 포스트에서는 이렇게 확보된 토큰을 활용하여 MCP 서버와 실제로 데이터를 주고받는 ‘핸드셰이크(Handshake)’ 과정을 디버깅해보겠습니다.

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

Wed, 17 Jun 2026 09:00:39 +0900

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

최근 Hacker News와 같은 커뮤니티에서 “Stop Using JWTs"라는 주제가 다시 한번 뜨거운 감자로 떠올랐습니다. JWT(JSON Web Token)는 처음 등장했을 때만 해도 “무상태(Stateless)“라는 마법의 주문 덕분에 마이크로서비스 아키텍처(MSA)의 표준처럼 여겨졌습니다. 하지만 현실의 웹 서비스를 운영하면서 무상태의 함정에 빠지는 경우가 너무나 많습니다.

이 글에서는 왜 많은 개발자가 JWT에서 발을 떼고, 전통적인 세션 기반 인증(혹은 DB 기반 토큰)으로 돌아가고 있는지, 그리고 이를 실전에서 어떻게 구현하는지 살펴보겠습니다.

JWT의 달콤한 함정

JWT의 가장 큰 장점은 서버에 사용자 상태를 저장하지 않아도 된다는 점입니다. 토큰 자체에 모든 정보가 담겨 있으니, 데이터베이스 조회 없이 서명만 검증하면 됩니다. 이론적으로는 확장성이 뛰어납니다.

하지만 이 “장점"은 곧 “단점"이 됩니다.

1. 폐기 불가능성(Revocation Problem)

JWT는 발급되면 유효기간이 끝날 때까지 유효합니다. 만약 사용자가 로그아웃을 하거나, 관리자가 강제로 탈퇴시켜야 한다면 어떻게 할까요?

Option 1: 토큰을 즉시 파기할 수 없으니 냅두기 (보험상 불가능)
Option 2: 블랙리스트를 도입하기 (결국 DB/Redis 조회 필요 -> Stateless의 장점 상실)

블랙리스트를 도입하는 순간, JWT 검증을 위해 매번 블랙리스트를 확인해야 하므로, “데이터베이스 조회 없이"라는 장점이 사라집니다.

2. 토큰 크기와 부하

JWT는 헤더, 페이로드, 서명을 포함하여 일반적인 세션 ID보다 훨씬 큽니다. 사용자별로 다양한 클레임(Role, 권한 등)을 담을수록 토큰은 비대해집니다. 이는 매 요청마다 네트워크 대역폭을 낭비하게 만듭니다.

세션 기반 인증으로의 회귀

결론적으로, 우리는 **“서버 측에서 상태를 관리한다”**는 사실을 받아들이는 것이 낫습니다. Redis와 같은 인메모리 DB를 사용하면 매우 빠르게 세션을 관리할 수 있으며, 로그아웃이나 강제 탈퇴가 즉시 가능합니다.

이번 섹션에서는 Go 언어와 Redis를 사용하여 간단하지만 강력한 세션 기반 인증 시스템을 구축해 보겠습니다.

사전 준비

Redis가 로컬에 설치되어 있고 실행 중이라고 가정합니다.

구현 코드 (Go)

아래 코드는 /login, /protected, /logout 엔드포인트를 제공하는 간단한 HTTP 서버입니다.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/go-redis/redis/v8"
	"github.com/google/uuid"
	"github.com/gorilla/mux"
	"golang.org/x/crypto/bcrypt"
)

var ctx = context.Background()
var rdb *redis.Client

// 사용자 정보 (실제로는 DB에서 조회)
var userDB = map[string]string{
	"user1": "$2a$14$ajq8Q7fbnFR0nXf8bA7HcuiJ/6V.Z.yzX1lYh8g8h5x6z7x8x9x0x", // password: "password"
}

type Credentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

func main() {
	// Redis 클라이언트 초기화
	rdb = redis.NewClient(&redis.Options{
		Addr: "localhost:6379",
		Password: "", // no password set
		DB: 0, // use default DB
	})

	r := mux.NewRouter()
	r.HandleFunc("/login", loginHandler).Methods("POST")
	r.HandleFunc("/protected", authMiddleware(protectedHandler)).Methods("GET")
	r.HandleFunc("/logout", authMiddleware(logoutHandler)).Methods("POST")

	fmt.Println("Server starting on port 8000...")
	log.Fatal(http.ListenAndServe(":8000", r))
}

// 로그인 핸들러
func loginHandler(w http.ResponseWriter, r *http.Request) {
	var creds Credentials
	err := json.NewDecoder(r.Body).Decode(&creds)
	if err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}

	// 사용자 존재 및 비밀번호 확인
	hashedPassword, exists := userDB[creds.Username]
	if !exists {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}

	if err := bcrypt.CompareHashAndPassword([]byte(hashedPassword), []byte(creds.Password)); err != nil {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}

	// 새로운 세션 ID 생성
	sessionToken := uuid.NewString()

	// Redis에 세션 저장 (만료 24시간)
	err = rdb.Set(ctx, sessionToken, creds.Username, 24*time.Hour).Err()
	if err != nil {
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	// 쿠키 설정 (HttpOnly, Secure 권장)
	http.SetCookie(w, &http.Cookie{
		Name: "session_token",
		Value: sessionToken,
		Expires: time.Now().Add(24 * time.Hour),
		HttpOnly: true,
		Secure: true, // HTTPS 환경에서만
		Path: "/",
		SameSite: http.SameSiteStrictMode,
	})

	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(map[string]string{"message": "Login successful"})
}

// 인증 미들웨어
func authMiddleware(next http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		c, err := r.Cookie("session_token")
		if err != nil {
			if err == http.ErrNoCookie {
				w.WriteHeader(http.StatusUnauthorized)
				return
			}
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		sessionToken := c.Value

		// Redis에서 세션 조회
		response, err := rdb.Get(ctx, sessionToken).Result()
		if err != nil {
			if err == redis.Nil {
				w.WriteHeader(http.StatusUnauthorized)
				return
			}
			w.WriteHeader(http.StatusInternalServerError)
			return
		}

		// 요청 컨텍스트에 사용자 이름 저장 (선택 사항)
		// r = r.WithContext(context.WithValue(r.Context(), "username", response))

		next(w, r)
	}
}

// 보호된 리소스 핸들러
func protectedHandler(w http.ResponseWriter, r *http.Request) {
	c, _ := r.Cookie("session_token")
	username, _ := rdb.Get(ctx, c.Value).Result()
	json.NewEncoder(w).Encode(map[string]string{"message": fmt.Sprintf("Hello %s, you accessed a protected route!", username)})
}

// 로그아웃 핸들러
func logoutHandler(w http.ResponseWriter, r *http.Request) {
	c, _ := r.Cookie("session_token")
	sessionToken := c.Value

	// Redis에서 세션 삭제 (즉시 폐기)
	rdb.Del(ctx, sessionToken)

	// 쿠키 무효화
	http.SetCookie(w, &http.Cookie{
		Name: "session_token",
		Value: "",
		Expires: time.Now().Add(-1 * time.Hour),
		HttpOnly: true,
		Path: "/",
	})

	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(map[string]string{"message": "Logout successful"})
}

코드 설명 및 적용 팁

안전한 쿠키 사용: HttpOnly와 Secure 플래그를 사용하여 XSS(교차 사이트 스크립팅) 및 중간자 공격을 방지했습니다. 클라이언트(브라우저)가 토큰을 LocalStorage가 아닌 쿠키에 저장하도록 유도하는 것이 안전합니다.
Redis 활용: Redis는 싱글 스레드 기반이므로 원자적 연산이 빠르며, 세션 저장소로 사용하기에 최적입니다. 만약 Redis가 다운되더라도 영구적으로 데이터가 필요한 것은 아니므로(재로그인하면 됨), 빠른 응답 속도에 집중하여 설정합니다.
즉시 로그아웃: logoutHandler를 보면 Redis에서 키를 삭제하는 코드(rdb.Del)가 있습니다. 이는 JWT의 가장 큰 약점인 “로그아웃이 안 됨"을 완벽하게 해결합니다. 키가 삭제되는 순간, 해당 토큰(세션 ID)은 더 이상 유효하지 않습니다.

결론: 무엇을 선택해야 할까?

JWT가 좋은 경우: 당신이 구축하는 시스템이 진정으로 독립적인 마이크로서비스들로 구성되어 있고, 서비스 간 통신에서 사용자 인증이 필요하며, 로그아웃/재발급 로직이 중요하지 않은 단순 API 통신인 경우.
세션/Cookie가 좋은 경우: 일반적인 웹 서비스, SaaS, 사용자의 보안(계정 탈�� 시 즉각적인 조치 필요)이 중요한 대부분의 경우.

“Stop Using JWTs"라는 말은 JWT가 나쁜 기술이라서가 아니라, 상황에 맞지 않게 오남당되고 있기 때문입니다. 간단한 세션 저장소 하나면 해결될 문제에 복잡한 JWT 라이브러리와 블랙리스트 로직을 추가하는 것은 기술 부채를 쌓는 행위일 수 있습니다.

위의 Go 코드 예제를 프로젝트에 적용해 보시고, 관리의 용이성과 보안성을 직접 경험해 보시길 권장합니다.

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

Wed, 20 May 2026 09:00:35 +0900

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

최근 LLM(Large Language Model)을 활용한 에이전트 시스템이 급격히 발전하고 있습니다. Hacker News에서는 “Forge – Guardrails take an 8B model from 53% to 99% on agentic tasks"라는 흥미로운 사례가 화제가 되었습니다. 이는 모델의 파라미터 수를 늘리는 것보다, 적절한 **가드레일(Guardrails)**을 적용하는 것이 특정 작업의 성공률을 비약적으로 높일 수 있음을 시사합니다.

저희 팀에서 진행 중인 ZeroClaw 및 MCP(Model Context Protocol) 기반 프로젝트들에 있어 에이전트의 신뢰성은 필수적입니다. 이번 포스트에서는 오픈소스 가드레일 프레임워크인 Forge의 개념을 살펴보고, 이를 기존 MCP 아키텍처에 통합하여 에이전트의 안정성을 확보하는 구체적인 방법을 소개합니다.

문제 정의: 자율성의 딜레마

에이전트에게 자율성을 부여할수록 예상치 못한 행동을 할 위험이 커집니다. 예를 들어, 블로그 게시글을 생성하라는 MCP 요청이 있을 때, 에이전트가 시스템 명령어를 실행하거나 허용되지 않은 API를 호출하려 시도할 수 있습니다.

기존의 [blog-api-server] 구현에서는 프롬프트 엔지니어링과 간단한 JSON 스키마 검증으로 이를 방어하려 했으나, 복잡한 멀티 에이전트 환경에서는 한계가 있었습니다. 이를 해결하기 위해 입력과 출력을 사전에 필터링하는 L1 가드레일 레이어를 도입하기로 결정했습니다.

솔루션: Guardrails 패턴 적용

Forge가 보여주듯, 에이전트 작업의 성공률(53% → 99%)을 높이는 핵심은 실행 전 검증입니다. 우리는 에이전트가 LLM으로부터 응답을 받아 사용자에게 전달하거나 도구(Tool)를 실행하기 전, 중간 계층에서 이를 검증하는 구조를 설계했습니다.

아키텍처 개요

기존 MCP 클라이언트와 LLM 사이에 Validator 계층을 두어 다음을 수행합니다.

입력 검증 (Input Validation): 사용자의 요청이 시스템 정책을 위반하지 않는지 확인 (예: 공격적인 프롬프트 필터링).
출력 검증 (Output Validation): LLM이 생성한 JSON이나 함수 호출 인자가 스키마에 부합하는지 확인.

실전 코드 예제: Rust로 구현하는 안전장치

ZeroClaw의 Rust 환경에서 가벼운 출력 검증기를 구현해 보겠습니다. 복잡한 외부 라이브러리 없이, serde와 regex를 활용하여 LLM이 생성한 코드 실행 명령을 안전하게 감싸는 예제입니다.

1. 검증 로직 구현하기

먼저, 에이전트가 생성한 명령어가 안전한지 판별하는 간단한 검증기입니다.

use regex::Regex;
use serde::{Deserialize, Serialize};

// 에이전트가 생성할 수 있는 명령어 구조
#[derive(Debug, Serialize, Deserialize)]
struct AgentCommand {
 tool_name: String,
 parameters: String,
}

pub struct Guardrail;

impl Guardrail {
 // 위험한 문자열 필터링 (간단한 예시)
 fn is_dangerous(input: &str) -> bool {
 let dangerous_patterns = vec!["rm -rf", "sudo", "eval", "__import__"];
 dangerous_patterns.iter().any(|&pat| input.contains(pat))
 }

 // 명령어 실행 전 검증 로직
 pub fn validate_command(cmd: &AgentCommand) -> Result<&AgentCommand, String> {
 // 1. 도구 이름 화이트리스트 확인
 let allowed_tools = vec!["blog_post", "search", "read_file"];
 if !allowed_tools.contains(&cmd.tool_name.as_str()) {
 return Err(format!("허용되지 않은 도구 사용 시도: {}", cmd.tool_name));
 }

 // 2. 파라미터 내 위험 키워드 검사
 if Self::is_dangerous(&cmd.parameters) {
 return Err("파라미터에 잠재적으로 위험한 명령어가 포함되어 있습니다.".to_string());
 }

 // 3. 안전하다면 명령어 승인
 Ok(cmd)
 }
}

2. 에이전트 루프에 통합하기

이제 검증기를 MCP 서버의 요청 처리 루프에 연결합니다. 에이전트가 응답을 생성하면, 실제 시스템이 이를 실행하기 전에 Guardrail을 거쳐야 합니다.

// 가상의 에이전트 실행 함수
fn execute_agent_task(llm_output: &str) -> Result<String, String> {
 // 1. LLM 출력 파싱 (실제로는 JSON 파싱 등)
 // 여기서는 간단히 파싱되었다고 가정합니다.
 let command = AgentCommand {
 tool_name: "blog_post".to_string(),
 parameters: "title: 'Hello World'".to_string(),
 };

 // 2. 가드레일 통과 전
 println!("[System] LLM 응답 수신: {}", command.tool_name);

 // 3. 가드레일 검증 실행
 let safe_command = Guardrail::validate_command(&command)?;

 // 4. 검증된 명령어 실행
 println!("[System] 안전한 명령어 실행 중...");
 // 실제 도구 실행 로직 (예: 블로그 API 호출)
 Ok("게시글이 성공적으로 생성되었습니다.".to_string())
}

fn main() {
 // 정상 케이스
 match execute_agent_task("valid_response") {
 Ok(msg) => println!("성공: {}", msg),
 Err(e) => println!("차단됨: {}", e),
 }

 // 비정상 케이스 시뮬레이션
 let malicious_cmd = AgentCommand {
 tool_name: "system_shell".to_string(), // 화이트리스트에 없음
 parameters: "rm -rf /".to_string(),
 };

 match Guardrail::validate_command(&malicious_cmd) {
 Ok(_) => println!("오류: 해커가 침입했습니다!"),
 Err(e) => println!("보호됨: {}", e), // "보호됨: 허용되지 않은 도구 사용 시도: system_shell"
 }
}

효과 및 전망

이러한 L1 방어선을 구축함으로써 우리는 다음과 같은 이점을 얻을 수 있습니다.

안정성 향상: Forge 사례처럼 8B 모델도 충분히 안전하게 활용할 수 있어 추론 비용 절감.
투명성 확보: 에이전트가 왜 특정 작업을 거부했는지 로그를 통해 명확히 파악 가능.
유지보수성: 보안 정책이 변경되어도 Guardrail 모듈만 수정하면 됨.

앞으로 ZeroClaw 프로젝트에서는 이 검증 로직을 비동기 런타임에 통합하여, 멀티 에이전트 간 통신([Discord MCP], [Cloud Monitor]) 시에도 실시간으로 안전성을 모니터링할 계획입니다.

단순히 모델의 성능을 높이는 것에 집착하기보다, 이처럼 시스템 레벨에서의 안전장치를 어떻게 설계하느냐가 AI 에이전트를 실제 프로덕션에 배포하는 관건이 될 것입니다.

이 글은 ZeroClaw 및 MCP 관련 아키텍처 설계 문서들을 참고하여 작성되었습니다.

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

Mon, 11 May 2026 09:01:26 +0900

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

안녱하세요! ZeroClaw 프로젝트의 진행에 따라 고성능 Rust 에이전트 런타임과 멀티 에이전트 시스템을 구축하며 겪은 설계상의 고민과 해결 과정을 공유하고자 합니다. 최근 ‘Obsidian 플러그인을 악용한 원격 접속 트로이어나(RAT)’ 사건과 같은 보안 이슈들은 플러그인 및 에이전트 시스템에서 **보안(Security)**과 **신뢰성(Trust)**이 얼마나 중요한지를 다시금 상기시켜 줍니다.

오늘은 ZeroClaw의 코드베이스를 분석하며 설계한, 안전하고 확장 가능한 에이전트 간 통신 프로토콜을 구체적인 Rust 코드 예제와 함께 소개하겠습니다.

1. 서론: 보안을 고려한 에이전트 통신의 필요성

기존의 MCP(Model Context Protocol)나 블로그 자동화 시스템 구축 과정에서 우리는 단순한 데이터 전송을 넘어, 에이전트 간의 **신원 확인(Authentication)**과 **권한 부여(Authorization)**가 필수적임을 깨달았습니다. 특히 여러 에이전트가 협업하여 파일을 생성하거나 외부 API를 호출하는 멀티 에이전트 환경에서는 악의적인 명령 삽입을 방지하는 메커니즘이必不可少입니다.

ZeroClaw는 이를 위해 Rust의 타입 안전성(Type Safety)과 소유권(Ownership) 시스템을 적극 활용하여, 컴파일 타임에 많은 버그를 잡고 런타임 오버헤드를 최소화하는 아키텍처를 채택했습니다.

2. 통신 프로토콜 설계: IPC와 메시지 큐

ZeroClaw의 통신 플랫폼은 크게 **로컬 IPC(Inter-Process Communication)**와 비동기 메시지 큐로 나뉩니다. 로그 시스템 개선 과정에서 얻은 경험을 바탕으로, 모든 통신은 비동기(async)로 처리되며 각 에이전트의 독립성을 보장합니다.

주요 설계 원칙

Zero-Copy Serialization: serde와 bincode를 활용하여 데이터 직렬화 오버헤드를 최소화합니다.
Message Validation: 들어오는 모든 메시지를 검증하는 레이어를 두어, 변조된 데이터가 시스템 코어에 도달하는 것을 방지합니다.
Capability-Based Security: 단순한 토큰 기반 인증 넘어, 에이전트가 수행할 수 있는 행위(Capability) 자체를 제한합니다.

3. Rust로 구현하는 안전한 메시징 핸들러

이제 실제 코드를 통해 어떻게 구현했는지 살펴보겠습니다. 이 예제는 tokio를 기반으로 하며, 안전한 메시지 전달을 위한 기본 구조를 보여줍니다.

3.1 메시지 정의 및 검증

먼저, 에이전트 간에 오가는 데이터 구조를 정의하고, validator 크레이트를 사용하여 입력값을 검증합니다.

// message.rs
use serde::{Deserialize, Serialize};
use validator::Validate;

/// 에이전트 간 통신 메시지 타입
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AgentMessage {
 TaskRequest { id: String, payload: TaskPayload },
 TaskResponse { id: String, result: String },
 Heartbeat,
}

/// 작업 페이로드 (검증 로직 포함)
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct TaskPayload {
 #[validate(length(min = 1, max = 100))]
 pub command: String,
 
 // JSON 형식의 인자를 받지만, 구조적으로 안전하게 파싱해야 함
 pub args: serde_json::Value, 
}

impl AgentMessage {
 /// 바이트 배열로부터 안전하게 메시지를 역직렬화합니다.
 pub fn from_bytes(bytes: &[u8]) -> Result<Self, Box<dyn std::error::Error>> {
 // 1. 기본 직렬화 검증
 let msg: AgentMessage = bincode::deserialize(bytes)?;
 
 // 2. 비즈니스 로직 검증 (예: Command Injection 방지)
 if let AgentMessage::TaskRequest { payload, .. } = &msg {
 payload.validate()?; // validator 크레이트 사용
 
 // 보안: 허용되지 않는 쉘 명령어 필터링 예시
 if payload.command.contains("rm ") || payload.command.contains("sudo") {
 return Err("Blocked potentially dangerous command".into());
 }
 }
 
 Ok(msg)
 }
}

3.2 액터 모델 기반 에이전트 구조

각 에이전트는 자신의 상태를 가지며, 메시지를 받아 처리하는 Actor 패턴을 따릅니다. Rust의 tokio::sync::mpsc 채널을 사용하여 메일박스를 구현합니다.

// agent.rs
use tokio::sync::mpsc;
use super::message::AgentMessage;

pub struct Agent {
 id: String,
 receiver: mpsc::Receiver<AgentMessage>,
 // 에이전트의 상태는 여기에 캡슐화되어 외부에서 직접 접근 불가
}

impl Agent {
 pub fn new(id: String, receiver: mpsc::Receiver<AgentMessage>) -> Self {
 Self { id, receiver }
 }

 /// 에이전트의 메인 루프
 pub async fn run(mut self) {
 println!("[{}] Agent started", self.id);
 
 while let Some(msg) = self.receiver.recv().await {
 if let Err(e) = self.handle_message(msg).await {
 eprintln!("[{}] Error handling message: {:?}", self.id, e);
 }
 }
 }

 async fn handle_message(&self, msg: AgentMessage) -> Result<(), Box<dyn std::error::Error>> {
 match msg {
 AgentMessage::TaskRequest { id, payload } => {
 println!("[{}] Executing task {}: {}", self.id, id, payload.command);
 // 여기에 실제 작업 실행 로직 (예: LLM 호출, 파일 쓰기 등)
 // 안전 장치: 샌드박스 환경에서 실행하거나 권한을 제한합니다.
 },
 AgentMessage::Heartbeat => {
 // 생존 신호 처리
 },
 _ => return Err("Unknown message type".into()),
 }
 Ok(())
 }
}

3.3 런타임 및 메시지 라우팅

마지막으로, 여러 에이전트를 생성하고 메시지를 라우팅하는 간단한 런타임 시스템입니다.

// runtime.rs
use tokio::sync::mpsc;
use std::collections::HashMap;
use super::agent::Agent;
use super::message::AgentMessage;

pub struct Runtime {
 agents: HashMap<String, mpsc::Sender<AgentMessage>>,
}

impl Runtime {
 pub fn new() -> Self {
 Self { agents: HashMap::new() }
 }

 pub fn spawn_agent(&mut self, id: &str) {
 let (tx, rx) = mpsc::channel(32);
 let agent = Agent::new(id.to_string(), rx);
 
 // 에이전트를 별도의 태스크로 실행
 tokio::spawn(agent.run());
 
 self.agents.insert(id.to_string(), tx);
 println!("Runtime: Agent '{}' spawned", id);
 }

 pub async fn broadcast(&self, msg: AgentMessage) {
 for (id, tx) in self.agents.iter() {
 if let Err(e) = tx.send(msg.clone()).await {
 eprintln!("Failed to send to {}: {:?}", id, e);
 }
 }
 }
}

4. 마무리 및 다음 단계

위에서 구현한 코드는 ZeroClaw 멀티 에이전트 시스템의 핵심인 **‘안전한 통신’**과 **‘격리된 상태 관리’**를 보여줍니다. Obsidian 플러그인 사건처럼, 외부 입력이나 스크립트를 실행하는 시스템은 언제나 공격의 대상이 될 수 있습니다.

ZeroClaw는 Rust의 강력한 타입 시스템을 통해 이러한 위험을 컴파일 타임에 대부분 차단하고, 런타임에도 추가적인 검증 레이어를 두어 방어합니다. 다음 포스트에서는 이 에이전트 시스템이 실제로 Discord나 MCP와 같은 외부 게이트웨이와 어떻게 연동되는지, 그리고 LLM 설정을 통해 어떻게 제어되는지에 대해 다루겠습니다.

지금까지 ZeroClaw의 아키텍처 설계 현황을 공유했습니다. 고성능이면서도 안전한 에이전트 시스템을 구축하려는 분들께 도움이 되기를 바랍니다!

참고: 위 코드는 개념 증명(POC) 수준의 예제이며, 실제 프로덕션 환경에서는 더욱 견고한 에러 핸들링과 로깅 시스템(이전 포스트에서 개선한 로깅 설정 참조)이 통합되어야 합니다.

블로그 AI 자동 댓글 시스템 구축기 (2/3) — 보안 강화

Sun, 03 May 2026 01:10:00 +0900

개요

1부에서 AI 자동 댓글 시스템의 아키텍처와 구현을 다뤘습니다. 이번 2부에서는 보안 측면을 집중적으로 다룹니다.

외부 Webhook을 수신하고, GitHub API 토큰을 관리하며, 사용자 입력을 처리하는 시스템은 보안이 특히 중요합니다. 환경 변수 대신 파일 기반 인증으로 전환한 과정과 그 이유, 각 보안 계층의 설계를 설명합니다.

보안 위협 모델

이 시스템이 방어해야 하는 위협:

위협	공격 벡터	방어 수단
위장 Webhook	공격자가 가짜 Webhook 전송	HMAC-SHA256 시그니처 검증
토큰 유출	환경 변수 노출, 로그 노출	파일 기반 인증 + 권한 제한
XSS/인젝션	악의적인 댓글 내용	입력 sanitization
과도한 요청	DDoS, 남용	Flask-Limiter 속도 제한
권한 상승	워커 프로세스 탈취	systemd 보안 디렉티브
무한 루프	AI가 자신에게 응답	마커 기반 댓글 감지

파일 기반 인증 관리

환경 변수의 문제점

처음에는 GitHub 토큰과 Webhook 시크릿을 환경 변수로 관리했습니다:

# 초기 (안전하지 않음)
Environment=GITHUB_TOKEN=ghp_xxxxx
Environment=GITHUB_WEBHOOK_SECRET=my-secret-key

환경 변수 방식의 문제점:

/proc/PID/environ: Linux에서 프로세스의 환경 변수가 파일로 노출됨
로그 노출: 디버깅 중 환경 변수가 로그에 기록될 위험
자식 프로세스 상속: subprocess.run으로 Claude Code 실행 시 모든 환경 변수가 상속됨
systemd 설정 파일: 서비스 파일에 평문 시크릿이 포함되면 git에 커밋될 위험

파일 기반으로 전환

인증 정보를 파일 시스템에 저장하고, 환경 변수에는 파일 경로만 지정합니다:

# 개선 후 — 경로만 노출
Environment=GITHUB_TOKEN_FILE=/etc/auto-comment-worker/github-token
Environment=GITHUB_WEBHOOK_SECRET_FILE=/etc/auto-comment-worker/credentials/webhook-secret

서버의 디렉토리 구조:

/etc/auto-comment-worker/
├── github-token # GitHub Personal Access Token (640)
└── credentials/
 └── webhook-secret # GitHub Webhook HMAC Secret (600)

토큰 파일 로드 코드

import stat

GITHUB_TOKEN_FILE = os.environ.get('GITHUB_TOKEN_FILE', '')
if GITHUB_TOKEN_FILE and os.path.exists(GITHUB_TOKEN_FILE):
 # 파일 권한 검증
 st = os.stat(GITHUB_TOKEN_FILE)
 if st.st_mode & stat.S_IWOTH:
 raise PermissionError("Token file must not be world-writable")
 with open(GITHUB_TOKEN_FILE, 'r') as f:
 GITHUB_TOKEN = f.read().strip()
else:
 GITHUB_TOKEN = os.environ.get('GITHUB_TOKEN', '')

핵심 설계 결정:

파일 존재 시 파일 우선: 환경 변수는 폴백으로만 사용
권한 검증: 파일을 읽기 전에 권한을 확인
strip(): 파일 끝의 개행 문자 제거

파일 권한 검증 — 삽질의 기록

이 부분에서 가장 많은 시간을 소비했습니다. 초기 코드는 지나치게 엄격했습니다:

# 초기 코드 — 너무 엄격함
if st.st_mode & (stat.S_IRWXO | stat.S_IRWXG):
 raise PermissionError("Token file must be 600 or 400")

이 코드의 문제: S_IRWXO | S_IRWXG는 그룹의 모든 권한(읽기/쓰기/실행)과 기타의 모든 권한을 검사합니다. 즉, 파일 권한이 640 (소유자 읽기/쓰기, 그룹 읽기)이면 거부됩니다.

# 비트 마스크 분석
S_IRWXG = 0o070 # 그룹의 읽기+쓰기+실행
S_IRWXO = 0o007 # 기타의 읽기+쓰기+실행

# 640 = 0o640
0o640 & (0o070 | 0o007) = 0o640 & 0o077 = 0o040 # 0이 아님 → 거부!

실제 보안상 중요한 것은 다른 사용자(other)가 파일을 수정할 수 없는 것입니다. 그룹 읽기 권한은 같은 그룹 사용자가 파일을 읽을 수 있게 해주며, 보안상 문제가 되지 않습니다.

수정 후:

# 수정 후 — 실제 위협에 집중
if st.st_mode & stat.S_IWOTH:
 raise PermissionError("Token file must not be world-writable")

stat.S_IWOTH (0o002)만 검사하면 됩니다. 이는 “기타 사용자에게 쓰기 권한이 있는가"만 확인합니다.

권한	8진수	초기 코드	수정 후
`600`	`0o600`	허용	허용
`640`	`0o640`	거부	허용
`644`	`0o644`	거부	허용
`646`	`0o646`	거부	거부
`666`	`0o666`	거부	거부

HMAC-SHA256 시그니처 검증

GitHub Webhook은 요청 본문을 Webhook 시크릿으로 HMAC-SHA256 해싱한 시그니처를 X-Hub-Signature-256 헤더로 전송합니다. 이를 검증하여 요청이 실제 GitHub에서 왔는지 확인합니다.

def verify_webhook_signature(payload: bytes, signature: str) -> bool:
 """GitHub 웹훅 시그니처 검증"""
 if not signature:
 logger.warning("Missing webhook signature")
 return False

 if not WEBHOOK_SECRET:
 logger.warning("WEBHOOK_SECRET not configured - skipping validation")
 return True # 개발 모드 허용

 try:
 hash_algorithm, github_signature = signature.split('=', 1)
 if hash_algorithm != 'sha256':
 return False

 mac = hmac.new(
 WEBHOOK_SECRET.encode(),
 msg=payload,
 digestmod=hashlib.sha256
 )
 expected_signature = mac.hexdigest()

 # 타이밍 공격 방지
 if not hmac.compare_digest(expected_signature, github_signature):
 return False

 return True
 except Exception as e:
 logger.error(f"Signature verification error: {e}")
 return False

주요 포인트:

hmac.compare_digest(): 일반 == 비교 대신 상수 시간 비교를 사용하여 타이밍 공격을 방지합니다.
raw bytes 사용: request.data (원본 바이트)를 사용합니다. request.json으로 파싱 후 재직렬화하면 원본과 달라질 수 있습니다.
개발 모드: 시크릿이 설정되지 않으면 검증을 건너뜁니다. 프로덕션에서는 반드시 시크릿을 설정해야 합니다.

nginx 헤더 포워딩

시그니처 검증이 정상 작동하려면 nginx가 X-Hub-Signature-256 헤더를 포워딩해야 합니다:

location /webhook {
 proxy_pass http://localhost:8081;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Hub-Signature-256 $http_x_hub_signature_256;
}

X-Hub-Signature-256을 명시적으로 포워딩하지 않으면, 기본 proxy_pass만으로는 커스텀 헤더가 전달되지 않을 수 있습니다.

요청 검증 (marshmallow 스키마)

Webhook 페이로드의 구조를 marshmallow 스키마로 검증합니다:

class WebhookSchema(Schema):
 action = fields.Str(required=True, validate=validate.Equal('created'))
 comment = fields.Dict(required=True)
 discussion = fields.Dict(required=True)
 repository = fields.Dict(required=True)
 sender = fields.Dict(required=False)

action = 'created'만 허용: 댓글 수정(edited)이나 삭제(deleted) 이벤트는 거부합니다.
필수 필드 검증: comment, discussion, repository가 없으면 400 에러를 반환합니다.
ValidationError → 감사 로그: 잘못된 요청은 감사 로그에 기록됩니다.

입력 Sanitization

사용자 댓글은 외부 입력이므로 반드시 처리합니다:

def sanitize_comment(body: str) -> str:
 """사용자 입력 sanitization"""
 body = re.sub(r'<[^>]+>', '', body) # HTML 태그 제거
 body = html.escape(body) # 특수 문자 이스케이프
 body = body[:1000] # 길이 제한
 return body

이 sanitization이 적용되는 곳:

댓글 본문 (comment_body)
토론 제목과 본문 (discussion_title, discussion_body)
원작성자 이름 (original_author)
AI 응답 게시 시 인용 부분

사용자명 마스킹

로그에 사용자 이름 전체를 기록하지 않습니다:

def mask_username(username: str) -> str:
 """사용자명 마스킹"""
 if not username or len(username) < 4:
 return "***"
 return f"{username[:3]}***"

로그에는 yar***처럼 마스킹된 이름만 표시됩니다. 개인정보 보호와 디버깅 편의성 사이의 균형을 맞춥니다.

속도 제한

Flask-Limiter로 엔드포인트별 속도 제한을 적용합니다:

limiter = Limiter(
 app=app,
 key_func=get_remote_address,
 default_limits=["10 per minute"],
 storage_uri="memory://"
)

@app.route('/webhook', methods=['POST'])
@limiter.limit("10 per minute")
def github_webhook():
 ...

분당 10회 제한: 정상적인 Webhook 호출 빈도를 고려한 수치
get_remote_address: 클라이언트 IP 기준으로 제한
memory://: 인메모리 저장소 (단일 프로세스에 적합)

systemd 보안 디렉티브

3부에서 systemd 배포를 상세히 다루지만, 보안 관련 디렉티브는 여기서 설명합니다:

[Service]
# 보안 강화
NoNewPrivileges=true # 권한 상승 방지
PrivateTmp=true # 독립된 /tmp 제공
ProtectSystem=strict # 파일시스템 읽기 전용
ProtectHome=false # 홈 디렉토리 접근 허용 (Claude Code 설정)
ReadWritePaths=/var/www/auto-comment-worker /var/log/auto-comment-worker

# 리소스 제한
MemoryMax=512M # 메모리 제한
CPUQuota=50% # CPU 사용량 제한
TasksMax=100 # 프로세스 수 제한

디렉티브	효과
`NoNewPrivileges=true`	`setuid`, `setgid` 등으로 권한 상승 불가
`PrivateTmp=true`	독립된 `/tmp` 네임스페이스, 다른 프로세스와 격리
`ProtectSystem=strict`	전체 파일시스템을 읽기 전용으로 마운트
`ReadWritePaths`	명시적으로 쓰기를 허용할 경로만 지정
`MemoryMax=512M`	OOM 상황에서 시스템 전체를 보호

`ProtectSystem=strict`과 `ReadOnlyPaths`의 충돌

초기에 ReadOnlyPaths=/etc/auto-comment-worker를 추가했다가 토큰 파일을 읽지 못하는 문제가 발생했습니다. ProtectSystem=strict가 이미 전체 파일시스템을 읽기 전용으로 설정하므로, 별도의 ReadOnlyPaths는 불필요합니다. 오히려 일부 환경에서 충돌을 일으킬 수 있어 제거했습니다.

마무리

이번 2부에서는 파일 기반 인증 관리, 파일 권한 검증 삽질기, HMAC-SHA256 시그니처 검증, 입력 sanitization, 속도 제한, systemd 보안 디렉티브를 다뤘습니다.

보안에서 가장 중요한 교훈: “너무 엄격한 검증은 너무 느슨한 검증만큼 해롭다.” 파일 권한을 600만 허용하는 초기 코드는 보안상 안전했지만, 실제 운영 환경에서 640 권한의 파일을 거부하여 서비스가 시작되지 않았습니다. 실제 위협(world-writable)에만 집중하는 것이 올바른 접근입니다.

다음 3부에서는 배포와 트러블슈팅 — systemd 서비스 구성, nginx 리버스 프록시, 실제 겪은 오류들과 해결 과정을 다룹니다.

이 글은 AgentForge 블로그 자동 댓글 시스템 시리즈의 2부입니다.

[ZeroClaw] 2026 상반기 발전방향 회의록

Sat, 28 Feb 2026 09:55:15 +0900

ZeroClaw 2026 상반기 발전방향 팀 회의록

회의 일시: 2026-02-28 참석자: 아키텍트, 보안 리드, 프로덕트 오너, DevOps 리드 회의 장소: ZeroClaw 개발팀 회의실 작성자: ZeroClaw Team

1. 회의 개요

본 회의는 ZeroClaw 프로젝트의 2026년 상반기 발전방향을 논의하고, 각 영역별 로드맵과 우선순위를 수립하기 위해 개최되었다.

1.1 회의 안건

멀티 에이전트 아키텍처 발전 방향
보안 강화 및 컴플라이언스 대응
제품 경쟁력 강화 및 사용자 경험 개선
DevOps 및 인프라 고도화
종합 로드맵 및 우선순위 합의

2. 아키텍처 발전방향 논의

2.1 아키텍트 발언

“현재 ZeroClaw는 Phase 1(인프로세스 위임)을 완료하고 Phase 2(파일 기반 멀티 에이전트) 구현 중에 있습니다. 2026년 상반기에는 다음과 같은 기술적 목표를 달성해야 합니다.”

2.1.1 멀티 에이전트 오케스트레이션 고도화

제안 사항:

DAG 기반 워크플로우 실행 엔진 구현
순차/병렬/조건/반복 실행 패턴 지원
에이전트 간 작업 분배 알고리즘 개선

우선순위: 높음 (P1)

// 제안하는 워크플로우 구조
pub struct Workflow {
 pub id: String,
 pub nodes: Vec<WorkflowNode>,
 pub edges: Vec<WorkflowEdge>,
 pub start_node: String,
 pub end_nodes: Vec<String>,
 pub error_handling: ErrorHandlingPolicy,
}

2.1.2 IPC 통신 프로토콜 개선

제안 사항:

현재 stdout 기반 통신을 구조화된 IPC로 전환
Unix Socket, gRPC, WebSocket 다중 전송 계층 지원
메시지 직렬화 최적화 (JSON → MessagePack/CBOR)

우선순위: 중간 (P2)

2.1.3 확장성 및 모듈화

제안 사항:

플러그인 아키텍처 도입 검토
Wasm 실행 모드 구현 (샌드박싱 강화)
외부 에이전트 등록 API 제공

우선순위: 낮음 (P3)

2.1.4 성능 최적화

제안 사항:

Zero-copy 메시지 전달
연결 풀링 및 캐싱 전략
비동기 I/O 최적화

우선순위: 중간 (P2)

2.2 토의 내용

보안 리드:

“IPC 프로토콜 개선 시 보안 채널 적용이 선행되어야 합니다. 에이전트 간 통신에 대한 암호화와 인증이 필요합니다.”

프로덕트 오너:

“사용자 관점에서는 에이전트 정의가 더 직관적이어야 합니다. YAML 스키마를 단순화하는 것도 고려해봅시다.”

DevOps 리드:

“성능 최적화 작업은 관찰성 향상과 병행되어야 합니다. 메트릭 수집이 먼저 확보되어야 최적화 효과를 측정할 수 있습니다.”

3. 보안 발전방향 논의

3.1 보안 리드 발언

“ZeroClaw는 이미 강력한 보안 기반을 갖추고 있으나, OWASP Top 10 관점에서 보완이 필요한 영역이 있습니다. 특히 샌드박스 격리와 감사 로깅 강화가 시급합니다.”

3.1.1 샌드박스 강화

현재 문제점:

Docker 샌드박스: --read-only, --cap-drop, seccomp 미적용
Firejail: 네트워크 격리 미적용 (--net=none 누락)

제안 사항:

// Docker 강화 프로필
docker_cmd.args([
 "run", "--rm",
 "--read-only",
 "--security-opt", "no-new-privileges",
 "--cap-drop", "ALL",
 "--network", "none",
 "--memory", "256m",
 "--pids-limit", "64",
]);

우선순위: 높음 (P1)

3.1.2 감사 로깅 강화

제안 사항:

로그 서명 (Log Signing) 도입으로 변조 방지
실시간 보안 알림 웹훅 연동
Prometheus 메트릭 노출

우선순위: 중간 (P2)

3.1.3 SSRF 방어

제안 사항:

외부 요청 시 HTTPS 강제
사설 IP 대역 차단
도메인 허용목록 검증 강화

우선순위: 중간 (P2)

3.1.4 TOCTOU 취약점 수정

제안 사항:

경로 검증과 정규화를 원자적으로 수행
심볼릭 링크 레이스 컨디션 방지

우선순위: 높음 (P1)

3.2 토의 내용

아키텍트:

“샌드박스 강화는 Wasm 실행 모드와 연계하여 진행하면 더 강력한 격리를 제공할 수 있습니다.”

DevOps 리드:

“Prometheus 메트릭은 Grafana 대시보드와 연동하여 운영 가시성을 크게 개선할 수 있습니다.”

프로덕트 오너:

“보안 강화로 인한 사용자 경험 저하가 없도록 기본값은 안전하게, 고급 사용자는 유연하게 설정할 수 있어야 합니다.”

4. 제품 발전방향 논의

4.1 프로덕트 오너 발언

“ZeroClaw의 핵심 가치는 ‘고성능’, ‘확장성’, ‘보안’입니다. 2026년 상반기에는 이를 더욱 강화하면서 사용자 경험을 개선해야 합니다.”

4.1.1 사용자 경험 개선

CLI 개선:

zeroclaw agent list 출력 개선 (테이블 포맷)
대화형 에이전트 실행 모드
진행 상황 시각화

설정 단순화:

에이전트 정의 YAML 스키마 단순화
sensible defaults 제공
설정 검증 및 오류 메시지 개선

우선순위: 높음 (P1)

4.1.2 문서화 및 온보딩 강화

제안 사항:

Quickstart 가이드 개선
API 참조 문서 자동 생성
예제 시나리오 확장
다국어 문서 (한국어, 일본어, 중국어)

우선순위: 중간 (P2)

4.1.3 커뮤니티 성장 전략

제안 사항:

CONTRIBUTING.md 개선
Good first issue 라벨링
정기 릴리즈 노트 발행
Discord/Slack 커뮤니티 채널

우선순위: 중간 (P2)

4.1.4 차별화 포인트 강화

제안 사항:

하드웨어 페리퍼럴 지원 강화 (STM32, RPi)
특화 도메인 에이전트 템플릿
성능 벤치마크 공개

우선순위: 낮음 (P3)

4.2 토의 내용

아키텍트:

“CLI 개선은 ergonomics 측면에서 중요합니다. structopt 대신 clap 4.x로 업그레이드하는 것도 검토해봅시다.”

보안 리드:

“다국어 문서 작성 시 보안 관련 내용은 정확한 번역이 중요합니다. 용어집을 먼저 작성하는 것을 권장합니다.”

DevOps 리드:

“커뮤니티 채널은 GitHub Discussions부터 시작하는 것이 좋습니다. 별도 인프라 없이 시작할 수 있습니다.”

5. DevOps 발전방향 논의

5.1 DevOps 리드 발언

“안정적인 배포와 운영을 위해 CI/CD 파이프라인과 모니터링 시스템을 고도화해야 합니다.”

5.1.1 CI/CD 파이프라인 고도화

현재 상태:

GitHub Actions 기반 CI
cargo fmt, clippy, test 자동화
Docker 빌드

제안 사항:

cargo audit 통합 (취약점 스캔)
크로스 플랫폼 빌드 (Linux, macOS, Windows)
릴리즈 자동화 (cargo-release)
배포 전 스모크 테스트

우선순위: 높음 (P1)

# 제안하는 CI 워크플로우
- name: Security audit
 run: cargo audit

- name: Cross-platform build
 strategy:
 matrix:
 os: [ubuntu-latest, macos-latest, windows-latest]
 runs-on: ${{ matrix.os }}

5.1.2 모니터링 및 관찰성

제안 사항:

Prometheus 메트릭 엔드포인트
Grafana 대시보드 템플릿
분산 추적 (OpenTelemetry)
로그 집계 (ELK/Loki)

우선순위: 중간 (P2)

5.1.3 배포 자동화 및 롤백

제안 사항:

Blue-Green 배포 지원
자동 롤백 임계값 설정
Canary 릴리즈 옵션

우선순위: 중간 (P2)

5.1.4 개발 환경 개선

제안 사항:

devcontainer 구성
git hooks 자동 설정
개발용 설정 프로파일

우선순위: 낮음 (P3)

5.2 토의 내용

아키텍트:

“OpenTelemetry 통합은 멀티 에이전트 추적에 필수적입니다. 에이전트 간 호출 체인을 시각화할 수 있어야 합니다.”

보안 리드:

“cargo audit은 CI에 반드시 포함되어야 합니다. 또한 의존성 라이선스 검사도 추가하는 것이 좋습니다.”

프로덕트 오너:

“devcontainer는 신규 기여자 온보딩에 큰 도움이 될 것입니다. 우선순위를 높여도 좋습니다.”

6. 종합 로드맵 및 우선순위

6.1 2026년 상반기 로드맵

Q1 (3월-4월)

항목	담당	우선순위
Docker/Firejail 샌드박스 강화	보안	P1
TOCTOU 취약점 수정	보안	P1
CI/CD 보안 스캔 통합	DevOps	P1
CLI 개선 및 UX 향상	프로덕트	P1
DAG 기반 워크플로우 엔진	아키텍트	P1

Q2 (5월-6월)

항목	담당	우선순위
IPC 통신 프로토콜 개선	아키텍트	P2
감사 로깅 강화	보안	P2
SSRF 방어 구현	보안	P2
Prometheus 메트릭 노출	DevOps	P2
문서화 및 온보딩 개선	프로덕트	P2
커뮤니티 인프라 구축	프로덕트	P2

6.2 합의된 원칙

보안 우선: 모든 새로운 기능은 보안 리뷰를 거쳐야 함
점진적 배포: 큰 변경은 단계적으로 롤아웃
롤백 가능: 모든 변경은 쉽게 롤백 가능해야 함
문서 동기화: 기능 변경 시 문서 업데이트 필수
테스트 커버리지: 새로운 코드는 테스트 필수

6.3 리스크 및 대응

리스크	확률	영향	대응 방안
샌드박스 호환성 문제	중간	높음	폴백 메커니즘 구현
성능 회귀	낮음	중간	벤치마크 자동화
의존성 취약점	중간	높음	cargo audit 자동화
문서 부실	높음	중간	문서 PR 필수화

7. 결론 및 다음 단계

7.1 회의 결론

아키텍처: 멀티 에이전트 오케스트레이션 고도화를 최우선으로 진행
보안: 샌드박스 강화와 TOCTOU 수정을 즉시 착수
제품: CLI UX 개선으로 사용자 경험 향상
DevOps: CI/CD 보안 강화와 모니터링 기반 구축

7.2 액션 아이템

#	항목	담당자	기한
1	Docker 샌드박스 보안 프로필 적용	보안 리드	2026-03-07
2	TOCTOU 경로 검증 수정	보안 리드	2026-03-10
3	CI cargo audit 통합	DevOps 리드	2026-03-05
4	CLI agent list 개선	프로덕트 오너	2026-03-12
5	워크플로우 엔진 설계 문서	아키텍트	2026-03-15

7.3 다음 회의 일정

일시: 2026-03-14 10:00
안건: Q1 진행 상황 리뷰 및 Q2 상세 계획

부록: 참고 문서

docs/project/multi-agent-architecture-design.md - 멀티 에이전트 아키텍처 설계
docs/project/multi-agent-communication-protocols.md - 통신 프로토콜 설계
docs/security/security-improvements.md - 보안 개선 보고서
CLAUDE.md - 엔지니어링 프로토콜

회의록 작성일: 2026-02-28 승인자: ZeroClaw Team Lead 배포: ZeroClaw 개발팀 전체

영어 버전: English Version

[ZeroClaw] 코드베이스 아키텍처 분석

Thu, 26 Feb 2026 10:07:29 +0900

ZeroClaw 코드베이스 아키텍처 분석 보고서

2026년 2월 26일 작성

개요

ZeroClaw는 Rust로 작성된 고성능 자율 에이전트 런타임입니다. 이 보고서는 코드베이스 구조와 보안 아키텍처에 대한 분석 결과를 정리합니다.

1. 핵심 아키텍처 패턴

ZeroClaw는 **트레이트 기반 확장성(Trait-driven extensibility)**을 핵심 설계 원칙으로 채택하고 있습니다.

1.1 주요 트레이트 (7개)

트레이트	위치	역할
`Provider`	src/providers/traits.rs	AI 모델 프로바이더 인터페이스
`Channel`	src/channels/traits.rs	통신 채널 인터페이스
`Tool`	src/tools/traits.rs	도구 실행 인터페이스
`Memory`	src/memory/traits.rs	메모리 백엔드 인터페이스
`Observer`	src/observability/traits.rs	관측 가능성 인터페이스
`RuntimeAdapter`	src/runtime/traits.rs	런타임 어댑터 인터페이스
`Peripheral`	src/peripherals/traits.rs	하드웨어 주변장치 인터페이스

2. 보안 아키텍처

ZeroClaw는 다층 방어(Defense-in-Depth) 전략을 통해 보안을 구현합니다.

2.1 보안 레이어 (6개)

SecurityPolicy Core - 자율성 수준 관리
Gateway Security - Bearer 토큰 인증
Tool Validation - 인젝션 방지
Runtime Sandbox - Landlock/Firejail/Docker
Secret Management - ChaCha20-Poly1305
Audit Logging - 이벤트 추적

2.2 핵심 보안 경계

명령어 허용 목록: 15개
속도 제한: 20회/시간
환경 변수: 8개만 허용

3. 멀티 에이전트 시스템

구현 로드맵

Phase	기간	내용
1	1주	코어 트레이트, DelegateTool 확장
2	2-3주	Docker/Wasm 실행 모드
3	4주+	분산 메시지 버스, 합의 알고리즘

결론

ZeroClaw는 확장성, 보안, 성능, 유지보수성 측면에서 우수한 아키텍처를 가지고 있습니다.

이 보고서는 ZeroClaw 개발 팀의 협업 분석 결과를 바탕으로 작성되었습니다.

영어 버전: English Version

Security on Yarang's Tech Lair

[MicroVM] Firecracker를 활용한 고립형 샌드박스 구축 가이드

[MicroVM] Firecracker를 활용한 고립형 샌드박스 구축 가이드

왜 MicroVM인가?

사전 준비 사항

1. Firecracker 다운로드 및 준비

2. MicroVM 부팅을 위한 루트 파일시스템 생성

3. Rust로 제어 로직 작성하기

4. 실행 및 제어 (CLI 방식)

결론 및 ZeroClaw 적용 계획

참고자료

Zero-Touch OAuth 구현을 위한 MCP 인증 아키텍처 설계

왜 Zero-Touch인가?

아키텍처 설계

구현 단계 1: 서버 사이드 (blog-api-server)

구현 단계 2: 클라이언트 사이드 (MCP Client)

ZeroClaw 런타임 통합 고찰

마치며

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

Stop Using JWTs: 세션 기반 인증의 실용성과 구현

JWT의 달콤한 함정

1. 폐기 불가능성(Revocation Problem)

2. 토큰 크기와 부하

세션 기반 인증으로의 회귀

사전 준비

구현 코드 (Go)

코드 설명 및 적용 팁

결론: 무엇을 선택해야 할까?

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

문제 정의: 자율성의 딜레마

솔루션: Guardrails 패턴 적용

아키텍처 개요

실전 코드 예제: Rust로 구현하는 안전장치

1. 검증 로직 구현하기

2. 에이전트 루프에 통합하기

효과 및 전망

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

1. 서론: 보안을 고려한 에이전트 통신의 필요성

2. 통신 프로토콜 설계: IPC와 메시지 큐

주요 설계 원칙

3. Rust로 구현하는 안전한 메시징 핸들러

3.1 메시지 정의 및 검증

3.2 액터 모델 기반 에이전트 구조

3.3 런타임 및 메시지 라우팅

4. 마무리 및 다음 단계

블로그 AI 자동 댓글 시스템 구축기 (2/3) — 보안 강화

개요

보안 위협 모델

파일 기반 인증 관리

환경 변수의 문제점

파일 기반으로 전환

토큰 파일 로드 코드

파일 권한 검증 — 삽질의 기록

HMAC-SHA256 시그니처 검증

nginx 헤더 포워딩

요청 검증 (marshmallow 스키마)

입력 Sanitization

사용자명 마스킹

속도 제한

systemd 보안 디렉티브

ProtectSystem=strict과 ReadOnlyPaths의 충돌

마무리

[ZeroClaw] 2026 상반기 발전방향 회의록

ZeroClaw 2026 상반기 발전방향 팀 회의록

1. 회의 개요

1.1 회의 안건

2. 아키텍처 발전방향 논의

2.1 아키텍트 발언

2.1.1 멀티 에이전트 오케스트레이션 고도화

2.1.2 IPC 통신 프로토콜 개선

2.1.3 확장성 및 모듈화

2.1.4 성능 최적화

2.2 토의 내용

3. 보안 발전방향 논의

3.1 보안 리드 발언

3.1.1 샌드박스 강화

3.1.2 감사 로깅 강화

3.1.3 SSRF 방어

`ProtectSystem=strict`과 `ReadOnlyPaths`의 충돌