> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 보안 아키텍처

> 암호화, 감사 추적 및 PII 보호 기능을 갖춘 6계층 심층 방어 보안 모델입니다.

# 보안 아키텍처

Myrm은(는) 6개 계층으로 심층 방어 보안 모델을 구현하여 광범위한 자율성이 부여된 경우에도 에이전트가 안전하게 작동하도록 보장합니다.

## 보안 계층

| Layer    | Function                  | How It Works                                                                                                                                                                                                                                                                  |
| -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **L1**   | Budget Control            | MultidimensionalBudgetGuard (per-session / daily / per-call) with 4-level progressive response (warn → eco → finalize → block) + Per-channel budget isolation (DailyBudgetGuard + SSE alerts + DB persistence) + GoalBudget (max\_tokens / max\_usd / max\_time / max\_turns) |
| **L2**   | Permission                | 12-dimension tool and resource access policies                                                                                                                                                                                                                                |
| **L3**   | Rate Limiting             | HTTP signature detection + minimum recovery time + SSE event throttling                                                                                                                                                                                                       |
| **L4**   | Loop Detection            | 7 detectors (repetition, ping-pong, no-progress, divergence, output-diminishing, consecutive-failures, error-signature) + FrequencyGuard (100 calls/60s global, 30/tool/60s) + progressive WARN→BREAK hard-stop                                                               |
| **L5**   | PII Protection            | Automatic PII detection, redaction, and taint tracking                                                                                                                                                                                                                        |
| **L5.5** | Trajectory Classification | Behavioral analysis with blind trajectory classifier for anomaly detection                                                                                                                                                                                                    |

## 승인 모드

에이전트의 자율성 정도를 제어합니다.

| Mode             | Description                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| **Auto**         | Read-only operations auto-approved, writes require confirmation                                         |
| **YOLO**         | All operations auto-approved (for trusted environments)                                                 |
| **HITL**         | Human-in-the-loop approval for every action                                                             |
| **Always-Allow** | Per-tool permanent approval with 4-level granularity (permission / tool / exact-args / command-pattern) |
| **Domain-HITL**  | Approval based on domain/resource classification                                                        |

### 세션 보안 사전 설정

입력 도구 모음에서 채팅 세션별로 보안 상태를 전환합니다. 전역 설정을 변경할 필요가 없습니다.

| Preset                 | Behavior                                                                                           | Use Case                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| **HITL** (default)     | Every tool call requires approval                                                                  | Sensitive tasks, production environments      |
| **Auto-Approve Edits** | File reads/writes auto-approved; shell, browser, MCP require approval with AI-powered smart review | Coding, document editing, routine development |
| **Read-Only**          | All write operations denied; reads auto-approved                                                   | Code review, exploration, research            |

* 사전 설정은 **YOLO 모드와 상호 배타적**입니다. 기본이 아닌 사전 설정을 선택하면 자동으로 YOLO가 비활성화되고 그 반대의 경우도 마찬가지입니다.
* `Auto-Approve Edits` 사전 설정은 셸 명령에 대한 **기록 분류자**(LLM 기반 스마트 검토)를 활성화합니다. 의심스러운 명령은 여전히 ​​사람의 검토를 트리거하므로 담요 ALLOW보다 안전합니다.
* `Read-Only` 사전 설정은 읽기 및 에이전트 위임을 열린 상태로 유지하면서 쓰기 작업(파일 쓰기/편집/삭제, 셸, 코드 해석기, 브라우저 자동화, 스킬/크론 관리)의 12가지 범주를 정확하게 거부합니다.
* 에이전트 모드에서만 사용할 수 있습니다. 빠른 검색 모드에서는 선택기가 자동으로 숨겨집니다.

### 계획 검토

복잡한 작업을 실행하기 전에 상담원은 사용자 검토 계획을 제안할 수 있습니다. 설정 → 보안에서 **계획 검토**가 활성화된 경우:

* 상담원의 첫 번째 계획 생성은 채팅 UI에서 **PlanConfirmationCard**를 트리거합니다.
* 사용자는 **확인**(현재대로 진행), **수정**(실행 전 계획 수정) 또는 **건너뛰기**(에이전트가 계획 제약 없이 진행하도록 허용)를 수행할 수 있습니다.
* Deep Research 및 General Agent 워크플로를 모두 지원합니다.
* 승인 모드와 함께 작동합니다. YOLO가 활성화된 경우에도 계획 검토가 여전히 필요할 수 있습니다.

이는 에이전트가 작업을 시작하기 전에 높은 수준의 체크포인트를 제공하여 도구 호출별 승인 시스템을 보완합니다.

### 구조화된 설명

상담원은 조치를 취하기 전에 `ask_question_tool`를 사용하여 구조화된 질문을 할 수 있습니다.

* 단일 선택, 객관식, 자유 텍스트 질문 유형
* 프런트엔드는 일반 텍스트 채팅이 아닌 전용 **ClarificationInput** 양식을 렌더링합니다.
* 응답은 구조화된 데이터로 에이전트 루프로 다시 전달됩니다.
* 에이전트가 올바르게 진행하려면 사용자 입력이 필요한 모호한 작업에 특히 유용합니다.

### 10계층 점진적 승인 아키텍처

모든 도구 호출은 사용자에게 도달하기 전에 최대 10개 계층의 결정론적 및 지능적 검사를 거칩니다.

| Layer | Mechanism                        | What it does                                                                               |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------ |
| L0    | **YOLO Full-Auto**               | Auto-approves everything except hard DENY rules                                            |
| L1    | **CapabilitySet**                | Checks declared capabilities with negative-priority deny rules                             |
| L2    | **Command Risk Classifier**      | Categorizes shell commands by risk level (SAFE / UNKNOWN / DANGEROUS)                      |
| L3    | **URL Domain Allowlist**         | Auto-allows network access to trusted domains                                              |
| L4    | **Path Policy**                  | Enforces file access boundaries (workspace-only, deny-list, etc.)                          |
| L5    | **Fast-Path Read-Only MCP**      | Auto-allows MCP tools with `readOnlyHint=true` and no destructive/open-world flags         |
| L6    | **Allowlist Persistence**        | 4-level matching: permission → tool → exact args hash → command glob pattern               |
| L7    | **Taint-Aware Escalation**       | Escalates already-ALLOW tools to ASK when session contains tainted data (PII, credentials) |
| L8    | **Cron Capability Pre-Approval** | Auto-allows declared capabilities in scheduled tasks; fail-closed without declarations     |
| L9    | **Domain HITL Runtime**          | Auto-allows previously-approved domains within the same session                            |
| L10   | **LLM Security Review**          | AI classifier for ASK/Taint/Shell-Escalation/Outbound-Check scenarios                      |

### 다중 플랫폼 승인 UX

모든 승인은 모든 채널에서 동일한 4가지 작업을 나타냅니다.

| Action                     | WebUI                                                                                      | Telegram/Slack/Feishu             |
| -------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------- |
| **Approve** (once)         | Button                                                                                     | `/approve`, `1`, `y`, 👍 emoji    |
| **Edit & Approve**         | Inline editor with re-validation                                                           | N/A (edit in WebUI)               |
| **Reject** (with feedback) | Button + feedback textarea                                                                 | `/deny`, `2`, `n`, 👎 emoji       |
| **Allow Always**           | Button → confirmation dialog (4 scopes for shell: permission / tool / exact / **pattern**) | `/approve-always`, `!y`, ♾️ emoji |

**항상 허용**은 네 가지 세부 수준을 제공합니다.

* **권한**: 이 권한 유형을 가진 모든 도구를 허용합니다(예: 모든 파일 쓰기).
* **도구**: 인수에 관계없이 이 특정 도구를 허용합니다.
* **정확함**: 다음과 같은 정확한 인수가 있는 경우에만 이 도구를 허용합니다(셸 도구의 기본값 - 가장 안전함).
* **패턴**(셸에만 해당): 파생된 glob(예: `curl -sS *`)과 일치하는 명령을 허용합니다. 복합 쉘(`&&`, `|`, `;`)은 **절대로** 저장되지 않습니다. 모든 패턴 행은 **설정 → 허용 목록**에 표시되며 언제든지 삭제할 수 있습니다.

<Note>
  **Migration benefit:** Approve a recurring deploy script once with "Allow always (this pattern)" — later runs auto-approve without YOLO. Claude Code and OpenClaw typically stop at tool-name allowlists or CLI-only signing; Myrm gives you GUI-managed, revocable pattern rules with Chrome LIVE E2E proof (Jul 2026).
</Note>

일괄 작업은 `/batch a,d,aa`(승인, 거부, 항상) 및 UI 대량 버튼을 통해 지원됩니다.

### 사이드바 주의 표시기

상담원이 승인을 위해 일시 중지하면 현재 다른 대화를 보고 있는 경우에도 사이드바에 영향을 받은 채팅 옆에 실시간 황색 펄스 표시기가 표시됩니다. 이렇게 하면 보류 중인 승인이 있는지 각 세션을 수동으로 확인할 필요가 없습니다.

* **황색 펄스 점**: 상담원이 귀하의 승인/설명을 기다리고 있습니다.
* **녹색 펄스 점**: 에이전트가 활발하게 생성 중입니다.
* **점 없음**: 세션이 유휴 상태입니다.

표시기는 페이지 새로 고침(서버 측 승인 복구를 통해) 후에도 유지되며 SSE 멀티플렉스를 통해 열려 있는 모든 브라우저 탭에서 실시간으로 동기화됩니다. 승인을 해결하면 상담원이 재개되면서 표시기가 즉시 사라집니다.

### 승인 시간 초과 레이스 보호

승인 시간 초과가 발생하고 사용자가 거의 동시에 수동으로 승인하면 시스템은 멱등성 `resolve_if_first` 가드를 통해 **정확히 한 번 실행**을 보장합니다.

* **WebUI**: 백엔드가 HTTP 409를 반환 → 프런트엔드에서 환영 메시지를 표시하고 오래된 승인 카드를 제거합니다.
* **IM 채널**: 상담원은 사용자에게 승인이 이미 처리되었음을 알리는 현지화된 메시지(EN/ZH)로 응답합니다.
* **동시 안전**: 첫 번째 확인자만 승리합니다. 이후의 모든 시도는 무작동입니다.

이는 이중 에이전트 실행, 중복된 LLM 비용 및 모순된 작업(대부분의 경쟁 프레임워크에 존재하는 격차)을 방지합니다.

### 세션 디렉터리 부여(로컬 및 데스크톱)

에이전트가 현재 작업공간(예: `~/Downloads`, 언급한 프로젝트 폴더) **외부** 파일이 필요한 경우 Myrm은(는) 자동으로 액세스를 확장하는 대신 명시적인 권한을 요청합니다.

| Step             | What happens                                                                                                                                         | User benefit                                                       |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Agent asks**   | `request_directory_tool` shows a composer card (path + read/write toggle), or a file approval card offers **Grant directory** (unchecked by default) | You always know *which folder* is being opened                     |
| **You grant**    | Access is stored on the chat row and shown as chips above the input (RO/RW badge)                                                                    | One grant lasts the session — no repeated popups for the same path |
| **You revoke**   | Click × on a chip to remove that root instantly                                                                                                      | Mistakes are reversible without restarting the chat                |
| **Safety floor** | Dangerous paths (e.g. `~/.ssh`) are rejected **before** grant; cloud sandboxes skip this tool when the workspace already equals the sandbox root     | Same HITL UX on desktop, fail-closed on cloud                      |

**경쟁사와 비교:** OpenWorker Cowork는 비슷한 `request_directory` 흐름을 가지고 있습니다. OpenClaw, Hermes, DeerFlow, LobsterAI, CoPaw 및 jiuwenclaw는 코드베이스에서 세션 범위 디렉터리 HITL을 제공하지 않습니다. Myrm은 파일 승인, 지속적인 취소, 6개 로케일 UI 및 배포 경계 확인에 대한 경로 ASK 부여를 추가합니다.

### 교정 학습

승인된 작업의 인수를 편집하거나 도구 호출을 거부하면 시스템이 자동으로 사용자의 기본 설정을 학습합니다.

* **제로 LLM 비용**: 결정적 dict-diff 분류(추가 추론 호출 없음)
* **경로 기본 설정**: 파일 작업 거부 또는 편집 → 작업 공간 규칙으로 기억
* **명령 규칙**: 쉘 명령 거부 → 영구 규칙으로 절차 메모리에 추가됨
* **반복 추적**: 유사한 패턴의 반복 거부 → 자동 거부(묻지 않음)

시간이 지남에 따라 상담원이 귀하의 작업 스타일에 맞춰짐에 따라 승인 메시지가 자연스럽게 감소합니다.

## 오류 자가 치유

14계층 오류 복구 시스템은 사용자 개입 없이 자동으로 오류를 처리합니다. 자세한 내용은 [오류 복구](/docs/core-concepts/error-recovery)를 참조하세요.

주요 기능:

* 스트림 중단 복구(토큰 수준 정밀도)
* 3단계 쿨타임이 있는 회로 차단기
* 모델 폴백 체인
* 점진적인 예산 증가로 잘림 자동 재시도
* 결정적 대체(LLM 없는 안전망)

## 인증 및 상태 모니터링

자동 경고를 통해 자격 증명 유효성 및 시스템 상태를 실시간으로 모니터링합니다.

| Capability            | What It Does                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Auth Detector**     | Recognizes 15+ authentication failure patterns across all major providers (OpenAI, Anthropic, Google, etc.)                                |
| **Circuit Breaker**   | Immediately stops retrying on permanent auth failures, saving tokens and preventing billing waste                                          |
| **Probe Policy**      | Intelligent recovery probing (60s for session expiry, 600s for permanent auth) to auto-detect when keys become valid again                 |
| **Brute-Force Alert** | Background monitor detects suspicious auth patterns (10+ failures/IP/hour), creates deduplicated system notifications                      |
| **Health History**    | Records system health score every 3 minutes to database, retains 7-day trend for diagnosis                                                 |
| **Real-time Push**    | Health status changes and memory metrics streamed to the frontend via dedicated ServerEventBus channels (separate from chat tool progress) |
| **Deployment-Aware**  | Local mode skips network audit (saves resources), remote mode enables full monitoring                                                      |

## 신속한 주입 방어

두 개의 보완적인 하위 시스템이 즉각적인 삽입을 방지합니다. 하나는 에이전트 **로** 유입되는 신뢰할 수 없는 외부 콘텐츠를 위한 것이고, 다른 하나는 사용자/파일 **입력**을 보호하는 것입니다.

### 콘텐츠 경계(출력측)

LLM 컨텍스트에 들어가기 전에 모든 외부 컨텐츠와 도구 출력을 래핑하는 5계층 방어로 **전체 도구 체인을 포괄**(내장 도구 + 타사 MCP 도구 + PTC 내장 도구):

| Layer | Technique                | What It Catches                                                                                         |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| **1** | Unicode folding          | Invisible Unicode characters used to smuggle payloads                                                   |
| **2** | Structural framing strip | Removes XML/HTML-like structural markers that mimic system tags                                         |
| **3** | Marker sanitization      | Replaces known boundary/delimiter patterns to prevent breakout                                          |
| **4** | Random boundary          | Wraps content in a cryptographically random delimiter (`===BOUNDARY_xxx===`) unpredictable to attackers |
| **5** | Pattern detection        | Detects remaining injection patterns (role override, instruction override, system simulation)           |

타사 MCP 도구에서 반환된 데이터는 LLM 컨텍스트에 들어가기 전에 자동으로 5개 방어 계층을 모두 통과하여 악성 MCP 서버가 도구 출력을 통해 명령을 주입하는 것을 방지합니다.

### 프롬프트 가드(입력측)

26개 위협 범주에 걸친 113개 탐지 패턴으로 사용자 메시지, 프로젝트 규칙 및 기술 파일을 검사합니다.

* **난독화 방지**: Leet 말하기 반전, 보이지 않는 유니코드 제거, 공백 접기, Base64 디코딩
* **이중 언어 감지**: 영어 및 중국어 프롬프트 삽입 패턴(예: "忽略之前的指令")
* **2단계 감지**: 먼저 정규화된 텍스트에서, 그 다음 Base64로 디코딩된 콘텐츠에서

### 메모리 쓰기 경로 검색

입력 측 가드(대화 보호)와 달리 쓰기 경로 스캐너는 **내구성 메모리**를 보호합니다. 이는 지속성 **이전** 모든 메모리 쓰기에 대해 결정적으로 실행되므로 프롬프트 주입 에이전트는 주입이 업스트림에 성공하더라도 악의적인 명령, 비밀 또는 위조된 시스템 태그를 저장할 수 없습니다.

* **명령 형태 감지** — 가드레일 우회 명령 및 신뢰할 수 없는 채널 쓰기가 차단됩니다(이중 언어 공격 라이브러리)
* **자격 증명 제로 보존** — API 키, 비밀번호, PIN/OTP 숫자 자격 증명이 삭제됩니다. 오탐을 방지하기 위해 연도와 전화번호는 제외됩니다.
* **가짜 시스템 태그 차단** — `System:`/`Assistant:` 콜론 접두사는 삽입으로 처리됩니다.
* **모든 쓰기 경로는 가드를 공유합니다** — 수동 저장, 일괄 쓰기, 업데이트, 프로필, 규칙, MCP 도구, 에이전트 자동 추출 및 가져오기 복구
* **CI 오염 벤치마크 게이트** — 회귀를 방지하기 위해 CI에서 2계층 기대 테스트(탐지 계층 + 추출 계층)가 실행됩니다.

### 파일 잠금 심볼릭 링크 방어

업스트림 콘텐츠 가드가 모두 작동하더라도 프롬프트 주입에 유도된 에이전트가 프레임워크 디렉터리에 민감한 파일(예: `~/.env`, SSH 키)을 가리키는 **심볼릭 링크**를 만들 수 있습니다. 나중에 "생성/절단" 의미로 해당 잠금 경로를 여는 코드는 링크가 가리키는 파일을 **조용히 파괴**합니다. 프레임워크 수준 공개 API에 대한 실제 데이터 손실 경로입니다.

harness의 `FileLock`(전달 큐에서 사용)은 `O_NOFOLLOW`로 잠금 파일을 엽니다(Windows에서는 `hasattr` 가드). 심어진 심볼릭 링크는 따라가지 않고 **거부**됩니다:

| 동작                               | 결과                                      |
| -------------------------------- | --------------------------------------- |
| 잠금 디렉터리에 심볼릭 링크 심기 → `acquire()` | `False` 반환(잠금 미획득), **대상 파일 무손상**       |
| 잠금 파일 권한                         | `0o600` — 샌드박스 소유자만 읽기/쓰기 가능            |
| `O_NOFOLLOW` 없는 플랫폼(예: Windows)  | 일반 `O_CREAT\|O_RDWR`로 우아한 저하, 잠금은 정상 작동 |
| 심볼릭 링크 제거 후                      | 리소스를 즉시 다시 획득 가능 — 거부가 잠금 경로를 오염시키지 않음  |

이는 또 하나의 심층 방어 계층입니다. 프롬프트 주입 공격이 파일 시스템 수준에서 성공하더라도 잠금 경로를 통한 임의 파일 절단은 구조적으로 불가능합니다.

심볼릭 링크 방어 외에도 harness `FileLock`은 잠금 전체 수명주기에서 오용과 조용한 실패를 방지하도록 강화되었습니다:

| Guard            | Behavior                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| **모드 화이트리스트**    | `exclusive` / `shared`만 허용. `exclusiv` 같은 오타는 조용히 공유 잠금으로 강등되어 상호 배제를 깨는 대신 즉시 fail-fast                     |
| **차단 fail-fast** | 동기 `blocking=True`(asyncio 이벤트 루프를 얼릴 수 있음)는 매달리는 대신 `TypeError`를 발생                                         |
| **잠금 키 살균**      | 리소스 ID를 안전한 문자 집합으로 필터링하고 128자로 제한한 뒤 SHA-256 해시 — 경로 주입·숨김 파일 없음                                            |
| **예외 삼키지 않음**    | 잠금 보유 중 발생한 비즈니스 예외가 오해를 부르는 오류로 포장되지 않고 그대로 전파                                                              |
| **크래시 자가 치유**    | 잠금은 OS 수준(`fcntl.flock`)이라 프로세스가 종료되는 즉시 커널이 해제 — 하트비트/TTL/수동 정리 불필요; 전달 중복 제거로 메시지는 재시작 후에도 at-most-once 보장 |

교차 프로세스 상호 배제는 asyncio 동시성 통합 테스트와 함께 CI의 subprocess 테스트(macOS)로 검증됩니다.

### 하위 에이전트 보안

다중 에이전트 워크플로에는 ID 드리프트 및 권한 상승 위험이 발생합니다. Myrm은 모든 수준에서 이 문제를 해결합니다.

| Control               | Mechanism                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tool Whitelisting** | `DelegationCapabilityManifest` — parent explicitly declares which tools each child agent can access                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Memory Isolation**  | 3 policies: `EPHEMERAL_SESSION` (clean slate), `READ_ONLY_GLOBAL` (read but not write), `COLLABORATIVE_SESSION` (shared with audit)                                                                                                                                                                                                                                                                                                                                                                                       |
| **Taint Propagation** | `TaintTracker` labels flow from child → parent. If a child touches external network data, the parent session is automatically tainted                                                                                                                                                                                                                                                                                                                                                                                     |
| **Sink Policies**     | Tainted sessions escalate to HITL approval for dangerous tool combinations (e.g., `EXTERNAL_NETWORK` taint + `bash_tool` = blocked without approval)                                                                                                                                                                                                                                                                                                                                                                      |
| **Budget Boundary**   | 4-dimension `DelegationBudget` (token + USD + time + max descendants) prevents runaway sub-agent chains                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Recursion Guard**   | 5-layer progressive defense: L1 global depth hard limit (max 3) + L2 per-config depth (LEAF agents forced to depth=0) + L3 descendant budget (max 20 including parallel branches, atomic reserve) + L4 concurrency limits (semaphore=5 + per-agent children=5) + L5 LoopGuard 7-class behavioral detection (repetition/ping-pong/no-progress/divergence/diminishing). Rejections emit frontend STATUS events with actionable suggestions for LLM self-correction. Cascade cancellation of all descendants on parent abort |

## 스킬 설치 보안

모든 소스(GitHub, SkillHub, 파일 업로드)에서 기술을 설치할 때 모든 기술은 활성화되기 전에 **3중 보안 게이트**를 통과합니다.

| Layer             | Mechanism                                       | What It Catches                                                                                |
| ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Regex Scanner** | 113 patterns across 26 threat categories        | Shell injection, credential theft, data exfiltration, obfuscated payloads                      |
| **AST Analyzer**  | Python Abstract Syntax Tree structural analysis | Dangerous imports (`os.system`, `subprocess`), hidden function calls, suspicious code patterns |
| **LLM Auditor**   | Semantic threat assessment by language model    | Socially-engineered attacks, multi-step exfiltration chains, intent-masked malicious logic     |

### 신뢰 수준

기술에는 런타임 기능을 결정하는 네 가지 신뢰 수준 중 하나가 할당됩니다.

| Level         | Source                      | Capabilities                           |
| ------------- | --------------------------- | -------------------------------------- |
| **TRUSTED**   | Built-in / official         | Full tool access                       |
| **INSTALLED** | User-installed, scan passed | Scoped `allowed_tools` access          |
| **UNTRUSTED** | Scan flagged warnings       | Read-only tools, no network/filesystem |
| **REJECTED**  | Scan critical findings      | Quarantined, cannot execute            |

`quarantine_aware` 데코레이터는 런타임 시 거부된 기술을 자동으로 필터링합니다. 즉, 격리된 기술은 오류 없이 에이전트의 사용 가능한 도구에서 사라집니다.

### 런타임 권한 경계

기술 설치가 통과된 후에도 런타임의 민감 작업은 **기술 권한 게이트**(`SkillBoundaryProvider`)의 적용을 받습니다. 파일 쓰기, 명령 실행, 네트워크, 환경 변수 읽기 등 민감한 권한 유형은 반드시 사전 승인되어야 하며, 그렇지 않으면 엔진 계층에서 도구 호출이 즉시 거부됩니다(`skill_boundary.violation`, fail-loud, 조용한 다운그레이드 없음).

* **단일 권위(SSOT)**: 도구 이름 → 권한 유형은 도구 레지스트리 `resolve_permission_type`이 일괄 해석하여, '차단인데 통과'되는 매핑 드리프트를 원천 차단합니다.
* **한 번 승인 시 자동 실행**: 이미 승인된 권한은 호출마다 팝업 없이 자동 통과되며, 무인 작업이 중단되지 않습니다. 철회(revoke)는 캐시 무효화 콜백으로 즉시 적용되며 재시작이 필요 없습니다.
* **세분화 분리**: 샌드박스 코드 실행(`code_interpreter`)과 네이티브 셸(`shell_exec`)이 독립적으로 승인되어 서로를 넘어설 수 없습니다.
* **전체 감사 추적**: 모든 권한 판정(승인/거부 + 대상)이 권한 사용 로그에 기록되어 추적 가능합니다.
* **사용 통계 대시보드**: 감사 로그를 시각적 대시보드로 집계합니다 — 권한 유형별 총/허용/거부 횟수, 정확한 거부 사유, 최근 10개 작업, 1/7/30/90일 기간 필터. 이상 행동(예: 스킬이 환경 변수를 반복 탐색하며 매번 거부당하는 경우)도 원시 로그에 묻히지 않고 한눈에 보입니다.
* **검증**: 기술 경계 100% 단위 테스트 + 실제 DB 전 구간 통합 검증(승인 → 게이트 → 실행 → 철회 → 즉시 거부).

### GUI 보안 검토

세 가지 프런트엔드 구성 요소가 함께 작동하여 보안 검색 결과를 제공하며, 각 결과에는 개발자가 문제가 있는 코드로 바로 이동할 수 있도록 **정확한 줄 번호 타겟팅**(예: `L42 Command injection: recursive delete`)이 포함되어 있습니다.

| Component               | Trigger                                 | Content                                                                       |
| ----------------------- | --------------------------------------- | ----------------------------------------------------------------------------- |
| **ScanConfirmDialog**   | Installing from SkillHub search         | Finding list + severity badges + line numbers + confirm/cancel                |
| **Blocked Dialog**      | Enabling a skill with CRITICAL findings | Block reason + finding details + line numbers + "Force Enable" option         |
| **SecurityScanSection** | Skill detail page                       | Full finding list grouped by severity + line numbers + security score (0-100) |

보안 점수는 100점 시스템을 사용하며 발견 항목별로 CRITICAL −25, HIGH −15, MEDIUM −8, LOW −3을 차감합니다. 신뢰 결정을 안내하기 위해 `trust_recommendation`(신뢰됨/설치됨/신뢰되지 않음/거부)도 생성됩니다.

## MCP 도구 보안

### 도구 이름 격리

여러 MCP 서버가 활성화되면 도구 이름이 충돌할 수 있습니다(예: GitHub 및 GitLab 서버 모두 `search_repos`을 노출함). Myrm은 모든 MCP 도구 이름 앞에 이중 밑줄 구분 기호를 붙입니다.\`\`\`
mcp\_\_{server}\_\_{tool}

```

- **명확한 구문 분석** — 단일 밑줄 체계와 달리 `__` 구분 기호는 서버 이름에 밑줄이 포함된 경우에도 정확한 역방향 구문 분석을 허용합니다.
- **권한 격리** — 접두사가 붙은 MCP 도구 이름은 내장 도구와 충돌하지 않으므로 실수로 권한 우회를 방지할 수 있습니다.
- **추적성 감사** — 모든 도구 호출 로그 항목은 원래 MCP 서버를 식별합니다.

### SSRF 예방

DNS 고정은 에이전트가 HTTP 리디렉션을 통해 내부 네트워크에 액세스하도록 속이는 것을 방지합니다.

- **통합 아웃바운드 HTTP 계층**: 에이전트가 시작한 모든 HTTP 종료(web_fetch, HTTP 도구, OpenAPI 실행기, 기술 ZIP 설치, 미디어 확인자, 로봇/사이트맵 가져오기, 채널 미디어 다운로드, Feishu 첨부 파일)가 `secure_fetch` / `async_pin_url`에 수렴 — 단일 구현, 베어 httpx 사각지대 없음
- **수동 리디렉션 루프**: 홉별 재검증이 포함된 `follow_redirects=False` — 모든 리디렉션 대상은 팔로우하기 전에 완전히 확인됩니다.
- **DNS 고정**: 확인된 IP가 HTTP 연결에서 호스트 이름을 대체하여 DNS 리바인딩 TOCTOU 공격을 제거합니다.
- **포괄적인 IP 차단 목록**: RFC1918 프라이빗, CGNAT, 링크-로컬, 멀티캐스트, 예약, 클라우드 메타데이터 엔드포인트(AWS/GCP/Alibaba/Tencent) 및 IPv4 매핑 IPv6 감지
- **데이터 유출 감지**: 6가지 패턴 카테고리(API 키, 파일 경로, base64, JWT, 비밀 키, DB 연결 문자열)로 URL 매개변수를 통한 민감한 데이터 유출을 방지합니다.
- **도메인 HITL 승인**: 허용 목록에 없는 도메인은 `domainHitlEnabled`가 활성화될 때 인간 개입(Human-In-The-Loop) 승인을 트리거합니다. UI를 통해 에이전트별 네트워크 허용 목록 구성 가능
- **파서 혼동 문자 방어**: 파서 간 호스트 이름 추출 분기를 방지하기 위해 URL의 탭, 줄 바꿈 및 백슬래시를 차단합니다(CVE 클래스 SSRF 우회 방지).
- **내부 호스트 이름 접미사 차단**: `.local`, `.svc`, `.cluster.local`, `.home.arpa` 접미사는 mDNS 및 Kubernetes 내부 네트워크 액세스를 방지하기 위해 차단됩니다.
- **감사 추적**: 차단된 요청은 SIEM 및 프런트엔드 감사 보기에 대한 `SSRF_BLOCKED` 보안 결정을 내보냅니다.
- **에이전트 API 범위**: `/v1/chat/completions`은 Myrm 에이전트만 실행합니다(원시 LLM 패스스루 없음). 사용자 구성 공급자 apiUrl SSRF 검사는 에이전트 내 LLM 호출에 유지됩니다. 배포 모드 인식: 로컬 모드는 루프백 호스트(Ollama/vLLM)를 허용하고, 클라우드/샌드박스 모드는 개인 네트워크 및 클라우드 메타데이터 엔드포인트를 차단합니다.
- **461개 이상의 전용 SSRF 테스트**: 핵심 보호, 에이전트 보안, 브라우저 탐색, DNS 고정, 미디어 검증, A2A 확인자, 웹 가져오기, SessionVault, 권한 엔진 및 공급자 URL 검증에 대한 적용 범위

### 악성 URL 아키텍처 면역

Myrm은 정적 피싱 도메인 차단 목록(예: 250만 개의 사기 도메인)을 유지하는 대신 아키텍처 수준에서 위협을 제거합니다.

