권한

에이전트가 IDE에서 할 수 있는 작업을 제어하는 역량(capability) 기반 권한 모델을 소개합니다.

개요

팁: 권한 모델은 IDE 1.0에서 새로 도입되었습니다. 0.x에서 업그레이드하는 경우 IDE 1.0 새 기능에서 변경 사항을 확인하세요.

에이전트가 수행하는 모든 작업에 하나의 통합된 권한 모델이 적용됩니다. 규칙 하나만 작성하면 모든 세션에서 npm * 명령을 허용하거나, .env 읽기를 거부해 모든 도구가 이를 동시에 준수하도록 만들 수 있습니다. 시각적 동의 흐름은 작업하는 과정에서 정책을 자동으로 구성합니다. 프롬프트에서 허용 또는 거부를 선택하고, 패턴을 고르고, 적용 범위를 지정하면 끝입니다.

규칙 구조

각 규칙은 네 개의 필드로 구성됩니다.

필드	설명	필수 여부
`capability`	제어 대상이 되는 작업 유형	예
`match`	리소스가 일치해야 하는 glob 패턴	아니요(기본값은 전체)
`exclude`	규칙 적용에서 리소스를 제외하는 glob 패턴	아니요
`effect`	`deny`, `ask`, `allow` 중 하나	예

효과(effect)는 제한 강도에 따라 결정됩니다. deny > ask > allow 순으로, 더 관대한 규칙이 더 제한적인 규칙을 덮어쓸 수는 없습니다.

규칙이 저장되는 위치

범위	위치	허용되는 효과
User	`~/.kiro/settings/permissions.yaml`	deny, ask, allow
Workspace	`~/.kiro/workspace-roots/<hash>/permissions.yaml`	deny, ask, allow

다음 범위는 시스템이 관리합니다.

범위	목적	허용되는 효과
Kiro	하드코딩된 보안 불변 규칙(재정의 불가)	deny, ask
Administration	엔터프라이즈/MDM으로 관리되는 정책(엔터프라이즈 플랜 전용)	deny, ask
Session	IDE에서 내린 동의 결정으로부터 생성된 메모리 내 규칙	deny, ask, allow

워크스페이스 권한은 저장소 외부에 사용자별로 ~/.kiro/workspace-roots/<hash(workspaceRoot)>/ 경로에 저장됩니다. 따라서 복제한 저장소가 권한 규칙을 주입할 수 없습니다.

IDE 동의 흐름

도구 호출이 ask로 평가되면 IDE는 채팅 패널 상단에 권한 프롬프트를 표시합니다. 다음 네 가지 즉시 선택지가 제공됩니다.

버튼	동작
Allow	이번 한 번의 호출만 허용합니다
Always allow	허용 규칙을 저장하는 영속화 대화상자를 엽니다
Deny	이번 한 번의 호출만 차단합니다
Always deny	거부 규칙을 저장하는 영속화 대화상자를 엽니다

결정 영속화

"Always allow" 또는 "Always deny"를 클릭하면 프롬프트가 확장되어 두 개의 추가 컨트롤을 표시합니다.

Pattern: 규칙에 사용할 glob 패턴입니다. IDE는 명령을 기반으로 패턴을 자동 제안합니다(예: git add 호출에 대해 git add *). 더 구체적으로 또는 더 넓게 직접 수정할 수 있습니다.

Apply to: 규칙이 저장되는 위치입니다.

범위	의미
All workspaces	`~/.kiro/settings/permissions.yaml`에 저장되어 모든 곳에 적용됩니다
This workspace	`~/.kiro/workspace-roots/<hash>/permissions.yaml`에 저장되어 이 프로젝트에서만 적용됩니다
This session	세션이 끝날 때까지 메모리에 유지됩니다

"Always allow"(또는 "Always deny")를 클릭해 확정합니다. 규칙은 즉시 적용되며, 선택한 범위에서 일치하는 작업에 대해 다시 프롬프트가 표시되지 않습니다.

UI에서 패턴이 동작하는 방식

