Workspace Trust for Extension Authors

[sbatten]

This issue will be updated as information becomes available. Please subscribe and check back.

This issue will function as the landing page for extension authors while Workspace Trust is in development. If you are an extension author, please subscribe to this issue to receive notifications when the issue is updated.

Note that the feature has been in the works for some time now and we are nearing the phase where we would like extension authors to test it out and provide feedback. Once it is ready, we will post the extension authoring guide in this issue so that you can try adopting the new API.

To learn more about the development of the feature, check out our development issue: #106488

[sbatten]

Workspace Trust Extension Guide

What is Workspace Trust?

Workspace Trust is a feature driven by the security risks associated with unintended code execution when a user opens a workspace in VS Code. For example, consider that a language extension, in order to provide functionality may execute code from the currently loaded workspace. In this scenario, the user should trust that the contents of the workspace are not malicious. Workspace Trust centralizes this decision within VS Code so that extension authors do not have to handle this themselves. VS Code will offer static declaration and API support to onboard extensions quickly without the need to duplicate code across extensions.

Onboarding

Static Declarations

In your extension's package.json, VS Code will support the following new property:

capabilities:
	untrustedWorkspaces:
		{ supported: true } |
		{ supported: false, description: string } |
		{ supported: 'limited', description: string, restrictedConfigurations?: string[] }

For the supported property, the following values are accepted:

• true - The extension is fully supported in an untrusted workspace as it does not need workspace trust to perform any functionality. It will be enabled exactly as before.
• false - The extension is not supported in an untrusted worskpace as it cannot function without workspace trust. It will remain disabled until workspace trust is granted.
• 'limited' - Some features of the extension are supported in an untrusted workspace. Trust-sensitive features should be disabled until workspace trust is granted. The extension can use our API to hide or disable these features. Workspace settings can be gated by trust automatically using the restrictedConfigurations property.

For the description property, a description of why trust is needed must be provided to help the user understand what features will be disabled or what they should review before granting or denying workspace trust. If supported is set to true, this property is ignored.

💡The value for the description property should be added to package.nls.json and then referenced in the package.json file for localisation support.

For the restrictedConfigurations property, an array of configuration settings IDs are provided. When provided, the extension will not be given workspace-defined values for the given settings in an untrusted workspace.

How do I decide how my extension should support untrusted workspaces?

To help extension authors understand what is in scope for Workspace Trust, we have created a list of questions to consider.

Does my extension have a main entry point?

If the extension does not have a main entry point (ex: themes, language grammars), the extensions does not require workspace trust. Extension authors do not need to take any action for such extensions as they will continue to function independent whether the workspace is trusted or not.

Does my extension rely on files in the opened workspace to provide features?

This can mean things like settings that can be set by the workspace or actual code in the workspace. If the extension never uses any of the contents of the workspace, it probably doesn't require trust. Otherwise, take a look at the other questions.

Does my extension treat any contents of the workspace as code?

The most common example of this is using a project's workspace dependencies, such as the node modules stored in the local workspace. A malicious workspace might check in a compromised version of the module. Thus, this is a security risk for the user and extension. Auxiliary to this, an extension may rely on JavaScript or other configuration files that control the extension or other modules' behavior. However, many other examples could occur, such as executing an opened code file to determine its output a error reporting.

Does my extension use settings that can be defined in the workspace in any code execution?

Your extension might use settings values as flags to a CLI that your extension executes. If these settings are overridden by a malicious workspace, they could be used as an attack vector against your extension. On the other hand, if the settings' values are only used to detect certain conditions, (e.g. if the value of a preferred shell setting is bash or pwsh determines what documentation you show), then it may not be a security risk and does not require Workspace Trust. Below is a section dedicated to guidance on settings to help you find the optimal configuration for your extension.

This is not an exhaustive list of cases that might require Workspace Trust. As we review more extensions, we will update this list. Use this list to think of similar behavior your extension might be doing when considering Workspace Trust.

What if I don't make changes to my extension?

As mentioned above, an extension that does not contribute anything to their package.json will be treated as not supporting untrusted workspaces. It will be disabled when the workspace is not trusted and the user will be notified that some extensions are not working due to Workspace Trust. This measure is the most security-conscious approach for the user. Even though this is the default, it is still a best practice to set the appropriate value indicating that as an extension author, you have made the effort to protect the user and your extension from malicious workspace content.

How do I use the API?

As described above, the first step to using the API is adding the static declarations to your package.json. The easiest method of onboarding would be to use a false value for the supported property. Once again, this is the default behavior even if you do nothing, but it's a great signal to the user that you have made a deliberate choice. In this case, your extension does not need to do anything else. It will simply not be activated until trust is given and your extension can know that it is executing with the consent of the user. However, if your extension only requires trust for part of its functionality, this is likely not the best option.