- **SessionVault 도메인 바인딩**: 자격 증명(쿠키/비밀번호)은 도메인별로 엄격하게 격리됩니다. — `bank.com` 로그인 상태는 `bank-secure-login.xyz`와 같은 피싱 도메인으로 전송되지 않으므로 자격 증명 도용을 방지하도록 설계되었습니다.
- **에이전트 수준 세션 격리**: 구성된 각 에이전트는 자체 물리적 SessionVault 하위 디렉터리를 갖습니다. 동일한 웹 사이트에 액세스하는 "작업 도우미" 및 "개인 비서"는 완전히 독립적인 로그인 상태를 유지하여 에이전트 간의 신원 오염을 방지합니다.
- **브라우저 샌드박스 격리**: 에이전트 브라우저는 격리된 샌드박스에서 실행됩니다. 악성 사이트를 방문하더라도 사용자의 호스트 시스템은 영향을 받지 않습니다.
- **4계층 심층 도메인 필터링**: CSP 정책(커널 수준 네트워크 제한) + 프로토콜 차단(context.route가 허용 목록에 없는 도메인 차단) + 메인 스레드 강화(WebRTC/WebTransport/ServiceWorker 차단) + CDP 감사 모니터링

이 아키텍처를 사용하면 대규모 피싱 도메인 데이터베이스를 불필요하게 유지할 수 있습니다. 매일 수천 개의 새로운 도메인이 나타나고 정적 목록은 빠르게 구식이 되며 50~100MB의 메모리를 소비합니다.

### 구성 보안 검색

모든 MCP 서버 구성은 활성화 전에 13가지 위협 유형을 검사합니다.

| Threat Type | What It Catches |
|-------------|----------------|
| `prompt_injection` | Malicious system prompts embedded in config |
| `name_injection` | Tool names designed to mislead the LLM |
| `concealment` | Hidden instructions in descriptions |
| `exfiltration` | Data theft via outbound channels |
| `credential_harvesting` | Attempts to collect user secrets |
| `context_leak` | Leaking conversation context to external services |
| `arbitrary_execution` | Unrestricted code execution capabilities |
| `risky_profile` | Known high-risk server profiles |
| `suspicious_url` | Non-HTTPS or suspicious domain patterns |
| `sensitive_path` | Access to sensitive filesystem paths |
| `hardcoded_secret` | Credentials embedded in configuration |
| `supply_chain` | Dependency chain compromise indicators |
| `supply_chain_malware` | Known malicious package signatures |

조사 결과는 심각도 배지와 함께 `ScanConfirmDialog`에 표시됩니다. 사용자는 각 서버를 신뢰하거나 거부하거나 강제로 활성화할 수 있습니다(자신의 책임 하에).

### 악성 패키지 탐지

MCP 도구가 종속성을 설치할 때 OSV(오픈 소스 취약점) API을 실시간으로 참조하여 알려진 악성 패키지를 탐지합니다.

### 동적 공구 교환 안전

MCP 서버가 런타임 시(`tools/list_changed` 알림을 통해) 도구를 추가하거나 제거하면 Myrm은 작업 흐름을 중단하지 않고 보안을 보장합니다.

- **자동 보안 조사** — 새로 추가된 도구는 구성 시 적용된 동일한 13가지 위협 보안 검색을 기준으로 평가됩니다. 도구가 검사에 실패하면 거부되고 경고가 기록됩니다. 안전하지 않은 도구는 자동으로 활성화되지 않습니다.
- **프롬프트 캐시 보존** — 에이전트의 프롬프트 표시 도구 목록이 고정됩니다. 동적 변경은 내부 실행 계층만 업데이트합니다. 이는 프롬프트 접두사 캐시 적중이 외부 MCP 서버 동작에 의해 무효화되지 않도록 보장합니다.
- **사용자 중단 없음** — 수동 `/reload` 확인이 필요한 CLI 기반 경쟁사와 달리 Myrm은 도구 변경을 투명하게 처리합니다. 사용자는 의미 있게 평가할 수 없는 이벤트에 대한 확인 대화 상자로 인해 방해를 받지 않습니다.

### 에이전트별 도구 필터링

서로 다른 에이전트는 동일한 서버에서 서로 다른 MCP 도구를 활성화할 수 있습니다. "코드 검토자" 에이전트는 읽기 전용 도구만 볼 수 있는 반면 "DevOps" 에이전트는 모든 도구를 볼 수 있습니다. `destructiveHint` 주석이 있는 도구는 안전 세트에서 기본적으로 비활성화되어 있습니다.

## 작업 수준 의미론적 위험 감지

전체 웹사이트를 "고위험"(깨지기 쉽고 유지 관리가 많이 필요한 접근 방식)으로 표시하는 대신 Myrm은 **개별 작업 수준**에서 위험을 감지합니다. 모든 클릭, 양식 제출 및 명령이 실시간으로 분석됩니다.

### 7-범주 의미론적 DOM 위험 감지

에이전트가 웹페이지의 버튼이나 링크를 클릭하면 해당 요소의 텍스트가 영어와 중국어로 된 7가지 위험 범주에 대해 분석됩니다.

| Category | Trigger Keywords (EN/ZH) | What Happens |
|----------|-------------------------|--------------|
| **Destructive** | delete, remove / 删除, 移除 | HITL approval required |
| **Financial** | pay, purchase, checkout / 付款, 购买 | HITL approval required |
| **Account** | deactivate, close account / 注销, 关闭账号 | HITL approval required |
| **Admin** | admin settings, permissions / 管理, 权限 | HITL approval required |
| **Publish** | publish, post, submit / 发布, 发表 | HITL approval required |
| **Share** | share, send, transfer / 分享, 发送 | HITL approval required |
| **Sensitive** | password, credit card / 密码, 信用卡 | HITL approval required |

이 접근 방식은 다음과 같은 이유로 도메인 수준 위험 태그보다 우수합니다.
- **유지보수 제로**: "고위험 웹사이트" 목록을 유지 관리할 필요가 없습니다.
- **유니버설 커버리지**: 신규 웹사이트를 포함한 모든 웹사이트에서 작동
- **세부적**: Amazon의 "장바구니 보기"는 자동으로 통과하지만 "주문하기"에는 승인이 필요합니다.
- **법적 위험 없음**: 특정 플랫폼에 대한 차별이 없습니다.

### 스마트 인텐트 가드

AI 분류자(`TranscriptClassifier`)는 도구 호출을 검토하여 사용자의 원래 의도와 일치하는지 확인합니다.

- **Reasoning-Blind**: 사용자 메시지 + 도구 호출 순서만 확인(에이전트 추론 아님)하여 자기 정당화 공격 방지
- **결정적**: `temperature=0`은 동일한 입력이 항상 동일한 결과를 생성하도록 보장합니다.
- **구조화된 출력**: 감사 추적성을 위해 `reason` 필드가 있는 Pydantic 강제 JSON
- **Fail-safe**: 오류나 모호성은 자동 승인이 아닌 HITL로 대체됩니다.

### 리스크 거버넌스 시스템

기본 제공 규칙, 사용자 지정 규칙 관리 및 전체 스택 이벤트 처리를 갖춘 완벽한 양방향 위험 감지 및 거버넌스 프레임워크입니다. 동일한 규칙 엔진이 WebUI 입력과 IM 채널 인바운드 메시지 **모두**를 사각지대 없이 보호합니다.

7개 카테고리의 **31개 기본 제공 규칙**은 민감한 데이터가 LLM에 도달하기 전에 감지합니다.

| Category | Examples | Count |
|----------|---------|-------|
| **Personal** | Email, phone, Chinese ID number, passport, address | 8 |
| **Security** | API keys (OpenAI, AWS, GCP, Azure), SSH private keys, JWT tokens | 7 |
| **Company** | Internal IPs, employee IDs, project codenames, internal URLs | 5 |
| **Customer** | Customer IDs, order numbers, support ticket numbers | 4 |
| **Finance & Legal** | Bank accounts, credit cards, tax IDs, contract numbers | 4 |
| **Political** | Politically sensitive content patterns | 3 |

**대칭 인바운드/아웃바운드 게이트**: IM 채널 메시지는 에이전트에 도달하기 전에 라우터 수준에서 `RiskDetectionService.detect()`을 통과합니다. 차단된 메시지는 현지화된 알림(6개 언어)을 받고 감사 기록됩니다. 아웃바운드 에이전트 응답은 `_apply_outbound_risk_gate`을 통해 동일한 엔진을 통과하여 폐쇄 루프 방어를 형성합니다.

**GUI 규칙 관리**: WebUI 설정 패널을 통한 전체 CRUD — 정규식 패턴을 사용하여 사용자 정의 규칙을 만들고, 규칙 켜기/끄기를 전환하고, 배치 작업을 수행하고, 배포 전에 규칙 테스트를 수행합니다. 코드가 필요하지 않습니다.

**감사 추적**: 모든 위험 적중은 규정 준수 감사를 위한 `trace_id`, `session_id`, 일치 규칙 및 심각도 수준을 기록합니다.

**전체 스택 이벤트 루프**: 입력 위험이 감지되면 서버는 `risk_blocked` SSE 이벤트를 발생시킵니다. 프런트엔드 `riskEvents` 핸들러는 이 이벤트를 가로채고 어떤 규칙이 트리거되었는지 설명하는 사용자 친화적인 토스트 알림을 표시합니다. 자동 실패는 없습니다.

### 테스트 범위

30,000개 이상의 테스트를 통해 PII/DLP/프라이버시 라우팅(1136), 셸 명령 승인(하네스 1209 + 서버 261), 의미론적 DOM 위험(75), 셸 분류(379), SQL 문 가드(68, 99.1% 적용 범위), 보안 엔진 통합(163+74), 자격 증명 검색(35), 도구 가드(9), 권한 엔진을 포함한 전체 보안 파이프라인을 검증합니다. (119), 도구 레지스트리 및 상속(67), 가드레일 미들웨어(15), 아키텍처 레지스트리(4), 서버 권한(18), 에이전트 내장 도구 API(12), 프로필 확인(36), 프런트엔드 승인 및 메시지(15), 위험 거버넌스(117), 웹훅 경로(2), 동적 인증 가드레일(845), MCP 벤치마크 도출(166) 등.

## 셸 명령 보안

명령은 실행 전에 5계층 인용 인식 파이프라인을 통해 분석됩니다.

| Layer | Detection | Response |
|-------|-----------|----------|
| **L1** | Binary characters, 12 invisible Unicode categories (zero-width, direction overrides) | BLOCK |
| **L1.5** | ANSI-C quoting `$'...'` and locale quoting `$"..."` | BLOCK |
| **L2** | 6 injection vectors (`$()`, backtick, `${}`, `;`, process substitution) + 70+ dangerous command patterns | BLOCK → DENY |
| **L2.5** | SQL syntax-level guard: detects destructive SQL in DB client commands (`psql`, `mysql`, `sqlite3`, etc.) — handles multi-statement injection and WITH CTE bypass vectors | ESCALATE → ASK |
| **L3** | Suspicious patterns (`curl\|sh`, `eval`, `base64 -d`, kill/pkill) | ESCALATE → ASK |
| **L4** | Recursive analysis of nested commands in `bash -c '...'`, `sh -lc '...'`, `zsh -c '...'`, `trap '...'` wrappers — depth-limited to prevent DoS | Recursive BLOCK/ESCALATE |

