Permissions

목표

Kiro의 capability 기반 permissions 시스템을 이해하고, permissions.yaml로 에이전트의 도구 사용을 안전하게 통제하는 방법을 파악합니다.

안전하게 시작하기

처음에는 기본 승인 흐름을 유지하고, 민감 파일의 쓰기를 막는 규칙 하나부터 추가하세요. 반복해 확인한 읽기 전용 작업만 좁은 범위로 allow하고, 파일 쓰기·패키지 설치·원격 변경은 필요한 범위를 확인한 뒤 규칙을 추가합니다.

첫 규칙의 예시는 아래처럼 비밀 파일의 쓰기를 거부하는 것입니다. 특정 프로젝트에만 적용하려면 workspace-scoped 파일(~/.kiro/workspace-roots/<hash>/permissions.yaml)에 넣습니다.

rules:
  - capability: fs_write
    match: ["*.env", "*.pem", "*.key"]
    effect: deny

개념

Kiro는 capability 기반 permissions 시스템을 사용해, 에이전트가 할 수 있는 일을 세밀하고 선언적으로 통제합니다. capability마다 match 패턴과 명시적 effect로 규칙을 정의하며, 과거의 이분법적 trust 모델을 대체합니다.

시스템은 세 가지 핵심 개념으로 구성됩니다.

개념	내용
Capabilities	fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, sandbox_network. 메타 capability는 확장됨: all(sandbox_network을 제외한 모든 capability), builtin(모든 내장 도구), filesystem(fs_read + fs_write)
Effects	deny(항상 차단), ask(확인 요청), allow(조용히 진행)
Priority	deny > ask > allow — deny 규칙은 scope와 무관하게 항상 이김. 단 sandbox_network host 규칙은 예외

추가 규칙 속성:

• Match patterns — 규칙의 범위를 정하는 glob 패턴(fs는 파일 경로, shell은 명령 prefix, MCP는 서버/도구 이름)
• Exclude — 매치되면 안 되는 glob 패턴으로, "X만 빼고 전부 허용"을 구현

활용

Capability	IDE	CLI	Web	Mobile
Permissions YAML configuration	✓	✓	N/A	—
Interactive approval prompts	✓	✓	N/A	—
Global + workspace scopes	✓	✓	N/A	—
Managed cloud sandbox instead of permission prompts	N/A	N/A	✓	—

Web에서는 permissions.yaml 모델과 대화형 승인이 적용되지 않습니다. 에이전트가 동작마다 묻지 않고 격리된 cloud sandbox에서 실행되므로, 해당 행은 미지원이 아니라 N/A로 표시됩니다.

규칙 정의

규칙은 두 수준의 YAML 파일에서 정의합니다.

User-scoped (~/.kiro/settings/permissions.yaml) — 모든 프로젝트에 적용. 신뢰하는 작업을 미리 승인할 때 사용합니다.

🚨 범위를 넓히지 마세요

git *, npm *, npx * 같은 광범위한 shell 허용은 설치·게시·원격 변경까지 포함할 수 있습니다. 필요한 읽기 전용 명령이나 특정 스크립트만 별도 규칙으로 허용하고, 처음에는 ask를 유지하세요.

rules:
  # 예시로만 제시합니다. 실제 설정에서는 git/npm 전체가 아니라
  # 필요한 읽기 전용 명령 또는 특정 스크립트만 좁게 허용하세요.
  - capability: shell
    match: ["git *", "npm *", "npx *"]
    effect: allow

  - capability: fs_write
    match: ["src/**", "tests/**"]
    effect: allow

  - capability: fs_read
    effect: allow

  - capability: mcp
    match: ["my-server/*"]
    effect: allow

Workspace-scoped (~/.kiro/workspace-roots/<hash>/permissions.yaml) — 특정 프로젝트에만 적용.

rules:
  - capability: shell
    match: ["rm -rf *", "sudo *"]
    effect: deny

위 안전하게 시작하기의 fs_write 규칙과 이 예시처럼 프로젝트별 규칙을 함께 둘 수 있습니다.

