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


Deploy PlantUML safely

Sysdreamの協力を得て、PlantUMLにセキュリティプロファイルの概念を導入することになりました。

version 1.2020.11以降、 PlantUMLを実行する際にセキュリティプロファイルを選択しなければなりません。 デフォルトはLEGACYです。 このプロファイルは古いバージョンのPlantUMLの動作をエミュレートします。ですから、安全に1.2020.11にアップグレードすることができます。しかし、アップグレード後にはあなたの使用法に適したプロファイルを選択する必要があります。

これは、PlantUMLが異なるセキュリティ設定を必要とする多くの異なる構成で使用できるために必要となった機能です。

もし1.2020.11より古いバージョンを使用していて、システムがインターネットからアクセス可能であれば、古いバージョンの PlantUML は、あなたが期待するよりも少しだけ多くのことを暴露するかもしれませんので、アップグレードすべきでしょう。 デフォルトのLEGACYプロファイルでさえ、古いバージョンの PlantUML の動作よりも安全です。 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.
WARNING
 This translation need to be updated. 
WARNING

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.

Choose your Security Profile

セキュリティプロファイルは、2種類の方法で設定することができます。

  • OS環境変数PLANTUML_SECURITY_PROFILEの設定
  • Java環境変数PLANTUML_SECURITY_PROFILEの設定

OS環境変数の設定は、次のようにします。

set PLANTUML_SECURITY_PROFILE=INTERNET

または

setenv PLANTUML_SECURITY_PROFILE INTERNET

Java環境変数の設定は、コマンドラインのオプションで行います。 (-Dフラグを忘れずに)

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

JavaとPlantUMLをライブラリとして使用している場合は、次のようにします。

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");

List of Security Profiles

5つの異なるセキュリティプロファイルから選択できます。

UNSECURE

PlantUMLがUNSECUREプロファイルで動作する場合、PlantUMLは実行中のサーバのすべてのローカルファイルにアクセスでき、どのようなURLにもアクセスできることを意味します。

UNSECUREという名前は、このプロファイルを使用してはいけないという意味ではありません。ローカルのPlantUML環境で、スクリプトからドキュメントを生成する場合は、完全に安全であり問題ありません。

インターネットからアクセス可能なWebサーバで使用されている場合は、ユーザの入力したテキストで何が起きるかをコントロールできないため、問題になる可能性があります。

LEGACY

現在、このプロファイルがPlantUMLのデフォルトです。古いバージョンのPlantUMLと同じように、ローカルファイルとURLへの完全なアクセスを提供します。これは、スクリプトの動作を変えることなく、安全にバージョン1.2020.11へアップグレードできることを意味します。

しかし、アップグレード後にLEGACY以外の適切なセキュリティプロファイルを設定することを検討してください。

INTERNET

このプロファイルは、インターネットに接続されているサーバー向けの設計がされています。

INTERNETプロファイルで実行している場合、PlantUMLは(ホワイトリストを使用している場合を除き)ローカルファイルにアクセスできません。ただし、ポート80または443を使用している全てのURLにアクセス可能です。特定のポート(イントラネットサーバ用の8080のような)へのアクセスが必要な場合、ホワイトリストを使用することもできます。

ALLOWLIST

ALLOWLISTプロファイルでは、PlantUMLはローカルファイルやURLにアクセスできません。ローカルまたはリモートへのアクセスを明示的に許可するために、ホワイトリストを使用しなければいけません。

SANDBOX

SANDBOXプロファイルでは、PlantUMLはローカルファイルやURLにアクセスできません。ホワイトリストも無視されます。つまり、完全に閉じた環境です。

このプロファイルは主にテストで使用します。もし誰かがSANDBOXプロファイルを実行中に外へのアクセスに成功したならば、私たちはセキュリティホールがあると認識し、修正対応を行います。

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.

Allowlists

ホワイトリストを定義するための変数を3つ用意しています。

  • ローカルファイル向けのplantuml.allowlist.path
  • ローカルファイル向けのplantuml.include.path
  • リモートリソース(URL)向けのplantuml.allowlist.url

これらの変数はPLANTUML_SECURITY_PROFILEと同じ方法で設定できます。

plantuml.allowlist.path

; (Windows) または : (Linux)を区切りとしたフォルダのリストに対して、ユーザーがアクセスする権限を与えます。

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

plantuml.include.path

plantuml.allowlist.pathとほぼ同じように機能します。唯一の違いは、ユーザーがファイルをフルパスで記述する必要がなくなるという点です。PlantUMLはユーザーがフルパスを指定せずにファイル名だけを指定した場合にも、plantuml.include.pathで定義されたフォルダ内のファイルを検索します。

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

plantuml.allowlist.url

; (Windows、Linux共通)を区切りとしたURLのリストに対して、ユーザーがアクセスする権限を与えます。

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.