peg/rampart
요약
Rampart는 Claude Code, Cline, Codex와 같은 AI 에이전트가 시스템에 미칠 수 있는 위험을 방지하기 위한 보안 계층입니다. 에이전트의 모든 명령, 파일 액세스 및 네트워크 요청을 정책에 따라 평가하여 위험한 명령의 실행을 차단합니다.
핵심 포인트
- AI 에이전트의 자율 모드(autonomous modes) 사용 시 발생할 수 있는 보안 취약점(SSH 키 유출, 파일 삭제 등)을 방어합니다.
- 모든 도구 호출은 실행 전 Rampart의 정책 엔진을 통해 검증됩니다.
- macOS, Linux, Windows를 모두 지원하며 Homebrew 및 PowerShell을 통해 간편하게 설치할 수 있습니다.
- 설정 파일(config.yaml) 및 환경 변수를 통해 세밀한 API 및 URL 제어가 가능합니다.
Claude Code의 --dangerously-skip-permissions 모드와 Cline 및 Codex의 유사한 자율 모드(autonomous modes)는 에이전트(agent)에게 제한 없는 셸(shell) 액세스 권한을 부여합니다. 귀하의 에이전트는 아무런 보호 장치(guardrails) 없이 SSH 키를 읽거나, .env 파일을 유출하거나, rm -rf /를 실행할 수 있습니다.
Rampart는 에이전트와 귀하의 시스템 사이에 위치합니다. 모든 명령, 파일 액세스 및 네트워크 요청은 실행되기 전에 귀하의 정책(policy)에 따라 평가됩니다. 위험한 명령은 절대 실행되지 않습니다.
# Homebrew (macOS 및 Linux, 권장)
brew install peg/tap/rampart
# 한 줄 설치 (sudo 불필요)
...
Windows (PowerShell):
irm https://rampart.sh/install.ps1 | iex
설치 후, rampart quickstart를 실행하거나 아래의 설정 단계를 따르십시오.
에이전트를 선택하고 명령 하나를 실행하십시오:
# Claude Code
rampart setup claude-code
# OpenClaw
...
그게 전부입니다. 모든 것이 제대로 작동하는지 확인하십시오:
rampart doctor
그 다음, 에이전트를 실시간으로 관찰하십시오:
rampart watch
환경 변수(environment variables)를 계속 내보내기(exporting)를 원하지 않는 경우, Rampart는 로컬 기본값(local defaults)을 위한 ~/.rampart/config.yaml도 지원합니다:
url: http://127.0.0.1:9090
# serve_url: http://127.0.0.1:9090 # url에 대한 호환성 별칭(compatibility alias)
# api: http://127.0.0.1:9091 # 데몬/분할 토폴로지(daemon/split-topology) API 설정을 위한 선택적 고급 재정의(advanced override)
| 설정 | 용도 | 비고 |
|---|---|---|
url | 기본 Rampart 베이스 URL | hook/watch/plugin/service-backed 흐름을 위한 표준 설정 |
serve_url | url에 대한 하위 호환 별칭 | 호환성을 위해 유지됨; 새 설정에서는 url을 권장함 |
api | 승인/제어 명령을 위한 선택적 API 베이스 URL 재정의 | 고급 사용자용; API를 메인 서브 엔드포인트(serve endpoint)에서 분리하지 않는 한 보통 불필요함 |
참고 사항:
url은 주요 제어 장치(main knob)입니다. 특별한 이유가 없다면 이것을 사용하십시오. api는 rampart serve를 위한 일반적인 설정이 아닙니다. 이는 고급 데몬/분할 토폴로지(daemon/split-topology) 설정을 위한 것입니다.
- 클라이언트 측
--api플래그는 API 베이스 URL(http://127.0.0.1:9091)을 기대하는 반면, 데몬/서버--api...
플래그는 API 리슨 주소 (API listen address)(127.0.0.1:9091)를 참조합니다.
해결 순서(Resolution order)는 다음과 같습니다: 플래그(flag) → 환경 변수(environment) → 설정 파일(config file) → 자동 검색된 상태(auto-discovered state) → 기본값(default).
실행이 시작되면, 모든 도구 호출(tool call)은 먼저 Rampart의 정책 엔진(policy engine)을 통과합니다:
ALLOW 14:23:01 exec "npm test" [allow-dev]
ALLOW 14:23:03 read ~/project/src/main.go [default]
DENY 14:23:05 exec "rm -rf /tmp/*" [block-destructive]
...
패턴 매칭(Pattern matching)은 95% 이상의 결정을 마이크로초 단위로 처리합니다. 선택 사항인 rampart-verify 사이드카(sidecar)는 모호한 명령에 대해 LLM 기반의 분류(classification) 기능을 추가합니다. 모든 결정 사항은 해시 체인 방식의 감사 추적(hash-chained audit trail)으로 기록됩니다.
| 에이전트 (Agent) | 설정 명령 (Setup command) | 통합 방식 (Integration) |
|---|---|---|
| Claude Code | rampart setup claude-code | ~/.claude/settings.json을 통한 네이티브 PreToolUse 훅 (hooks) |
| OpenClaw | rampart setup openclaw | 네이티브 플러그인 + 선택적 네이티브 승인 |
| Cline | rampart setup cline | 설정을 통한 네이티브 훅 (hooks) |
| Codex CLI | rampart setup codex | rampart preload를 통해 Codex를 실행하는 래퍼 (Wrapper) |
| 모든 에이전트 (Any agent) | rampart wrap -- <agent> | $SHELL을 통한 셸 래핑 (Shell wrapping) |
| MCP 서버 (MCP servers) | rampart mcp -- <server> | MCP 프로토콜 프록시 (proxy) |
| 시스템 전체 (System-wide) | rampart preload -- <cmd> | LD_PRELOAD 시스템 호출 가로채기 (syscall interception) |
목차 (Table of Contents)
시작하기 (Getting Started): 설치 · 빠른 시작 · Claude Code · OpenClaw · 모든 에이전트 래핑
핵심 기능 (Core Features): 정책 (Policies) · 승인 흐름 (Approval flow) · 감사 추적 (Audit trail) · 라이브 대시보드 · 웹훅 알림 (Webhook notifications)
고급 (Advanced): LD_PRELOAD · MCP 프록시 · SIEM 통합 · 웹훅 액션 · Preflight API
참조 (Reference): 성능 · 보안 · OWASP 커버리지 · CLI 참조 · 호환성 · 소스 빌드
Claude Code의 훅(hook) 시스템을 통한 네이티브 통합. 모든 Bash 명령, 파일 읽기 및 쓰기는 실행 전 Rampart를 통과합니다:
# 백그라운드 서비스 설치
rampart serve install
# 훅 연결
...
그 후 Claude Code를 평소처럼 사용하면 됩니다. Rampart는 백그라운드에서 보이지 않게 실행됩니다.
제거하려면:
rampart setup claude-code --remove
현재의 OpenClaw 빌드에서는 네이티브 플러그인 통합 (Native plugin integration)이 권장되는 설정 방식입니다:
rampart setup openclaw
이 방식은 OpenClaw의 네이티브 승인 UI (native approval UI)를 유지하면서, 어떤 명령어가 실제로 승인이 필요한지는 Rampart가 결정하도록 합니다.
rampart serve는 이 경로의 일부입니다. 플러그인은 정책 평가 (policy evaluation), 승인 (approvals), 그리고 감사 흐름 (audit flow)을 위해 로컬 Rampart 서비스에 호출을 보냅니다.
Rampart는 전역 tools.exec.ask 설정을 `
rampart preload -- codex
rampart preload -- python my_agent.py
rampart preload -- node agent.js
...
execve, execvp, system(), popen(), 그리고 posix_spawn()을 가로챕니다 (Intercepts). 거부된 호출은 EPERM을 반환합니다.
플랫폼 참고 사항: Linux의 모든 동적 링크 바이너리 (dynamically-linked binaries)에서 작동합니다. macOS에서는 Homebrew/nvm/pyenv 바이너리와 함께 작동하며, /usr/bin/*에 대해서는 SIP (System Integrity Protection)에 의해 차단됩니다 (AI 에이전트는 그곳에 위치하지 않습니다).
에이전트와 모든 MCP 서버 사이의 드롭인 프록시 (Drop-in proxy):
rampart mcp -- npx @modelcontextprotocol/server-filesystem /path
MCP 설정 (Claude Desktop 등)에서:
{
"mcpServers": {
"filesystem": {
...
MCP 서버의 도구 목록으로부터 정책 (policies) 자동 생성:
rampart mcp scan -- npx @modelcontextprotocol/server-filesystem .
정책은 YAML 형식입니다. Glob 매칭을 지원하며, 파일 변경 시 핫 리로드 (hot-reload) 됩니다.
rampart setup은 시작 템플릿으로 ~/.rampart/policies/custom.yaml을 생성합니다. 이는 업그레이드 시에도 절대 덮어쓰이지 않습니다.
version: "1"
default_action: allow
policies:
...
부분 문자열 매칭 (대소문자 구분 없음)을 위해 command_contains를 사용하세요:
- name: block-dangerous-substrings
match:
tool: ["exec"]
...
승인 프롬프트 (approval prompt)를 트리거하려면 action: ask를 사용하세요:
- name: ask-before-sudo
match:
agent: ["claude-code"]
...
일반적인 경우에는 YAML 편집이 필요하지 않습니다. 명령이 차단되면, Rampart는 실행할 내용을 제안합니다:
# "npm install lodash"가 거부되었을 때:
# 💡 이를 허용하려면: rampart allow "npm install *"
rampart allow "npm install *"
...
평가 (Evaluation): 거부 (Deny)가 항상 우선합니다. 우선순위 숫자가 낮을수록 먼저 평가됩니다. 네 가지 액션 (actions): deny, ask, watch, allow.
프로젝트별 규칙을 위해 모든 git 리포지토리에 .rampart/policy.yaml을 배치하세요. 모든 팀원이 자동으로 동일한 규칙을 적용받을 수 있도록 커밋하십시오:
rampart init --project
보안 참고 사항: 신뢰할 수 없는 리포지토리에서 작업할 때 프로젝트 정책 로딩을 건너뛰려면 RAMPART_NO_PROJECT_POLICY=1을 설정하세요.
rampart init --profile standard # 기본 허용(allow-by-default), 위험한 명령 차단
rampart init --profile paranoid # 기본 차단(deny-by-default), 명시적 허용 목록(allowlist) 사용
rampart init --profile ci # 엄격 모드; 모든 승인이 강제 차단(hard denies)으로 변경됨
...
사람의 결정이 필요한 명령의 경우:
policies:
- name: production-deploys
match:
...
승인 요청이 전달되는 방식은 환경에 따라 다릅니다:
| 환경 | 승인 방식 |
|---|---|
| Claude Code | 터미널 내 네이티브 승인 프롬프트 |
| ... |
rampart pending # 대기 중인 항목
rampart approve abc123 # 승인 허용
rampart deny abc123 # 차단
대기 중인 승인은 기본적으로 2분 후에 만료됩니다 (--approval-timeout 옵션으로 변경 가능).
모든 도구 호출(tool call)은 해시 체인(hash-chained) 방식의 JSONL로 기록됩니다. 기록을 조작하면 체인이 깨집니다:
rampart audit tail --follow # 이벤트 스트림 확인
rampart audit verify # 체인 무결성 검사
rampart audit stats # 결정 내역 분석
...
rampart watch # TUI: 실시간 컬러 이벤트 스트림
rampart serve가 실행 중일 때 http://localhost:9090/dashboard/ 에서 웹 대시보드를 사용할 수 있습니다. 세 개의 탭으로 구성됩니다: 실시간 스트림(live stream), 히스토리(history), 그리고 명령을 실행하기 전에 테스트할 수 있는 정책 REPL(policy REPL).
notify:
url: "https://discord.com/api/webhooks/your/webhook"
on: ["deny"]
...
Discord 웹훅(webhooks), Slack 인커밍 웹훅(incoming webhooks), 또는 모든 HTTP 엔드포인트(endpoint)와 연동됩니다.
# RFC 5424 syslog (Wazuh, QRadar, ArcSight, Sentinel)
rampart serve --syslog localhost:514
# Common Event Format (Splunk, QRadar)
...
허용/차단 결정을 외부 서비스에 위임할 수 있습니다:
rules:
- action: webhook
when:
...
모호한 명령을 처리하기 위한 선택적 LLM 사이드카(sidecar)인 rampart-verify를 확인하세요 (호출당 약 ~$0.0001).
실행하지 않고 호출이 허용될지 여부를 확인하려면:
curl -s localhost:9090/v1/preflight/exec \
-H "Authorization: Bearer $TOKEN" \
-d '{"agent":"a","session":"s","params":{"command":"rm -rf /"}}'
...
정책 평가(Policy evaluation)는 한 자릿수 마이크로초(microseconds) 단위로 이루어집니다:
| 명령어 (Command) | 결정 (Decision) | 시간 (Time) |
|---|---|---|
rm -rf / | 거부 (deny) | 8µs |
sudo reboot | 관찰 (watch) | 6µs |
.ssh/id_rsa 읽기 (read) | 거부 (deny) | 3µs |
git status | 허용 (allow) | 4µs |
curl ngrok.io | 거부 (deny) | 3µs |
자기 수정 보호 (Self-modification protection). 에이전트(Agents)는 rampart allow 또는 rampart block을 실행하여 자신의 정책을 우회할 수 없습니다. 해당 명령어들은 에이전트에 의해 실행될 때 차단됩니다. 정책 수정은 반드시 인간(human)에 의해 이루어져야 합니다.
AI 에이전트를 root 권한으로 실행하지 마세요. root 접근 권한은 사용자 분리(user separation) 원칙을 무력화합니다. 에이전트 프레임워크(agent frameworks)는 권한이 없는 사용자(unprivileged user)로 실행하십시오.
운영 환경(production)에서는 rampart serve를 별도의 사용자로 실행하여 에이전트가 감사 로그(audit logs)를 읽거나 정책을 수정하는 것을 방지하십시오.
위협 모델(threat model)에 대한 전체 논의는 docs/THREAT-MODEL.md를 참조하십시오.
Rampart는 에이전트 애플리케이션을 위한 OWASP Top 10에 대응합니다:
| 리스크 (Risk) | 커버리지 (Coverage) |
|---|---|
| ASI02: 도구 오용 (Tool Misuse) | 예: 모든 도구 호출(tool call)은 실행 전 평가됨 |
| ASI05: 예기치 않은 코드 실행 (Unexpected Code Execution) | 예: 패턴 매칭(pattern matching) 및 선택적 LLM 검증 |
| ASI08: 데이터 유출 (Data Exfiltration) | 예: 도메인 차단 및 자격 증명 응답 스캔 (credential response scanning) |
| ASI09: 인간-에이전트 신뢰 (Human-Agent Trust) | 예: ask 액션이 인간 참여(human-in-the-loop)를 강제함 |
| ASI10: 통제 불능 에이전트 (Rogue Agents) | 예: 해시 체인 기반 감사 추적(hash-chained audit trail) 및 응답 스캔 |
| ASI01: 목표 탈취 (Goal Hijack) | 부분적: 정책이 목표를 변경하더라도 피해 범위(blast radius)를 제한함 |
| ASI06: 컨텍스트 오염 (Context Poisoning) | 부분적: 응답 스캔이 컨텍스트 창(context window)으로부터 자격 증명을 차단함 |
| ASI07: 에이전트 간 통신 (Inter-Agent Communication) | ❌ 다루지 않음 |
# 설정 (Setup)
rampart quickstart # 자동 감지, 설치, 구성, 상태 확인 (health check)
rampart setup claude-code # Claude Code 네이티브 훅 (native hooks)
...
| 에이전트 (Agent) | 메서드 (Method) | 플랫폼 (Platforms) |
|---|---|---|
| Claude Code | rampart setup claude-code | Linux, macOS, Windows |
| OpenClaw | rampart setup openclaw | Linux, macOS |
| Cline | rampart setup cline | Linux, macOS, Windows |
| Codex CLI | rampart setup codex | Linux, macOS (필요: librampart.so /.dylib) |
| Claude Desktop | rampart mcp | 전체 (All) |
| Aider, OpenCode, Continue | rampart wrap | Linux, macOS |
| Python 에이전트 (Python agents) | rampart preload 또는 HTTP API | Linux, macOS |
| Node.js 에이전트 (Node.js agents) | rampart preload 또는 HTTP API | Linux, macOS |
| 모든 MCP 서버 (Any MCP server) | rampart mcp | 전체 (All) |
| 모든 프로세스 (Any process) | rampart preload | Linux, macOS |
| 사용자 지정 에이전트 (Custom agents) | localhost:9090의 HTTP API | 전체 (All) |
git clone https://github.com/peg/rampart.git
cd rampart
go build -o rampart ./cmd/rampart
...
Go 1.24 이상 필요.
v0.9.9 버전에는 세 가지 주요 변경 사항(breaking changes)이 포함되어 있습니다:
** action: require_approval는 이제 치명적인 오류(hard error)입니다.**
정책을 다음 형식으로 업데이트해야 합니다:
- action: require_approval
를
- action: ask
ask:
audit: true
다음 명령어를 실행하여 모든 발생 지점을 찾으세요.
rampart policy lint
** --serve-token 플래그가 제거되었습니다.**
대신 다음 환경 변수를 사용하세요:
RAMPART_TOKEN
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기