From e1233a0fbc6299d9fa54ff545e8cf3c53e131b5c Mon Sep 17 00:00:00 2001 From: Jeffrey Regan Date: Thu, 27 Jun 2019 10:19:19 -0700 Subject: [PATCH] Plainer plugin security discussion. --- docs/plugins/README.md | 42 ++++++++++++++++++++------------- docs/plugins/goPluginCaveats.md | 30 +++++++++++++---------- 2 files changed, 44 insertions(+), 28 deletions(-) diff --git a/docs/plugins/README.md b/docs/plugins/README.md index 36fa977c9..730897a0e 100644 --- a/docs/plugins/README.md +++ b/docs/plugins/README.md @@ -26,9 +26,9 @@ or [transformer configs] doesn't meet your needs. * A _transformer_ plugin might perform special container command line edits, or any other - transformation that exceeds the power of the - builtin transformations (`namePrefix`, - `commonLabels`, etc.). + transformation beyond those provided by the + builtin (`namePrefix`, `commonLabels`, etc.) + transformers. ## Specification in `kustomization.yaml` @@ -76,7 +76,8 @@ Given this, the kustomization process would expect to find a file called `chartInflator.yaml` in the kustomization [root](../glossary.md#kustomization-root). -This is the _plugin's configuration file_. +This is the plugin's configuration file; +it contains a YAML configuration object. The file `chartInflator.yaml` could contain: @@ -115,16 +116,18 @@ e.g. the tests for [ChartInflator] or Each plugin gets its own dedicated directory named +[`XDG_CONFIG_HOME`]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html + ``` $XDG_CONFIG_HOME/kustomize/plugin /${apiVersion}/LOWERCASE(${kind}) ``` -The default value of `XDG_CONFIG_HOME` is +The default value of [`XDG_CONFIG_HOME`] is `$HOME/.config`. The one-plugin-per-directory requirement eases -creation of a plugin bundle (source, test, plugin +creation of a plugin bundle (source, tests, plugin data files, etc.) for sharing. In the case of a [Go plugin](#go-plugins), it also @@ -169,23 +172,30 @@ The order specified in the `transformers` field is respected, as transformers cannot be expected to be commutative. +#### No Security + +Kustomize plugins do not run in any kind of +kustomize-provided sandbox. There's no notion +of _"plugin security"_. + A `kustomize build` that tries to use plugins but omits the flag > `--enable_alpha_plugins` -will fail with a warning about plugin use. +will not load plugins and will fail with a +warning about plugin use. -Flag use is an opt-in acknowledging both tthe -unstable (alpha) plugin API, and the absence of -plugin provenance. It's meant to give pause to -someone who blindly downloads a kustomization from -the internet and attempts to run it, without -realizing that it might attempt to run 3rd party -code in plugin form. The plugin would have to be -installed already, but nevertheless the flag is a -reminder. +The use of this flag is an opt-in acknowledging +the unstable (alpha) plugin API, the absence of +plugin provenance, and the fact that a plugin +is not part of kustomize. +To be clear, some kustomize plugin downloaded +from the internet might wonderfully transform +k8s config in a desired manner, while also +quietly doing anything the user could do to the +system running `kustomize build`. ## Authoring diff --git a/docs/plugins/goPluginCaveats.md b/docs/plugins/goPluginCaveats.md index 06d9588ca..e9d2e4bd5 100644 --- a/docs/plugins/goPluginCaveats.md +++ b/docs/plugins/goPluginCaveats.md @@ -54,7 +54,6 @@ This means a one-time run of ``` GOPATH=${whatever} go get \ sigs.k8s.io/kustomize/cmd/kustomize@${releaseVersion} - ``` and then a normal development cycle using @@ -75,37 +74,44 @@ must do to write a [tensorflow plugin]. The Go plugin developer sees the same API offered to native kustomize operations, assuring certain -semantics, invariants, checks, etc. An exec +semantics, invariants, checks, etc. An exec plugin sub-process dealing with this via stdin/stdout will have an easier time screwing things up for downstream transformers and consumers. +Minor point: if the plugin reads files via +the kustomize-provided file `Loader` interface, it +will be constrained by kustomize file loading +restrictions. Of course, nothing but a code audit +prevents a Go plugin from importing the `io` package +and doing whatever it wants. + ### Debugging A Go plugin developer can debug the plugin _in situ_, setting breakpoints inside the plugin and elsewhere while running a plugin in feature tests. -### Unit of contribution - -All the builtin generators and transformers -are themselves Go plugins. This means it's -trivial for the kustomize maintainers to -promote a contributed Go plugin to -_builtin_ status. - To get the best of both worlds (shareability and safety), a developer can write an `.go` program that functions as an _exec plugin_, but can be processed by `go generate` to emit a _Go plugin_ (or vice versa). +### Unit of contribution + +All the builtin generators and transformers +are themselves Go plugins. This means that +the kustomize maintainers can promote a contributed +plugin to a builtin without needing code changes +(beyond those mandated by normal code review). + ### Ecosystems grow through use Tooling could ease Go plugin _sharing_, but this requires some critical mass of Go plugin _authoring_, which in turn is hampered by confusion around sharing. [Go modules], once they -are more widely adopted, will solve one of the -biggest plugin sharing difficulties - ambiguous +are more widely adopted, will solve the +biggest plugin sharing difficulty: ambiguous plugin vs host dependencies.