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/master
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:
