Leitfaden für Erweiterungen für den Arbeitsbereich-Vertrauensschutz

Was ist Arbeitsbereich-Vertrauensschutz?

Arbeitsbereich-Vertrauensschutz ist eine Funktion, die auf den Sicherheitsrisiken basiert, die mit der unbeabsichtigten Ausführung von Code verbunden sind, wenn ein Benutzer einen Arbeitsbereich in VS Code öffnet. Betrachten Sie zum Beispiel, dass eine Spracherweiterung, um Funktionalität bereitzustellen, Code aus dem aktuell geladenen Arbeitsbereich ausführen kann. In diesem Szenario sollte der Benutzer darauf vertrauen, dass der Inhalt des Arbeitsbereichs nicht bösartig ist. Der Arbeitsbereich-Vertrauensschutz zentralisiert diese Entscheidung innerhalb von VS Code und unterstützt einen eingeschränkten Modus, um vor der automatischen Ausführung von Code zu schützen, sodass Erweiterungsautoren diese Infrastruktur nicht selbst handhaben müssen. VS Code bietet statische Deklarationen und API-Unterstützung, um Erweiterungen schnell zu integrieren, ohne dass Code über Erweiterungen hinweg dupliziert werden muss.

Onboarding

Statische Deklarationen

In der package.json Ihrer Erweiterung unterstützt VS Code die folgende neue Eigenschaft capabilities mit dem Namen untrustedWorkspaces

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

Für die Eigenschaft supported werden die folgenden Werte akzeptiert

• true - Die Erweiterung wird im eingeschränkten Modus vollständig unterstützt, da sie keinen Arbeitsbereich-Vertrauensschutz benötigt, um Funktionalität auszuführen. Sie wird genau wie zuvor aktiviert.
• false - Die Erweiterung wird im eingeschränkten Modus nicht unterstützt, da sie ohne Arbeitsbereich-Vertrauensschutz nicht funktionieren kann. Sie bleibt deaktiviert, bis der Arbeitsbereich-Vertrauensschutz gewährt wird.
• 'limited' - Einige Funktionen der Erweiterung werden im eingeschränkten Modus unterstützt. Vertrauenssensitive Funktionen sollten deaktiviert werden, bis der Arbeitsbereich-Vertrauensschutz gewährt wird. Die Erweiterung kann die VS Code API verwenden, um diese Funktionen auszublenden oder zu deaktivieren. Arbeitsbereich-Einstellungen können automatisch durch Vertrauenswürdigkeit eingeschränkt werden, indem die Eigenschaft restrictedConfigurations verwendet wird.

Für die Eigenschaft description muss eine Beschreibung bereitgestellt werden, warum Vertrauenswürdigkeit erforderlich ist, damit der Benutzer versteht, welche Funktionen deaktiviert werden oder was er überprüfen sollte, bevor er den Arbeitsbereich-Vertrauensschutz gewährt oder verweigert. Wenn supported auf true gesetzt ist, wird diese Eigenschaft ignoriert.

Der Wert für die Eigenschaft description sollte zu package.nls.json hinzugefügt und dann in der Datei package.json zur Lokalisierungsunterstützung referenziert werden.

Die Eigenschaft restrictedConfigurations nimmt ein Array von Konfigurationseinstellungs-IDs entgegen. Für die aufgeführten Einstellungen erhält die Erweiterung im eingeschränkten Modus für einen nicht vertrauenswürdigen Arbeitsbereich keine arbeitsbereichsspezifischen Werte.

Wie unterstütze ich den eingeschränkten Modus?

Um Erweiterungsautoren zu helfen, zu verstehen, was im Geltungsbereich des Arbeitsbereich-Vertrauensschutzes liegt und welche Arten von Funktionen im eingeschränkten Modus sicher sind, finden Sie hier eine Liste von Fragen, die Sie berücksichtigen können.

Hat meine Erweiterung einen Haupteinstiegspunkt?

Wenn eine Erweiterung keinen main-Einstiegspunkt hat (z. B. Themes und Grammatiken von Sprachen), benötigt die Erweiterung keinen Arbeitsbereich-Vertrauensschutz. Erweiterungsautoren müssen für solche Erweiterungen keine Maßnahmen ergreifen, da sie unabhängig davon, ob der Arbeitsbereich vertrauenswürdig ist oder nicht, weiter funktionieren.

Basiert meine Erweiterung zur Bereitstellung von Funktionen auf Dateien im geöffneten Arbeitsbereich?

