정책, 명령, 샌드박싱

에이전트의 모든 도구 호출은 실행이 허용되기 전에 Revka의 SecurityPolicy를 통과합니다. 이 정책은 자율성 수준, 따옴표 인식 셸 파서를 갖춘 명령 허용 목록, 위험 분류, 워크스페이스 경계, 슬라이딩 윈도우 속도 제한기를 적용하며, 명령 실행 후에는 OS 수준의 샌드박스 백엔드가 추가로 감싸줍니다. 이 페이지는 해당 게이트 전체에 대한 구성 참조 문서로, 각 게이트가 확인하는 내용, 실행 순서, 그리고 이를 조정하는 [autonomy] 및 [security.sandbox] 키를 설명합니다.

배포를 강화하거나, 명령이 차단된 이유를 디버깅하거나, 에이전트가 접근할 수 있는 명령과 경로를 결정할 때 이 페이지를 참조하세요. 이 계층들이 암호화, 감사, 격리와 어떻게 결합되는지에 대한 개념적 모델은 먼저 보안 모델을 읽어보세요. 자율성 및 승인에 대한 개념적 설명은 자율성 수준 및 승인을 참조하세요.

참고

이 페이지의 모든 설정은 ~/.revka/config.toml에 있습니다. 파일을 직접 수정하거나, Supervised 자율성과 워크스페이스 범위 접근을 기본값으로 설정하는 온보딩 마법사를 통해 기본값을 구성할 수 있습니다. revka config schema를 실행하면 전체 JSON Schema를 출력합니다.

[autonomy] 구성 섹션

[autonomy]는 에이전트가 수행할 수 있는 작업을 제어하는 단일 섹션입니다. 자율성 수준, 셸 허용 목록, 파일시스템 경계, 승인 게이트, 정책별 예산을 설정합니다.

[autonomy]
level = "supervised"
workspace_only = true
allowed_commands = ["git", "python", "node"]
forbidden_paths = ["/etc", "/root", "/proc", "/sys", "~/.ssh", "~/.gnupg", "~/.aws"]
allowed_roots = ["~/Desktop/projects", "/opt/shared-repo"]
max_actions_per_hour = 20
max_cost_per_day_cents = 500
require_approval_for_medium_risk = true
block_high_risk_commands = true

키	타입	기본값	의미
level	string	"supervised"	자율성 모드: read_only, supervised, full 중 하나.
workspace_only	bool	true	allowed_roots에 포함되지 않는 워크스페이스 외부의 절대 경로를 거부합니다.
allowed_commands	list	[]	셸 명령 허용 목록: 이름, 전체 경로, 또는 모두 허용하는 "*" (위험 게이트는 여전히 적용됨).
forbidden_paths	list	내장 목록	기본적으로 차단되는 시스템 경로 및 민감한 닷 디렉터리.
allowed_roots	list	["~/.revka/workflows", "~/.revka/artifacts", "~/.revka/workspace"]	워크스페이스 외부에서도 접근 가능한 추가 루트 경로.
max_actions_per_hour	u32	20	정책별 작업 예산 (슬라이딩 1시간 윈도우).
max_cost_per_day_cents	u32	500	정책별 일일 LLM 지출 한도 (US$5.00).
require_approval_for_medium_risk	bool	true	중간 위험 명령에 대한 승인 게이트.
block_high_risk_commands	bool	true	고위험 명령에 대한 하드 블록.
auto_approve	list	내장 읽기 전용 도구 목록 (file_read, web_search_tool, web_fetch, calculator, glob_search, content_search, image_info, weather; 사용자 항목과 병합)	항상 자동 승인되는 도구 작업.
always_ask	list	[]	항상 승인을 요구하는 도구 작업.

현재 자율성 수준은 모델이 자신의 제약 조건을 인식할 수 있도록 LLM 시스템 프롬프트에 자동으로 주입됩니다.

자율성 수준

정책 엔진의 진입점은 에이전트의 행동 가능 여부를 결정하는 3단계 모드입니다.

