现已推出！阅读 10 月份的新功能和修复。

工作区信任扩展指南

什么是工作区信任？

工作区信任 是一个功能，它由用户在 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 入口点（例如主题和语言语法），则扩展不需要工作区信任。扩展作者不需要对这些扩展采取任何措施，因为无论工作区是否信任，它们都将继续独立运行。

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

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

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

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

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

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

这不是可能需要工作区信任的案例的详尽列表。随着我们审查更多扩展，我们将更新此列表。在考虑工作区信任时，使用此列表来考虑你的扩展可能做出的类似行为。

如果我不对我的扩展进行更改怎么办？

如上所述，没有向其 package.json 做出任何贡献的扩展将被视为不支持工作区信任。当 workspace 处于受限模式时，它将被禁用，并且用户会收到通知，告知某些扩展由于工作区信任而无法正常工作。这是对用户最安全的做法。即使这是默认行为，但最好设置适当的值，表明作为扩展作者，你已尽力保护用户和你的扩展免受恶意 workspace 内容的影响。

工作区信任 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 还公开了一个上下文键 isWorkspaceTrusted，供在 when 子句中使用，如下所述。

贡献点

命令、视图或其他 UI

当用户未信任工作区时，他们将以受限模式运行，其功能有限，侧重于浏览代码。你应在受限模式下禁用的任何功能都应从用户界面中隐藏。这可以通过 when 子句上下文 和上下文键 isWorkspaceTrusted 来实现。即使命令未在 UI 中显示，也可以调用该命令，因此你应根据上述 API 在扩展代码中阻止执行或不注册命令。

配置（设置）

首先，你应该检查你的设置，以确定它们是否需要考虑信任。如上所述，workspace 可能会为你的扩展使用的设置定义一个对使用来说是恶意的值。如果你确定了易受攻击的设置，你应该为 supported 属性使用 'limited'，并将设置 ID 列在 restrictedConfigurations 数组中。

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

调试扩展

VS Code 在受限模式下会阻止调试。因此，调试扩展通常不需要请求信任，应将 supported 属性设置为 true。但是，如果您的扩展提供不在内置调试流程中的其他功能、命令或设置，则应使用 'limited' 并遵循上述指南。

任务提供程序

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

测试工作区信任

有关启用和配置工作区信任的详细信息，请参阅 工作区信任用户指南。

10/29/2024