Dies kann Dinge wie Einstellungen bedeuten, die vom Arbeitsbereich festgelegt werden können, oder tatsächlichen Code im Arbeitsbereich. Wenn die Erweiterung niemals Inhalte des Arbeitsbereichs verwendet, benötigt sie wahrscheinlich keinen Vertrauensschutz. Andernfalls werfen Sie einen Blick auf die anderen Fragen.

Behandelt meine Erweiterung Inhalte des Arbeitsbereichs als Code?

Das häufigste Beispiel hierfür ist die Verwendung von Projekt-Arbeitsbereich-Abhängigkeiten, wie z. B. Node.js-Module, die im lokalen Arbeitsbereich gespeichert sind. Ein bösartiger Arbeitsbereich könnte eine kompromittierte Version des Moduls einchecken. Dies ist daher ein Sicherheitsrisiko für den Benutzer und die Erweiterung. Darüber hinaus kann eine Erweiterung auf JavaScript oder andere Konfigurationsdateien angewiesen sein, die das Verhalten der Erweiterung oder anderer Module steuern. Es gibt viele andere Beispiele, wie z. B. die Ausführung einer geöffneten Code-Datei, um deren Ausgabe für die Fehlerberichterstattung zu ermitteln.

Verwendet meine Erweiterung Einstellungen, die die Codeausführung bestimmen und im Arbeitsbereich definiert werden können?

Ihre Erweiterung könnte Einstellungswerte als Flags für eine CLI verwenden, die Ihre Erweiterung ausführt. Wenn diese Einstellungen durch einen bösartigen Arbeitsbereich überschrieben werden, könnten sie als Angriffsvektor gegen Ihre Erweiterung verwendet werden. Wenn die Werte der Einstellungen jedoch nur verwendet werden, um bestimmte Bedingungen zu erkennen, ist dies möglicherweise kein Sicherheitsrisiko und erfordert keinen Arbeitsbereich-Vertrauensschutz. Eine Erweiterung könnte beispielsweise prüfen, ob der Wert einer bevorzugten Shell-Einstellung bash oder pwsh lautet, um zu bestimmen, welche Dokumentation angezeigt werden soll. Der Abschnitt Konfigurationen (Einstellungen) unten enthält Anleitungen zu Einstellungen, die Ihnen helfen, die optimale Konfiguration für Ihre Erweiterung zu finden.

Dies ist keine erschöpfende Liste von Fällen, die Arbeitsbereich-Vertrauensschutz erfordern könnten. Wenn wir weitere Erweiterungen überprüfen, werden wir diese Liste aktualisieren. Verwenden Sie diese Liste, um über ähnliche Verhaltensweisen nachzudenken, die Ihre Erweiterung möglicherweise bei der Berücksichtigung des Arbeitsbereich-Vertrauensschutzes ausführt.

Was passiert, wenn ich keine Änderungen an meiner Erweiterung vornehme?

Wie oben erwähnt, wird eine Erweiterung, die nichts zu ihrer package.json beiträgt, als nicht unterstützend für den Arbeitsbereich-Vertrauensschutz behandelt. Sie wird deaktiviert, wenn ein Arbeitsbereich im eingeschränkten Modus ist, und der Benutzer wird darüber informiert, dass einige Erweiterungen aufgrund des Arbeitsbereich-Vertrauensschutzes nicht funktionieren. Diese Maßnahme ist der sicherheitsbewussteste Ansatz für den Benutzer. Auch wenn dies der Standard ist, ist es eine bewährte Methode, den entsprechenden Wert anzugeben, der darauf hinweist, dass Sie als Erweiterungsautor Anstrengungen unternommen haben, den Benutzer und Ihre Erweiterung vor bösartigen Arbeitsbereichsinhalten zu schützen.

Arbeitsbereich-Vertrauensschutz API

Wie oben beschrieben, ist der erste Schritt zur Verwendung der API das Hinzufügen der statischen Deklarationen zu Ihrer package.json. Die einfachste Methode für das Onboarding wäre die Verwendung eines Werts von false für die Eigenschaft supported. Auch hier ist dies das Standardverhalten, selbst wenn Sie nichts tun, aber es ist ein gutes Signal für den Benutzer, dass Sie eine bewusste Entscheidung getroffen haben. In diesem Fall muss Ihre Erweiterung nichts weiter tun. Sie wird erst aktiviert, wenn Vertrauenswürdigkeit gewährt wurde, und dann weiß Ihre Erweiterung, dass sie mit Zustimmung des Benutzers ausgeführt wird. Wenn Ihre Erweiterung jedoch nur einen Teil ihrer Funktionalität vertrauenswürdig erfordert, ist dies wahrscheinlich nicht die beste Option.

