🚀 VS Code で で入手しましょう!

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

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

ワークスペース信頼は、ユーザーが 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' を使用し、restrictedConfigurations 配列に設定 ID をリストする必要があります。

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

デバッグ拡張機能

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

タスクプロバイダー

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

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

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

04/03/2025