Sql reflection config (#955)

* sql reflection config * Update docs/modules/sql/pages/sql-reflection-configuration.adoc Co-authored-by: Krzysztof Jamróz <[email protected]> * Update docs/modules/sql/pages/sql-reflection-configuration.adoc Co-authored-by: rebekah-lawrence <[email protected]> * review fixes * review fixes * Update docs/modules/secure-cluster/pages/hardening-recommendations.adoc Co-authored-by: rebekah-lawrence <[email protected]> * Update docs/modules/sql/pages/sql-reflection-configuration.adoc Co-authored-by: rebekah-lawrence <[email protected]> * Update docs/modules/sql/pages/sql-reflection-configuration.adoc Co-authored-by: rebekah-lawrence <[email protected]> * Update docs/modules/sql/pages/sql-reflection-configuration.adoc Co-authored-by: rebekah-lawrence <[email protected]> * review fixes --------- Co-authored-by: Krzysztof Jamróz <[email protected]> Co-authored-by: rebekah-lawrence <[email protected]>
hazelcast · Jan 18, 2024 · a303e0c · a303e0c
1 parent 1b22369
commit a303e0c
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 0 deletions.
diff --git a/docs/modules/secure-cluster/pages/hardening-recommendations.adoc b/docs/modules/secure-cluster/pages/hardening-recommendations.adoc
@@ -57,6 +57,7 @@ To avoid deserialization of objects from untrusted sources, Hazelcast offers som
 xref:security:tls-ssl.adoc#mutual-authentication[mutual TLS authentication] and disabling xref:clusters:network-configuration.adoc#multicast-element[multicast join] configuration.
 We recommend using Java serialization filter configuration for whitelisting the set of trusted classes or
 packages which are allowed for deserialization.
+* Hazelcast uses Java reflection during SQL execution when the object format is set to `java`. We recommend using xref:sql:sql-reflection-configuration.adoc#configuring-reflection[Java reflection filter configuration] to whitelist the set of trusted classes or packages that are allowed to create through reflection.
 * You can disable script executions on the Hazelcast members. Scripts executed from Management center have access
 to system resources (files, etc.) with privileges of user running Hazelcast.
 We recommend that scripting be xref:maintain-cluster:monitoring.adoc#toggle-scripting-support[disabled] on members.
diff --git a/docs/modules/sql/pages/sql-reflection-configuration.adoc b/docs/modules/sql/pages/sql-reflection-configuration.adoc
@@ -0,0 +1,98 @@
+= Configuring Reflection
+:description: Clusters can be configured to restrict the capability of creating objects through reflection during SQL execution.
+
+When you have set the object format to `java`, you can configure clusters to restrict object creation using reflection during SQL execution.
+
+== Disallowing Reflection of Untrusted Java Classes
+
+To prevent Hazelcast from constructing objects of arbitrary classes through reflection, you can allow or deny reflection for Java classes based on class name, package name, or prefix using the `java-reflection-filter` parameter.
+
+When objects are constructed through reflection, the following filtering rules apply:
+
+* When the `whitelist` option is empty:
+** If the object's class name or package name is blacklisted, reflection fails.
+** Otherwise, reflection is allowed.
+* When the `whitelist` option is populated:
+** If the object's class name or package name is blacklisted, reflection fails.
+** If the object's class name or package name is whitelisted, reflection is allowed
+** Otherwise, reflection fails.
+
+When reflection fails, a `SecurityException` is thrown.
+
+By default, reflection restriction filter is empty and all class names or package names are allowed.
+
+If the reflection restriction filter is not empty, class names or package names with the specified prefixes are automatically added to the whitelist by default:
+
+* `java`
+* `com.hazelcast.`
+* `[` (for primitives and arrays)
+
+If you do not want to allow these default prefixes, set the `defaults-disabled` attribute to `true`.
+
+[tabs]
+====
+XML::
++
+--
+[source,xml]
+----
+<hazelcast>
+  ...
+  <sql>
+    <java-reflection-filter defaults-disabled="true">
+      <whitelist>
+        <class>example.Foo</class>
+        <package>com.acme.app</package>
+        <prefix>com.hazelcast.</prefix>
+        <prefix>java.</prefix>
+        <prefix>javax.</prefix>
+        <prefix>[</prefix>
+      </whitelist>
+      <blacklist>
+        <class>com.acme.app.BeanComparator</class>
+      </blacklist>
+    </java-reflection-filter>
+  </sql>
+  ...
+</hazelcast>
+----
+--
+
+YAML::
++
+--
+[source,yaml]
+----
+hazelcast:
+  sql:
+    java-reflection-filter:
+      defaults-disabled: true
+      whitelist:
+        class:
+          - example.Foo
+        package:
+          - com.acme.app
+        prefix:
+          - com.hazelcast.
+          - java.
+          - javax.
+          - \[
+      blacklist:
+        class:
+          - com.acme.app.BeanComparator
+----
+--
+Java::
++
+--
+[source,java]
+----
+Config config = new Config();
+JavaSerializationFilterConfig reflectionConfig = new JavaSerializationFilterConfig();
+reflectionConfig.setDefaultsDisabled(true);
+reflectionConfig.getBlacklist().addClasses(SomeDeniedClass.class.getName());
+reflectionConfig.getWhitelist().addClasses(SomeAllowedClass.class.getName());
+config.getSqlConfig().setJavaReflectionFilterConfig(reflectionConfig);
+----
+--
+====
diff --git a/docs/modules/sql/partials/nav.adoc b/docs/modules/sql/partials/nav.adoc
@@ -18,6 +18,7 @@
 * xref:sql:parameterized-queries.adoc[Query Parameters]
 * xref:sql:finding-mappings.adoc[Finding Mappings]
 * xref:sql:improving-performance.adoc[Improving Performance]
+* xref:sql:sql-reflection-configuration.adoc[Reflection Configuration]
 * xref:sql:troubleshooting.adoc[Troubleshooting]
 * Statements
 ** xref:sql:sql-statements.adoc[Overview]