工作区信任扩展指南

什么是工作区信任？

工作区信任 是一个由与在 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的数组。对于列出的设置，当处于不受信任的工作区的受限模式时，扩展将不会被赋予工作区定义的值。

如何支持受限模式？

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

我的扩展是否有主入口点？

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

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

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

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

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

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

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

这不是一个详尽的需要工作区信任的情况列表。随着我们审查更多的扩展，我们将更新此列表。在考虑工作区信任时，请使用此列表来思考您的扩展可能执行的类似行为。

如果我不对我的扩展进行更改会怎样？

如上所述，一个没有对其package.json做出任何贡献的扩展将被视为不支持工作区信任。当工作区处于受限模式时，它将被禁用，并且用户将被告知由于工作区信任，某些扩展无法正常工作。这一措施是对用户最安全的方法。尽管这是默认设置，但作为扩展作者，设置适当的值以表明您已经努力保护用户和您的扩展免受恶意工作区内容的影响，是最佳实践。

工作区信任API

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

对于希望在Workspace Trust上控制其功能的扩展，它们应该为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 子句中。

贡献点

命令、视图或其他用户界面

当用户未信任工作区时，他们将在受限模式下操作，该模式的功能有限，主要用于浏览代码。在受限模式下禁用的任何功能应对用户隐藏。这可以通过when clause contexts和上下文键isWorkspaceTrusted来实现。即使命令未在用户界面中显示，仍然可以调用该命令，因此您应根据上述API在扩展代码中阻止执行或不注册命令。

配置（设置）

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

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

调试扩展

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

任务提供者

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

测试工作区信任

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