수준	동작
read_only	관찰만 가능합니다. ls, cat과 같은 안전한 읽기 작업을 포함한 모든 도구 동작이 차단됩니다. 신뢰할 수 없는 채널에 가장 안전한 선택입니다.
supervised	기본값입니다. 허용 목록 내에서 동작하며, 중간 및 고위험 명령은 명시적인 승인(approved = true)이 필요합니다.
full	승인 게이트 없이 동작하지만, 명령 허용 목록, 위험 차단, 워크스페이스 경계, 속도 제한은 여전히 적용됩니다.

[autonomy]
level = "supervised"   # read_only | supervised | full

주의

full은 중간 위험 승인 프롬프트를 건너뛰지만, 구성된 가드레일을 비활성화하지는 않습니다. 허용 목록, 고위험 차단, 경로 샌드박싱, 속도 제한은 모두 유지됩니다.

명령 허용 목록 및 셸 파서

모든 셸 명령은 실행 전에 allowed_commands에 대해 검사됩니다. 이 검사는 따옴표 인식 셸 렉서를 사용하여 복합 입력을 따옴표 없는 ;, |, &&, || 및 줄 바꿈으로 분리한 뒤, 각 하위 명령을 개별적으로 검증합니다. 이를 통해 명령 체이닝을 통한 우회를 방지합니다. 허용된 명령 뒤에 차단된 명령을 추가하는 방식으로 게이트를 우회할 수 없습니다.

[autonomy]
allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep", "find",
                    "echo", "pwd", "wc", "head", "tail", "date", "df",
                    "du", "uname", "uptime", "hostname", "python", "python3",
                    "pip", "node"]

참고

Windows에서는 기본 목록에 dir, type, findstr, where, more 및 Windows 동등 명령도 포함됩니다.

5가지 우회 방지 게이트

각 후보 명령은 순서대로 5가지 독립적인 검사를 통과해야 합니다. 하나라도 실패하면 해당 명령은 거부됩니다.