**인용 인식 전처리**: 문자 수준 상태 머신(`_strip_quoted_content`)은 L2/L3 스캔 전에 작은따옴표로 묶인 콘텐츠를 자리 표시자로 대체하여 `echo 'rm -rf /'`에 대한 오탐을 방지하는 동시에 큰따옴표 또는 따옴표가 없는 컨텍스트에서 실제 위협을 포착합니다.

**권한 에스컬레이션 플로어**: `sudo apt install`, `sudo -S`(stdin 비밀번호 파이핑), `env sudo cmd` 및 `bash -c 'sudo ...'`(L4에 의해 재귀적으로 포착됨)을 포함하여 모든 `sudo` 명령은 L2에서 무조건 차단됩니다. 이는 YOLO 모드, 스마트 가드 또는 사용자 승인으로 우회할 수 없습니다. Hermes과 같은 경쟁업체는 `sudo -S`(비밀번호 추측 벡터)만 차단하고 여전히 SUDO_PASSWORD 삽입을 통해 일반 `sudo`을 허용합니다. 즉, 공격 표면이 더 넓습니다. 다른 6명의 경쟁업체에는 sudo 가드가 전혀 없습니다.

**파괴적 명령에 대한 자동 스냅샷**: 파괴적인 패턴(임의 플래그 접두어가 있는 `rm`, `mv`, `git reset/clean/checkout/restore/apply`, `sed -i`, 리디렉션 덮어쓰기)과 일치하는 명령은 실행 전에 자동 작업 영역 스냅샷을 트리거하여 결과에 관계없이 전체 복구를 보장합니다.

**SQL Guard(L2.5)**: 데이터베이스 클라이언트 명령에 포함된 파괴적인 SQL 작업(`DROP`, `DELETE`, `TRUNCATE`, `ALTER`, `INSERT`, `UPDATE`, `CREATE`)을 탐지하기 위해 *original* 명령(따옴표 제거 전)을 분석합니다. 다중 문 삽입(`SELECT 1; DROP TABLE`) 및 WITH CTE 래핑(`WITH x AS (...) DELETE FROM`)이라는 두 가지 고급 우회 벡터를 방어합니다. 플래그 기반(`psql -c '...'`) 및 파이프 기반(`echo '...' | psql`) 패턴과 함께 작동합니다. 어떤 경쟁업체도 셸 실행을 위한 SQL 수준 명령 분석을 구현하지 않습니다.

**안전한 실행 경로**: 셸 메타 문자가 없는 간단한 명령은 `create_subprocess_exec`(셸 인터프리터 없음)를 통해 실행되어 `$IFS`, glob 확장 및 명령 대체 주입 클래스를 구조적으로 제거합니다.

### AI 궤적 분류기(레이어 5.5)

정적 분석이 ASK(불확실함)를 반환하면 AI 분류자는 의미론적 수준의 판단을 제공합니다.

- **추론 맹목적 설계**: 사용자 메시지와 도구 호출 시퀀스만 확인하고 보조 추론이나 도구 출력은 확인하지 않아 에이전트가 분류자를 지나 위험한 행동을 합리화하는 것을 방지합니다.
- **구조화된 출력**: Pydantic 스키마는 JSON 형식(자유 텍스트 아님)을 강제하여 주입 표면을 줄입니다.
- **결정적**: 재현 가능한 결정을 위한 `temperature=0`, `max_tokens=200`
- **실패 안전**: 모든 오류, 시간 초과 또는 구문 분석 실패는 불확실함을 반환 → HITL 승인으로 돌아갑니다.
- **컨텍스트 인식**: 미묘한 판단을 위해 오염 라벨(EXTERNAL_NETWORK, SECRET) 및 신뢰할 수 있는 도메인을 수신합니다.

### 이중 언어 명령 설명

승인을 트리거하는 모든 명령은 결정론적으로 생성된 사람이 읽을 수 있는 이중 언어 설명(`humanize_command`)을 표시합니다(0 LLM 호출, 마이크로초 대기 시간).

- 매개변수 인식 설명(URL, 파일 이름, 패키지 이름 추출)이 포함된 **73개의 일반 명령 포함**
- **sudo 접두사 자동 태그됨**, 위험한 파이프 패턴 강조 표시
- 사용자는 쉘 전문 지식 없이도 승인하기 전에 명령이 수행하는 *작업*을 이해합니다.
- 완전히 규칙 기반: LLM 기반 대안과 달리 프롬프트 주입을 통해 조작할 수 없습니다.

<Note>
**Frontend humanize SSOT (2026-08)** — Beyond harness `humanize_command` for shell, the WebUI module `lib/humanize/` generates the **same plain-language dialect** for ProgressSteps titles and all three approval surfaces (Single / Polymorphic / ToolCall). Scope hints (`local` vs `external` channel) use `resolveScopeNote` + `ApprovalScopeNoteLine` in six locales. Save-skill approvals show a structured preview before you approve. Validated: **49 focused vitest, 0 failures** (Aug 2026).
</Note>

### Slopcheck 설치(슬롭스쿼팅 방지)

모든 `pip install` / `npm install` / `yarn add` / `bun add` 명령 전에 실행 전 검사를 통해 각 패키지 이름이 실제로 공용 레지스트리에 있는지 확인합니다.

| Aspect | Detail |
|--------|--------|
| **Detection** | HEAD probe against PyPI JSON API (`/pypi/{name}/json`) and npm registry (`/{name}`) |
| **Normalization** | PEP 503 rules (underscores, dots, mixed case → canonical lowercase-hyphen) |
| **Concurrency** | All packages probed in parallel via `asyncio.gather()` |
| **Cache** | In-memory set of verified packages — zero repeated network calls within a session |
| **Private registries** | Commands with `--index-url`, `--extra-index-url`, or `--registry` are auto-skipped |
| **Graceful fallback** | Network timeout or DNS failure → allow install (never block legitimate work) |
| **Response** | Unknown package → `ToolError` blocks the install and explains which packages were not found |

이렇게 하면 공격자가 LLMs가 일반적으로 환각을 느끼는 패키지 이름을 등록하여 게시된 패키지에 악성 코드를 삽입하는 **슬롭 스쿼팅 공격**을 방지할 수 있습니다.

## 암호화 및 기업 네트워크 호환성

| Scope | Standard |
|-------|----------|
| **At Rest** | AES-256-GCM for stored data (secrets, API keys, user content) |
| **In Transit** | TLS 1.3 for all network connections |
| **API Keys** | Encrypted secrets vault with per-user isolation |
| **Memory** | Optional encryption for sensitive memory entries |
| **Incognito Mode** | Physical isolation and read-after-burn for sensitive sessions |

### 엔터프라이즈 TLS 호환성

기업 네트워크에서는 모든 HTTPS 연결이 실패할 수 있는 TLS 검사 프록시(Zscaler, Netskope, Palo Alto Prisma)를 배포하는 경우가 많습니다. Myrm은 원클릭 엔터프라이즈 네트워크 호환성을 제공합니다.

- **설정 → 고급 → 기업 네트워크 호환성** 또는 `MYRM_TLS_STRICT=0` 설정
- Python 3.13+ `VERIFY_X509_STRICT` 플래그의 정밀 완화 — 인증서 확인을 비활성화하지 않습니다.
- 사용자 정의 CA 번들 지원: `SSL_CERT_FILE`(시스템 신뢰 저장소 교체) 또는 `NODE_EXTRA_CA_CERTS`(시스템 신뢰 저장소에 추가)
- **MCP서버별 TLS**: 각 MCP 서버는 전체 mTLS에 대해 자체 `ssl_verify`(참/거짓/사용자 지정 CA 경로) 및 `client_cert`/`client_key`/`client_key_password`을 지정할 수 있습니다.
- 4계층 자동 주입: 인프라(`tls_compat.py`) → 서버(`tls_config.py`) → MCP(`client.py`) → LLM(`llm.py`), 28개 이상의 HTTP 클라이언트 호출 사이트 포함
- 자동 TLS 오류 진단: 8개 오류 패턴 감지, 5개 언어 수정 힌트
- **144개의 TLS 관련 테스트 검증**(38개의 TLS 코어 + 31개의 MCP TLS + 75개의 오류 진단)

### 시크릿 모드 심층 분석

메시지 입력 영역의 원클릭 토글은 세션별 개인 정보 격리를 활성화합니다.

- **하네스 레이어**: `IncognitoPolicy`는 MEMORY 및 ARCHIVE 컨텍스트 장면에 대한 모든 쓰기를 물리적으로 건너뜁니다.
- **서버 계층**: 메모리 관리자 바인딩 및 모든 메모리 도구(`memory_search_tool`, `memory_save`, `memory_manage`)를 건너뛰고 메모리 컨텍스트 삽입, 아카이브 체크포인트 및 세션 정리 콜백을 비활성화합니다.
- **데이터베이스 레이어**: `is_incognito` 플래그는 세션이 사이드바 목록에서 숨겨지고 전체 텍스트 검색에서 제외되도록 보장합니다.
- **자체 호스팅 이점**: 데이터를 공급업체 서버에 보관하기 위해 별도의 "로컬 모드" 토글이 필요한 SaaS 경쟁업체와 달리 Myrm의 자체 호스팅 아키텍처는 사용자 데이터가 설계상 시스템 외부로 절대 나가지 않음을 의미합니다. 시크릿 모드는 세션 수준 비지속성을 추가합니다.

## 자격 증명 보호

### 자격증명 보관 양식

비밀번호 및 TOTP 시드는 **LLM 컨텍스트를 입력하지 않습니다**. **설정 → 자격 증명**에서 레이블이 있는 자격 증명을 구성합니다. 에이전트는 라벨 이름(예: `github-personal`)만 보고 `fill_credential`을 호출합니다(브라우저와 데스크톱은 동일한 작업을 사용함). 하네스는 메모리의 레이블을 확인하고 DOM 또는 OS 입력 레이어에 삽입합니다. 일반 텍스트는 결코 채팅, 도구 인수 또는 로그로 다시 흐르지 않습니다.

공급자 API 키(OpenAI, Anthropic, Gemini 등)는 LiteLLM의 `api_key` 매개변수를 통해 전달됩니다 — **제로 `os.environ` 쓰기**. 프로세스 수준 샌드박스 격리와 결합되어 구조적으로 사용자 간 자격 증명 유출을 제거합니다. **279** 자격 증명 보안 테스트를 통과했습니다.

