Claude Code 플러그인을 팀에 배포하기 전에 — 9월 하순 2주간 고친 권한·마켓플레이스·비밀값 동작과 관리 설정

핵심 요약

먼저 알아 둘 용어

2주간 바뀐 것 — 다섯 가지

아래 인용은 모두 Claude Code 공식 변경 기록(code.claude.com/docs/en/changelog, GitHub의 CHANGELOG.md에서 생성)의 원문입니다. 버전은 그 항목이 처음 나온 버전입니다.

1) allowed-tools 사전 승인이 관리 설정을 넘던 문제

즉 2.1.284 이전에는 조직이 권한 규칙을 관리 설정으로만 제한해도, 공식 출처나 관리 설정이 보증한 출처가 아닌 마켓플레이스에서 설치한 플러그인이 자체 스킬 파일 상단의 allowed-tools로 도구를 미리 승인할 수 있었습니다. 공식 스킬 문서는 지금 이 동작을 이렇게 적습니다. "When your organization sets allowManagedPermissionRulesOnly in managed settings, Claude Code ignores allowed-tools in project and personal skills … This requires Claude Code v2.1.282 or later." 무시된 스킬은 /status에서 확인할 수 있습니다.

2) 마켓플레이스 이름 모방과 출처 제한

• 2.1.277 (09-18): "Fixed one malformed strictKnownMarketplaces or blockedMarketplaces entry silently disabling the whole enterprise marketplace policy". 허용·차단 목록에 잘못된 항목이 하나만 있어도 정책 전체가 경고 없이 꺼졌다는 뜻입니다. 2.1.277 전 버전에서 이 목록을 썼다면 항목 형식을 다시 확인해야 합니다
• 2.1.280 (09-22): "Changed plugin marketplaces whose name imitates a reserved marketplace name to be refused when added, and to stop loading if one was already added"
• 2.1.283 (09-25): "Fixed claude plugin validate saying Claude Code accepts a plugin or marketplace name it cannot install"
• 2.1.285 (09-29): "Improved plugin marketplace errors to name why a git address is refused instead of citing enterprise policy"

공식 마켓플레이스 문서는 claude-plugins-official 같은 공식 이름으로 마켓플레이스를 추가하면 "The name '<name>' is reserved for official Anthropic marketplaces"로 시작하는 메시지와 함께 거부한다고 적었습니다. 플러그인 이름에 claude·anthropic이 들어가는 경우는 claude plugin init·tag만 검사하고, 문서에 따르면 "Claude Code still installs and loads a plugin whose name they refuse"입니다. 이름만으로 공식 플러그인인지 판단하면 안 된다는 뜻입니다.

3) npm 소스와 의존성

• 2.1.286 (09-30): "Changed plugin installs to refuse npm sources that are git repositories or folders, and to install plugin dependencies only from registry packages"
• 2.1.284 (09-28): "Fixed a failed first claude plugin install leaving the plugin enabled and recorded when a dependency's version range could not be met"

마켓플레이스 참조 문서는 npm 플러그인 소스를 "fetched with your npm client and unpacked without running install scripts"라고 설명합니다. 2.1.286부터는 npm 패키지 이름 자리에 git 저장소나 로컬 폴더를 넣는 방식이 거부되고, 의존성도 레지스트리 패키지에서만 받습니다.

4) 설치 기록의 커밋이 실제 설치 상태와 맞지 않던 문제

세 번째 항목이 특히 중요합니다. 버전을 적지 않은 플러그인은 캐시가 지워졌을 때 설치했던 커밋이 아니라 출처의 최신 커밋으로 경고 없이 복원됐습니다. 따라서 검토한 코드와 실제 실행되는 코드가 달라질 수 있었습니다. 마켓플레이스 파일에서 github·url·git-subdir 소스는 ref와 함께 sha로 커밋을 고정할 수 있습니다(공식 마켓플레이스 참조 문서).

5) 로그·오류 메시지의 비밀값

비공개 마켓플레이스를 https://사용자:토큰@호스트/…처럼 비밀번호가 든 git 주소로 추가했거나, MCP 서버에 Bearer 토큰을 넘기는 팀이라면 2.1.286 전 버전의 로그·대화 기록·/feedback 파일에 비밀값 일부가 남았을 수 있습니다. 변경 기록은 2.1.286에서 "/feedback가 저장하는 zip의 대화 기록이 비밀값 가리기 뒤 잘못된 JSON 줄을 담던 문제"도 고쳤다고 적었습니다.

관리자가 지금 확인할 설정

버전

claude --version          # 2.1.286 이상인지 확인

위 다섯 가지 수정이 모두 들어간 첫 버전은 2.1.286입니다. 변경 기록은 매일 바뀌므로, 배포 시점의 최신 버전으로 맞추는 것이 더 낫습니다.

관리 설정 두 키

{
  "allowManagedPermissionRulesOnly": true,
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/approved-plugins" },
    { "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
  ]
}

