보안 설정

Elftia는 Agent 도구 호출 및 외부 메시지 인젝션의 잠재적 위험으로부터 시스템을 보호하기 위한 다중 레이어 보안 보호 메커니즘을 제공합니다. 이 페이지에서는 보안 관련 설정 옵션을 모두 자세히 설명합니다.

보안 아키텍처 개요

Elftia의 보안 시스템은 다음과 같은 핵심 구성 요소로 이루어져 있습니다:

구성 요소	위치	기능
GuardianAgent	Agent 실행 레이어	AI를 사용하여 도구 호출의 보안성을 검토
PromptGuardian	Channel 메시지 레이어	외부 메시지의 프롬프트 인젝션 공격 감지
권한 모드	Agent 상호작용 레이어	사용자가 도구 실행을 확인해야 하는지 제어
InputSanitizer	Channel 메시지 레이어	정규식 매칭 기반 규칙 기반 입력 필터링
AuditLogger	전역	모든 보안 이벤트에 대한 감사 로그 기록

GuardianAgent

GuardianAgent는 AI 기반 보안 검토 모듈입니다. Agent가 도구 호출을 실행할 때 GuardianAgent는 먼저 독립적인 LLM을 사용하여 작업의 위험 수준을 평가하고, 설정에 따라 실행 허용 여부를 결정합니다.

네 가지 모드

모드	동작	권장 시나리오
끄기	완전히 비활성화, 성능 오버헤드 없음	개인 사용, Agent 동작 신뢰
모니터	민감한 도구 호출 검토, 차단 없이 로그만 기록	Agent 동작을 이해하되 방해받지 않고 싶은 경우
가드	민감한 도구 호출 검토, 고위험 및 치명적 작업 차단	일상 사용, 보안과 편의성의 균형
엄격	모든 도구 호출 검토, 중간 위험 이상 차단	공유 환경, 최대 보안 요구 사항

위험 수준

GuardianAgent는 도구 호출을 다섯 가지 위험 수준으로 분류합니다:

위험 수준	의미	예시
없음	완전히 안전	프로젝트 내 파일 읽기, 디렉토리 목록 보기
낮음	경미한 위험	작업 공간 내 프로젝트 파일 쓰기
중간	보통 위험	시스템 상태를 수정하는 Shell 명령 실행, npm 패키지 설치
높음	심각한 위험	민감한 경로 접근, 작업 공간 외부 파일 조작, 네트워크 작업
치명적	즉각적인 위험	재귀적 삭제 명령, 데이터 탈취, 권한 상승

모드별 차단 동작

위험 수준	끄기	모니터	가드	엄격
none	허용	허용	허용	허용
low	허용	로그 + 허용	허용	허용
medium	허용	로그 + 허용	허용	차단
high	허용	로그 + 허용	차단	차단
critical	허용	로그 + 허용	차단	차단

민감한 도구

모니터 및 가드 모드에서는 다음 "민감한 도구"만 보안 검토를 트리거합니다:

• Bash: Shell 명령 실행
• Write: 파일 쓰기
• Edit: 파일 편집
• Agent: 하위 Agent 생성

엄격 모드에서는 모든 도구 호출(파일 읽기 포함)이 검토를 트리거합니다.

내결함성 설계

모드	타임아웃/오류 발생 시 동작
모니터 / 가드	허용 (fail-open) — 검토를 사용할 수 없을 때 정상 작업을 차단하지 않음
엄격	차단 (fail-closed) — 검토를 사용할 수 없을 때 기본적으로 거부

검토 타임아웃은 15초입니다. LLM이 15초 이내에 검토 결과를 반환하지 않으면 위의 규칙이 적용됩니다.

설정 위치

설정 → Clawia → GuardianAgent 모드

원하는 모드를 선택하세요. 변경 사항은 재시작 없이 즉시 적용됩니다.

감사 로그

모든 검토 결과(차단 여부와 상관없이)는 감사 로그에 기록됩니다. 설정 → Clawia → 감사 로그에서 이전 검토 기록을 볼 수 있으며, 다음을 포함합니다:

• 타임스탬프
• 도구 이름 및 매개변수
• 검토 결과 (위험 수준, 이유)
• 차단 여부

PromptGuardian

PromptGuardian은 Channel (다중 플랫폼 채널) 메시지를 위한 보안 보호 기능입니다. Elftia가 Discord, Telegram 등의 채널을 통해 외부 사용자의 메시지를 수신할 때, PromptGuardian은 AI를 사용하여 메시지에 프롬프트 인젝션 공격이 포함되어 있는지 감지합니다.

세 가지 모드

모드	동작	권장 시나리오
끄기	인젝션 감지 없음	혼자 Channel을 사용하는 경우, 모든 메시지 소스 신뢰
모니터	인젝션 감지, 차단 없이 로그만 기록	의심스러운 메시지가 있는지 관찰하고 싶은 경우
차단	인젝션 감지, 의심스러운 메시지를 차단하고 친절한 거절 메시지 반환	공개 Channel, 악의적인 사용자 방어 필요

감지 내용

