ワークスペースの信頼に関する拡張機能ガイド
ワークスペースの信頼とは？
ワークスペースの信頼は、ユーザーが VS Code でワークスペースを開いた際に発生する、意図しないコード実行に関連するセキュリティリスクに対処するための機能です。例えば、言語拡張機能が機能を提供するために、現在読み込まれているワークスペースからコードを実行する場合を考えてみてください。このシナリオでは、ユーザーはワークスペースの内容が悪意のあるものではないと信頼できる必要があります。ワークスペースの信頼は、この判断を VS Code 内で一元化し、自動的なコード実行から保護する制限付きモードをサポートすることで、拡張機能開発者がこのインフラストラクチャを自身で管理する必要がないようにします。VS Code は静的宣言と API サポートを提供し、拡張機能間でコードを重複させることなく、迅速に拡張機能を導入できるようにします。
導入方法
静的宣言
拡張機能の package.json において、VS Code は以下の新しい capabilities プロパティ untrustedWorkspaces をサポートしています。
capabilities:
untrustedWorkspaces:
{ supported: true } |
{ supported: false, description: string } |
{ supported: 'limited', description: string, restrictedConfigurations?: string[] }
supported プロパティには、以下の値を指定できます。
true- 拡張機能は制限付きモードで完全にサポートされます。機能の実行に「ワークスペースの信頼」を必要としないためです。これまで通りに有効になります。false- 拡張機能は制限付きモードではサポートされません。ワークスペースの信頼なしでは機能できないためです。ワークスペースの信頼が付与されるまで、拡張機能は無効のままになります。'limited'- 拡張機能の一部の機能が制限付きモードでサポートされます。信頼が必要な機能は、ワークスペースの信頼が付与されるまで無効にする必要があります。拡張機能は VS Code API を使用して、これらの機能を非表示にしたり無効にしたりできます。ワークスペースの設定は、restrictedConfigurationsプロパティを使用して、信頼に基づいて自動的に制限をかけることができます。
description プロパティには、なぜ信頼が必要なのかを説明する記述を指定する必要があります。これにより、ユーザーはどの機能が無効になるのか、あるいは信頼を付与または拒否する前に何を確認すべきかを理解できます。supported が true に設定されている場合、このプロパティは無視されます。
description プロパティの値は package.nls.json に追加し、ローカライズサポートのために package.json ファイルから参照するようにしてください。
restrictedConfigurations プロパティは、構成設定 ID の配列を受け取ります。リストされた設定については、制限付きモードの未信頼ワークスペースにおいて、ワークスペースで定義された値が拡張機能に与えられることはありません。
制限付きモードをサポートするには？
拡張機能開発者が「ワークスペースの信頼」の対象範囲と、制限付きモードで安全な機能の種類を理解できるよう、検討すべき質問リストを以下に示します。
拡張機能にメインのエントリポイントはありますか？
拡張機能に main エントリポイントがない場合（テーマや言語文法など）、ワークスペースの信頼は不要です。このような拡張機能は、ワークスペースの信頼状態にかかわらず動作し続けるため、開発者は何も対応する必要はありません。
拡張機能は、機能を提供するために開いているワークスペース内のファイルに依存していますか？
これは、ワークスペースによって設定可能な設定項目や、ワークスペース内の実際のコードなどを指します。拡張機能がワークスペースの内容を一切使用しないのであれば、おそらく信頼は必要ありません。そうでない場合は、他の質問を確認してください。
拡張機能はワークスペース内のコンテンツをコードとして扱いますか？
最も一般的な例は、プロジェクトのワークスペース依存関係（ローカルワークスペースに保存された Node.js モジュールなど）を使用する場合です。悪意のあるワークスペースが、改ざんされたバージョンのモジュールをコミットしている可能性があります。これはユーザーと拡張機能にとってのセキュリティリスクです。さらに、拡張機能が自身や他のモジュールの動作を制御する JavaScript やその他の設定ファイルに依存している場合もあります。他にも、エラー報告のために開かれたコードファイルを実行して出力を確認するような例も多く存在します。
拡張機能は、ワークスペースで定義可能な「コード実行を決定する設定」を使用していますか？
拡張機能が実行する CLI へのフラグとして設定値を使用しているかもしれません。これらの設定が悪意のあるワークスペースによって上書きされると、拡張機能に対する攻撃ベクトルの悪用される可能性があります。一方で、設定値がある特定の条件を検出するためにのみ使用される場合は、セキュリティリスクではないため、ワークスペースの信頼は不要です。例えば、優先されるシェル設定の値が bash か pwsh かを確認して、表示するドキュメントを決定するような場合です。以下の「構成（設定）」セクションで、拡張機能に最適な構成を見つけるためのガイダンスを提供しています。
これは、ワークスペースの信頼が必要となる可能性のある全ケースの網羅的なリストではありません。今後、より多くの拡張機能をレビューする中で、このリストを更新していきます。拡張機能を考える際、自身の拡張機能に同様の動作がないか、このリストを参考にしてください。
拡張機能に変更を加えない場合はどうなりますか？
前述の通り、package.json に何も記述しない拡張機能は「ワークスペースの信頼をサポートしていない」とみなされます。ワークスペースが制限付きモードの場合、その拡張機能は無効化され、ワークスペースの信頼が原因で一部の拡張機能が動作しない旨がユーザーに通知されます。この措置は、ユーザーにとって最もセキュリティ意識の高いアプローチです。これがデフォルトではありますが、拡張機能作者としてユーザーと拡張機能の内容を悪意のあるワークスペースから保護する努力を行ったことを示すため、適切な値を設定することがベストプラクティスです。
ワークスペースの信頼 API
前述の通り、API を使用するための第一歩は package.json に静的宣言を追加することです。導入の最も簡単な方法は、supported プロパティに false を設定することです。繰り返しますが、これは何も設定しない場合のデフォルト動作ですが、ユーザーに対して「慎重な選択をした」という良いシグナルになります。この場合、拡張機能は他に何もする必要はありません。信頼が付与されるまでアクティブ化されず、ユーザーの同意のもとで実行されていることを拡張機能が認識します。ただし、拡張機能の機能の一部のみに信頼が必要な場合、これは最適なオプションではない可能性があります。
ワークスペースの信頼に基づいて機能を制限したい拡張機能は、supported プロパティに 'limited' を使用すべきであり、VS Code は以下の API を提供します。
export namespace workspace {
/**
* When true, the user has explicitly trusted the contents of the workspace.
*/
export const isTrusted: boolean;
/**
* Event that fires when the current workspace has been trusted.
*/
export const onDidGrantWorkspaceTrust: Event<void>;
}
isTrusted プロパティを使用して現在のワークスペースが信頼されているかを確認し、onDidGrantWorkspaceTrust イベントを使用して信頼が付与されたタイミングをリッスンします。この API を使用して特定のコードパスをブロックし、ワークスペースが信頼された後に必要な登録処理を実行できます。
VS Code は、後述するように when 句で使用するためのコンテキストキー isWorkspaceTrusted も公開しています。
コントリビューションポイント
コマンド、ビュー、その他の UI
ユーザーがワークスペースを信頼していない場合、制限付きモードで動作し、コードの閲覧を主目的とした限定的な機能に制限されます。制限付きモードで無効にする機能は、ユーザーから見えないようにすべきです。これは、when 句コンテキストとコンテキストキー isWorkspaceTrusted を使用して実現できます。UI 上で表示されていなくてもコマンドは呼び出せる可能性があるため、拡張機能のコード内で上記の API に基づいて実行をブロックするか、コマンドを登録しないようにしてください。
構成（設定）
まず、拡張機能が利用する設定が信頼を考慮する必要があるかどうかを確認してください。前述のように、ワークスペースはユーザーにとって悪意のある設定値を定義できる可能性があります。脆弱な設定を特定した場合は、supported プロパティに 'limited' を使用し、設定 ID を restrictedConfigurations 配列に列挙してください。
restrictedConfigurations 配列に設定 ID を追加すると、制限付きモードでは VS Code はユーザー定義の設定値のみを返すようになります。そのため、拡張機能側で設定を処理するための追加コード変更は不要です。信頼が付与されると、ワークスペースの信頼イベントに加えて、構成変更イベントが発生します。
デバッグ拡張機能
VS Code は制限付きモードでのデバッグを禁止します。このため、デバッグ拡張機能は一般的に信頼を必要としないため、supported プロパティに true を選択すべきです。ただし、拡張機能が組み込みのデバッグフローに含まれない追加機能、コマンド、または設定を提供している場合は、'limited' を使用し、上記のガイダンスに従ってください。
タスクプロバイダー
デバッグと同様に、VS Code は制限付きモードでのタスク実行を禁止します。拡張機能が組み込みのタスクフローに含まれない追加機能、コマンド、または設定を提供している場合は、'limited' を使用し、上記のガイダンスに従ってください。それ以外の場合は、supported: true を指定できます。
ワークスペースの信頼をテストする
ワークスペースの信頼の有効化および設定に関する詳細については、ワークスペースの信頼ユーザーガイドを参照してください。