工作区信任扩展指南

什么是工作空间信任？

工作区信任是一项由与用户在 VS Code 中打开工作区时意外执行代码相关的安全风险驱动的功能。例如，考虑语言扩展为了提供功能，可以从当前加载的工作空间执行代码。在这种情况下，用户应该相信工作区的内容不是恶意的。Workspace Trust 将此决策集中在 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 的数组。对于列出的设置，在不受信任的工作区处于受限模式时，不会向扩展提供工作区定义的值。

如何支持受限模式？

为了帮助扩展作者了解 Workspace Trust 的范围以及哪些类型的功能在受限模式下是安全的，这里列出了需要考虑的问题。

我的扩展程序有主入口点吗？

如果扩展程序没有main入口点（例如主题和语言语法），则该扩展程序不需要工作区信任。扩展作者不需要对此类扩展采取任何操作，因为无论工作区是否受信任，它们都将继续独立运行。

我的扩展是否依赖于打开的工作区中的文件来提供功能？

这可能意味着可以由工作区或工作区中的实际代码设置的设置等。如果扩展从不使用工作区的任何内容，则它可能不需要信任。否则，看看其他问题。

我的扩展是否将工作区的任何内容视为代码？

最常见的示例是使用项目的工作区依赖项，例如存储在本地工作区中的 Node.js 模块。恶意工作区可能会签入该模块的受损版本。因此，这对于用户和分机来说是一个安全风险。此外，扩展程序可能依赖于 JavaScript 或其他控制扩展程序或其他模块行为的配置文件。还有许多其他示例，例如执行打开的代码文件以确定其输出以进行错误报告。

我的扩展是否使用确定可以在工作区中定义的代码执行的设置？

您的扩展程序可能会使用设置值作为您的扩展程序执行的 CLI 的标志。如果这些设置被恶意工作区覆盖，它们可能会被用作针对您的扩展的攻击媒介。另一方面，如果设置值仅用于检测某些条件，则可能不存在安全风险，并且不需要工作区信任。例如，扩展可能会检查首选 shell 设置的值是否为bash或pwsh确定要显示的文档。下面的配置（设置）部分提供了设置指南，可帮助您找到分机的最佳配置。

这并不是可能需要工作区信任的案例的详尽列表。当我们审查更多扩展时，我们将更新此列表。使用此列表来考虑您的扩展程序在考虑工作空间信任时可能会执行的类似行为。

如果我不更改我的扩展程序怎么办？

如上所述，不对其做出任何贡献的扩展package.json将被视为不支持 Workspace Trust。当工作区处于受限模式时，它将被禁用，并且用户将收到通知，某些扩展由于工作区信任而无法工作。对于用户来说，这种措施是最有安全意识的做法。尽管这是默认值，但最佳实践是设置适当的值，表明作为扩展程序作者，您已尽力保护用户和您的扩展程序免受恶意工作区内容的影响。

工作空间信任 API

如上所述，使用 API 的第一步是将静态声明添加到您的package.json. 最简单的加入方法是使用属性false的值supported。再说一遍，即使您什么都不做，这也是默认行为，但这对用户来说是一个很好的信号，表明您已经做出了深思熟虑的选择。在这种情况下，您的扩展不需要执行任何其他操作。在给予信任之前它不会被激活，然后您的扩展程序就会知道它是在用户同意的情况下执行的。但是，如果您的扩展仅需要信任其部分功能，那么这可能不是最佳选择。

对于希望在 Workspace Trust 上控制其功能的扩展，他们应该使用'limited'该属性的值supported，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 还公开了一个上下文键isWorkspaceTrusted，供在子句中使用when，如下所述。

贡献点

命令、视图或其他 UI

当用户不信任工作区时，他们将在受限模式下运行，并且浏览代码的功能有限。您在受限模式下禁用的任何功能都应对用户隐藏。这可以通过when 子句上下文和上下文 key来完成isWorkspaceTrusted。即使命令未显示在 UI 中，仍然可以被调用，因此您应该阻止执行或不在扩展代码中注册基于上述 API 的命令。

配置（设置）

首先，您应该检查您的设置以确定是否需要考虑信任。如上所述，工作区可能会为您的扩展所使用的设置定义一个对用户恶意的值。如果您识别出易受攻击的设置，则应使用'limited'该supported属性并在数组中列出设置 ID restrictedConfigurations。

当您将设置 ID 添加到restrictedConfigurations数组时，VS Code 将仅在受限模式下返回该设置的用户定义值。然后，您的扩展程序不需要进行任何额外的代码更改来处理该设置。授予信任后，除了工作区信任事件之外，还将触发配置更改事件。

调试扩展

VS Code 将阻止在受限模式下进行调试。因此，调试扩展通常不需要信任，而应该选择true该supported属性。但是，如果您的扩展提供了不属于内置调试流程的附加功能、命令或设置，则您应该使用'limited'并遵循上述指南。

任务提供者

与调试类似，VS Code 会阻止在受限模式下运行任务。如果您的扩展提供了不属于内置任务流的附加功能、命令或设置，您应该使用'limited'并遵循上述指南。否则，您可以指定supported: true.

测试工作空间信任

有关启用和配置 Workspace Trust 的详细信息，请参阅Workspace Trust 用户指南。