Merge branch 'tp32' Conflicts: docs/src/reference/gremlin-applications.asciidoc
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/b8d1c049 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/b8d1c049 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/b8d1c049 Branch: refs/heads/TINKERPOP-1730 Commit: b8d1c0494ca2b7a337b132f7be919dce1e0da81a Parents: 28e2328 9a69516 Author: Stephen Mallette <sp...@genoprime.com> Authored: Tue Sep 19 14:03:21 2017 -0400 Committer: Stephen Mallette <sp...@genoprime.com> Committed: Tue Sep 19 14:03:21 2017 -0400 ---------------------------------------------------------------------- docs/src/reference/gremlin-applications.asciidoc | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/b8d1c049/docs/src/reference/gremlin-applications.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/reference/gremlin-applications.asciidoc index 26b5fd7,5af699f..a783f64 --- a/docs/src/reference/gremlin-applications.asciidoc +++ b/docs/src/reference/gremlin-applications.asciidoc @@@ -400,6 -384,10 +400,11 @@@ on how to develop a driver for Gremlin By default, communication with Gremlin Server occurs over link:http://en.wikipedia.org/wiki/WebSocket[WebSocket] and exposes a custom sub-protocol for interacting with the server. + WARNING: Gremlin Server allows for the execution of remotely submitted "scripts" (i.e. arbitrary code sent by a client + to the server). Developers should consider the security implications involved in running Gremlin Server without the -appropriate precautions. Please review the <<script-execution,Script Execution Section>> for more information. ++appropriate precautions. Please review the <<security,Security Section>> and more specifically, the ++<<script-execution,Script Execution Section>> for more information. + [[starting-gremlin-server]] Starting Gremlin Server ~~~~~~~~~~~~~~~~~~~~~~~ @@@ -1245,32 -1200,14 +1250,33 @@@ The `TraversalOpProcessor` provides a w |cacheMaxSize |The maximum number of entries in the side-effect cache. |1000 |========================================================= -Security and Execution -^^^^^^^^^^^^^^^^^^^^^^ ++[[security]] +Security +^^^^^^^^ image:gremlin-server-secure.png[width=175,float=right] Gremlin Server provides for several features that aid in the -security of the graphs that it exposes. It has built in SSL support and a pluggable authentication framework using +security of the graphs that it exposes. In particular it supports SSL for transport layer security, protective measures against +malicious script execution, and authentication. SSL options are described in the configuration settings table in the +<<connecting-via-java, "Connecting via Java">> section. Script execution options are covered +<<script-execution, "at the end of this section">>. This section starts with authentication. + + +Gremlin Server supports a pluggable authentication framework using link:https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer[SASL] (Simple Authentication and -Security Layer). SSL options are described in the configuration settings table above, so this section will focus on -authentication. +Security Layer). Depending on the client used to connect to Gremlin Server, different authentication +mechanisms are accessible, see the table below. + +[width="70%",cols="3,5,3",options="header"] +|========================================================= +|Client |Authentication mechanism |Availability +|HTTP |BASIC |3.0.0-incubating +1.3+v|Gremlin-Java/ +Gremlin-Console |PLAIN SASL (username/password) |3.0.0-incubating +|Pluggable SASL |3.0.0-incubating +|GSSAPI SASL (Kerberos) |3.3.0 +|Gremlin-Python |PLAIN SASL |3.2.2 +|Gremlin-Javascript |PLAIN SASL |3.3.0 +|========================================================= By default, Gremlin Server is configured to allow all requests to be processed (i.e. no authentication). To enable authentication, Gremlin Server must be configured with an `Authenticator` implementation in its YAML file. Gremlin @@@ -1440,34 -1332,37 +1446,40 @@@ some problems would be, `while(true) {} preventing it from serving other requests. Sending enough of these kinds of scripts would eventually consume all available threads and Gremlin Server would stop responding. - Gremlin Server (more specifically the `GremlinGroovyScriptEngine`) provides methods to protect itself from these - kinds of troublesome scripts. A user can configure the script engine with a `GroovyCompilerGremlinPlugin` + Scripts have access to the full power of their language and the JVM on which they are running. This means that they + can access certain APIs that have nothing to do with Gremlin itself, such as `java.lang.System` or the `java.io` + and `java.net` packages. Scripts offer developers a lot of flexibility, but having that flexibility comes at the cost + of safety. A Gremlin Server instance that is not secured appropriately provides for a big security risk. + + The previous sections discussed methods for securing Gremlin Server through authentication and encryption, which is a + good first step in protection. Another layer of protection comes in the form of specific configurations for the -`GremlinGroovyScriptEngine`. A user can configure the script engine with different `CompilerCustomizerProvider` -implementations. Consider the basic configuration from the Gremlin Server YAML file: ++`GremlinGroovyScriptEngine`. A user can configure the script engine with a `GroovyCompilerGremlinPlugin` +implementation. Consider the basic configuration from the Gremlin Server YAML file: [source,yaml] +---- scriptEngines: { gremlin-groovy: { - imports: [java.lang.Math], - staticImports: [java.lang.Math.PI], - scripts: [scripts/empty-sample.groovy]}} + plugins: { org.apache.tinkerpop.gremlin.server.jsr223.GremlinServerGremlinPlugin: {}, + org.apache.tinkerpop.gremlin.tinkergraph.jsr223.TinkerGraphGremlinPlugin: {}, + org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin: {classImports: [java.lang.Math], methodImports: [java.lang.Math#*]}, + org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin: {files: [scripts/empty-sample.groovy]}}}} +---- -This configuration can be extended to include a `config` key as follows: +This configuration can be expaded to include a the `GroovyCompilerGremlinPlugin`: [source,yaml] +---- scriptEngines: { gremlin-groovy: { - imports: [java.lang.Math], - staticImports: [java.lang.Math.PI], - scripts: [scripts/empty-sample.groovy], - config: { - compilerCustomizerProviders: { - "org.apache.tinkerpop.gremlin.groovy.jsr223.customizer.TimedInterruptCustomizerProvider":[10000] }}} - -This configuration sets up the script engine with a `CompilerCustomizerProvider` implementation. The -`TimedInterruptCustomizerProvider` injects checks that ensure that loops (like `while`) can only execute for `10000` + plugins: { org.apache.tinkerpop.gremlin.server.jsr223.GremlinServerGremlinPlugin: {}, + org.apache.tinkerpop.gremlin.tinkergraph.jsr223.TinkerGraphGremlinPlugin: {} + org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin: {classImports: [java.lang.Math], methodImports: [java.lang.Math#*]}, + org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin: {files: [scripts/empty-sample-secure.groovy]}, + org.apache.tinkerpop.gremlin.groovy.jsr223.GroovyCompilerGremlinPlugin: {timedInterrupt: 10000}}}} +---- + +This configuration sets up the script engine with to ensure that loops (like `while`) can only execute for `10000` milliseconds. With this configuration in place, a remote execution as follows, now times out rather than consuming the thread continuously: