ワークスペースの信頼拡張機能ガイド
ワークスペースの信頼とは何ですか？
ワークスペースの信頼は、ユーザーが 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を指定できます。
ワークスペースの信頼のテスト
ワークスペースの信頼の有効化と構成の詳細については、ワークスペースの信頼ユーザーガイドを参照してください。