Plainer plugin security discussion.

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
 

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.