For extensions that wish to gate their features on Workspace Trust, they should use the limited value for the supported property, and we provide the following 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>;
}

We provide a property to determine if the current workspace is trusted and an event for listening to when trust has been granted to the workspace. You can use these block specific code paths and perform any necessary registrations once the workspace has been trusted.

We also expose a context key isWorkspaceTrusted for use in when clauses as described below.

What about my contributions?

Commands, Views, or other UI

When the user has not trusted the workspace, they will operating in a mode with functionality geared towards browsing code. Any features that you provide that will not be trusted should be hidden from the user. This can be done via when clauses and the context key isWorkspaceTrusted. Since code can still call a command even if it is not presented in the UI, you should still block execution or not register a command based on the API above in your extension code.

Configurations/Settings

First, you should review your settings to determine if they need to take trust into account. As described above, a workspace may define a value for a setting that your extension consumes that is malicious to the use. If you identify settings that are vulnerable, you should use 'limited' for the supported property and list the setting ID in the restrictedConfigurations array.

When you add a setting ID to the restrictedConfigurations array, VS Code will only return the user-defined value of the setting in an untrusted workspace. This means your extension needs no additional code changes to handle the setting. When trust is granted, a configuration change event will fire in addition to the workspace trust event.

What is the guidance for debug extensions?

VS Code will prevent debugging in an untrusted workspace. For this reason, generally, debugging extensions do not need to additionally require trust and should select true for the supported property. However, if your extension provides additional functionality, commands, or settings that are not part of the built-in debugging flow, you should use 'limited' and the above guidance.

What is the guidance for task providers?

Similar to debugging, VS Code will prevent running tasks in an untrusted workspace. If your extension provides additional functionality, commands, or settings that are not part of the built-in tasks flow, you should use 'limited' and the above guidance. Otherwise, you can specify true.

How do I test Workspace Trust?

Please see this issue for current details on development of Workspace Trust. It should be up to date with how the feature is currently enabled.

[sbatten]

For those subscribed, we are now ready to share the API and guidance for onboarding to workspace trust for extension authors. This is the first time sharing the guidance to a broader audience so please post questions here and we can update it for clarity. Thanks for your engagement.

[gjsjohnmurray]

Is Workspace Trust going to land in the upcoming release?

[sbatten]

The setting to enable the feature will remain disabled by default in the upcoming release

[RandomFractals]

@sbatten thank you for providing guidance on how trusted workspaces would work.

I am concerned about your default behaviour and my expectations would be that extensions that provide web views, side bar views, pseudo terminals and commands you can run in terminal, and work with workspace files, would still function as before when this feature is released.

I would rather see this feature as opt-in for extensions that want to be enabled for trusted workspaces, and work as before for untrusted workspaces. I think the behavior you describe is the opposite.

What if I don't make changes to my extension?

As mentioned above, an extension that does not contribute anything to their package.json will be treated as not supporting untrusted workspaces. It will be disabled when the workspace is not trusted and the user will be notified that some extensions are not working due to Workspace Trust. This measure is the most security-conscious approach for the user. Even though this is the default, it is still a best practice to set the appropriate value indicating that as an extension author, you have made the effort to protect the user and your extension from malicious workspace content.

[firelizzard18]

@sbatten Is there a way to prompt the user, "To enable this feature, you must trust the workspace"? For extensions that provide actions a user can execute, simply hiding (and disabling) that functionality may be bad UX. For example, the ESLint extension - at the moment - will prompt the user to execute ./node_modules/.bin/eslint if it is present, saying something like "Do you trust this?" How should that be updated for Workspace Trust? As I read your explanation, the extension should silently disable that functionality for untrusted workspaces. As a user, I would prefer a prompt - "The extension eslint wants to do <some thing> that requires you to trust this workspace - continue?"

As another example, I have an extension that provides code lenses for profiling benchmarks (CPU/memory use). If I hide these code lenses in untrusted workspaces, I'm sure someone will report that as a bug ("the benchmark code lens doesn't show up for my workspace"). I'd like the API to include something like this:

export namespace workspace {
    export function shouldExecuteActionRequiringTrust(description: string, alertOnFailure: bool, details?: string): Promise<bool>
}

If the workspace is not yet trusted and has not yet been prompted, this would show a prompt asking if the user wants to trust the workspace. If the workspace is untrusted and alertOnFailure is true, this would show a notification that, " cannot execute because the workspace is not trusted".