strictKnownMarketplacesで許可できるソースの種類と書式

strictKnownMarketplacesは、組織のメンバーが追加できるマーケットプレイスのソースを許可リスト化する設定キーです。managed settingsに置き、/plugin marketplace addの時点から効きます。書式はソースの種類ごとに違います。GitHubリポジトリ1件を許可する書き方と、社内Gitサーバーをホスト単位でまとめて許可する書き方は別物です。

ここでは、許可リストに書ける8種類のソース、完全一致と正規表現で判定が変わる箇所、許可リストを置いても塞げない経路を扱います。

設定する前に知っておく適用範囲

このキーはmanaged settings(managed-settings.json、OSのポリシー配布、claude.aiの管理コンソール)だけで効きます。プロジェクトの.claude/settings.jsonやユーザー設定に書いても効きません。

値は3通りで、挙動が大きく違います。

この全ブロックが止めるのはマーケットプレイスの追加と取得です。claude.aiから同期されるプラグインは対象外で、止めるにはmanaged settingsでsyncClaudeAiPluginsをfalseにします(v2.1.273以降)。claude.aiで組織のSkillsをオフにする方法もあります。

許可リストは、他の設定ファイルの値と足し合わされません。managed settingsの複数のソースに書いた場合は、最も優先度の高いソースのリストが丸ごと使われ、下位のソースのエントリは加わりません。複数ソースに分けて書き足す運用は成立しないので、リストは1か所にまとめます。

claude.aiの管理コンソールに設定した場合は、claude.ai側でもgitリポジトリからのマーケットプレイス追加に同じ制限がかかります。

判定が走るタイミング

許可リストを設定している間は、マーケットプレイスが見つからないプラグインも、not-foundではなくポリシーのエラーで表示されます。典型例は、誰も登録していないマーケットプレイスを指す古いenabledPluginsのエントリです。

許可リストに書ける8種類のソース

エントリの書式は次のとおりです。hostPatternとpathPatternが正規表現マッチ、それ以外は完全一致です(githubのオーナーワイルドカードだけは例外)。

マーケットプレイス側のソース型には、ほかにnpm(package)とsettings(name・plugins・owner)があります。npmは許可リストに書いても何にもマッチしません。marketplace addがnpmマーケットプレイスを登録することがないためです。

urlソースはmarketplace.jsonだけをダウンロードし、そのサーバーから相対パスでプラグイン本体を取ることはしません。相対パスのプラグインを配るならgitかgithubのマーケットプレイスにします。プラグイン自身のsourceフィールドは別の書式です。相対パス、github、url、git-subdir、npm、archive、commandのいずれかを取ります。gitはマーケットプレイス側にしかなく、git-subdir・archive・commandはプラグイン側にしかありません。違いはClaude Codeプラグインソースの使い分けで扱っています。

ユーザーが打つ入力は、どの種別として照合されるか

許可リストは、ユーザーがclaude plugin marketplace addに渡した入力が分類された結果の種別に対して照合されます。入力の書き方と種別の対応は次のとおりです。

同じGitHubリポジトリでも、owner/repoと書けばgithub、https://github.com/owner/repo.gitと書けばgitとして扱われます。githubエントリは後者にマッチしません。許可リストにgithubエントリを置いた組織で、ユーザーがgit形式のURLで追加しようとして弾かれるのは、この分類の差が原因です。

完全一致・ワイルドカード・正規表現の使い分け

githubとgitの完全一致は、repo(またはurl)・ref・pathのすべてが一致したときだけ成立します。refを書いたエントリは同じrefのソースにしか合わず、書いていないエントリはrefなしのソースにしか合いません。次の2つは別のソースです。

