ワークスペース信頼機能拡張ガイド
ワークスペース信頼機能とは
ワークスペース信頼機能は、ユーザーが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配列にリストする必要があります。
設定IDをrestrictedConfigurations配列に追加すると、VS Codeは制限付きモードで設定のユーザー定義値のみを返します。これにより、拡張機能は設定を処理するために追加のコード変更を行う必要がありません。信頼が許可されると、ワークスペース信頼イベントに加えて、構成変更イベントが起動します。
デバッグ拡張機能
VS Codeは制限付きモードでのデバッグを防止します。このため、デバッグ拡張機能は通常、信頼を必要とせず、supportedプロパティにtrueを選択する必要があります。ただし、拡張機能が組み込みのデバッグフローの一部ではない追加機能、コマンド、または設定を提供する場合、'limited'を使用し、上記のガイダンスに従う必要があります。
タスクプロバイダー
デバッグと同様に、VS Codeは制限付きモードでのタスクの実行を防止します。拡張機能が組み込みのタスクフローの一部ではない追加機能、コマンド、または設定を提供する場合、'limited'を使用し、上記のガイダンスに従う必要があります。それ以外の場合は、supported: trueを指定できます。
ワークスペース信頼機能のテスト
ワークスペース信頼機能の有効化と構成の詳細については、ワークスペース信頼機能ユーザーガイドを参照してください。