workspace permissions는 저장소 밖, 사용자별로 ~/.kiro/workspace-roots/<hash(workspaceRoot)>/에 저장됩니다. 복제한 저장소가 권한 규칙을 주입할 수 없다는 뜻입니다 — trust는 내 컴퓨터에서 직접 설정합니다.

Scopes와 우선순위

규칙은 여러 scope에 걸쳐 평가되며, deny-overrides 알고리즘(deny > ask > allow)을 씁니다. scope 간 우선순위는 없고, 어느 scope에서 왔든 가장 제한적인 effect가 이깁니다.

Scope	위치	허용 effect
Kiro	하드코딩된 보안 불변식(설정으로 변경 불가)	deny, ask
administration	managed-settings.json의 enterprise 정책	deny, ask
user	~/.kiro/settings/permissions.yaml	deny, ask, allow
workspace	~/.kiro/workspace-roots/<hash>/permissions.yaml	deny, ask, allow
agent	agent profile의 permissions 필드	deny, ask, allow
session	세션 중 consent 결정으로 생긴 in-memory 규칙	deny, ask, allow

🚨 주의

어느 scope의 deny 규칙이든 다른 곳의 allow 규칙과 무관하게 동작을 차단합니다. 어떤 allow 규칙도 이를 덮어쓸 수 없으니 deny 규칙은 신중하게 두세요. sandbox_network host 규칙만은 대신 순서가 결정합니다.

기본 동작

permissions.yaml이 없으면 기본 에이전트 정책은 다음을 허용합니다.

• ./**에 대한 fs_read — 워크스페이스 파일을 조용히 읽기
• 흔한 git 읽기 전용 명령(git status, git log, git diff, git branch 등)
• 시스템 정보 명령(pwd, whoami, uname 등)

Kiro scope(하드코딩, 설정 변경 불가)는 다음을 강제합니다.

• 항상 거부: ~/.kiro/settings/, .kiro/settings/, ~/.kiro/workspace-roots/, 모든 깊이의 .kiroignore에 대한 쓰기(에이전트가 자신의 권한/읽기 경계 파일을 못 바꾸게 함) 등
• 항상 확인: .git/**, .vscode/**, **/*.code-workspace, 그리고 .kiro와 ~/.kiro의 agents·hooks·workflows·powers 디렉터리에 대한 쓰기

permissions.yaml을 만들면 이 기본값에 더해질 뿐, 대체하지 않습니다.

해볼 것

💡 연습용 프로젝트에서 수행하세요. 민감 파일을 보호하는 규칙을 먼저 넣습니다.

1단계: workspace 규칙으로 민감 파일 쓰기 막기

해당 프로젝트의 ~/.kiro/workspace-roots/<hash>/permissions.yaml에 위 안전하게 시작하기의 fs_write deny 규칙을 적용합니다. 워크스페이스 신뢰 화면은 Kiro CLI 2.33 이상의 대화형 V3 세션에서 나타나며, 신뢰한 답은 ~/.kiro/workspace-roots/ 아래의 워크스페이스별 permissions 파일에 workspaceTrusted로 저장됩니다.

2단계: 승인 흐름 확인하기

deny 규칙에 걸리는 명령(예: rm -rf …)은 즉시 차단되고, 규칙에 없는 명령은 승인 프롬프트가 뜨는지 구분해 관찰합니다. 체인 명령(cd /path && cargo build)은 각 하위 명령이 따로 승인 제시된다는 점을 확인하세요.

3단계: 안전한 allow 규칙 추가하기

user scope에 fs_read: allow 같은 안전한 규칙을 추가해, 반복되는 읽기 확인 프롬프트가 사라지는지 확인합니다.

더 알아보기

• Permissions — policy presets, workspace trust, surface별 관리 포함
• Kiro 동작 원리 — 권한이 turn의 3단계(도구 호출 검사)에 붙는 위치
• 커스텀 에이전트 — agent profile의 permissions 필드
• Local command sandbox — sandbox_network capability와 host 규칙

---

출처: kiro.dev 공식 문서 "Permissions" (2026-10-26 확인).