Multilingual Wiki Documentation

You are currently using syntax.
In an attempt to improve PlantUML documentation...
Please do not use this website for your own diagrams.
You can click here and use the online server here for your own documentation.

Wiki Toc    Recent changes    View page history    Add new chapter    Reorder page    Raw


Déployer PlantUML de façon sécurisée

Notre travail en commun avec Sysdream nous a amené à proposer la notion de profil de sécurité dans PlantUML.

A partir de la version 1.2020.11, vous devez choisir quel profil de sécurité utiliser dans PlantUML. Le profil par défaut est LEGACY. Il reproduit le comportement des anciennes versions de PlantUML. Cela veut dire que vous pouvez sans problème mettre à jour votre configuration vers la version 1.2020.11. Toutefois, après la mise à jour, il serait sage que vous choisissiez alors un mode plus approprié selon la façon dont vous utilisez PlantUML.

Tout ceci est nécessaire car PlantUML est utilisé dans de nombreuses situations différentes qui nécessitent des réglages de sécurité différents.

Si vous utilisez une version antérieure à la version 1.2020.11 et que votre système est accessible depuis Internet, il est vraiment important que vous mettiez à jour votre serveur car les anciennes versions de PlantUML exposent un peu plus de données sur Internet qu'il est nécessaire. De fait, le nouveau mode par défault LEGACY est plus sécurisé que le mode de fonctionnement des anciennes versions.

Deploy PlantUML safely

Our collaboration with Sysdream leads us to introduce the notion of security profile within PlantUML.

Starting with version 1.2020.11, you have to choose which security profile use when running PlantUML. The default one is LEGACY. It emulates the behavior of older PlantUML versions. This means you can safely upgrade to 1.2020.11. However, you should then pick up an appropriate mode for your usage.

This is needed because PlantUML can be used in many different configurations which require different security setting.

If you are using a version older than 1.2020.11 and if your system is accessible from Internet, you should probably upgrade because older versions of PlantUML may expose a little more than you would expect. Even the new LEGACY default mode is now more secure than older PlantUML behavior.

Choisir son Profil de Securité

Le profil de sécurité peut être positionné de plusieurs façons:

  • Avec la variable d'environnement système PLANTUML_SECURITY_PROFILE
  • Avec la variable d'environnement Java PLANTUML_SECURITY_PROFILE

En pratique, vous pouvez faire:

set PLANTUML_SECURITY_PROFILE=INTERNET

ou bien:

setenv PLANTUML_SECURITY_PROFILE INTERNET

Une autre façon est d'utiliser la ligne de commande (ne pas oublier le -D) :

java -DPLANTUML_SECURITY_PROFILE=INTERNET -jar /path/to/plantuml.jar ...

Ou encore si vous utilisez Java et PlantUML comme bibliothèque:

System.setProperty("PLANTUML_SECURITY_PROFILE", "INTERNET");

Choose your Security Profile

The Security Profile can be set two different ways:

  • Setting the OS environnement variable PLANTUML_SECURITY_PROFILE
  • Setting the Java environnement variable PLANTUML_SECURITY_PROFILE

In practice, you can do:

set PLANTUML_SECURITY_PROFILE=INTERNET

or

setenv PLANTUML_SECURITY_PROFILE INTERNET

Another way is an option in the command line (do not forget the -D flag):

java -DPLANTUML_SECURITY_PROFILE=INTERNET -jar /path/to/plantuml.jar ...

Or if you are using Java and PlantUML as a library:

System.setProperty("PLANTUML_SECURITY_PROFILE", "INTERNET");

Profil de sécurité disponibles

Il y a cinq profils de sécurité différents:

UNSECURE

Quand PlantUML est en mode UNSECURE mode, PlantUML peut avoir accès à tous les fichiers locales du serveur sur lequel il tourne ainsi qu'à n'importe quelle URL.

Le nom de ce profil ne signifie pas que vous ne devez pas l'utiliser. Par exemple, si vous utiliser PlantUML depuis un script pour générer votre documentation, il n'y a aucun problème à utiliser ce mode.

Cela devient problématique si ce mode est utilisé depuis un serveur Web accessible depuis Internet. En effet, vous n'avez dans ce cas aucun contrôle sur ce que les utilisateurs vont faire dans leurs diagrammes.

LEGACY

Pour l'instant, ce mode est le mode par défaut de PlantUML. Ce mode donne le même comportement que les anciennes versions de PlantUML: accès complet aux fichiers locaux et aux URL. En conséquence, vous pouvez vous mettre à jour vers la version 1.2020.11 sans aucun risque de régressions.

Ceci dit, après votre mise à jour, vous devriez choisir un profil de sécurité autre que LEGACY parce que ce mode sera supprimé dans les prochaines versions de PlantUML et le mode par défaut sera plus restrictif.

INTERNET

Ce mode a été conçu pour les serveurs connectés à Internet

Quand PlantUML est en mode INTERNET, il est impossible d'accéder à des fichiers locaux (sauf si vous définissez des listes d'autorisation, voir plus bas). De plus, toutes les URLs standards sur les ports 80 et 443 sont accessibles. Si vous avez besoin de ports spécifiques (par exemple, 8080 pour certaines ressources disponibles sur un serveur Intranet), vous devez aussi définir une liste d'autorisation.

