Generate script engine allowlist in server from config.

Author: Cole-Greer

CHANGELOG.asciidoc

@@ -34,6 +34,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 * Added `GraphManager` to `LifeCycleHook.Context` for Java-based hooks to access configured graphs.
 * Deprecated Groovy-based `LifeCycleHook` and `TraversalSource` creation via init scripts in favor of YAML configuration.
 * Updated all default Gremlin Server configs to remove Groovy dependency from initialization.
+* Added script engine allowlist to Gremlin Server - the `scriptEngines` YAML configuration now restricts which engines can serve requests; `gremlin-lang` is always available.
 
 [[release-4-0-0-beta-2]]
 === TinkerPop 4.0.0-beta.2 (April 1, 2026)

docs/src/upgrade/release-4.x.x.asciidoc

@@ -150,6 +150,31 @@ lifecycleHooks:
 
 The `g` binding is implicitly created from the `graph` entry. No `scriptEngines` section is needed.
 
+===== Script Engine Allowlist
+
+The `scriptEngines` configuration in the Gremlin Server YAML now acts as an allowlist. Only engines explicitly listed in
+the configuration will accept requests. The `gremlin-lang` engine is always available regardless of configuration.
+
+Previously, any `GremlinScriptEngineFactory` discovered via Java's `ServiceLoader` mechanism on the classpath could be
+used by clients, even if it was not listed in the server's `scriptEngines` configuration. This meant that
+`gremlin-groovy` was always available as long as its JAR was on the classpath, regardless of the server configuration.
+
+With this change, a request specifying a `language` that is not in the `scriptEngines` configuration will receive a
+`400 Bad Request` response. Providers who rely on `gremlin-groovy` or any other script engine must explicitly include it
+in their `scriptEngines` configuration:
+
+[source,yaml]
+----
+scriptEngines: {
+  gremlin-lang: {},
+  gremlin-groovy: {
+    plugins: {
+      org.apache.tinkerpop.gremlin.server.jsr223.GremlinServerGremlinPlugin: {}}}}
+----
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2720[TINKERPOP-2720],
+link:https://issues.apache.org/jira/browse/TINKERPOP-3107[TINKERPOP-3107]
+
 == TinkerPop 4.0.0-beta.2
 
 *Release Date: April 1, 2026*

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/jsr223/CachedGremlinScriptEngineManager.java

@@ -18,6 +18,7 @@
  */
 package org.apache.tinkerpop.gremlin.jsr223;
 
+import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
@@ -47,6 +48,15 @@ public CachedGremlinScriptEngineManager(final ClassLoader loader) {
         super(loader);
     }
 
+    /**
+     * Creates a cached manager with an allowlist of engine names.
+     *
+     * @see DefaultGremlinScriptEngineManager#DefaultGremlinScriptEngineManager(Set)
+     */
+    public CachedGremlinScriptEngineManager(final Set<String> allowedEngines) {
+        super(allowedEngines);
+    }
+
     /**
      * Gets a {@link GremlinScriptEngine} from cache or creates a new one from the {@link GremlinScriptEngineFactory}.
      * <p/>
@@ -55,6 +65,7 @@ public CachedGremlinScriptEngineManager(final ClassLoader loader) {
     @Override
     public GremlinScriptEngine getEngineByName(final String shortName) {
         final GremlinScriptEngine engine = cache.computeIfAbsent(shortName, super::getEngineByName);
+        if (engine == null) return null;
         registerLookUpInfo(engine, shortName);
         return engine;
     }

gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/jsr223/DefaultGremlinScriptEngineManager.java

@@ -35,6 +35,7 @@
 import java.util.Optional;
 import java.util.ServiceConfigurationError;
 import java.util.ServiceLoader;
+import java.util.Set;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -99,11 +100,19 @@ public class DefaultGremlinScriptEngineManager implements GremlinScriptEngineMan
      */
     private List<GremlinPlugin> plugins = new ArrayList<>();
 
+    /**
+     * Optional set of engine names that are allowed to be resolved by this manager. When {@code null}, all
+     * SPI-discovered engines are available (the default). When set, {@link #getEngineByName(String)} will
+     * return {@code null} for any engine name not in this set.
+     */
+    private final Set<String> allowedEngines;
+
     /**
      * The effect of calling this constructor is the same as calling
      * {@code DefaultGremlinScriptEngineManager(Thread.currentThread().getContextClassLoader())}.
      */
     public DefaultGremlinScriptEngineManager() {
+        this.allowedEngines = null;
         final ClassLoader ctxtLoader = Thread.currentThread().getContextClassLoader();
         initEngines(ctxtLoader);
     }
