ワークスペース信頼拡張機能ガイド

ワークスペース信頼とは？

ワークスペース信頼は、ユーザーが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 clause contextsとコンテキストキーisWorkspaceTrustedを介して行うことができます。コマンドは、UIに表示されていなくても呼び出される可能性があるため、拡張機能のコードで上記のAPIに基づいて実行をブロックするか、コマンドを登録しないようにする必要があります。

構成（設定）

まず、設定をレビューして、信頼を考慮する必要があるかどうかを判断する必要があります。前述のとおり、ワークスペースは、拡張機能が使用する設定の値を定義する可能性があり、それが使用に対して悪意のあるものである可能性があります。脆弱な設定を特定した場合は、supportedプロパティに'limited'を使用し、restrictedConfigurations配列に設定IDをリストする必要があります。

設定IDをrestrictedConfigurations配列に追加すると、VS Codeは制限付きモードで設定のユーザー定義値のみを返します。したがって、拡張機能は設定を処理するために追加のコード変更を行う必要はありません。信頼が付与されると、ワークスペース信頼イベントに加えて構成変更イベントが発生します。

デバッグ拡張機能

VS Codeは、制限付きモードでのデバッグを防止します。このため、デバッグ拡張機能は通常、信頼を必要とせず、supportedプロパティにtrueを選択する必要があります。ただし、拡張機能が組み込みのデバッグフローの一部ではない追加機能、コマンド、または設定を提供する場合は、'limited'を使用し、上記のガイダンスに従う必要があります。

タスクプロバイダー

デバッグと同様に、VS Codeは制限付きモードでのタスクの実行を防止します。拡張機能が組み込みのタスクフローの一部ではない追加機能、コマンド、または設定を提供する場合は、'limited'を使用し、上記のガイダンスに従う必要があります。それ以外の場合は、supported: trueを指定できます。

ワークスペース信頼のテスト

ワークスペース信頼の有効化と構成の詳細については、ワークスペース信頼ユーザーガイドを参照してください。