• allowManagedPermissionRulesOnly를 켜면 권한 규칙은 관리 설정에서만 적용되며, 2.1.282 이상에서는 저장소·개인 스킬의 allowed-tools가, 2.1.284 이상에서는 마켓플레이스·claude.ai·npm 플러그인의 allowed-tools가 무시됩니다. 공식 Anthropic 출처나 관리 설정이 보증한 출처의 플러그인만 사전 승인을 유지합니다
• strictKnownMarketplaces는 공식 문서에 따르면 마켓플레이스 추가와 플러그인 설치·업데이트·새로고침·자동 업데이트에서 "before any network or filesystem operation" 검사합니다. 기본값은 설정하지 않음(모든 마켓플레이스 허용)이고, 빈 배열은 공식 마켓플레이스까지 막는 전면 차단입니다

마켓플레이스 파일의 커밋 고정

{
  "name": "formatter",
  "source": { "source": "github", "repo": "your-org/formatter",
              "ref": "v2.0.0", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" }
}

공식 문서의 예시입니다. 팀 마켓플레이스를 직접 운영한다면 검토한 커밋을 sha로 적어, 출처가 바뀌어도 검토하지 않은 코드가 들어오지 않게 합니다.

배포 전 검사

• claude plugin validate: 2.1.281부터 MCP 서버 설정의 안전하지 않은 URL과 선언되지 않은 ${user_config.*} 참조를, 2.1.283부터는 outputStyles·themes·monitors·lspServers 경로가 없거나 플러그인 폴더 밖을 가리키는 경우도 보고합니다. 셸 형태 훅에서 따옴표 없는 ${CLAUDE_PLUGIN_ROOT}도 경고합니다(2.1.281)
• /status: allowed-tools가 무시된 스킬 목록을 보여 줍니다(공식 스킬 문서)

운영 기록 — 이 블로그의 환경

이 블로그는 글 쓰기·색인 요청·SNS 게시를 Claude Code 프로젝트 스킬 4개로 운영합니다. 2026-10-02에 이 글을 쓰면서 확인한 상태는 이렇습니다.

• 작성에 쓴 맥의 Claude Code는 2.1.284였습니다. allowed-tools 수정은 들어 있지만 2.1.285~2.1.286의 비밀값 마스킹 수정과 npm 소스 제한은 아직 없는 버전입니다
• 프로젝트 스킬 4개 모두 allowed-tools를 쓰지 않으므로, 스킬이 스스로 도구를 미리 승인하지 않습니다
• 외부 마켓플레이스 플러그인은 프로젝트 설정으로 묶어 두지 않았습니다. 1인 운영이라 관리 설정은 쓰지 않습니다

체크리스트

1. 구성원의 Claude Code 버전을 2.1.286 이상으로 맞추세요. claude --version으로 확인합니다.
2. 권한을 잠그는 조직이라면 allowManagedPermissionRulesOnly를 켜세요. 2.1.284 이상에서는 공식 출처나 관리 설정이 보증한 출처가 아닌 플러그인의 allowed-tools 사전 승인도 막힙니다. 무시된 스킬은 /status로 봅니다.
3. 허용할 마켓플레이스만 strictKnownMarketplaces에 적으세요. 이름이 공식처럼 보여도 출처를 확인하고, 2.1.277 전 버전이 섞여 있다면 항목 하나의 형식 오류로 정책 전체가 꺼질 수 있었다는 점도 확인합니다.
4. 팀 마켓플레이스의 플러그인은 sha로 고정하세요. 버전을 적지 않은 플러그인은 캐시가 지워지면 최신 커밋으로 복원되던 문제가 있었습니다(2.1.283에서 수정).
5. 비밀번호가 든 git 주소로 마켓플레이스를 추가했다면 로그를 확인하세요. 2.1.286 전 버전의 로그·대화 기록에 일부가 남았을 수 있습니다. 그 파일을 공유했거나 업로드했거나 중앙 로그로 모았다면 토큰을 교체합니다. 앞으로는 git 자격 증명 도우미를 씁니다.
6. 배포 전에 claude plugin validate를 실행하세요. 안전하지 않은 MCP URL과 폴더 밖 경로를 잡아 줍니다.

아직 결론이 아닌 것

• 근거는 Anthropic이 쓴 변경 기록입니다. 각 문제가 언제부터 있었는지, 실제로 악용됐는지, 몇 명에게 영향이 있었는지는 기록에 없습니다. 별도 보안 권고(CVE 등)는 확인하지 못했습니다.
• 직접 재현하지 않았습니다. 이 글은 변경 기록과 공식 문서를 대조한 정리이며, 수정 전 버전에서 문제를 다시 일으켜 보지는 않았습니다.
• "2.1.286 이상"은 이 글이 다룬 항목 기준입니다. 같은 기간 다른 수정도 많고, 이후 버전에서 동작이 다시 바뀔 수 있습니다.
• 변경 기록을 고른 기준은 이 글의 판단입니다. 플러그인·마켓플레이스·스킬·비밀값 관련 항목 가운데 팀 배포의 보안에 영향을 주는 것만 골랐습니다.
• 공식 마켓플레이스 플러그인의 안전성은 다루지 않았습니다. 출처 제한과 커밋 고정은 검토한 것을 그대로 쓰게 할 뿐, 검토 자체를 대신하지 않습니다.

참고자료

공식 문서는 Markdown 원본(URL 끝에 .md)으로 받아 2026-10-02에 대조했습니다.

Anthropic이 관련 보안 권고를 내거나 동작을 다시 바꾸면 이 글을 고치고 개정 날짜를 적겠습니다.