| What you get | Technical basis | Plain-language benefit |
|--------------|-----------------|------------------------|
| **Label-only agent view** | Tool schema exposes labels, not values | Safe to let the agent log in — it cannot "see" or repeat your password |
| **Browser + desktop coverage** | `fill_credential` (unified action) + password-field block on macOS/Windows/Linux | Same vault works for web apps and native desktop login |
| **Built-in TOTP** | RFC 6238 generation inside the vault | 2FA flows without you reading codes aloud or pasting into chat |
| **Encrypted storage** | AES-256-GCM in Server DB, synced to Harness memory vault on startup; partial metadata edits preserve in-memory secrets | Credentials at rest are encrypted; editing description in Settings does not break live automation |

<Note>
Payment-card CVV has no dedicated `use_payment_method` API yet (unlike FSB's browser extension). Password-type fields are covered; card checkout may need manual approval or future API.
</Note>

### 누출 감지

40개 이상의 정규식 패턴이 에이전트 출력에서 자격 증명을 감지합니다.

- API 키(OpenAI, Anthropic, AWS, GCP, Azure 등)
- 데이터베이스 연결 문자열
- JWT 토큰 및 세션 ID
- SSH 개인 키
- 알 수 없는 자격 증명 형식에 대한 엔트로피 기반 감지

### PII 수정 및 개인정보 보호 라우팅

Myrm은 57가지 이상의 탐지 기능을 갖춘 8계층 PII 방어 기능을 제공합니다. 이는 AI 에이전트 플랫폼 중 가장 심층적인 개인 정보 보호 기능입니다.

**탐지(3개 엔진, 57개 이상의 유형):**
- **Regex PII 스캐너**: 12개 이상의 구조화된 유형(전화, ID 카드, 여권, Luhn 검증이 포함된 은행 카드, SSN, 이메일, 주소, 택배 번호, 개인 IP 등)
- **LLM 시맨틱 스캐너**: PL2/PL3/PL4 분류를 갖춘 20개 이상의 비구조적 유형(의료 건강, 정치적 견해, 재무 기록, 정확한 위치, 생체 인식)
- **자격 증명 누출 스캐너**: Shannon 엔트로피 분석이 포함된 25개 이상의 비밀 패턴(AWS, OpenAI, Anthropic, GitHub, Slack, JWT, PEM 키 등)

**보호(사용자 선택 가능 모드 4개):**

| Mode | Action | Use Case |
|------|--------|----------|
| **WARN** | Log detection, pass content through | Monitoring-only environments |
| **REDACT** | Type-aware irreversible masking (e.g., `138****5678`) | Production default for S2 data |
| **PSEUDONYMIZE** | Reversible placeholder replacement via SQLite-backed `PseudonymStore` with streaming-safe chunk-boundary restoration | When AI needs context but user sees originals |
| **BLOCK** | Completely block the message | S3-level confidential data |

**개인 정보 보호 모델 라우팅**: 민감도 수준에 따라 요청을 자동으로 라우팅합니다(S1은 클라우드로, S2는 클라우드 수정 후 또는 로컬로, S3는 로컬 전용으로(데이터가 시스템을 떠나지 않음)). 구성 가능한 대체: 차단 또는 강제 수정 후 클라우드.

**GUI 구성**: 설정의 전체 개인 정보 보호 제어 — 토글 활성화/비활성화, 레벨별 작업 선택, 심층 스캔 토글, 로컬 모델 연결 테스트, 사용자 정의 키워드/정규식/민감한 도구 및 실시간 테스트 일치.

### 요약 경로 보호

긴 대화를 구조화된 요약으로 압축하면 PII와 자격 증명이 요약 프로세스에서 살아남을 수 있습니다. Myrm은 지속성 이전에 모든 요약 필드에 이중 수정(`redact_leaks` + `redact_pii`)을 적용하여 전화번호, 이메일, API 키 및 기타 민감한 데이터가 압축된 대화 기록에 지속되지 않도록 합니다.

### 오염 추적

`TaintTracker`는 에이전트 실행을 통해 민감한 데이터의 정보 흐름을 따라 PII가 간접 채널(예: 자격 증명이 포함된 파일을 읽은 다음 웹 요청에서 해당 데이터를 사용하는 도구)을 통해 유출되지 않도록 합니다.

### 에이전트 내보내기 보안

공유 또는 백업을 위해 에이전트 구성을 내보내면 자격 증명이 자동으로 제거됩니다.

| What's stripped | Where | Why |
|----------------|-------|-----|
| `api_key`, `bearer_token`, `client_secret`, `password`, `username` | `openapi_services[].auth` | Prevent API credential leaks in shared configs |
| `auth_token` | `tool_gateway_config` | Prevent gateway token leaks |

팀 에이전트는 반복적으로 내보내기 - 모든 구성원 구성은 자격 증명이 제거된 상태로 포함됩니다. 가져오기 시 팀 구성원은 원자적으로 생성됩니다(전부 아니면 전무 롤백).

<Note>
The `auth.type` field is preserved so the importer knows which authentication method to configure (e.g. "api_key", "bearer", "oauth2").
</Note>

### 개인 정보 보호 규칙 공유

절차적 메모리 규칙을 공유할 때(예: 팀원 또는 커뮤니티와) 추가 개인정보 보호 계층이 자동으로 적용됩니다.

- **경로 익명화** — 사용자 홈 디렉터리 경로가 `<USER>` 자리 표시자로 대체됩니다.
- **자격 증명 수정** — API 키와 비밀은 안전한 접두사(예: `sk-pro...f456`)로 잘립니다.
- **메타데이터 제거** — 타임스탬프, 업데이트 횟수, 내부 ID가 내보낸 규칙에서 제거됩니다.

이렇게 하면 개인 식별이 가능한 파일 경로나 자격 증명이 공유 규칙을 통해 유출될 수 없습니다. 자세한 내용은 [메모리 시스템 → 개인정보 보호 규칙 공유](/ko/core-concepts/memory-system#privacy-safe-rule-sharing)를 참조하세요.

### 비밀번호로 보호된 공유

아티팩트 및 대화 공유 링크는 상태 비저장, 제로 데이터베이스 설계로 **선택적 비밀번호 보호**를 지원합니다.

| What you get | How it works |
|--------------|-------------|
| **Password gate** | Password SHA-256 hash is mixed into the HMAC signing key — wrong password = invalid signature, no database lookup |
| **Adjustable expiry** | Choose 1, 7, 14, or 30 day TTL when creating the link (server-side min/max clamping) |
| **Rate limiting** | Public endpoints capped at 30 req/min (content) and 60 req/min (static assets) to prevent brute-force |
| **Dark-mode gate page** | Self-contained HTML page with dark/light mode, error feedback, and no external dependencies |
| **Salt isolation** | Artifact and conversation tokens use different HMAC salts — same password produces different signing keys |

비밀번호 보호는 전적으로 선택 사항입니다. 비밀번호 없이 생성된 링크는 UX 변경이나 성능 오버헤드 없이 이전과 동일하게 작동합니다.

<Note>
No competitors (Hermes, OpenClaw, LobsterAI, CoPaw, deer-flow, jiuwenclaw) offer artifact or conversation sharing, let alone password protection. Myrm is the only AI assistant with both capabilities.
</Note>

### 에이전트 비밀 관리 - 일반 텍스트 노출 제로

에이전트별 비밀(사용자 정의 API 키, 토큰, 환경 변수)은 **일반 텍스트 노출 제로 아키텍처**를 사용합니다.

| Security Property | How It Works |
|-------------------|--------------|
| **Frontend never receives values** | `listAgentSecrets` API returns only key names (`string[]`), never values |
| **No reveal endpoint** | Unlike competitors that return plaintext on "reveal," Myrm has no reveal pathway |
| **Edit requires new value** | Password input field, placeholder "Enter new value to overwrite" |
| **Sentinel protection unnecessary** | Since old values never reach the frontend, no "****" round-trip risk exists |
| **Encrypted at rest** | AES-256-GCM via `DatabaseSecretBackend` with server-side master key |
| **Atomic file writes** | `LocalSecretBackend` uses tempfile + `os.replace` + `fsync` for crash safety |
| **Log auto-redaction** | `SensitiveDataFilter` replaces token/key/secret patterns with `***REDACTED***` |
| **Agent isolation** | Each agent can only access its own secrets via `agent_id` scoping |

<Note>
Competitors (e.g., Multica) return plaintext environment variables to the frontend and must rely on sentinel values ("****") to prevent accidental overwrites. Myrm eliminates this entire attack surface by never exposing values.
</Note>

## 감사 추적

### 구조화된 감사 추적

모든 보안 결정은 Prometheus 실시간 지표와 함께 구조화된 감사 로그에 기록됩니다.

- 37가지 유형의 보안 결정(ALLOW, DENY, ASK, SSRF_BLOCKED, PII_REDACTED, TAINT_ESCALATE 등)
- 실시간 이상 탐지를 위한 Prometheus `policy_denial_total` 카운터
- `TaintTracker` 교차 도구 정보 흐름 추적 기능을 갖춘 세션 범위 누산기
- Cron 작업 메타데이터에는 실행 후 분석을 위한 전체 보안 감사가 자동으로 포함됩니다.

### 이벤트 유형

37개 이상의 구조화된 의사결정 유형은 다음을 포함하여 전체 보안 수명주기를 포괄합니다.

- `TOOL_CALL_START` / `TOOL_CALL_END`
- `APPROVAL_REQUESTED` / `APPROVAL_GRANTED` / `APPROVAL_DENIED`
- `MODEL_SWITCHED` / `FALLBACK_ACTIVATED`
- `ITERATION_LIMIT_REACHED` / `BUDGET_EXHAUSTED`
- `LOOP_DETECTED` / `CANCELLED`
- `COMPRESSION_TRIGGERED` / `CHECKPOINT_CREATED`

## 프로필 감사 엔진

**프로필 감사 엔진**은 모든 에이전트 프로필에 대한 실시간 구성 위험 평가를 제공합니다. 에이전트 설정에서 보안 탭을 열면 **상태 점수 카드**에 에이전트의 보안 상태가 즉시 표시됩니다.

- **점수**: 0–100(높을수록 안전함), 발견된 심각도에 따라 차감됩니다.
- **위험도**: 안전 / 낮음 / 중간 / 높음 / 심각 (5단계 색상으로 구분)
- **6차원 그룹 보기**: 차원별 색상 코딩을 사용하여 검사기 차원별로 그룹화된 결과 — 심각도 경계, 제목 및 실행 가능한 권장 사항이 포함된 개별 결과를 보려면 차원을 확장하세요.
- **원클릭 수정**: 정책 격차 발견에는 즉각적인 수정을 위한 수정(전환 전환) 또는 구성(설정 섹션으로 이동) 버튼이 포함됩니다.

### 6가지 감지 차원

| Checker | Color | Detects |
|---------|-------|---------|
| **Tool Exposure** | Orange | Dangerous built-in tool combinations (e.g., shell + file_write + MCP) and large tool surfaces |
| **MCP Auth** | Violet | MCP servers without authentication, insecure transport, or high scan findings |
| **Skill Aggregate** | Sky | Skills flagged as untrusted or rejected during import scanning |
| **Subagent Risk** | Rose | Multi-level delegation chains creating unauditable privilege paths |
| **Cron Risk** | Amber | Unattended scheduled tasks with high-privilege tools |
| **Policy Gap** | Slate | Missing security controls relative to enabled capabilities (with one-click fix) |

각 측정기준에는 문제 수 또는 '통과' 상태가 표시됩니다. 문제가 있는 측정기준을 확장하여 개별 결과를 표시할 수 있습니다.

### 디자인

- **Zero LLM**: 순수 결정론적 규칙 엔진 — 토큰 비용 없음, 즉각적인 응답
- **플러그인 아키텍처**: 각 검사기는 `BaseChecker`을 구현하며 독립적으로 확장 가능
- **자동 새로 고침**: 에이전트 구성 변경 사항을 저장하면 결과가 자동으로 업데이트됩니다.
- **프레임워크 수준**: 제품 UI뿐만 아니라 하네스 엔진을 사용하는 모든 프로젝트에서 사용 가능
- **테스트 범위**: 백엔드 단위 테스트 37개 + 프런트엔드 구성 요소 테스트 15개(총 52개)

## 작업공간 규칙 보안

Myrm은 모든 주요 AI 도구 생태계를 포괄하는 **17개 검색 지점**(루트 수준 파일 이름 13개 + 하위 디렉터리 패턴 4개)에서 프로젝트 수준 규칙 파일을 자동으로 검색하고 로드합니다.

- **루트 파일**: `.myrm.md`, `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `.cursorrules`, `.clinerules`, `.windsurfrules` 및 해당 대소문자 변형
- **하위 디렉터리**: `.myrm/rules/*.md`, `.cursor/rules/*.mdc`, `.claude/CLAUDE.md`, `.github/copilot-instructions.md`
- **첫 번째 일치 승리**: 디렉터리별로 우선순위가 가장 높은 파일만 로드하여 충돌을 방지합니다.
- **제로 구성 마이그레이션**: Hermes(`SOUL.md`), Cline(`.clinerules`), Cursor(`.cursorrules`), Claude Code(`CLAUDE.md`), Windsurf(`.windsurfrules`)의 사용자는 규칙 파일을 변경하지 않고 가져올 수 있습니다.

발견된 모든 파일은 삽입 전에 보안 검사를 거칩니다.

- 26개 위협 카테고리에 걸쳐 **113개 탐지 패턴**
- **난독화 방지**: Leet 말하기, 보이지 않는 유니코드, 공백 접기, Base64 디코딩
- **중국어 주입 감지**: CJK 문자 기반 프롬프트 주입 지원
- 차단된 콘텐츠는 구조화된 메타데이터가 포함된 `[BLOCKED]` 자리 표시자로 대체됩니다.

## 비상 통제

| Control | Description |
|---------|-------------|
| **E-Stop** | One-click emergency stop that halts all running agents immediately |
| **Session Kill** | Terminate a specific agent session |
| **Tool Blacklist** | Dynamically block specific tools across all agents |
| **Budget Override** | Hard spending cap that overrides all agent budgets |

## 보안 대시보드

전용 `/security` 페이지는 시스템 보안 상태에 대한 완전한 GUI 가시성을 제공합니다. CLI 명령은 필요하지 않습니다.

| Tab | What It Shows |
|-----|---------------|
| **Dependencies** | Vulnerability alerts (Critical/High/Medium/Low counts) + Dependabot PRs + SBOM availability |
| **Rate Limit** | Real-time per-user/per-resource throttle status (current/max/remaining/window) |
| **Audit Logs** | Security event stream with multi-dimension filters (user ID, event type, result) + CSV/JSON export |
| **Audit Stats** | 24-hour analytics: time series, top IPs, event distribution, success-vs-failure breakdown |

추가 기능:
- **설정 패널**: 웹후크, 모니터링되는 저장소 및 GitHub 토큰의 구성 안내
- **다중 소스**: 배포 모드에 따라 GitHub, 제어 영역 또는 병합된 소스에서 데이터를 가져옵니다.
- **원클릭 새로고침**: 탭별 실시간 데이터 다시 로드
- **내보내기**: SIEM 통합을 위해 CSV 또는 JSON 형식으로 내보낼 수 있는 감사 로그

이 GUI 우선 접근 방식은 Hermes' CLI 전용 보안 명령(`hermes config view security`, `hermes pairing list`)보다 우수합니다. 사용자는 터미널 전문 지식 없이도 시각적 분석을 통해 동일한 정보를 얻을 수 있습니다.

## 스마트 승인(자동 모드)

Smart Intent Guard는 모든 신규 사용자에 대해 **기본적으로 활성화**되어 있습니다. 보조 LLM(Transcript Classifier)는 도구 호출을 실시간으로 검토하여 안전을 희생하지 않고 장시간 무인 상담원 세션을 가능하게 합니다. 전용 검토자 모델이 구성되지 않은 경우 Myrm은(는) 자동으로 사용자의 기본 모델을 대체 모델로 사용하므로 지능형 승인의 이점을 누리기 위해 추가 설정이 필요하지 않습니다.

| Layer | What It Does | When It Fires |
|-------|-------------|---------------|
| **Deterministic Rules** | Static permission engine evaluates against rulesets | Always (first) |
| **CommandRiskLevel** | Shell-pipe-aware classifier: SAFE (auto-allow) or UNKNOWN (needs review) | shell_exec with Auto Mode |
| **Allowlist Memory** | "Always Allow" user choice permanently auto-approves identical actions | ASK actions with prior user approval |
| **Taint Escalation** | Session contains PII/credential → even ALLOW tools get LLM review | ALLOW + tainted session |
| **Transcript Classifier** | Reasoning-blind LLM (sees only user messages + tool calls) → ALLOW/DENY/UNCERTAIN | ASK actions in Auto Mode |
| **Outbound Check** | Delegation actions force LLM review regardless of rule result | delegate_agent actions |
| **Shell Escalation** | Non-SAFE shell commands get LLM review even if rules say ALLOW | shell_exec + UNKNOWN risk |
| **Threshold Breach** | Consecutive denials → circuit-break auto-approval, revert to HITL | Too many denials |

오류 방지 보장:
- 분류자 오류 → HITL로 대체(실패 시 자동 승인되지 않음)
- 결정론적이고 재현 가능한 결정을 위한 `temperature=0`
- Pydantic이 시행하는 구조화된 출력(자유 텍스트 조작 없음)
- 상황 인식 판단을 위해 Taint 라벨 삽입

### 스마트 거부 → 사용자 무시(1회)

Transcript Classifier가 DENY를 권장하면 Myrm은(는) 해당 작업을 자동으로 거부하지 **않습니다**. 대신 명확한 승인 카드가 표시됩니다.

| Aspect | Behavior |
|--------|----------|
| **Visual indicator** | Amber warning box displaying the reviewer's denial reason |
| **Available actions** | "Override Once" and "Reject" only (session/always/edit hidden) |
| **Override behavior** | Action executes this one time but is NOT added to the allowlist — next identical action still triggers review |
| **Audit trail** | `LLM_REVIEW_DENY_USER_OVERRIDE` event recorded with reason |
| **Non-interactive sessions** | Cron jobs and shadow agents auto-deny without override option (fail-closed) |
| **High-risk paths** | Taint escalation, outbound delegation, and shell escalation always hard-deny — no override possible (security red line) |

이는 AI 검토자가 합법적인 작업을 잘못 분류하는 "거짓 긍정 잠금"을 방지하는 동시에 전체 감사 가시성을 유지합니다.

**경쟁업체와 비교:** Hermes은 CLI 전용 `once`/`deny` 버튼이 있는 `smart_denied_for_owner`을 제공하지만 시각적 이유 표시, 감사 로깅 및 오염/아웃바운드 경로에 대한 계층화된 하드 거부가 없습니다.

### 고위험 시나리오: 항상 숨김 허용

6가지 고위험 시나리오에서는 "항상 허용" 버튼이 승인 카드에서 자동으로 숨겨집니다. 사용자는 한 번만 승인하거나 거부할 수 있습니다. 이렇게 하면 위험한 작업에 대한 보안 검사가 실수로 영구적으로 우회되는 것을 방지할 수 있습니다.

| Trigger | Why Always Allow Is Hidden |
|---------|---------------------------|
| **Taint Escalation** | Session contains external network data — permanent allow would bypass all future taint checks |
| **Outbound UNCERTAIN** | AI reviewer uncertain about outbound delegation safety |
| **Shell Escalation UNCERTAIN** | Non-safe shell command under AI review uncertainty |
| **LLM Review UNCERTAIN** | General AI reviewer uncertainty about any tool call |
| **Auto Mode Suspended** | Consecutive denial threshold breached — system reverted to HITL |
| **Shell Threat Detected** | ShellCommandAnalyzer flagged a threat pattern |

일반적인 저위험 승인에는 평소와 같이 "항상 허용"이 표시됩니다. 사용자는 안전한 작동을 위해 마찰 변화가 전혀 발생하지 않습니다.

**경쟁업체 대비:** Hermes은 `tirith` 콘텐츠 보안 경고에 대해서만 영구 허용을 숨깁니다(트리거 1개). OpenClaw는 "항상 사용할 수 없음" 경고 메시지와 함께 백엔드 `allowedDecisions` 배열을 통해 제어합니다. Myrm은 업계에서 가장 포괄적인 6가지 트리거 시나리오를 다룹니다.

## 명령 거부 목록(사용자 정의 하드 플로어)

사용자는 YOLO 모드, Smart Intent Guard 결정 또는 권한 규칙에 관계없이 특정 명령을 영구적으로 차단하는 glob 패턴을 정의할 수 있습니다. 이는 어떤 승인 메커니즘으로도 우회할 수 없는 사용자 제어 안전망을 제공합니다.

| Feature | How It Works |
|---------|-------------|
| **Glob Pattern Matching** | Case-insensitive `fnmatch` matching (e.g., `git push --force*`, `rm -rf /*`, `DROP TABLE*`) |
| **Global + Per-Agent** | Set global deny patterns in Security Settings, and per-agent overrides in Agent Configuration |
| **Union Merge** | Per-agent denylist is merged (union) with the global denylist — agents can only add restrictions, never remove global ones |
| **YOLO-Proof** | Denied commands are blocked even in YOLO mode — this is a hard floor below all approval layers |
| **GUI Editor** | Visual pattern editor with add/remove, example placeholders, and validation — no CLI or YAML editing needed |

명령 거부 목록은 승인 파이프라인의 **레이어 2a.5**에서 작동합니다. 즉, 권한 규칙 뒤, YOLO 우회 이전에 거부된 명령이 항상 차단되도록 합니다.

**자연어 정책 생성기**는 일반 언어 설명(예: "모든 강제 푸시 및 데이터베이스 삭제 명령 차단")에서 명령 거부 목록 및 네트워크 차단 목록 규칙을 생성할 수도 있습니다. 생성된 패턴은 검증되고, 사람이 읽을 수 있는 설명으로 미리 보고, 사용자 확인 후에만 적용됩니다.

## 메모리 쓰기 신뢰 격리

모든 메모리 쓰기는 AI에 의해 내부적으로 트리거된 경우에도 통합 보안 파이프라인을 통과합니다.

| Guard | What It Prevents |
|-------|-----------------|
| **Approval Queue** | Implicit preferences extracted by Cognitive Deriver go through the standard approval queue (no bypass). External content cannot silently pollute your Profile |
| **Security Scan** | Every memory write runs through `scan_and_clean_memory` with injection detection (CLEAN/WARN/REDACTED/BLOCKED) |
| **Preference Stability** | Multi-observation lifecycle (Candidate → Provisional → Active) ensures only validated preferences reach your Profile — single-conversation flukes are filtered out |
| **AGENT_SELF Priority Ceiling** | Agent self-generated procedural rules are capped at HIGH priority — they cannot claim CRITICAL (compression-immune) slots, preventing prompt inflation |
| **Profile Promotion** | Core preferences (communication style, cognitive depth, proactivity) promote to Profile only after stability validation, via `set_system_profile_attribute` with security scanning |

어떠한 경쟁업체도 메모리 쓰기 신뢰 격리를 구현하지 않습니다. 대부분의 에이전트는 승인, 검증 또는 우선순위 가드레일 없이 추출된 기본 설정을 사용자 프로필에 직접 기록합니다.

## 보안 프로필: 원클릭 안전 모드

MyRM은 사용자가 설정 UI에서 전환할 수 있는 세 가지 기본 보안 프로필을 제공합니다.

| Profile | Permissions | Use Case |
|---------|------------|----------|
| **Read Only** | All writes denied (files, shell, browser, skills, cron). Reads auto-allowed. | Research, planning, code review |
| **Workspace** | File ops within allowed roots, shell requires approval | Normal development |
| **Full Access** | All operations allowed (YOLO mode) | Trusted local environments |

프로필은 데이터베이스에 유지되며 서버를 다시 시작해도 유지됩니다. 각 에이전트는 자체적인 독립적인 보안 구성을 가질 수도 있어 "전체 액세스 개발자" 에이전트와 함께 "연구 전용 분석가" 에이전트와 같은 시나리오를 활성화할 수 있습니다.

## 크론 작업 실행 정책(작업별 최소 권한)

예약된 에이전트 작업은 바인드된 에이전트 프로필과 관계없이 **이중 계층 정책**을 지원합니다.

| Layer | What it controls | User benefit |
|-------|------------------|--------------|
| **Capability fence** (`required_capabilities`) | PermissionEngine gates shell, file write, MCP, code, etc. | Block dangerous operations even if the Agent profile is broad |
| **Tool scope** (`tools_allowed`) | Narrows which builtin tools mount at Turn1 (intersected with Agent tools at runtime) | Smaller schema, prompt-cache friendly, least-privilege unattended runs |

**편집 위치:** 설정 → 예약된 작업 → 작업 열기 → 실행 기록의 **실행 정책** 편집기(허용된 파일 시스템 루트와 동일한 배치 패턴) 새 작업은 기본적으로 제한되지 않습니다.

**내장된 보호 장치:**
- **기본적으로 실패 시 닫힘** — 명시적인 기능 선언이 없는 작업은 위험한 작업(셸, 코드 실행, MCP)을 자동으로 거부합니다. 경고 배너는 사용자에게 기능 펜스를 구성하거나 에이전트별로 YOLO 모드를 활성화하도록 안내합니다.
- **사전 설정 팩**(웹 전용/연구/devops) 이중 쓰기 기능 펜스 + 도구 범위, 청사진 SSOT에 맞춰 조정됩니다.
- **나중에 읽기 블루프린트**는 **빈 도구**와 함께 **라우터 모드**(`__wiki_source_sync__`)를 사용합니다. — 결정적 서버 측 풀, 제로 LLM 에이전트 회전, 브라우저 또는 코드 실행 없음.
- **Lifecycle Guard**는 Myrm 재시작/중지 또는 `pkill myrm-agent` 패턴을 포함하는 크론 프롬프트/명령/**실행 전 프로브 스크립트**를 거부하여 자체적으로 발생하는 중단 루프를 방지합니다.
- **제한된 작업은 기본 도구를 자동으로 얻지 않습니다** — 파일 전용 크론은 `code_execute`를 자동으로 활성화하지 않습니다. 제한되지 않은 작업은 여전히 ​​에이전트 기준을 상속합니다.

**경쟁업체 대비:** Hermes는 전역 `cron_mode: deny/approve` 부울 토글만 제공합니다. 모든 작업은 동일한 정책을 공유합니다. OpenClaw/LobsterAI/CoPaw/deer-flow/jiuwenclaw에는 크론 기능이 전혀 없습니다. Myrm은 GUI 편집, 청사진 자동 채우기 및 실패 시 닫힘 기본값을 통해 작업별 세분화된 기능 선언을 제공합니다.

## 하위 에이전트 재귀적 격리: 5계층 방어

에이전트가 하위 에이전트에 작업을 위임할 때 일반적인 실패 모드는 제어되지 않은 재귀 생성입니다. 즉, 하위 에이전트는 토큰 예산이 소진될 때까지 더 많은 하위 에이전트를 생성합니다.

MyRM은 5개 계층의 격리를 시행합니다.

| Layer | Mechanism |
|-------|-----------|
| **L0** | Type admission whitelist (only catalog-registered agent types) |
| **L1** | Global blocklist (7 orchestration tools + 2 privileged tools stripped from LEAF agents) |
| **L2** | Config-level blocklist + readonly mode additional blocks |
| **L3** | Child ⊆ Parent tool intersection (child can never have more tools than parent) |
| **L4** | Dual depth limits (global max 3 + per-config max_spawn_depth) |

추가 안전망: 페이로드 해시 중복 제거는 위임 루프를 방지하고, 결과 캐싱은 중복 작업을 방지하며, 3가지 메모리 격리 전략(EPHEMERAL / READ_ONLY_GLOBAL / COLLABORATIVE_SESSION)은 에이전트 간 데이터 오염을 방지합니다.

## 다중 에이전트 파일 보호: 8계층 방어

여러 에이전트가 동일한 작업 공간에서 동시에 작업하는 경우 파일 충돌은 데이터 손상의 가장 큰 원인입니다. MyRM은 8개 계층의 방어를 시행합니다. 모두 코드로 적용되며 프롬프트 의존도가 전혀 없습니다.

| Layer | Mechanism | What It Prevents |
|-------|-----------|-----------------|
| **L1** | **Read-Before-Write** (staleness_guard) | Blind edits on unread files — agent must read a file before writing |
| **L2** | **Version Match** (file_integrity_guard) | Stale edits — rejects writes when file content changed since last read |
| **L3** | **Full-Read-Before-Edit** (file_integrity_guard) | Partial reads — rejects edits if only part of a file was read |
| **L4** | **Line-Level Conflict Detection** (file_conflict_guard) | Overlapping edits — detects when two agents modify the same line range |
| **L5** | **Cross-Agent Activity Tracking** (file_activity_tracker) | Untracked concurrent access — records every agent's write activity per file |
| **L6** | **Automatic Workspace Isolation** (workspace_policy) | Shared-state corruption — auto-upgrades to ISOLATED_COPY when multiple agents write in parallel |
| **L7** | **Deferred Serial Merge** (batch_merge) | Merge conflicts — isolated workspaces merge back one-at-a-time |
| **L8** | **Auto-Cleanup on Completion** (subagent_manager) | Stale tracking data — clears all tracking records when a subagent finishes |

**실제 작동 방식:**

1. 상위 에이전트는 3가지 코딩 작업을 병렬 하위 에이전트에 위임합니다.
2. `workspace_policy`은 2개 이상의 병렬 작성기를 감지 → ISOLATED_COPY로 자동 업그레이드
3. 각 하위 에이전트는 자체 COW(기록 시 복사) 작업 영역 복제본을 갖습니다.
4. 하위 에이전트는 독립적으로 작동합니다. 잠금 경합이나 차단이 없습니다.
5. 완료되면 `batch_merge`은 변경 사항을 상위 작업 공간에 한 번에 하나씩 다시 적용합니다.
6. 두 하위 에이전트가 겹치는 줄을 편집한 경우 `file_conflict_guard`는 병합 시 충돌을 일으킵니다.

**경쟁업체 대비:** AWS Codex 에이전트 팀은 프롬프트 지침을 사용합니다("두 개의 활성 작업이 동일한 파일을 쓸 수 없습니다") — LLMs는 이 제약 조건을 무시할 수 있습니다. MyRM은 애플리케이션 코드의 모든 계층을 적용하므로 모델 동작에 관계없이 우회가 불가능합니다.

## 대 CaMeL 가드(hermes-agent-camel)

CaMeL Guard 프로젝트는 연구 기반 신뢰 경계 모델(신뢰할 수 있는 컨트롤러와 신뢰할 수 없는 데이터)을 구현합니다. Myrm의 보안 아키텍처는 훨씬 더 깊은 적용 범위를 제공합니다.

| Dimension | CaMeL Guard | Myrm |
|-----------|:---:|:---:|
| Defense layers | 1 (trust boundary) | **6** (onion defense-in-depth) |
| Loop detection | Simple threshold (warn after N, block after M) | **5 domain-specific detectors** with targeted suggestions (bash/browser/file/web/memory) |
| Error classification | Single-level FailoverReason enum | **3-layer system** (Recoverability → FailoverReason → ProbePolicy) |
| Credential pool | 2 strategies (fill_first/round_robin) | **4 strategies** + exponential backoff + jitter anti-stampede |
| Path security | Allowlist-based path checking | **PTC process-level sandbox isolation** |
| Context management | Single-file compressor | **20+ module pipeline** (cache healer + anti-thrashing + session notes) |
```