ALLOWLIST

Dans le mode ALLOWLIST, PlantUML n'a accès à aucun fichier local ou à aucune URL. Il faut définir des listes d'autorisation pour explicitement donner accès à ces ressources.

SANDBOX

Dans le mode SANDBOX, PlantUML n'a accès à aucun fichier local ou à aucune URL. Même les listes d'autorisation sont ignorées. Ainsi, ce mode est complètement fermé.

Le principal intérêt de ce mode est de tester: si quelqu'un réussit à avoir accès à quelque chose en utilisant ce mode, celà signifie qu'il y a un trou de sécurité quelquepart. Dans ce cas, nous corrigerons cette faille.

List of Security Profiles

There are five different profiles you can choose from :

UNSECURE

When PlantUML runs in UNSECURE mode, it means that PlantUML can access to all local files of the running instance and can access to any URL.

Despite its name, this does not mean that you should not use it. If you are running locally PlantUML from some scripts for your generated documentation, this is completely safe and ok.

It may become an issue if this is used from a Web Server which is accessible from Internet, because you cannot control what users are doing in their diagram text.

LEGACY

Right now, this mode is the default mode for PlantUML. It gives the same result as older PlantUML versions: full access to local files and full access to URL. This means that you can safely upgrade to version 1.2020.11 without breaking your scripts.

However, after upgrading, you should consider setting an appropriate Security Profile other than LEGACY because this mode will be removed in future releases and the default mode will be more restricted.

INTERNET

This mode has been designed for servers which are connected to Internet.

When running in INTERNET mode, PlantUML cannot have access to any local files (except if you are using allowlists, see below). However, all URLs on port 80 or 443 are accessible. If you need some specific ports (like 8080 for some Intranet server), you can also use allowlists.

ALLOWLIST

In ALLOWLIST mode, PlantUML cannot have any access to local files or URL. You have to use allowlists to explicitely authorize access to local or remote ressources.

SANDBOX

In SANDBOX mode, PlantUML cannot have any access to local files or URL. Even allowlists lists are ignored. So this mode is completely close.

The main interest of this one is testing: if someone succeed some access running this mode, it means we have a security hole and we will fix it.

Listes d'autorisation

Il y a trois façons de définir des listes d'autorisation:

  • plantuml.allowlist.path pour des fichiers locaux
  • plantuml.include.path encore pour des fichiers locaux
  • plantuml.allowlist.url pour des ressources distantes (URL)

Ces variables sont positionnées de la même façon que PLANTUML_SECURITY_PROFILE.

plantuml.allowlist.path

Cette variable détaille les dossiers auxquels les utilisateurs auront accès. Il faut se servir du point-virgule ; (sous Windows) ou du deux-points : (sous Linux) pour séparer les dossiers.

java -DPLANTUML_SECURITY_PROFILE=INTERNET  -Dplantuml.allowlist.path=/usr/common/:/usr/plantuml/  ...

plantuml.include.path

Cette variable est très proche de plantuml.allowlist.path. La seule différence est que les utilisateurs n'auront pas à donner de chemin complet lorsqu'ils voudront utiliser un fichier présent dans un de ces répertoires: PlantUML va chercher automatiquement les fichiers dans ces dossiers.

java -DPLANTUML_SECURITY_PROFILE=INTERNET  -Dplantuml.include.path=c:/windows/plantuml/  ...

plantuml.allowlist.url

Cette variable détaille les URLs auxquelles les utilisateurs auront accès. Il faut utiliser le point-virgule ; (que ce soit sous Windows ou sous Linux) pour donner plusieurs URLs.

java -DPLANTUML_SECURITY_PROFILE=ALLOWLIST  -Dplantuml.allowlist.url=https://plantuml.com/;http://somelocalserver:8080/commons/  ...

Allowlists

There are three different variables to define allowlists:

  • plantuml.allowlist.path for local files
  • plantuml.include.path for local files
  • plantuml.allowlist.url for remote ressources (URL)

These variables can be set using the same way as PLANTUML_SECURITY_PROFILE.

plantuml.allowlist.path

This variable lists using ; (Windows) or : (Linux) separator the folders users will be authorized to have access to.

java -DPLANTUML_SECURITY_PROFILE=INTERNET  -Dplantuml.allowlist.path=/usr/common/:/usr/plantuml/  ...

plantuml.include.path

This is very close to plantuml.allowlist.path. The only difference is that users will not have to specify full path of files for those folders: PlantUML will search files in thoses folder, even if users give only filenames without full path.

java -DPLANTUML_SECURITY_PROFILE=INTERNET  -Dplantuml.include.path=c:/windows/plantuml/  ...

plantuml.allowlist.url

This variable lists using ; (for both Windows and Linux) separator the URLs users will be authorized to have access to.

java -DPLANTUML_SECURITY_PROFILE=ALLOWLIST  -Dplantuml.allowlist.url=https://plantuml.com/;http://somelocalserver:8080/commons/  ...


Please report any bugs to plantuml@gmail.com or here.
This website is still in beta testing.