Für Erweiterungen, die ihre Funktionen vom Arbeitsbereich-Vertrauensschutz abhängig machen möchten, sollten sie den Wert 'limited' für die Eigenschaft supported verwenden, und VS Code bietet die folgende 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>;
}

Verwenden Sie die Eigenschaft isTrusted, um festzustellen, ob der aktuelle Arbeitsbereich vertrauenswürdig ist, und das Ereignis onDidGrantWorkspaceTrust, um auf den Zeitpunkt zu warten, an dem der Arbeitsbereich vertrauenswürdig geworden ist. Sie können diese API verwenden, um bestimmte Codepfade zu blockieren und alle erforderlichen Registrierungen vorzunehmen, sobald der Arbeitsbereich vertrauenswürdig geworden ist.

VS Code stellt außerdem einen Kontextschlüssel isWorkspaceTrusted für die Verwendung in when-Klauseln zur Verfügung, wie unten beschrieben.

Beitragspunkte

Befehle, Ansichten oder andere Benutzeroberflächen

Wenn der Benutzer den Arbeitsbereich nicht vertraut hat, arbeitet er im eingeschränkten Modus mit eingeschränkter Funktionalität, die auf das Durchsuchen von Code ausgerichtet ist. Alle Funktionen, die Sie im eingeschränkten Modus deaktivieren, sollten dem Benutzer ausgeblendet werden. Dies kann über when clause contexts und den Kontextschlüssel isWorkspaceTrusted erfolgen. Ein Befehl kann immer noch aufgerufen werden, auch wenn er nicht in der Benutzeroberfläche angezeigt wird. Daher sollten Sie die Ausführung blockieren oder einen Befehl basierend auf der obigen API in Ihrem Erweiterungscode nicht registrieren.

Konfigurationen (Einstellungen)

Zunächst sollten Sie Ihre Einstellungen überprüfen, um festzustellen, ob sie den Vertrauensschutz berücksichtigen müssen. Wie oben beschrieben, kann ein Arbeitsbereich einen Wert für eine Einstellung definieren, den Ihre Erweiterung verwendet und der für den Benutzer bösartig ist. Wenn Sie anfällige Einstellungen identifizieren, sollten Sie 'limited' für die Eigenschaft supported verwenden und die Einstellungs-ID im Array restrictedConfigurations auflisten.

Wenn Sie eine Einstellungs-ID zum Array restrictedConfigurations hinzufügen, gibt VS Code im eingeschränkten Modus nur den vom Benutzer definierten Wert der Einstellung zurück. Ihre Erweiterung muss dann keine zusätzlichen Codeänderungen vornehmen, um die Einstellung zu verarbeiten. Wenn Vertrauenswürdigkeit gewährt wird, wird zusätzlich zum Ereignis des Arbeitsbereich-Vertrauensschutzes ein Konfigurationsänderungsereignis ausgelöst.

Debug-Erweiterungen

VS Code verhindert das Debuggen im eingeschränkten Modus. Aus diesem Grund müssen Debugging-Erweiterungen im Allgemeinen keinen Vertrauensschutz erfordern und sollten true für die Eigenschaft supported wählen. Wenn Ihre Erweiterung jedoch zusätzliche Funktionalität, Befehle oder Einstellungen bereitstellt, die nicht Teil des integrierten Debugging-Flows sind, sollten Sie 'limited' verwenden und die obigen Anweisungen befolgen.

Aufgabenanbieter

Ähnlich wie beim Debugging verhindert VS Code die Ausführung von Aufgaben im eingeschränkten Modus. Wenn Ihre Erweiterung zusätzliche Funktionalität, Befehle oder Einstellungen bereitstellt, die nicht Teil des integrierten Aufgaben-Flows sind, sollten Sie 'limited' verwenden und die obigen Anweisungen befolgen. Andernfalls können Sie supported: true angeben.

Testen des Arbeitsbereich-Vertrauensschutzes

Weitere Informationen zur Aktivierung und Konfiguration des Arbeitsbereich-Vertrauensschutzes finden Sie im Benutzerhandbuch zum Arbeitsbereich-Vertrauensschutz.