Privacy by default

[DaLynxx]

This is a post both asking to validate my understanding, and if correct a request of a change.

First I want to say that I really enjoy the asciidoc language and asciidoctor tool set and that I am currently evaluating if asciidoctor can be used for some of our company's documentation. As part of the tool chain I investigated the use of the vscode asciidoctor extension as a supporting tool which is the reason that I ended here at the asciidoctorjs and asciidoctor-kroki projects.

My understanding of the current setup:

Assume that I have a previously created .adoc document that contains some plantuml graphics that i have rendered locally using asciidoctor (ruby) and asciidoctor-diagram + a local installation of plantuml.

If I then install asciidoctorjs and asciidoctor-kroki and use asciidoctorjs to render my .adoc document it will, without any other changes, try and send my diagram content out to https://kroki.io.

The above is what I read from the documentation chapter "Using your own Kroki". It states that "By default, this extension sends information and receives diagrams back from https://kroki.io."

The documentation chapter continues: "You may choose to use your own server due to: ...

• Privacy" ...and that you then can define an attribute to.

If my understanding above is correct, my proposal is to turn this around and require some extra step in the setup to get more of "Privacy by design".

I understand that from a simplicity point of view, having the default settings work out of the box is nice.

From a privacy point of view it feels as if I can easily end up with routing my data somewhere that I did not intend.

If I set up my own kroki server locally, missing to add the attribute in all documents or even a spelling error in the attribute name of the document such as "kroki-srver-url" would have the diagram data go out to the internet. (assuming that the computer that I use have internet connectivity).

Of course there are things I can do in my network setup to avoid having data sent to Kroki.io but that would leave the privacy highly dependent of settings outside of the tool at hand.

Perhaps asciidoctor-kroki could be changed to always require the attribute "kroki-server-url" to be defined i.e. even for kroki.io, or that or that some local config file need to have the https://kroki.io added by hand to set the default.

[ggrossetie]

Hey @DaLynxx

If I then install asciidoctorjs and asciidoctor-kroki and use asciidoctorjs to render my .adoc document it will, without any other changes, try and send my diagram content out to kroki.io.

If you explicitly enable/require the extension, then yes.

If I set up my own kroki server locally, missing to add the attribute in all documents or even a spelling error in the attribute name of the document such as "kroki-srver-url" would have the diagram data go out to the internet. (assuming that the computer that I use have internet connectivity).

You shouldn't add the attribute kroki-server-url in all your documents but rather configure it from the API using the attributes option or from the CLI using the -a option. https://kroki.io is the default value but you can override it from the API or the CLI (or in the document header using an attribute entry).

Of course there are things I can do in my network setup to avoid having data sent to Kroki.io but that would leave the privacy highly dependent of settings outside of the tool at hand.

In my opinion, this is the only way to effectively prevent sending data to https://kroki.io.

Perhaps asciidoctor-kroki could be changed to always require the attribute "kroki-server-url" to be defined i.e. even for kroki.io, or that or that some local config file need to have the kroki.io added by hand to set the default.

It would not prevent mistakes or misconfigurations but it would deteriorate user experience so I'm unwilling to do that. As mentioned above, if you are working on highly confidential diagrams, you should configure your network accordingly and do not trust user-settings.

Please note that, even if kroki-server-url was undefined, other tools (for instance the VSCode extension) could decide to set it by default to https://kroki.io... In other words, since the attribute can be set to any value using an undefined value (by default) provides little to no guarantee.

I would recommend to setup your own Kroki server locally and redirect any HTTP requests to kroki.io to your local instance. And if you are working on really confidential materials then your computer should not have access to Internet at all.

For reference, here's how the kroki-server-url is configured on GitLab: https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/asciidoc.rb#L65-74 It will prevent the attribute from being overridden on a document-level.

I hope this answers your question.

It's also important to note that kroki.io does not share data with any third-party but keeps HTTP requests for a short period of time (~30 days) for debugging/monitoring purpose. I created https://github.com/yuzutech/kroki.io/issues/41 to track progress.

[DaLynxx]

Thank you for the confirmation and your answers.

Agree that the choice of other toolmakers are theirs to make and is not under your control.

If I go back to kroki's own home page, you (if I understand it correctly that you are the developer of kroki as well) have under the install chapter presented the Self-managed solution along-side the "free service" alternative. For the self-managed part there are both the very-much-on-your-own .jar based way and also a nice docker provided.

This makes me feel that you have made a lot of work to support the self-hosted alternative and that Kroki "itself" does not have a default preference for using just kroki.io. since I always must direct my GET's and POSTs somewhere.

It is therefore somewhat surprising that asciidoctor-kroki got a "hard-coded" default.

I have not studied your code to any extent I just made a quick search for "kroki.io" and found the following in the client part.

  getServerUrl () {
    return this.doc.getAttribute('kroki-server-url') || 'https://kroki.io'
  }

Anyway, one thought/suggestion.

Having the last part of the return row (URL) in the code above to rather be fetched from a config file would provide admin/users with extended "configurability" and perhaps even make it easier for other toolmakers.

If you in then the asciidoctor-kroki release had that config to be "https://korki.io" by default the user experience could still be intact. Sure, I would still have the same concern but would provide a natural place to configure a local default in the tool itself.

Regardless, I thank your once again. I'm impressed with what you have have built with Kroki and the asciidoctor extensions.

[ggrossetie]

This makes me feel that you have made a lot of work to support the self-hosted alternative and that Kroki "itself" does not have a default preference for using just kroki.io. since I always must direct my GET's and POSTs somewhere.

Indeed, the extension will work with any URL as long as the API is compatible.

It is therefore somewhat surprising that asciidoctor-kroki got a "hard-coded" default. Having the last part of the return row (URL) in the code above to rather be fetched from a config file would provide admin/users with extended "configurability" and perhaps even make it easier for other toolmakers.

I'm not sure... Reading an external configuration file won't work great in a browser environment. Furthermore, it's uncommon for an Asciidoctor extension to use an external configuration file. Most of the time, attributes are used to configure extensions/converters.

The value https://kroki.io is really just a "convenient" default value. Asciidoctor provides a built-in mechanism to override/set the value:

asciidoctor.convertFile('doc.adoc', { attributes: { 'kroki-server-url': 'http://localhost:8000' } })

$ asciidoctor -r asciidoctor-kroki -a kroki-server-url=http://localhost:8000 doc.adoc

To prevent errors, you could even provide a script around the asciidoctor CLI to explicitly define the kroki-server-url attribute. The value could be read from a file or from an environment variable... depending on your preference.

I think the question is really should we provide a default value or not. As mentioned above, I think we should to avoid an extra step when getting started but I understand your point (everything has its own advantages and disadvantages).

[ggrossetie]

Regardless, I thank your once again. I'm impressed with what you have have built with Kroki and the asciidoctor extensions.

Thanks :flushed:

[mino-txa]

Before using your service, please confirm the security policy. I have confirmed that HTTP requests are retained for 30 days in the following issue: 　https://github.com/asciidoctor/asciidoctor-kroki/issues/192 Please confirm how diagrams and HTML files are handled: 　・Is there a possibility that they will be viewed by third parties? 　・Please provide the management policy for generated diagrams and HTML files. 　　For example, will they be deleted after 30 days like HTTP requests? 　・If sensitive information that should not be disclosed externally is mistakenly sent, would it be possible to have it deleted if we contact you and provide the URL?