Merge pull request #1 from kwwall/disabledByDefault

kwwall · web-flow · commit 05605c4cddf1 · 2025-06-20T15:15:20.000-04:00
Initial code to disable encodeForSQL
diff --git a/src/main/java/org/owasp/esapi/ESAPI.java b/src/main/java/org/owasp/esapi/ESAPI.java
@@ -16,10 +16,13 @@
  */
 package org.owasp.esapi;
 
+import java.util.Arrays;
+
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
 import org.owasp.esapi.util.ObjFactory;
+import org.owasp.esapi.errors.ConfigurationException;
 
 /**
  * ESAPI locator class is provided to make it easy to gain access to the current ESAPI classes in use.
@@ -93,16 +96,18 @@ public static Authenticator authenticator() {
     }
 
     /**
-     * The ESAPI Encoder is primarily used to provide <i>output</i> encoding to
+     * The ESAPI {@code Encoder} is primarily used to provide <i>output</i> encoding to
      * prevent Cross-Site Scripting (XSS).
-     * @return the current ESAPI Encoder object being used to encode and decode data for this application.
+     * @return the current ESAPI {@code Encoder} object being used to encode and decode data for this application.
      */
     public static Encoder encoder() {
         return ObjFactory.make( securityConfiguration().getEncoderImplementation(), "Encoder" );
     }
 
     /**
-     * @return the current ESAPI Encryptor object being used to encrypt and decrypt data for this application.
+     * ESAPI {@code Encryptor} provides a set of methods for performing common encryption, random number, and
+     * hashing operations.
+     * @return the current ESAPI {@code Encryptor} object being used to encrypt and decrypt data for this application.
      */
     public static Encryptor encryptor() {
         return ObjFactory.make( securityConfiguration().getEncryptionImplementation(), "Encryptor" );
@@ -221,4 +226,74 @@ public static String initialize( String impl ) {
     public static void override( SecurityConfiguration config ) {
         overrideConfig = config;
     }
+
+    // KWW - OPEN ISSUE: I don't like placing this here, but it's convenient and I
+    //       don't really know a better place for it and would rather not create
+    //       a whole new utility class just to use it.
+    /**
+     * Determine if a given fully qualified (ESAPI) method name has been explicitly
+     * enabled in the <b>ESAPI.properties</b>'s file via the property name
+     * <b>ESAPI.dangerouslyAllowUnsafeMethods.methodNames</b>. Note that there
+     * is no real reason for an ESAPI client to use this, It is intended for
+     * interal use,
+     * </p><p>
+     * The reason this method exists is because certain (other) ESAPI method names
+     * are considered "unsafe" and therefore should be used with extra caution.
+     * These "unsafe" methods may include methods that are:
+     * <ul>
+     * <li>Deprecated and thus no longer suggested for long term use.</li>
+     * <li>Methods where the programming contract is not in itself sufficient to ensure safety alone
+     * and developers are expected to take addional actions on their own to secure their application.</li>
+     * <li>Methods that are using some unpatched transitive dependency that we haven't firmly
+     * established grounds for it not being exploitable in the manner that ESAPI uses it.</li>
+     * <li>Methods whose reference implementations are not scalable to the enterprise level.</li>
+     * </ul>
+     * <i>Public</i> methods that are not in that list for the above ESAPI property
+     * are generally are considered enabled and okay to use unless their Javadoc
+     * indicates otherwise.
+     * </p><p>
+     * Note that this method is intended primarilly for internal ESAPI use and if we were
+     * using Java Modules (in JDK 9 and later), this method would not be exported.
+     * </p><p>
+     * For further details, please see the ESAPI GitHub wiki article,
+     * <a href="https://github.com/ESAPI/esapi-java-legacy/wiki/Reducing-the-ESAPI-Library's-Attack-Surface">"Reducing the ESAPI Library's Attack Surface"</a>.
+     * @param fullyQualifiedMethodName A fully qualified ESAPI class name (so, should start
+     *              "org.owasp.esapi.") followed by the method name (but without
+     *              parenthesis or any parameter signature information.
+     * @return {@code true} if the parameter {@code fullyQualifiedMethodName} is in the comma-separated
+     *         list of values in the ESAPI property <b>ESAPI.dangerouslyAllowUnsafeMethods.methodNames</b>,
+     *         otherwise {@code false} is returned.
+     */
+    public static boolean isMethodExplicityEnabled(String fullyQualifiedMethodName) {
+        if ( fullyQualifiedMethodName == null || fullyQualifiedMethodName.trim().isEmpty() ) {
+            throw new IllegalArgumentException("Program error: fullyQualifiedMethodName parameter cannot be null or empty");
+        }
+        String desiredMethodName = fullyQualifiedMethodName.trim();
+            // This regex is too liberal to be anything more than just a trivial
+            // sanity test to protect against typos.
+        if ( !desiredMethodName.matches("^org\\.owasp\\.esapi\\.(\\p{Alnum}|\\.)*$") ) {
+            throw new IllegalArgumentException("Program error: fullyQualifiedMethodName must start with " +
+                                               "'org.owasp.esapi.' and be a valid method name.");
+        }
+
+        String enabledMethods = null;
+        try {
+            // Need to do this w/in a try/catch because if the property is not
+            // found, getStringProp will throw a ConfigurationException rather
+            // than returning a null.
+            enabledMethods = securityConfiguration().getStringProp("ESAPI.dangerouslyAllowUnsafeMethods.methodNames");
+        } catch( ConfigurationException cex ) {
+            return false;   // Property not found at all.
+        }
+
+
+        // Split it up by ',' and then filter it by finding the first on that
+        // matches the desired method name passed in as the method parameter.
+        // If no matches, return the empty string.
+        String result = Arrays.stream( enabledMethods.trim().split(",") )
+                                  .filter(methodName -> methodName.trim().equals( desiredMethodName ) )
+                                  .findFirst()
+                                  .orElse("");
+        return !result.isEmpty();
+    }
 }
diff --git a/src/main/java/org/owasp/esapi/Encoder.java b/src/main/java/org/owasp/esapi/Encoder.java
@@ -472,7 +472,7 @@ public interface Encoder {
      * exception ticket to track it.
      * </p><p>
      * <b>IMPORTANT NOTE:</b> If you really do insist enabling leg cannon mode and use
-     * this method, then you <i>MUST<i> follow these instructions. Failure to do so will
+     * this method, then you <i>MUST</i> follow these instructions. Failure to do so will
      * result in a {@link org.owasp.esapi.errors.NotConfiguredByDefaultException} being
      * thrown when you try to call it. Thus to make it work, you need to add the implementation
      * method corresponding to this interace (defined in the property "<b>ESAPI.Encoder</b>"
diff --git a/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java b/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java
@@ -13,20 +13,22 @@
 public class NotConfiguredByDefaultException extends ConfigurationException {
 
     protected static final long serialVersionUID = 1L;
+    private static final String defaultMsg = "Unknown unsafe ESAPI method invoked without being explicitly allowed. " +
+                                             "Check exception stack trace for method name.";
 
     public NotConfiguredByDefaultException(Exception e) {
         super(e);
     }
 
     public NotConfiguredByDefaultException(String s) {
-        super(s);
+        super( (s == null || s.trim().isEmpty()) ? defaultMsg : s);
     }
 
     public NotConfiguredByDefaultException(String s, Throwable cause) {
-        super(s, cause);
+        super( (s == null || s.trim().isEmpty()) ? defaultMsg : s, cause);
     }
 
     public NotConfiguredByDefaultException(Throwable cause) {
-        super(cause);
+        super(defaultMsg, cause);
     }
 }
diff --git a/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java b/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
@@ -45,6 +45,11 @@
 import org.owasp.esapi.codecs.JSONCodec;
 import org.owasp.esapi.errors.EncodingException;
 import org.owasp.esapi.errors.IntrusionException;
+import org.owasp.esapi.errors.ConfigurationException;
+import org.owasp.esapi.errors.NotConfiguredByDefaultException;
+
+import static org.owasp.esapi.PropNames.ACCEPTED_UNSAFE_METHOD_NAMES;
+import static  org.owasp.esapi.PropNames.ACCEPTED_UNSAFE_METHODS_JUSTIFICATION;
 
 
 /**
@@ -271,11 +276,75 @@ public String encodeForVBScript(String input) {
         return vbScriptCodec.encode(IMMUNE_VBSCRIPT, input);
     }
 
+    ///////////////////////////////////////////////////////////////////////
+    // TODO - Move this method to some utility class (where?) when we
+    //        are ready to use it on other methods than just encodeForSQL.
+    //
+    //        At that time, also move the method ESAPI.isMethodExplicityEnabled
+    //        to the same utility class.
+    /**
+     * Utility class to throw {@code NotConfiguredByDefaultException} if the
+     * specified method name is not enabled by default.
+     *
+     * @param fullyQualifiedMethodName is the method name that we are checkig if
+     *                                 enabled in ESAPI.properties.
+     * @param customAuditMsg is a audit message to log and use in exceptions. If
+     *                       this value passed in is {@code null} or the string
+     *                       "&lt;default&gt;", then a canned message is used to
+     *                       compose the error message.
+     * @param seeAlso is a string that provides additional reference for context
+     *                such as a CVE ID, GHAS Security Advisory, or ESAPI Security Bulletin.
+     * @throws NotConfiguredByDefaultException if the specified method name is
+     *                not listed in the property <b>ESAPI.dangerouslyAllowUnsafeMethods.methodNames</b>
+     *                in the <b>ESAPI.properties</b> file.
+     */
+    private void ensureDangerousMethodExplicitlyEnabled(String fullyQualifiedMethodName,
+                                                        String customAuditMsg,
+                                                        String seeAlso) {
+
+        String auditMsg = null;
+        if ( customAuditMsg == null || customAuditMsg.equalsIgnoreCase("<default>") ) {
+            // Special case. Compose an audit message from a canned template.
+            // TODO: Null / empty check for 'seeAlso'.
+            auditMsg = "SIEM ALERT: Method '" + fullyQualifiedMethodName + "' has been invoked despite having credible " +
+                       "security concerns; for additional details, see " + seeAlso + ".";
+        } else {
+            auditMsg = customAuditMsg;  // Use the custom audit message
+        }
+ 
+        if ( ! ESAPI.isMethodExplicityEnabled( fullyQualifiedMethodName ) ) {
+            throw new NotConfiguredByDefaultException( "Method not explicitly enabled in property " +
+                                                        ACCEPTED_UNSAFE_METHOD_NAMES + "; " + auditMsg );
+        } else {
+            String justification = null;
+            try {
+                // This throws a ConfigurationException (rather than returning null if
+                // the property name is not found so we need to handle that.
+                justification = ESAPI.securityConfiguration().getStringProp( ACCEPTED_UNSAFE_METHODS_JUSTIFICATION );
+            } catch ( ConfigurationException cex ) {
+                logger.debug( Logger.EVENT_FAILURE, "Property " + ACCEPTED_UNSAFE_METHODS_JUSTIFICATION + " not found.");
+                justification = "None";
+            }
+
+            if ( justification == null || justification.trim().isEmpty() ) {
+                justification = "None";
+            }
+            logger.warning( Logger.EVENT_FAILURE, auditMsg + " Provided justification: " + justification );
+        }
+        return;
+    }
+
 
     /**
      * {@inheritDoc}
      */
     public String encodeForSQL(Codec codec, String input) {
+
+        // This will throw if this method is not explicitly enabled in ESAPI.properties.
+        ensureDangerousMethodExplicitlyEnabled( DefaultEncoder.class.getName() + ".encodeForSQL",
+                                                "<default>",
+                                                "see CVE-2025-????? and ESAPI Security Bulletin #13 for details" );
+
         if( input == null ) {
             return null;
         }
diff --git a/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java b/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java
@@ -0,0 +1,68 @@
+package org.owasp.esapi;
+
+import org.bouncycastle.crypto.modes.CBCModeCipher;
+import org.junit.Assert;
+import org.junit.Test;
+import org.mockito.Mockito;
+import org.owasp.esapi.errors.ConfigurationException;
+
+
+public class ESAPIVerifyAllowedMethods {
+
+	@Test (expected = IllegalArgumentException.class)
+	public void verifyNulParamThrows() {
+		ESAPI.isMethodExplicityEnabled(null);
+	}
+	
+	@Test (expected = IllegalArgumentException.class)
+	public void verifyEmptyNoWhitespaceParameterThrows() {
+		ESAPI.isMethodExplicityEnabled("");
+	}
+	
+	@Test (expected = IllegalArgumentException.class)
+	public void verifyEmptyOnlyWhitespaceParameterThrows() {
+		ESAPI.isMethodExplicityEnabled("   ");
+	}
+	
+	@Test (expected = IllegalArgumentException.class)
+	public void verifyEmptyOnlyTabWhitespaceParameterThrows() {
+		ESAPI.isMethodExplicityEnabled("\t");
+	}
+	
+	@Test (expected = IllegalArgumentException.class)
+	public void verifyEmptyOnlyNewlineWhitespaceParameterThrows() {
+		ESAPI.isMethodExplicityEnabled("\n");
+	}
+	
+	
+	
+	@Test (expected = IllegalArgumentException.class)
+	public void verifyNonEsapiPackageParameterThrows() {
+		ESAPI.isMethodExplicityEnabled("com.myPackage.myScope.method");
+	}
+	@Test 
+	public void verifyUnknownMethodFailsEnableCheck() {
+		Assert.assertFalse(ESAPI.isMethodExplicityEnabled("org.owasp.esapi.reference.DefaultEncoder.encodeForSQ"));
+	}
+	
+	@Test 
+	public void verifyDefinedRestrictionIsCaught() {
+		Assert.assertTrue(ESAPI.isMethodExplicityEnabled("org.owasp.esapi.reference.DefaultEncoder.encodeForSQL"));
+	}
+	
+	@Test 
+	public void testMissingPropertyReturnsFalse() {
+		try {
+		SecurityConfiguration mockConfig = Mockito.mock(SecurityConfiguration.class);
+		Mockito.when(mockConfig.getStringProp("ESAPI.dangerouslyAllowUnsafeMethods.methodNames")).thenThrow(ConfigurationException.class);
+		ESAPI.override(mockConfig);
+		
+		Assert.assertFalse(ESAPI.isMethodExplicityEnabled("org.owasp.esapi.thisValueDoesNotMatter"));
+		Mockito.verify(mockConfig, Mockito.times(1)).getStringProp("ESAPI.dangerouslyAllowUnsafeMethods.methodNames");
+		} finally {
+			ESAPI.override(null);
+		}
+		
+	}
+	
+}
diff --git a/src/test/resources/esapi/ESAPI.properties b/src/test/resources/esapi/ESAPI.properties
@@ -614,4 +614,4 @@ ESAPI.dangerouslyAllowUnsafeMethods.methodNames=org.owasp.esapi.reference.Defaul
 # justification as to why you have enabled these functions. This can be
 # anythuing such as a Jira or ServiceNow ticket number, a security exception
 # reference, etc. If it is left empty, it will just like "Justification: none".`
-ESAPI.enableLegCannonModeAndGetMyAssFired.justification=blah,blah. Please don't fire my @$$. Ticket # 12345
+ESAPI.dangerouslyAllowUnsafeMethods.justification=blah,blah. Please don't fire my @$$. Ticket # 12345-not-the-winning-lotto#

Original file line number	Diff line number	Diff line change
`@@ -13,20 +13,22 @@`
`13`	`13`	`public class NotConfiguredByDefaultException extends ConfigurationException {`
`14`	`14`
`15`	`15`	`protected static final long serialVersionUID = 1L;`
	`16`	`+ private static final String defaultMsg = "Unknown unsafe ESAPI method invoked without being explicitly allowed. " +`
	`17`	`+ "Check exception stack trace for method name.";`
`16`	`18`
`17`	`19`	`public NotConfiguredByDefaultException(Exception e) {`
`18`	`20`	`super(e);`
`19`	`21`	`}`
`20`	`22`
`21`	`23`	`public NotConfiguredByDefaultException(String s) {`
`22`		`- super(s);`
	`24`	`+ super( (s == null \|\| s.trim().isEmpty()) ? defaultMsg : s);`
`23`	`25`	`}`
`24`	`26`
`25`	`27`	`public NotConfiguredByDefaultException(String s, Throwable cause) {`
`26`		`- super(s, cause);`
	`28`	`+ super( (s == null \|\| s.trim().isEmpty()) ? defaultMsg : s, cause);`
`27`	`29`	`}`
`28`	`30`
`29`	`31`	`public NotConfiguredByDefaultException(Throwable cause) {`
`30`		`- super(cause);`
	`32`	`+ super(defaultMsg, cause);`
`31`	`33`	`}`
`32`	`34`	`}`