@@ -115,9 +124,23 @@ public DefaultGremlinScriptEngineManager() {
      * (installed extensions) are loaded.
      */
     public DefaultGremlinScriptEngineManager(final ClassLoader loader) {
+        this.allowedEngines = null;
         initEngines(loader);
     }
 
+    /**
+     * Creates a manager with an allowlist of engine names. Only engines whose names appear in
+     * {@code allowedEngines} will be returned by {@link #getEngineByName(String)}. Engines discovered
+     * via SPI but not in the allowlist will be rejected. Pass {@code null} to allow all engines.
+     *
+     * @param allowedEngines the set of permitted engine names, or {@code null} for no restriction
+     */
+    public DefaultGremlinScriptEngineManager(final Set<String> allowedEngines) {
+        this.allowedEngines = allowedEngines;
+        final ClassLoader ctxtLoader = Thread.currentThread().getContextClassLoader();
+        initEngines(ctxtLoader);
+    }
+
     @Override
     public List<Customizer> getCustomizers(final String scriptEngineName) {
         final List<Customizer> pluginCustomizers = plugins.stream().flatMap(plugin -> {
@@ -193,6 +216,11 @@ public Object get(final String key) {
     @Override
     public GremlinScriptEngine getEngineByName(final String shortName) {
         if (null == shortName) throw new NullPointerException();
+
+        if (allowedEngines != null && !allowedEngines.contains(shortName)) {
+            return null;
+        }
+
         //look for registered name first
         Object obj;
         if (null != (obj = nameAssociations.get(shortName))) {

gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/jsr223/SingleScriptEngineManagerTest.java

@@ -20,6 +20,7 @@
 
 import org.junit.Test;
 
+import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertSame;
 
 /**
@@ -37,8 +38,8 @@ public void shouldGetSameInstance() {
         assertSame(mgr, SingleGremlinScriptEngineManager.instance());
     }
 
-    @Test(expected = IllegalArgumentException.class)
+    @Test
     public void shouldNotGetGremlinScriptEngineAsItIsNotRegistered() {
-        mgr.getEngineByName("gremlin-groovy");
+        assertNull(mgr.getEngineByName("gremlin-groovy"));
     }
 }

gremlin-groovy/src/main/java/org/apache/tinkerpop/gremlin/groovy/engine/GremlinExecutor.java

@@ -44,6 +44,7 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
@@ -103,7 +104,7 @@ private GremlinExecutor(final Builder builder, final boolean suppliedExecutor,
         this.evaluationTimeout = builder.evaluationTimeout;
         this.globalBindings = builder.globalBindings;
 
-        this.gremlinScriptEngineManager = new CachedGremlinScriptEngineManager();
+        this.gremlinScriptEngineManager = new CachedGremlinScriptEngineManager(builder.allowedEngineNames);
         initializeGremlinScriptEngineManager();
 
         this.suppliedExecutor = suppliedExecutor;
@@ -502,6 +503,7 @@ public final static class Builder {
         private BiConsumer<Bindings, Throwable> afterFailure = (b, e) -> {
         };
         private Bindings globalBindings = new ConcurrentBindings();
+        private Set<String> allowedEngineNames = null;
 
         private Builder() {
         }
@@ -517,6 +519,16 @@ public Builder addPlugins(final String engineName, final Map<String, Map<String,
             return this;
         }
 
+        /**
+         * Set the allowed engine names for the {@link GremlinScriptEngineManager}. Only engines whose names
+         * appear in this set will be returned by {@link GremlinScriptEngineManager#getEngineByName(String)}.
+         * Pass {@code null} to allow all SPI-discovered engines (the default).
+         */
+        public Builder allowedEngineNames(final Set<String> allowedEngineNames) {
+            this.allowedEngineNames = allowedEngineNames;
+            return this;
+        }
+
         /**
          * Bindings to apply to every script evaluated. Note that the entries of the supplied {@code Bindings} object
          * will be copied into a newly created {@link ConcurrentBindings} object

gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/handler/HttpGremlinEndpointHandler.java

@@ -392,6 +392,15 @@ private void iterateScriptEvalResult(final Context context, MessageSerializer<?>
         final String language = args.containsKey(Tokens.ARGS_LANGUAGE) ? (String) args.get(Tokens.ARGS_LANGUAGE) : "gremlin-lang";
         final GremlinScriptEngine scriptEngine = gremlinExecutor.getScriptEngineManager().getEngineByName(language);
 
+        if (scriptEngine == null) {
+            if (!settings.scriptEngines.containsKey(language) && !language.equals("gremlin-lang")) {
+                logger.warn("Request for script engine [{}] could not be fulfilled - not configured in the server's scriptEngines setting", language);
+            } else {
+                logger.warn("Request for script engine [{}] could not be fulfilled - configured but failed to load (check classpath for the engine's implementation)", language);
+            }
+            throw new ProcessingException(GremlinError.scriptEngineNotAvailable(language));
+        }
+
         final Bindings mergedBindings = mergeBindingsFromRequest(context, new SimpleBindings(graphManager.getAsBindings()));
         final Object result = scriptEngine.eval(message.getGremlin(), mergedBindings);
 

gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/util/GremlinError.java

@@ -232,4 +232,15 @@ public static GremlinError transactionNotSupported(final UnsupportedOperationExc
     public static GremlinError transactionUnableToStart(final String message) {
         return new GremlinError(HttpResponseStatus.INTERNAL_SERVER_ERROR, message, "TransactionException");
     }
+
+    /**
+     * Creates an error for when a requested script engine is not available on the server.
+     *
+     * @param language the requested script engine name
+     * @return A GremlinError with appropriate message and status code
+     */
+    public static GremlinError scriptEngineNotAvailable(final String language) {
+        final String message = String.format("Script engine [%s] is not available.", language);
+        return new GremlinError(HttpResponseStatus.BAD_REQUEST, message, "InvalidRequestException");
+    }
 }

gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/util/ServerGremlinExecutor.java

@@ -138,14 +138,19 @@ public ServerGremlinExecutor(final Settings settings, final ExecutorService grem
 
         logger.info("Initialized Gremlin thread pool.  Threads in pool named with pattern gremlin-*");
 
+        // build the allowlist of script engines from the server config - gremlin-lang is always available
+        final Set<String> allowedEngines = new HashSet<>(settings.scriptEngines.keySet());
+        allowedEngines.add("gremlin-lang");
+
         final GremlinExecutor.Builder gremlinExecutorBuilder = GremlinExecutor.build()
                 .evaluationTimeout(settings.getEvaluationTimeout())
                 .afterFailure((b, e) -> this.graphManager.rollbackAll())
                 .beforeEval(b -> this.graphManager.rollbackAll())
                 .afterTimeout((b, e) -> this.graphManager.rollbackAll())
                 .globalBindings(this.graphManager.getAsBindings())
                 .executorService(this.gremlinExecutorService)
-                .scheduledExecutorService(this.scheduledExecutorService);
+                .scheduledExecutorService(this.scheduledExecutorService)
+                .allowedEngineNames(allowedEngines);
 
         settings.scriptEngines.forEach((k, v) -> {
             // use plugins if they are present

gremlin-server/src/test/java/org/apache/tinkerpop/gremlin/server/GremlinServerIntegrateTest.java

@@ -1136,6 +1136,20 @@ public void ensureScriptEngineDefaultsToGremlinLang() {
             } catch (Exception ex) {
                 final ResponseException re = (ResponseException) ex.getCause();
                 assertEquals(HttpResponseStatus.BAD_REQUEST, re.getResponseStatusCode());
+                assertEquals("InvalidRequestException", re.getRemoteException());
+                assertEquals("Script engine [gremlin-groovy] is not available.", re.getMessage());
+            }
+
+            // completely unknown engine should also fail
+            try {
+                final RequestOptions unknownEngine = RequestOptions.build().language("gremlin-foo").create();
+                client.submit("g.V()", unknownEngine).all().get();
+                fail("Should have failed for unknown script engine");
+            } catch (Exception ex) {
+                final ResponseException re = (ResponseException) ex.getCause();
+                assertEquals(HttpResponseStatus.BAD_REQUEST, re.getResponseStatusCode());
+                assertEquals("InvalidRequestException", re.getRemoteException());
+                assertEquals("Script engine [gremlin-foo] is not available.", re.getMessage());
             }
         } finally {
             cluster.close();