CASSANDRA-21146 Guardrail for client driver versions

conf/cassandra.yaml

@@ -2682,6 +2682,20 @@ max_security_label_length: 48
 # compressed by dictionary compressor and training_min_frequency is set to 0m (the default when unset).
 #unset_training_min_frequency_enabled: true
 
+# Minimum client driver versions. Connections from drivers whose version is below
+# the configured minimum will be warned or rejected. Connections that do not report
+# a driver name or version are considered valid. The map key is the driver name
+# as reported in the native protocol STARTUP message. The value is the minimum
+# version string.
+#minimum_client_driver_versions_warned:
+#  DataStax Java Driver: "4.0.0"
+#  DataStax Python Driver: "3.0.0"
+#  github.com/apache/cassandra-gocql-driver: "2.0.0"
+#minimum_client_driver_versions_disallowed:
+#  DataStax Java Driver: "4.0.0"
+#  DataStax Python Driver: "3.0.0"
+#  github.com/apache/cassandra-gocql-driver: "2.0.0"
+
 # Startup Checks are executed as part of Cassandra startup process, not all of them
 # are configurable (so you can disable them) but these which are enumerated bellow.
 # Uncomment the startup checks and configure them appropriately to cover your needs.

conf/cassandra_latest.yaml

@@ -2446,6 +2446,20 @@ default_secondary_index_enabled: true
 # compressed by dictionary compressor and training_min_frequency is set to 0m (the default when unset).
 #unset_training_min_frequency_enabled: true
 
+# Minimum client driver versions. Connections from drivers whose version is below
+# the configured minimum will be warned or rejected. Connections that do not report
+# a driver name or version are considered valid. The map key is the driver name
+# as reported in the native protocol STARTUP message. The value is the minimum
+# version string.
+#minimum_client_driver_versions_warned:
+#  DataStax Java Driver: "4.0.0"
+#  DataStax Python Driver: "3.0.0"
+#  github.com/apache/cassandra-gocql-driver: "2.0.0"
+#minimum_client_driver_versions_disallowed:
+#  DataStax Java Driver: "4.0.0"
+#  DataStax Python Driver: "3.0.0"
+#  github.com/apache/cassandra-gocql-driver: "2.0.0"
+
 # Startup Checks are executed as part of Cassandra startup process, not all of them
 # are configurable (so you can disable them) but these which are enumerated bellow.
 # Uncomment the startup checks and configure them appropriately to cover your needs.

src/java/org/apache/cassandra/config/Config.java

@@ -1006,6 +1006,9 @@ public static void setClientMode(boolean clientMode)
     public volatile boolean unset_training_min_frequency_warned = true;
     public volatile boolean unset_training_min_frequency_enabled = true;
 
+    public volatile Map<String, String> minimum_client_driver_versions_warned = Collections.emptyMap();
+    public volatile Map<String, String> minimum_client_driver_versions_disallowed = Collections.emptyMap();
+
     public volatile int sai_sstable_indexes_per_query_warn_threshold = 32;
     public volatile int sai_sstable_indexes_per_query_fail_threshold = -1;
     public volatile DataStorageSpec.LongBytesBound sai_string_term_size_warn_threshold = new DataStorageSpec.LongBytesBound("1KiB");

src/java/org/apache/cassandra/config/GuardrailsOptions.java

@@ -18,15 +18,20 @@
 
 package org.apache.cassandra.config;
 
+import java.util.ArrayList;
 import java.util.Collections;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.function.Consumer;
 import java.util.function.Supplier;
+import java.util.regex.Pattern;
 
 import javax.annotation.Nullable;
 
+import com.google.common.annotations.VisibleForTesting;
 import com.google.common.collect.Sets;
+import com.vdurmont.semver4j.Semver;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -113,6 +118,8 @@ public GuardrailsOptions(Config config)
                                  false);
         validatePasswordPolicy(config.password_policy);
         validateRoleNamePolicy(config.role_name_policy);
+        validateAndSanitizeClientDriverVersions(config.minimum_client_driver_versions_warned, "minimum_client_driver_versions_warned");
+        validateAndSanitizeClientDriverVersions(config.minimum_client_driver_versions_disallowed, "minimum_client_driver_versions_disallowed");
     }
 
     @Override
@@ -195,7 +202,7 @@ public Set<String> getKeyspacePropertiesWarned()
     {
         return config.keyspace_properties_warned;
     }