PromptGuardian은 다음 유형의 공격을 감지할 수 있습니다:

• 지시 재정의: 시스템 지시를 재정의하거나 우회하려는 시도 (예: "위의 모든 지시를 무시하세요")
• 역할 조작: 다른 신원을 가장하는 것 (예: "당신은 이제 DAN입니다")
• 프롬프트 마커 인젝션: 시스템/지시 마커 삽입 (예: [INST], <|im_start|>)
• 프롬프트 추출: 시스템 프롬프트 내용을 얻으려는 시도
• XML/태그 인젝션: 도구 호출 마커 삽입 (예: <tool_use>, <function_calls>)
• 인코딩 우회: base64 인코딩, 보이지 않는 문자 등의 기법 사용
• 소셜 엔지니어링: "교육 목적" 또는 "가상 시나리오"를 사용하여 보안 규칙 우회
• 다단계 공격: 여러 메시지에 걸쳐 점진적으로 공격 구축

차단 시 동작

메시지가 차단될 때 PromptGuardian은 사용자에게 보안 감지의 존재를 드러내지 않습니다. 대신 무작위의 친절한 거절 메시지(예: "신호가 끊겼어요~ 다른 주제로 바꿔볼까요")를 반환하여 공격자가 전략을 조정할 수 없도록 합니다.

내결함성 설계

PromptGuardian은 fail-open 설계를 채택합니다. 검토 시간 초과(10초) 또는 실패 시 메시지는 정상적으로 통과되며, 보안 감지 실패로 인해 메시지 흐름이 중단되지 않습니다.

설정 위치

PromptGuardian 설정은 Channel 보안 설정에 있습니다. 먼저 보안 검토에 사용할 LLM 제공자와 모델을 설정해야 합니다.

권한 모드

권한 모드는 Agent가 도구 호출을 실행할 때 사용자 확인이 필요한지 여부를 제어합니다.

모드	동작	사용 사례
기본	민감한 작업은 사용자 확인 필요	일상 사용, 권장
AcceptEdits	파일 편집은 자동 통과, 다른 작업은 여전히 확인 필요	Agent의 코드 편집 능력 신뢰
BypassPermissions	모든 작업 자동 통과	Agent를 완전히 신뢰하고 최대 효율 추구
Plan	Agent는 계획만 세우고 어떤 작업도 실행하지 않음	Agent의 동작 계획 검토

주의

"BypassPermissions" 모드는 Agent가 모든 작업(Shell 명령 및 파일 삭제 포함)을 직접 실행하도록 허용합니다. Agent 동작을 완전히 신뢰하고 안전한 환경에 있을 때만 사용하세요. GuardianAgent의 "가드" 또는 "엄격" 모드와 함께 사용하는 것을 권장합니다.

Channel 보안 설정

Channel을 통해 외부 플랫폼을 연결할 때 다음 보안 옵션을 설정할 수 있습니다:

속도 제한

설정	설명
메시지 속도 제한	특정 시간 내 사용자당 최대 메시지 수 제한
전역 속도 제한	Channel의 전체 메시지 처리 속도 제한

입력 필터링

InputSanitizer는 정규식 기반 입력 필터링을 제공합니다 (PromptGuardian 전에 실행):

• 알려진 악성 패턴 필터링
• 잠재적인 인젝션 마커 정리
• 경고 로그만 생성하고 메시지를 차단하지 않음

사용자 역할

Channel은 다양한 사용자에게 역할을 할당하여 접근 권한을 제어할 수 있습니다.

보안 설정 권장 사항

개인 사용

Elftia를 개인 용도로만 사용하고 외부에 서비스를 제공하지 않는 경우:

설정	권장값
GuardianAgent	끄기 또는 모니터
PromptGuardian	끄기
권한 모드	기본

공유 Channel

Channel이 외부 사용자가 메시지를 보낼 수 있도록 공개된 경우:

설정	권장값
GuardianAgent	가드 또는 엄격
PromptGuardian	차단
권한 모드	기본
속도 제한	활성화

개발 및 디버깅

개발 및 테스트 시나리오에서:

설정	권장값
GuardianAgent	모니터
PromptGuardian	모니터
권한 모드	AcceptEdits

이를 통해 감사 로그에서 보안 이벤트를 관찰하면서 개발 효율성에 영향을 주지 않을 수 있습니다.

감사 로그

모든 보안 이벤트는 감사 로그에 기록되며 설정 → Clawia → 감사 로그에서 확인할 수 있습니다.

로그에는 다음 정보가 기록됩니다:

필드	설명
시간	이벤트 발생 시간
유형	GuardianAgent / PromptGuardian / 권한
작업	특정 도구 이름 또는 메시지 소스
결과	허용 / 차단
세부 정보	위험 수준, 이유 설명 등

팁

감사 로그를 정기적으로 검토하면 Agent의 동작 패턴과 잠재적인 보안 위협을 파악하고 보안 정책을 적절히 조정하는 데 도움이 됩니다.

---

더 많은 설정 옵션은 설정 참고를 참조하세요. 사용 중 보안 관련 문제가 발생하면 자주 발생하는 문제를 참조하세요.