패턴 드롭다운은 구체적인 명령을 일반화한 버전을 제안합니다. 예를 들면 다음과 같습니다.

정확한 명령 git add contents/docs/는 패턴 git add *가 됩니다
정확한 경로 .env.local은 패턴 .env* 또는 **/.env*가 됩니다

제안된 패턴을 그대로 선택하거나, 특정 하위 명령만 일치하도록 더 제한적으로 편집하거나 더 넓은 작업을 포괄하도록 더 관대하게 편집할 수 있습니다.

설정 예시

~/.kiro/settings/permissions.yaml을 생성합니다.

rules:
  - capability: shell
    effect: allow
    match:
      - git *
      - npm *
      - npx *
  - capability: mcp
    effect: allow
  - capability: fs_read
    effect: allow
  - capability: fs_write
    effect: allow
    match:
      - src/**
      - tests/**

기본 동작

별도의 설정이 없으면 기본 에이전트 정책이 다음을 허용합니다.

fs_read — ./**: 워크스페이스의 모든 파일 읽기
shell — 일반적인 읽기 전용 명령(git status, git log, git diff 등)
유틸리티 도구(diagnostics, knowledge 등)

Kiro 범위(하드코딩되어 있으며 재정의 불가)는 다음을 강제합니다.

항상 거부: ~/.kiro/settings/, .kiro/settings/, ~/.kiro/workspace-roots/에 대한 쓰기(에이전트가 자신의 권한 파일을 수정하지 못하도록 방지)
항상 질문: .git/**, .kiro/agents/**, .kiro/hooks/**, .kiroignore에 대한 쓰기

그 외 나머지는 모두 승인을 요청합니다. permissions.yaml을 생성하면 이러한 기본값에 규칙이 추가됩니다.

사용 가능한 역량

역량	제어 대상
`fs_read`	파일 읽기, 디렉터리 나열, 검색
`fs_write`	파일 쓰기, 편집, 삭제
`filesystem`	`fs_read` + `fs_write`의 축약형
`shell`	명령 실행
`web_fetch`	URL 가져오기
`web_search`	웹 검색
`mcp`	MCP 서버 도구 호출(패턴: `server/tool`)
`subagent`	서브에이전트 위임
`skill`	Skills 활성화
`power`	Powers 활성화 및 도구 호출
`diagnostics`	Diagnostics 도구
`context`	Context 및 Steering 도구
`all`	모든 역량(메타)
`builtin`	모든 내장 도구(메타)

패턴 매칭

규칙은 glob 패턴을 사용합니다. 문법은 역량 유형에 따라 다릅니다.

파일시스템 패턴(fs_read, fs_write):

*는 단일 경로 구성 요소 내에서 일치합니다
**는 경로 구분자를 가로질러 일치합니다
중괄호 확장 {...}과 문자 클래스 [abc]가 지원됩니다
와일드카드가 없는 패턴은 하위 항목까지 암시적으로 일치합니다. ~/temp는 ~/temp/child와 일치합니다

Shell, web, MCP 패턴:

*는 임의의 문자 시퀀스와 일치합니다
**, ?, 문자 클래스는 지원되지 않습니다

rules:
  # npm publish를 제외한 npm 명령 허용
  - capability: shell
    effect: allow
    match:
      - "npm *"
    exclude:
      - "npm publish*"

  # 모든 깊이의 시크릿 읽기 거부
  - capability: fs_read
    effect: deny
    match:
      - "**/.env"
      - "**/.env.*"
      - "secrets/**"
      - "**/*.pem"

  # 특정 MCP 서버 허용
  - capability: mcp
    effect: allow
    match:
      - "my-server/*"

Shell 관련 동작

Shell 명령은 패턴 매칭 이전에 파싱됩니다. 복합 명령(;, &&, ||, | 사용)은 분리되어 각 하위 명령이 독립적으로 평가됩니다. 이로써 npm test * 규칙이 npm test ; curl attacker.com과 실수로 일치하는 것을 방지합니다.

더 알아보기

권한이 Hooks 및 Custom Agents와 어떻게 함께 동작하는지는 해당 페이지를 참고하세요.