-    
+
     public void setKeyspacePropertiesWarned(Set<String> properties)
     {
         updatePropertyWithLogging("keyspace_properties_warned",
@@ -209,7 +216,7 @@ public Set<String> getKeyspacePropertiesIgnored()
     {
         return config.keyspace_properties_ignored;
     }
-    
+
     public void setKeyspacePropertiesIgnored(Set<String> properties)
     {
         updatePropertyWithLogging("keyspace_properties_ignored",
@@ -223,7 +230,7 @@ public Set<String> getKeyspacePropertiesDisallowed()
     {
         return config.keyspace_properties_disallowed;
     }
-    
+
     public void setKeyspacePropertiesDisallowed(Set<String> properties)
     {
         updatePropertyWithLogging("keyspace_properties_disallowed",
@@ -1368,6 +1375,34 @@ public boolean getUnsetTrainingMinFrequencyEnabled()
         return config.unset_training_min_frequency_enabled;
     }
 
+    @Override
+    public Map<String, String> getMinimumClientDriverVersionsWarned()
+    {
+        return config.minimum_client_driver_versions_warned;
+    }
+
+    @Override
+    public Map<String, String> getMinimumClientDriverVersionsDisallowed()
+    {
+        return config.minimum_client_driver_versions_disallowed;
+    }
+
+    public void setMinimumClientDriverVersionsWarned(Map<String, String> versions)
+    {
+        updatePropertyWithLogging("minimum_client_driver_versions_warned",
+                                  versions,
+                                  () -> config.minimum_client_driver_versions_warned,
+                                  x -> config.minimum_client_driver_versions_warned = x);
+    }
+
+    public void setMinimumClientDriverVersionsDisallowed(Map<String, String> versions)
+    {
+        updatePropertyWithLogging("minimum_client_driver_versions_disallowed",
+                                  versions,
+                                  () -> config.minimum_client_driver_versions_disallowed,
+                                  x -> config.minimum_client_driver_versions_disallowed = x);
+    }
+
     private static <T> void updatePropertyWithLogging(String propertyName, T newValue, Supplier<T> getter, Consumer<T> setter)
     {
         T oldValue = getter.get();
@@ -1601,4 +1636,57 @@ private static void validateRoleNamePolicy(CustomGuardrailConfig config)
     {
         ValueGenerator.getGenerator("role_name_policy", config).generate(ValueValidator.getValidator("role_name_policy", config), Map.of());
     }
+
+    @VisibleForTesting
+    public static void validateAndSanitizeClientDriverVersions(Map<String, String> map, String guardrailName)
+    {
+        if (map == null || map.isEmpty())
+            return;
+
+        List<String> invalidEntries = new ArrayList<>();
+
+        for (Map.Entry<String, String> entry : map.entrySet())
+        {
+            String sanitized = sanitizeVersion(entry.getValue());
+            if (!isValidVersion(sanitized))
+                invalidEntries.add(entry.getKey());
+        }
+
+        if (!invalidEntries.isEmpty())
+            throw new IllegalArgumentException("Invalid version entries for " + guardrailName + " guardrail, they do not follow semver: " + invalidEntries);
+
+        map.replaceAll((driver, version) -> sanitizeVersion(version));
+    }
+
+    public static boolean isValidVersion(String version)
+    {
+        if (version == null)
+            return false;
+
+        // try to construct it
+        try
+        {
+            new Semver(version);
+        }
+        catch (Throwable t)
+        {
+            return false;
+        }
+
+        return true;
+    }
+
+    private static final Pattern VERSION_SANITATION_PATTERN = Pattern.compile("^[vV]");
+
+    public static String sanitizeVersion(String driverVersion)
+    {
+        String sanitizedVersionId = driverVersion == null ? null : driverVersion.trim();
+        if (sanitizedVersionId != null)
+            sanitizedVersionId = VERSION_SANITATION_PATTERN.matcher(sanitizedVersionId).replaceFirst("");
+
+        if (sanitizedVersionId == null || sanitizedVersionId.isBlank())
+            return null;
+
+        return sanitizedVersionId;
+    }
 }

src/java/org/apache/cassandra/db/guardrails/ClientDriverVersionGuardrail.java

@@ -0,0 +1,160 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.cassandra.db.guardrails;
+
+import java.util.Map;
+import java.util.function.Function;
+
+import javax.annotation.Nullable;
+
+import com.vdurmont.semver4j.Semver;
+import com.vdurmont.semver4j.Semver.SemverType;
+
+import org.apache.cassandra.config.GuardrailsOptions;
+import org.apache.cassandra.service.ClientState;
+
+/**
+ * A guardrail that warns or rejects client connections whose driver version
+ * is below a configured minimum per driver name.
+ * <p>
+ * The guardrail is configured with maps of driver name to minimum version string.
+ * Connections that do not report a driver name or version are considered valid
+ * and are not subject to this guardrail.
+ * <p>
+ * Version comparison uses semantic versioning via {@link Semver} with loose parsing
+ * to handle non-standard version strings reported by drivers.
+ */
+public class ClientDriverVersionGuardrail extends Predicates<String>
+{
+    private final Function<ClientState, Map<String, String>> warnVersions;
+    private final Function<ClientState, Map<String, String>> disallowVersions;
+
+    public ClientDriverVersionGuardrail(Function<ClientState, Map<String, String>> warnVersions,
+                                        Function<ClientState, Map<String, String>> disallowVersions)
+    {
+        super("minimum_client_driver_versions", null, null, null, null);
+        this.warnVersions = warnVersions;
+        this.disallowVersions = disallowVersions;
+    }
+
+    public void guard(@Nullable String driverName, @Nullable String driverVersion, @Nullable ClientState state)
+    {
+        if (!enabled(state))
+            return;
+
+        String sanitizedDriverId = driverName == null ? null : driverName.trim();
+        if (sanitizedDriverId == null || sanitizedDriverId.isBlank())
+        {
+            logger.debug("minimum_client_driver_versions guardrail identified empty driver " +
+                         "id to check the minimum version of, such connections will be allowed but " +
+                         "an operator should check what kind of clients are connecting to the cluster.");
+            return;
+        }
+
+        String sanitizedDriverVersion = GuardrailsOptions.sanitizeVersion(driverVersion);
+        if (sanitizedDriverVersion == null)
+        {
+            logger.debug("minimum_client_driver_versions guardrail identified empty driver " +
+                         "version to check the minimum version of, such connections will be allowed but " +
+                         "an operator should check what kind of clients are connecting to the cluster.");
+            return;
+        }
+
+        if (!GuardrailsOptions.isValidVersion(sanitizedDriverVersion))
+        {
+            logger.debug("minimum_client_driver_versions guardrail identified driver " +
+                         "version which is not compliant semver version, such connections will be allowed but " +
+                         "an operator should check what kind of clients are connecting to the cluster.");
+            return;
+        }
+
+        Map<String, String> disallowed = disallowVersions.apply(state);
+        if (disallowed != null && !disallowed.isEmpty())
+        {
+            String minimumVersionFail = disallowed.get(sanitizedDriverId);
+            if (minimumVersionFail != null && isBelowMinimum(sanitizedDriverVersion, minimumVersionFail))
+            {
+                fail(String.format("Client driver %s is below required minimum version %s, connection rejected",
+                                   sanitizedDriverId, minimumVersionFail), state);
+                return;
+            }
+        }
+
+        Map<String, String> warned = warnVersions.apply(state);
+        if (warned != null && !warned.isEmpty())
+        {
+            String minimumVersionWarn = warned.get(sanitizedDriverId);
+            if (minimumVersionWarn != null && isBelowMinimum(sanitizedDriverVersion, minimumVersionWarn))
+            {
+                warn(String.format("Client driver %s is below recommended minimum version %s",
+                                   sanitizedDriverId, minimumVersionWarn));
+            }
+        }
+    }
+
+    /**
+     * Driver id should be in the format "driver:version". It will be parsed and
+     * {@link #guard(String, String, ClientState)} called.
+     * <p>
+     * This method is not expected to be called in normal circumstances, it is just that we
+     * would need to pass it with colon separator from StartupMessage as guard method
+     * expects one string as a value to check, just so that we would break it apart in turn to get
+     * driver id and version again.
+     *
+     * @param rawDriverId the value to check, driver name and version delimited by a colon.
+     * @param state       client state
+     */
+    @Override
+    public void guard(String rawDriverId, @Nullable ClientState state)
+    {
+        if (rawDriverId == null)
+            return;
+
+        String[] pair = rawDriverId.trim().split(":");
+        if (pair.length != 2)
+            return;
+
+        String sanitizedDriverName = pair[0].trim();
+        if (sanitizedDriverName.isBlank())
+            return;
+
+        String sanitizedDriverVersion = pair[1].trim();
+        if (sanitizedDriverVersion.isBlank())
+            return;
+
+        guard(sanitizedDriverName, sanitizedDriverVersion, state);
+    }
+
+    /**
+     * Checks if the driver version is below the minimum version
+     * specified in the config map. If driver name is not in minimum versions,
+     * such connection is considered to be allowed.
+     * <p>
+     *
+     * @param driverVersion  version of a driver
+     * @param minimumVersion minimum allowed version
+     * @return true if the driver version is lower than the configured minimum
+     */
+    static boolean isBelowMinimum(String driverVersion, String minimumVersion)
+    {
+        Semver versionToCheck = new Semver(driverVersion, SemverType.LOOSE);
+        Semver minimumVersionAllowed = new Semver(minimumVersion, SemverType.LOOSE);
+        return versionToCheck.isLowerThan(minimumVersionAllowed);
+    }
+}