도구 권한 및 보안
Elftia의 Agent 시스템은 AI에게 강력한 실행 능력을 부여하는 동시에 다계층 보안 보호 메커니즘도 제공합니다. 이 페이지에서는 권한 모드, 도구 민감도 분류, 확인 대화 흐름, 그리고 각 보안 계층의 작동 방식을 자세히 설명합니다.
권한 모드
권한 모드는 Agent가 도구를 실행할 때의 보안 수준을 결정합니다. Agent 구성의 permissionMode 필드에서 설정합니다.
모드 개요
| 모드 | ID | 동작 | 최적 사용 시나리오 |
|---|---|---|---|
| 기본 | default | 민감한 도구는 매번 사용자 확인 필요 | 일상 사용; 보안 우선 |
| 편집 허용 | acceptEdits | 파일 읽기/쓰기는 자동 승인; Shell/MCP 도구는 여전히 확인 필요 | 파일 작업이 신뢰되는 코딩 시나리오 |
| 권한 우회 | bypassPermissions | 모든 도구 자동 실행 | Agent를 완전히 신뢰하는 경우 |
| 플랜 | plan | 읽기 전용 도구만 허용 | 정보 수집, 분석, 계획 수립 |
모드 동작 비교
| 도구 | default | acceptEdits | bypassPermissions | plan |
|---|---|---|---|---|
| Read / Glob / Grep | 자동 | 자동 | 자동 | 자동 |
| Write / Edit | 확인 | 자동 | 자동 | 차단 |
| Bash | 확인 | 확인 | 자동 | 차단 |
| spawn_agent | 확인 | 확인 | 자동 | 차단 |
| MCP 도구 | 확인 | 확인 | 자동 | 차단 |
| WebSearch / WebFetch | 자동 | 자동 | 자동 | 자동 |
plan 모드에서 허용되는 도구
plan 모드에서는 다음 읽기 전용 도구만 허용됩니다:
Read— 파일 읽기ListDir— 디렉토리 목록 보기Glob— 파일 매칭Grep— 내용 검색WebSearch— 웹 검색WebFetch— 웹 페이지 가져오기list_skills— 스킬 목록 보기read_skill— 스킬 읽기
도구 민감도 분류
TinyElf 엔진은 도구를 두 가지 범주로 분류합니다: 안전한 도구와 민감한 도구.
안전한 도구 (확인 불필요)
| 도구 | 설명 |
|---|---|
Read | 파일 내용 읽기 |
ListDir | 디렉토리 목록 보기 |
Glob | 파일 이름 패턴 검색 |
Grep | 파일 내용 검색 |
WebSearch | 웹 검색 |
WebFetch | 웹 콘텐츠 가져오기 |
list_skills | 사용 가능한 스킬 목록 보기 |
read_skill | 스킬 내용 읽기 |
Notify | 데스크톱 알림 전송 |
SessionsYield | Agent 루프 종료 |
SessionsHistory | 세션 히스토리 보기 |
민감한 도구 (권한 모드에 따라 확인 필요)
| 도구 | 위험 설명 |
|---|---|
Bash | 임의의 셸 명령 실행 가능 |
Write | 파일 생성 또는 덮어쓰기 가능 |
Edit | 기존 파일 내용 수정 가능 |
spawn_agent | 서브 Agent를 실행하여 작업 수행 가능 |
MCP 도구 (mcp__*) | 동작을 예측할 수 없는 외부 도구 |
:::info MCP 도구는 기본적으로 민감한 도구로 처리됩니다 모든 MCP 도구는 기본적으로 민감한 도구로 취급됩니다. 이는 MCP 도구가 외부 서버에서 제공되며 Elftia가 그 동작을 사전에 감사할 수 없기 때문입니다. :::
확인 대화 흐름
Agent가 민감한 도구를 사용하려 할 때 (확인이 필요한 권한 모드에서), 시스템은 사용자에게 확인 대화를 표시합니다.
데스크톱 모드 흐름
Agent가 Bash("npm test") 실행 요청
↓
시스템이 권한 요청 전송 (IPC: permissionRequest)
↓
프론트엔드가 확인 대화 표시:
┌─────────────────────────────┐
│ Bash: npm test │
│ │
│ [허용] [거부] [세션 동안 허용] │
└─────────────────────────────┘
↓
사용자 선택 → 결과가 Agent에 반환
사용자 옵션
| 옵션 | 동작 |
|---|---|
| 허용 | 이번 실행만 승인 |
| 거부 | 이번 실행 거부; Agent가 거부 알림 수신 |
| 세션 동안 허용 | 이번에 승인하고, 세션 내 동일 도구의 이후 호출은 자동 승인 |
세션 수준 도구 허용 목록
"세션 동안 허용"을 선택하면 해당 도구 이름이 현재 세션의 허용 목록에 추가됩니다. 이후 동일 도구 호출은 추가 확인 없이 자동으로 승인됩니다. 허용 목록은 세션이 종료될 때 초기화됩니다.
타임아웃 처리
사용자가 5분 이내에 확인 대화에 응답하지 않으면 시스템이 자동으로 요청을 거부합니다.
3계층 보안 보호
TinyElf 엔진은 다음 순서로 실행되는 3계층 보안 보호 파이프라인을 구현합니다:
도구 호출 요청
↓
[1계층] ExecutionFirewall — 경로 및 명령 검증
↓ (통과)
[2계층] GuardianAgent — AI 보안 평가
↓ (통과)
[3계층] Permission Callback — 사용자 확인
↓ (통과)
도구 실행
어느 계층에서든 요청이 거부되면 도구 실행이 즉시 종료됩니다.
1계층: ExecutionFirewall
ExecutionFirewall은 경로 규칙에 따라 민감한 시스템 파일 및 디렉토리에 대한 접근을 차단하는 결정론적 보안 게이트웨이입니다.
차단되는 경로 유형:
| 경로 유형 | 예시 | 차단 작업 |
|---|---|---|
| 시스템 디렉토리 | C:\Windows\, /etc/, /usr/ | 읽기 및 쓰기 모두 차단 |
| 프로그램 디렉토리 | C:\Program Files\, /sbin/ | 읽기 및 쓰기 모두 차단 |
| 자격증명 파일 | .ssh/, .aws/, .gnupg/ | 읽기 및 쓰기 모두 차단 |
| SSH 키 | id_rsa, id_ed25519 | 읽기 및 쓰기 모두 차단 |
| 환경 변수 | .env, .env.production | 읽기 및 쓰기 모두 차단 |
| 브라우저 데이터 | Chrome/Firefox/Edge 사용자 데이터 | 읽기 및 쓰기 모두 차단 |
| 레지스트리 | System32\config\SAM 등 | 읽기 및 쓰기 모두 차단 |
| 구성 파일 | .gitconfig, .bashrc, .npmrc | 읽기 가능, 쓰기 불가 |
2계층: GuardianAgent
GuardianAgent는 LLM을 사용하여 도구 호출에 대한 보안 평가를 수행합니다. 선택 사항이며 구성을 통해 활성화됩니다.
작동 모드:
| 모드 | ID | 동작 |
|---|---|---|
| 꺼짐 | off | 비활성화 (오버헤드 없음) |
| 모니터 | monitor | 민감한 도구 검토; 로그만 기록하고 차단하지 않음 |
| 가드 | guard | 민감한 도구 검토; 높음 및 심각 위험 차단 |
| 엄격 | strict | 모든 도구 검토; 중간 위험 이상 차단 |
위험 수준:
| 위험 수준 | 의미 | 예시 |
|---|---|---|
none | 완전히 안전 | 워크스페이스 내 파일 읽기 |
low | 낮은 위험 | 프로젝트 파일 쓰기 |
medium | 중간 위험 | npm 패키지 설치, 상태 수정 |
high | 높은 위험 | 민감한 경로 접근, 네트워크 작업 |
critical | 심각한 위험 | rm -rf, 권한 상승, 데이터 유출 |
핵심 규칙 (항상 높음/심각으로 표시됨):
- 워크스페이스 외부의 파일 삭제
- 재귀적 삭제 명령
- 시스템 디렉토리 작업
- 권한 상승 (sudo, runas)
- 파이프 실행 (curl | sh)
- 자격증명 접근 또는 유출
- 보안 기능 우회
오류 처리 전략:
| 모드 | 타임아웃/오류 시 동작 |
|---|---|
monitor / guard | 실패 개방 (실행 허용) |
strict | 실패 폐쇄 (실행 거부) |
3계층: Permission Callback
마지막 계층은 사용자 확인으로, IPC 메시지를 통해 프론트엔드에 확인 요청을 전송합니다.
채널 권한 게이팅
Agent가 채널(Discord, Telegram 등)을 통해 메시지를 수신할 때 권한 확인 흐름이 달라집니다.
채널 사용자 역할
| 역할 | 도구 사용 | 확인 필요 여부 |
|---|---|---|
| 관리자 | 허용 | 권한 모드에 따라 |
| 멤버 | 허용 | 모든 도구에 확인 필요 |
| 게스트 | 불허 | 어떤 도구도 사용 불가 |
채널 확인 흐름
채널 세션에서의 확인은 데스크톱 대화가 아닌 채널 메시지를 통해 처리됩니다:
- Agent가 민감한 도구 실행 요청
- 시스템이 채널에 확인 메시지 전송
- 사용자가
y(허용) /n(거부) /always(항상 허용) 중 하나로 답변
"항상 허용"의 적용 범위:
always 답변의 범위는 "도구 이름 + 인수 지문" 조합으로 제한됩니다. 예를 들어:
Bash: npm test를 허용해도Bash: rm -rf /가 자동으로 허용되지 않습니다- 각각의 고유한 명령/경로 조합은 별도의 승인이 필요합니다
타임아웃 처리: 5분 동안 응답이 없으면 자동으로 거부됩니다. 채널당 최대 5개의 대기 중인 확인 요청이 동시에 존재할 수 있습니다.
감사 로그
모든 보안 관련 이벤트는 사후 추적을 위해 감사 로그에 기록됩니다.
| 이벤트 유형 | 설명 |
|---|---|
firewall_block | ExecutionFirewall이 접근 차단 |
guardian_review | GuardianAgent 검토 결과 |
permission_granted | 사용자가 도구 실행 승인 |
permission_denied | 사용자가 도구 실행 거부 |
permission_timeout | 확인 타임아웃; 자동 거부 |
command_blocked | 차단 목록에 의해 셸 명령 차단 |
injection_detected | 프롬프트 인젝션 감지 |
rate_limited | 속도 제한 트리거됨 |
FAQ
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 매번 확인 요청이 번거로움 | 권한 모드가 default임 | acceptEdits 또는 bypassPermissions로 설정 |
| Firewall이 정당한 작업을 차단 | 해당 작업이 시스템 경로 또는 자격증명 파일을 포함함 | 이는 예상된 동작이며 시스템 파일은 수정하지 않아야 함 |
| GuardianAgent가 안전한 작업을 잘못 차단 | 평가가 지나치게 보수적 | 모드를 strict에서 guard로 변경 |
| 채널 사용자가 도구를 사용할 수 없음 | 사용자 역할이 "게스트" | 사용자를 "멤버" 또는 "관리자"로 승격 |
| 세션 허용 목록이 갑자기 작동 안 함 | 세션이 종료되고 재시작됨 | 세션 허용 목록은 세션 간에 유지되지 않으므로 재승인 필요 |
| plan 모드에서 파일 편집 불가 | plan 모드는 읽기 전용 도구만 허용 | default 또는 acceptEdits 모드로 전환 |
관련 링크
- Agent 개요 — Agent 시스템 개요
- 커스텀 Agent 만들기 — 권한 모드 구성
- 스킬 시스템 — 스킬의 도구 허용 목록