工作区信任扩展指南

什么是工作区信任？

工作区信任 是一个功能，由用户在 VS Code 中打开工作区时与意外代码执行相关的安全风险驱动。例如，考虑一种语言扩展，为了提供功能，可能会执行工作区中加载的代码。在这种情况下，用户应该信任工作区的内容不是恶意的。工作区信任在 VS Code 中集中了这个决策，并支持 受限模式 以保护免于自动代码执行，这样扩展作者就不需要自己处理这种基础设施。VS Code 提供静态声明和 API 支持，以便快速上扩展而无需在扩展之间重复代码。

入职

静态声明

在你的扩展中package.jsonVS Code 支持以下新功能能力财产不受信任的工作区输入：

功能:
  不信任的工作区:
    { 支持: 真 } |
    { 支持: 假, 描述: 字符串 } |
    { 支持: '有限', 描述: 字符串, 受限配置?: 字符串数组 }

对于支持属性，接受以下值：

• 真- 该扩展在受限模式下完全受支持，因为它不需要Workspace Trust来执行任何功能。它将像以前一样启用。
• 假的- 该扩展在受限模式下不受支持，因为它无法在没有工作区信任的情况下运行。在获得工作区信任之前，它将保持禁用状态。
• '有限的'- 一些扩展功能在受限模式下是受支持的。在授予工作区信任之前，应禁用与信任相关的功能。扩展可以使用 VS Code API 来隐藏或禁用这些功能。工作区设置可以通过信任自动控制，使用受限配置财产。

对于描述属性，必须提供为什么需要信任的描述，以帮助用户了解将禁用哪些功能或在授予或拒绝工作区信任之前他们应该审查什么。如果支持设置为真此属性被忽略。

该值为描述属性应添加到package.nls.json然后在package.json用于本地化支持的文件。

该受限配置属性接受一个配置设置 ID 的数组。对于列出的设置，在受限模式下，当对一个不受信任的工作区时，扩展不会被赋予由工作区定义的值。

如何支持受限模式？

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

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

如果一个扩展没有主要入口点（例如主题和语言语法），该扩展不需要Workspace Trust。扩展作者不需要对这样的扩展采取任何行动，因为无论工作区是否受信任，它们将继续正常工作。

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

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

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

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

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

您的扩展可能会将设置值用作您的扩展执行的 CLI 的标志。如果这些设置被恶意工作区覆盖，它们可能会被用作针对您的扩展的攻击向量。另一方面，如果设置的值仅用于检测某些条件，则可能不会构成安全风险，也不需要工作区信任。例如，一个扩展可能会检查首选 shell 设置的值是否为巴什或pwsh 以确定要展示哪些文档。 配置（设置） 部分下面有关于设置的指南，可以帮助您找到扩展的最佳配置。

这并不是需要Workspace Trust的案例的详尽列表。随着我们审查更多的扩展，我们会更新这个列表。在考虑Workspace Trust时，使用此列表来思考你的扩展可能会执行的类似行为。

如果我不更改我的扩展，会怎样？

如上所述，一个不为他们带来任何贡献的扩展package.json将被视为不支持Workspace Trust。当工作区处于受限模式时，它将被禁用，并且用户将收到通知，说明某些扩展无法工作，因为存在Workspace Trust。这是用户最安全的措施。尽管这是默认设置，但作为最佳实践，设置适当的值以表明您已努力保护用户及其扩展程序免受恶意工作区内容的侵害。

工作区信任 API

如上所述，使用 API 的第一步是将静态声明添加到你的package.json最简单的入职方法是使用一个假的值支持属性。再次强调，即使您什么都不做，这也是默认行为，但这是一个很好的信号，表明您已做出有意的选择。在这种情况下，您的扩展不需要做任何其他事情。在授予信任之前，它将不会被激活，然后您的扩展将知道它是在用户的同意下执行的。然而，如果您的扩展仅需要信任才能实现其部分功能，这可能不是最佳选择。

对于希望在Workspace Trust上限制其功能的扩展，他们应该使用'有限的'值支持属性，VS Code 提供了以下 API：

导出 命名空间 工作区 {
  /**
   * 当为真时，用户已明确信任工作区的内容。
   */
  导出 常量 isTrusted: 布尔值;

  /**
   * 当前工作区已受信任时触发的事件。
   */
  export const onDidGrantWorkspaceTrust: Event<void>;
}

使用是否可信属性用于确定当前工作区是否受信任onDidGrantWorkspaceTrust当信任已授予工作区时要监听的事件。您可以使用此 API 来阻止特定的代码路径，并在工作区被信任后执行任何必要的注册。

VS Code 还暴露了一个上下文键是否信任工作区用于当条款如下所述。

贡献积分

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

当用户尚未信任工作区时，他们将以受限模式运行，功能有限，旨在浏览代码。在受限模式下禁用的任何功能都应从用户隐藏。这可以通过以下方式实现：是否信任工作区即使命令未在用户界面中呈现，仍可以调用命令，因此您应在扩展代码中根据上述 API 阻止执行或不注册命令。

配置（设置）

首先，您应该审查您的设置，以确定是否需要考虑信任。如上所述，工作区可能会为您的扩展定义一个值，该值对使用是恶意的。如果您发现存在漏洞的设置，您应该使用'有限的'为了支持属性并列出设置ID受限配置数组。

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

调试扩展

VS Code将在受限模式下阻止调试。因此，调试扩展通常不需要信任，并且应该选择真为了支持然而，如果您的扩展提供了内置调试流程之外的额外功能、命令或设置，您应该使用'有限的'并遵循上述指导。

任务提供者

类似于调试，VS Code 阻止以受限模式运行任务。如果您的扩展提供了内置任务流程之外的附加功能、命令或设置，您应该使用'有限的'并遵循上述指导。否则，您可以指定支持：真输入：.

测试工作区信任

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