본문으로 건너뛰기

도구 권한 및 보안

Elftia의 Agent 시스템은 AI에게 강력한 실행 능력을 부여하는 동시에 다계층 보안 보호 메커니즘도 제공합니다. 이 페이지에서는 권한 모드, 도구 민감도 분류, 확인 대화 흐름, 그리고 각 보안 계층의 작동 방식을 자세히 설명합니다.

권한 모드​

권한 모드는 Agent가 도구를 실행할 때의 보안 수준을 결정합니다. Agent 구성의 permissionMode 필드에서 설정합니다.

모드 개요​

모드ID동작최적 사용 시나리오
기본default민감한 도구는 매번 사용자 확인 필요일상 사용; 보안 우선
편집 허용acceptEdits파일 읽기/쓰기는 자동 승인; Shell/MCP 도구는 여전히 확인 필요파일 작업이 신뢰되는 코딩 시나리오
권한 우회bypassPermissions모든 도구 자동 실행Agent를 완전히 신뢰하는 경우
플랜plan읽기 전용 도구만 허용정보 수집, 분석, 계획 수립

모드 동작 비교​

도구defaultacceptEditsbypassPermissionsplan
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데스크톱 알림 전송
SessionsYieldAgent 루프 종료
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 등)을 통해 메시지를 수신할 때 권한 확인 흐름이 달라집니다.

채널 사용자 역할​

역할도구 사용확인 필요 여부
관리자허용권한 모드에 따라
멤버허용모든 도구에 확인 필요
게스트불허어떤 도구도 사용 불가

채널 확인 흐름​

채널 세션에서의 확인은 데스크톱 대화가 아닌 채널 메시지를 통해 처리됩니다:

  1. Agent가 민감한 도구 실행 요청
  2. 시스템이 채널에 확인 메시지 전송
  3. 사용자가 y (허용) / n (거부) / always (항상 허용) 중 하나로 답변

"항상 허용"의 적용 범위:

always 답변의 범위는 "도구 이름 + 인수 지문" 조합으로 제한됩니다. 예를 들어:

  • Bash: npm test를 허용해도 Bash: rm -rf /가 자동으로 허용되지 않습니다
  • 각각의 고유한 명령/경로 조합은 별도의 승인이 필요합니다

타임아웃 처리: 5분 동안 응답이 없으면 자동으로 거부됩니다. 채널당 최대 5개의 대기 중인 확인 요청이 동시에 존재할 수 있습니다.

감사 로그​

모든 보안 관련 이벤트는 사후 추적을 위해 감사 로그에 기록됩니다.

이벤트 유형설명
firewall_blockExecutionFirewall이 접근 차단
guardian_reviewGuardianAgent 검토 결과
permission_granted사용자가 도구 실행 승인
permission_denied사용자가 도구 실행 거부
permission_timeout확인 타임아웃; 자동 거부
command_blocked차단 목록에 의해 셸 명령 차단
injection_detected프롬프트 인젝션 감지
rate_limited속도 제한 트리거됨

FAQ​

문제원인해결 방법
매번 확인 요청이 번거로움권한 모드가 default임acceptEdits 또는 bypassPermissions로 설정
Firewall이 정당한 작업을 차단해당 작업이 시스템 경로 또는 자격증명 파일을 포함함이는 예상된 동작이며 시스템 파일은 수정하지 않아야 함
GuardianAgent가 안전한 작업을 잘못 차단평가가 지나치게 보수적모드를 strict에서 guard로 변경
채널 사용자가 도구를 사용할 수 없음사용자 역할이 "게스트"사용자를 "멤버" 또는 "관리자"로 승격
세션 허용 목록이 갑자기 작동 안 함세션이 종료되고 재시작됨세션 허용 목록은 세션 간에 유지되지 않으므로 재승인 필요
plan 모드에서 파일 편집 불가plan 모드는 읽기 전용 도구만 허용default 또는 acceptEdits 모드로 전환

관련 링크​