1. 서브셸 연산자 — 백틱 `, $(...), 프로세스 치환 <(...) / >(...) 은 거부됩니다.

2. 리다이렉션 — 입출력 리다이렉트 < 및 >는 거부됩니다.

3. tee — 임의 파일에 쓰기 때문에 허용 목록에 관계없이 항상 차단됩니다.

4. 백그라운드 & — 단독 후행 & (백그라운드 실행)는 거부됩니다.

5. 세그먼트별 허용 목록 — 분리된 각 하위 명령은 basename, 전체 경로, 또는 와일드카드 "*"로 허용 목록의 항목과 일치해야 합니다.

허용 목록 항목 형식

형식	매칭 대상	예시
단순 이름	해당 basename을 가진 모든 실행 파일	"git"은 /usr/bin/git과 git 모두에 매칭됨
전체 경로	해당 정확한 실행 파일 경로만	"/usr/bin/antigravity"
와일드카드 "*"	모든 명령 이름	"*"

"*"를 사용하더라도 위험한 인수 패턴은 차단 상태로 유지됩니다. find -exec, find -ok, git config, git -c, git alias는 git 또는 find가 허용 목록에 있어도 임의 인수 주입을 허용하기 때문에 거부됩니다. "*" 와일드카드는 block_high_risk_commands도 우회하지 않습니다 — 고위험 안전망은 그대로 유지됩니다.

명령 위험 분류

모든 명령, 그리고 복합 명령의 각 세그먼트는 낮음 / 중간 / 높음 위험으로 분류됩니다. 파이프라인이나 체인은 임의 세그먼트 중 가장 높은 위험 수준을 상속합니다. 분류기는 argv 파싱 후 각 후보를 다음 방법으로 평가합니다.

1. basename 조회 (rm, git, powershell, …).
2. 위험도가 하위 명령 동사에 따라 달라지는 명령(git, npm, cargo)의 경우, 해당 동사를 화이트리스트와 대조 확인.
3. basename만으로는 안전해 보이더라도 알려진 파괴적 패턴을 찾기 위해 결합된 명령 문자열 스캔 (rm -rf /, fork-bomb, format c:).

[autonomy]
block_high_risk_commands = true          # 기본값 — 높음 위험 명령은 디스패치 전 거부됨
require_approval_for_medium_risk = true  # 기본값 — 중간 위험 명령은 승인 대기열로 라우팅됨

높음 위험

block_high_risk_commands = true(기본 설정)일 때 완전히 차단됩니다. false로 설정하면 높음 위험 명령도 중간 위험과 동일한 승인 게이트를 거칩니다.

카테고리	명령
파일 삭제	rm, mkfs, dd
전원 / 부팅	shutdown, reboot, halt, poweroff
권한 상승	sudo, su, runas
권한 / 소유권	chown, chmod, icacls, takeown
계정 관리	useradd, userdel, usermod, passwd
파일시스템 마운트	mount, umount
방화벽	iptables, ufw, firewall-cmd, netsh
외부 네트워크	curl, wget, nc, ncat, netcat, scp, ssh, ftp, telnet
Windows 레지스트리 / 서비스	reg, net, wmic, sc
Windows 셸 / 스크립트	powershell, pwsh
Windows 파괴적 명령	del, rmdir, format

파괴적 패턴 매처 (basename이 안전하더라도 높음으로 분류됨):

• 결합된 세그먼트 내 어디서든 나타나는 rm -rf / 및 rm -fr /
• 고전적인 fork-bomb 리터럴 :(){:|:&};:
• Windows 재귀 삭제 리터럴 del /s /q 및 rmdir /s /q
• format c: 리터럴

중간 위험

require_approval_for_medium_risk = true(기본 설정)일 때 승인이 필요합니다. level = "full"이면 이 게이트는 건너뜁니다(다른 가드레일은 여전히 적용됨).

도구	중간 위험으로 전환되는 동사
git	commit, push, reset, clean, rebase, merge, cherry-pick, revert, branch, checkout, switch, tag
npm / pnpm / yarn	install, add, remove, uninstall, update, publish
cargo	add, remove, install, clean, publish

basename만으로 중간 위험인 명령 (인수에 관계없이): touch, mkdir, mv, cp, ln, 그리고 Windows 동등 명령 copy, xcopy, robocopy, move, ren, rename, mklink.

낮음 위험

그 외 나머지 — 읽기 전용이거나 안전한 명령은 승인 없이 실행됩니다: ls, cat, grep, find, git status, git log, npm ls, cargo check, cargo test, which, ps, df. 분류기는 모든 안전한 명령을 열거하는 대신 기본적으로 낮음으로 분류하므로, 높음 및 중간 목록은 보수적으로 유지됩니다.

참고

명시적 허용 목록 예외. ssh와 같은 고위험 명령을 와일드카드가 아닌 항목으로 allowed_commands에 추가하면 해당 명령에 대해 block_high_risk_commands를 우회할 수 있습니다. 단, supervised 모드에서는 여전히 approved = true가 필요합니다. 반면 allowed_commands = ["*"]와 block_high_risk_commands = false를 함께 설정하면 모든 명령 수준의 위험 게이트가 비활성화됩니다.

주의

위험 목록은 Revka가 제공하는 보안 태세의 일부이며, src/security/policy.rs를 기준으로 관리됩니다. 이 표의 내용이 실행 중인 바이너리와 다를 경우, 코드가 기준이 됩니다 — 이슈를 등록해 주세요.

경로 샌드박싱 및 워크스페이스 경계

6가지 독립적인 검사가 파일 작업을 워크스페이스 내부로 제한하며, 심볼릭 링크 탈출을 방지하는 정규화 후 검사도 포함됩니다.

[autonomy]
workspace_only = true      # 기본값 — 워크스페이스로 제한
allowed_roots = ["/data/shared", "~/projects/other"]
forbidden_paths = ["/etc", "/root", "/home", "~/.ssh", "~/.aws", "~/.config"]

순서대로 실행되는 검사:

1. Null 바이트 주입 — \0을 포함하는 경로는 거부됩니다.
2. .. 경로 탐색 — .. 경로 구성 요소가 있으면 거부됩니다.
3. URL 인코딩된 경로 탐색 — ..%2f와 같은 인코딩된 형식은 거부됩니다.
4. ~user 틸다 확장 — ~otheruser/... 참조는 거부됩니다.
5. 워크스페이스 전용 절대 경로 잠금 — workspace_only = true일 때, 절대 경로는 workspace_dir 또는 allowed_roots의 항목 아래에 있어야 합니다.
6. 금지 접두사 차단 목록 — 경로가 forbidden_paths(예: /etc, /root, ~/.ssh, ~/.aws)에 대해 접두사 매칭됩니다.

경로가 결합되고 정규화된 후, 추가적인 해석된 경로 검사가 최종 위치를 재검증합니다. 이를 통해 심볼릭 링크 탈출(워크스페이스 내부에서 외부를 가리키는 링크)을 감지합니다.

필드 참조

키	타입	기본값	의미
workspace_only	bool	true	false이면, 워크스페이스 외부 경로는 forbidden_paths에 의해서만 차단됩니다.
allowed_roots	list	["~/.revka/workflows", "~/.revka/artifacts", "~/.revka/workspace"]	workspace_only = true일 때도 에이전트가 접근할 수 있는 절대 경로. 틸다 확장이 적용되며, 상대 항목은 워크스페이스 기준으로 해석됩니다.
forbidden_paths	list	내장 목록	틸다 확장된 경로에 대해 접두사 매칭됩니다. 워크스페이스/허용 루트 검사 이후에 확인됩니다.

참고

우선순위 순서가 중요합니다. 워크스페이스와 allowed_roots는 forbidden_paths보다 먼저 검사됩니다. 따라서 그렇지 않으면 금지된 트리 내에 중첩된 워크스페이스 — 예를 들어 /home이 forbidden_paths에 있을 때 /home 아래의 워크스페이스 — 는 여전히 허용됩니다. 쓰기가 워크스페이스 이탈로 거부될 경우, 오류 메시지에서 해당 경로를 allowed_roots에 추가하도록 안내합니다.

Revka 자체의 런타임 구성 파일(config.toml, active_workspace.toml)은 에이전트 수정에 대해 별도로 보호됩니다. 이 보호는 자동으로 적용되며 재정의할 수 없습니다.

속도 제한 (작업 및 비용)

두 가지 독립적인 예산이 에이전트의 작업량을 제한합니다. 슬라이딩 1시간 윈도우가 작업 횟수를 추적하며, 에이전트가 max_actions_per_hour에 도달하면 윈도우가 만료될 때까지 모든 Act 유형의 도구 작업이 차단됩니다. 별도의 일일 한도(max_cost_per_day_cents)는 LLM API 지출을 제한합니다. 파일 읽기 등의 읽기 작업은 속도 제한을 받지 않습니다.

[autonomy]
max_actions_per_hour = 20      # 기본값
max_cost_per_day_cents = 500   # 기본값 (US$5.00)

키	타입	기본값	의미
max_actions_per_hour	u32	20	인메모리 슬라이딩 윈도우로 집계됩니다.
max_cost_per_day_cents	u32	500	별도의 비용 추적기에 의해 적용됩니다.

작업 예산이 소진되면 정책은 Rate limit exceeded: action budget exhausted를 반환합니다.

주의

작업 속도 윈도우는 인메모리로 유지되며 데몬이 재시작되면 초기화됩니다. 영구적인 계정 수준의 지출 제어를 위해서는 일별/월별 한도를 적용하는 별도의 [cost] 예산 섹션을 구성하세요.

OS 수준 샌드박스 백엔드

애플리케이션 계층 정책 위에, 명령 실행을 OS 격리 백엔드로 감쌀 수 있습니다. 시작 시 자동 감지가 사용 가능한 최선의 백엔드를 선택합니다. 각 백엔드는 단일 Sandbox 트레이트를 구현하므로 플러그인 형태로 교체 가능하며 플랫폼에 종속되지 않습니다.

[security.sandbox]
enabled = true
backend = "auto"   # auto | none | firejail | bubblewrap | landlock | sandbox-exec | docker

백엔드	플랫폼	비고
firejail	Linux	루트 권한 불필요한 사용자 공간 샌드박싱. Linux에서 가장 쉽게 설정 가능.
bubblewrap	Linux / macOS	사용자 네임스페이스 컨테이너. sandbox-bubblewrap 기능 필요.
landlock	Linux 5.13+	커널 수준의 파일시스템 제한으로 가장 강력한 격리를 제공. sandbox-landlock 기능 필요.
sandbox-exec	macOS	Apple Seatbelt 샌드박스 프로파일.
docker	전체	Docker 컨테이너 내 서브프로세스 격리. 명령당 스폰 오버헤드가 있음.
none	전체	애플리케이션 계층 보안만 적용. 항상 사용 가능한 폴백.

키	타입	기본값	의미
enabled	bool	—	false로 설정하면 모든 OS 샌드박싱이 비활성화됩니다.
backend	string	"auto"	"auto"는 사용 가능한 최선의 백엔드를 선택하며, 명시적으로 지정할 수도 있습니다.

요청된 백엔드가 런타임에 사용 불가능한 경우, Revka는 no-op 샌드박스로 폴백하고 경고를 기록합니다. 정책 엔진은 허용 목록, 위험 게이트, 경로 경계를 여전히 적용하며 자동으로 열린 상태로 실패하지 않습니다.

샌드박스 기능과 함께 빌드하기

무거운 백엔드는 컴파일 타임 Cargo 기능 플래그 뒤에 있으므로, 비활성화된 백엔드는 바이너리 크기에 전혀 영향을 주지 않습니다.

Linux (Landlock)

cargo build --release --features sandbox-landlock

Linux / macOS (Bubblewrap)

cargo build --release --features sandbox-bubblewrap

Default release

# Firejail, sandbox-exec, Docker, and the no-op fallback need no extra features.
cargo build --release

팁

Linux에서는 Firejail이 가장 빠른 방법입니다 (sudo apt install firejail 후 backend = "firejail" 설정). Landlock은 가장 강력한 커널 수준의 파일시스템 격리를 제공하지만 Linux 5.13 이상이 필요합니다. Docker 백엔드는 가장 완전한 격리를 제공하지만 명령당 스폰 오버헤드가 발생합니다.

전체 기능 매트릭스는 Cargo 기능 플래그 및 ADR을 참조하세요.

샌드박싱 로드맵

위의 백엔드들은 현재 기능 플래그와 자동 감지를 통해 런타임에 연결되어 있습니다. 원래 샌드박싱 제안에서는 아직 안정적인 구성 표면이 아닌 백엔드별 튜닝도 설계되었습니다.

• Firejail 추가 인수 (예: --seccomp, --caps.drop=all).
• Landlock 명시적 읽기 전용 / 읽기-쓰기 경로 목록.

이러한 튜닝 옵션은 현재 동작이 아닌 로드맵으로 취급하세요. 위에 문서화된 [security.sandbox] 키 — enabled 및 backend — 가 현재 지원되는 구성 표면입니다.

강화 체크리스트

1. 적절한 자율성 수준을 선택하세요. 신뢰할 수 없는 채널에는 read_only를 사용하고, 사람이 위험한 작업을 승인할 수 있는 경우 supervised(기본값)를 유지하며, 신뢰할 수 있는 범위가 좁은 자동화에만 full을 사용하세요.

2. 허용 목록의 범위를 좁게 설정하세요. "*" 대신 명시적인 allowed_commands 목록을 사용하세요. "*"와 block_high_risk_commands = false를 함께 사용하는 것은 피하세요.

3. 워크스페이스를 잠그세요. workspace_only = true를 유지하고, 에이전트가 필요한 특정 allowed_roots만 추가하세요.

4. 현실적인 예산을 설정하세요. 워크로드에 맞게 max_actions_per_hour 및 max_cost_per_day_cents를 조정하고, 영구적인 [cost] 예산과 함께 사용하세요.

5. OS 샌드박스를 활성화하세요. [security.sandbox].enabled = true로 설정하고 backend = "auto"로 자동 선택하거나, 사용 가능한 것으로 확인된 백엔드를 명시하세요.

6. 변경할 때마다 검증하세요. revka doctor를 실행하고 감사 로그를 검토하여 게이트가 의도한 대로 동작하는지 확인하세요.

관련 페이지

보안 모델 정책, 샌드박스, 암호화, 감사 계층이 어떻게 심층 방어를 구성하는지 설명합니다.

자율성 수준 및 승인 자율성 모드와 승인 흐름에 대한 개념적 설명입니다.

OTP 게이팅 및 긴급 정지 TOTP 게이팅 작업과 OTP 게이팅 재개 기능이 있는 비상 정지 킬 스위치입니다.

감사 로그 Merkle 체인 이벤트 로그, HMAC 서명, API를 통한 무결성 검증입니다.

시크릿, 페어링 및 기기 인증 암호화된 시크릿 저장소, 페어링 흐름, 베어러 토큰 관리입니다.

구성 개요 전체 config.toml 참조, 우선순위, 스키마입니다.