{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

urlの完全一致は、書かれたurlの値だけを比べます。headersは比較に使われません。末尾スラッシュの有無、.gitサフィックスの有無、https://とssh://の違いは、すべて別のURLです。1つのマーケットプレイスを複数のURL形式でクローンできる組織は、リテラルなurlエントリよりhostPatternのほうが取りこぼしません。

オーナーワイルドカード

githubエントリのrepoは"acme-corp/*"と書け、そのオーナー配下の全リポジトリにマッチします(Claude Code v2.1.223以降)。

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/*" }
  ]
}

ワイルドカードにできるのはリポジトリ名の位置全体だけです。*、*/plugins、acme-corp/tools-*は無効なエントリとして無視され、どのリポジトリにもマッチしません。v2.1.223より前は、acme-corp/*が文字どおりに比較されて何にも合わなかったため、許可リストに書いたつもりでも全拒否になっていました。

ワイルドカードエントリは、完全一致よりpathの扱いが緩くなります。pathを書いたエントリはその値と一致する場合だけ、書いていないエントリはリポジトリ内のどのpathにもマッチします。refは完全一致と同じ規則のままです。

hostPatternとpathPattern

どちらも正規表現で、対象文字列のどこかに一致すれば成立します。^と$で固定しないと意図より広くマッチするので、ホストは^github\\.example\\.com$のように両端を固定します。

hostPatternが照合するホストは、ソースの種類と書き方で決まります。

• githubソースは常にgithub.com
• urlソースはURLのホスト名
• gitソースは、スキーム付きURLならそのホスト名、git@git.example.com:tools/plugins.gitのようなuser@host:path形式なら@と:の間のホスト
• スキームのないそれ以外の形式はホストなしで、どのhostPatternエントリにもマッチしない

最後の点は、v2.1.234より前のhostPatternが、gitがSSHアドレスと見なさない一部の形式にもマッチしていたことと対になっています。fileとdirectoryはホストを持たないので、hostPatternにはマッチしません。GHESやGitLabの自社ホストを丸ごと許可する設定例はGHESプラグインマーケットプレイスを許可リストで運用するにあります。

pathPatternは、ファイルシステム上のマーケットプレイスに使います。".*"は任意のローカルパスを許可します。hostPatternと組み合わせれば、ネットワーク側とファイルシステム側を別々に制御できます。

claude.aiがホストするマーケットプレイスは、ホストがclaude.aiにマッチするhostPatternエントリで許可・拒否します。許可リストにこのエントリを置くと、組織のclaude.aiマーケットプレイスとclaude.aiの既定マーケットプレイスが通ります。メンバー個人がclaude.aiにアップロードして作ったマーケットプレイスや、claude.ai側がスコープを示していないものは通りません。この扱いはClaude Code v2.1.273以降です。

公式マーケットプレイスだけを許可する

公式Anthropicマーケットプレイス以外を許可しない設定は、リポジトリを1件だけ書きます。

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" }
  ]
}

このエントリがあると、登録済みの公式マーケットプレイスはそのまま使えます。まっさらなマシンでも、Claude Codeを最初に対話的な端末セッションで起動したときに自動登録されます。

自動登録が働かないケースは3つあります。

• 初回の対話的な端末セッションより前に動く非対話環境
• Claude CodeをVS Code拡張経由でしか動かしたことのないマシン
• 過去に空配列ロックダウンのようなブロック下で端末セッションを動かしたマシン。ブロックされた試行は記録され、ポリシーを変えても自動では再試行されません

こうしたマシンには、同じmanaged-settings.jsonにextraKnownMarketplacesを足して自動登録させます。もう1つの方法は、claude plugin marketplace add anthropics/claude-plugins-officialを手動で実行します。extraKnownMarketplacesは「あれば登録する」設定で、strictKnownMarketplacesとは役割が違います。許可リストはextraKnownMarketplacesの登録も止めます。エントリのソースが許可リストに合わなければ、managed settingsに書いたものでも登録されません。

両方を同じファイルに書くと、制限と事前登録を同時に行えます。

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

社内マーケットプレイスを全員に配って必須化する運用はClaude Codeプラグインマーケットプレイスの必須化と自動更新設定にまとめています。

blockedMarketplacesとの違い

拒否リストのblockedMarketplacesは、strictKnownMarketplacesと同じソース書式を取り、許可リストより先に判定されます。判定ルールは次の点で違います。

urlエントリは、ユーザーがhttps://のリポジトリURLを追加し、Claude Codeがそれをクローンする場合にも効きます。素のgithub.comやgitlab.comのリポジトリURLが該当します(v2.1.232以降)。

拒否リストにも制約があります。すでに登録済みのマーケットプレイスは、拒否リストのエントリに合わないソースから登録されていれば、止められません。通常は許可リストだけで足り、特定のリポジトリだけを名指しで塞ぎたいときにblockedMarketplacesを足す形が扱いやすくなります。

許可リストが見ていないもの

strictKnownMarketplacesが見るのはマーケットプレイスの出所だけです。マーケットプレイスは登録せず、許可済みマーケットプレイスの中のエントリも制限しません。--plugin-dirも止めません。次の3つは別の設定で塞ぎます。

disableCommandPluginSourcesをtrueにすると、command sourceのコマンドは一切実行されません。該当プラグインはインストールも更新もされず、インストール済みのものも読み込まれなくなります。マーケットプレイスのheadersHelperコマンドも止まります(managed settings自身が宣言したマーケットプレイスは除く。この部分はv2.1.238以降)。未設定のときはallowManagedHooksOnlyの値に従うため、hookをmanaged設定だけに絞っている組織では、command sourceも既に止まっています。falseにすると明示的に許可できます。

disableSideloadFlagsは、対象のフラグを起動時に拒否してエラー終了します。エラーには拒否したフラグ名が出ます。Agent SDKのpluginsオプションと、CLAUDE_CODE_PLUGIN_DIRS環境変数で指定したフォルダも同様に拒否されます(環境変数側はv2.1.280以降)。クラウドセッションでは、セッション自体は始まります。そのうえで、サーバーから渡された--mcp-configのエントリは、プロセス内のtype: "sdk"とClaude TagのSlackツールを除いて捨てられます。.mcp.jsonやclaude mcp add、SDKが渡すサーバーは対象外なので、MCPはallowedMcpServersと併用します。

strictPluginOnlyCustomizationはtrueで4種類すべてを、プラグインかmanaged settings経由だけに絞ります。["skills", "hooks"]のように対象を限る配列も書けます。許可リストが入手経路を、この設定が読み込み元を絞るので、組み合わせるとカスタマイズの供給網全体を管理者の統制下に置けます。

pluginSuggestionMarketplacesは名前が似ていますが、/pluginのDiscoverタブなどに提案として表示してよいマーケットプレイスを絞る設定です。インストールの可否には影響しないので、許可リストの代わりにはなりません。

追加したマーケットプレイスはどう見えるか(v2.1.287で確認)

ポリシーを置かない状態で、ローカルディレクトリのマーケットプレイスを追加すると、分類がdirectoryになる様子が確認できます。ユーザー設定を汚さないよう、HOMEとCLAUDE_CONFIG_DIRを空のフォルダに差し替えて実行しました。

$ claude --version
2.1.287 (Claude Code)
 
$ claude plugin marketplace add ./mp --json
{"command":"marketplace-add","outcome":"ok","marketplace":"demo-mp","message":"Successfully added marketplace: demo-mp (declared in user settings)"}
 
$ claude plugin marketplace list
Configured marketplaces:
 
  ❯ anthropic-plugin-directory
    Source: Built in (Anthropic Directory)
 
  ❯ demo-mp
    Source: Folder (~/demo/mp)

marketplace addの--scopeはuser(既定)・project・localから選べ、--sparseでモノレポの一部ディレクトリだけをチェックアウトできます。ここでSource: Folderと表示されるものが、許可リストではdirectoryとして照合されます。

よくあるつまずき

• 許可リストを設定したらスキルフォルダのプラグインが読み込まれなくなった: .claude-plugin/plugin.jsonを持つスキルフォルダは、どんな許可リストでも読み込みが止まります。空配列も含みます。対象は~/.claude/skills/とプロジェクトの.claude/skills/です。維持するには{ "source": "skills-dir" }を加えます。plugin.jsonのない普通のSKILL.mdのスキルは影響を受けません
• allowedMarketplacesという別名で書いたのに無視される: この別名(とadditionalMarketplaces)が読まれるのはv2.1.232以降です。古いバージョンが混在するフリートに配るファイルでは、正式名のstrictKnownMarketplacesを使います。両方書いたファイルでは正式名の値が使われます
• hostPatternを書いたのにマッチしない: ホストを取り出せるのはスキーム付きURLとuser@host:path形式だけです。それ以外のスキームなし形式にはホストがなく、どのhostPatternともマッチしません
• 許可したgithubリポジトリなのに追加が弾かれる: refを付けて追加していないか、git形式のURLで打っていないかを見ます。ref・path・書式のどれが違っても別のソースです

「Marketplace is registered from an untrusted source」というエラーは、この許可リストとは別物です。Claude Code組み込みの予約名チェックによるものです。違いは「untrusted source」エラーの対処で扱っています。

まとめ

許可リストを書くときは、ユーザーが実際に打つ入力がどの種別に分類されるかを先に決めます。出所以外の経路は別のキーで塞ぎます。

command sourceとCLIフラグの持ち込みは、disableCommandPluginSourcesとdisableSideloadFlagsで止まります。マーケットプレイスの作り方や配布の基礎はClaude Codeプラグイン完全ガイドにあります。