From 31e221ad72b0c8366a62b2ec0f6d28be58587f07 Mon Sep 17 00:00:00 2001
From: kwwall
Date: Tue, 10 Jun 2025 18:31:31 -0400
Subject: [PATCH 01/25] Fix javadoc botch forgetting to end italics. :(
---
src/main/java/org/owasp/esapi/Encoder.java | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/main/java/org/owasp/esapi/Encoder.java b/src/main/java/org/owasp/esapi/Encoder.java
index b16624add..b544a02b6 100644
--- 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.
*
* IMPORTANT NOTE: If you really do insist enabling leg cannon mode and use
- * this method, then you MUST follow these instructions. Failure to do so will
+ * this method, then you MUST 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 "ESAPI.Encoder"
From 21105d9cd9e2c037934da0237b786ab72cc73b8a Mon Sep 17 00:00:00 2001
From: kwwall
Date: Thu, 12 Jun 2025 00:05:25 -0400
Subject: [PATCH 02/25] Added new static method 'isMethodExplicityEnabled' abd
other minor Javadoc tweaks.
---
src/main/java/org/owasp/esapi/ESAPI.java | 90 +++++++++++++++++++++++-
1 file changed, 87 insertions(+), 3 deletions(-)
diff --git a/src/main/java/org/owasp/esapi/ESAPI.java b/src/main/java/org/owasp/esapi/ESAPI.java
index c42a21ff8..6ab5dba04 100644
--- 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 output encoding to
+ * The ESAPI {@code Encoder} is primarily used to provide output 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,83 @@ 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 ESAPI.properties's file via the property name
+ * ESAPI.dangerouslyAllowUnsafeMethods.methodNames. Note that there
+ * is no real reason for an ESAPI client to use this, It is intended for
+ * interal use,
+ *
+ * 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:
+ *
+ * - Deprecated and thus no longer suggested for long term use.
+ * - 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.
+ * - 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.
+ * - Methods whose reference implementations are not scalable to the enterprise level.
+ *
+ * Public 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.
+ *
+ * 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.
+ *
+ * For further details, please see the ESAPI GitHub wiki article,
+ * "Reducing the ESAPI Library's Attack Surface".
+ * @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 ESAPI.dangerouslyAllowUnsafeMethods.methodNames,
+ * 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.
+ }
+
+ if ( enabledMethods == null || enabledMethods.trim().isEmpty() ) {
+ // TODO: Log something here? Maybe at DEBUG level?
+ return false; // No methods in the list, so no match possible.
+ }
+
+ // 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("");
+
+ if ( result.isEmpty() ) {
+ return false; // No match, so method not enabled
+ } else {
+ return true; // Method found, thus enabled
+ }
+ }
}
From d7d6f1ca25eb464f8cccfc37d1c6056806615dbf Mon Sep 17 00:00:00 2001
From: kwwall
Date: Thu, 12 Jun 2025 00:10:09 -0400
Subject: [PATCH 03/25] Added default exception message if one wasn't specified
or was empty.
---
.../esapi/errors/NotConfiguredByDefaultException.java | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java b/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java
index 3c30dbfec..58a0cbc98 100644
--- 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);
}
}
From bab8f2cd57e2815e52c420bce11e1eef2ea326cd Mon Sep 17 00:00:00 2001
From: kwwall
Date: Thu, 12 Jun 2025 01:07:46 -0400
Subject: [PATCH 04/25] Changed to use a more politically correct property
name. But I still like
'ESAPI.enableLegCannonModeAndGetMyAssFired.justification' better. ;-)
---
src/test/resources/esapi/ESAPI.properties | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/test/resources/esapi/ESAPI.properties b/src/test/resources/esapi/ESAPI.properties
index 7327fbc85..e10691d1f 100644
--- 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#
From c12a3e9c8b013fed6b46067260320bb3b774616e Mon Sep 17 00:00:00 2001
From: kwwall
Date: Thu, 12 Jun 2025 01:11:35 -0400
Subject: [PATCH 05/25] Add code to ensure that DefaultEncoder.encodeForSQL is
explicity enabled if someone wants to use it.
---
.../owasp/esapi/reference/DefaultEncoder.java | 69 +++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java b/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
index 348cb4a4d..e83e5a367 100644
--- 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
+ * "<default>", 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 ESAPI.dangerouslyAllowUnsafeMethods.methodNames
+ * in the ESAPI.properties file.
+ */
+ private void ensureDangerousMethodExplicitlyEnabled(String fullyQualifiedMethodName,
+ String customAuditMsg,
+ String seeAlso) {
+
+ String auditMsg = null;
+ if ( customAuditMsg == null || customAuditMsg.equalsIgnoreCase("") ) {
+ // 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",
+ "",
+ "see CVE-2025-????? and ESAPI Security Bulletin #13 for details" );
+
if( input == null ) {
return null;
}
From ece2dd373c0b76f2798f39e4afbf3b8dfa8dfcf2 Mon Sep 17 00:00:00 2001
From: "jeremiah.stacey"
Date: Mon, 16 Jun 2025 17:55:31 -0500
Subject: [PATCH 06/25] Updating ESAPI util for ExplictMethod verify
Updating parameter null check to test null case.
Removing null check on property result (if null ConfigurationException
is thrown).
Simplifying return from method to verify response is not empty.
---
src/main/java/org/owasp/esapi/ESAPI.java | 13 ++-----------
1 file changed, 2 insertions(+), 11 deletions(-)
diff --git a/src/main/java/org/owasp/esapi/ESAPI.java b/src/main/java/org/owasp/esapi/ESAPI.java
index 6ab5dba04..55e4d896d 100644
--- a/src/main/java/org/owasp/esapi/ESAPI.java
+++ b/src/main/java/org/owasp/esapi/ESAPI.java
@@ -265,7 +265,7 @@ public static void override( SecurityConfiguration config ) {
* otherwise {@code false} is returned.
*/
public static boolean isMethodExplicityEnabled(String fullyQualifiedMethodName) {
- if ( fullyQualifiedMethodName != null && fullyQualifiedMethodName.trim().isEmpty() ) {
+ if ( fullyQualifiedMethodName == null || fullyQualifiedMethodName.trim().isEmpty() ) {
throw new IllegalArgumentException("Program error: fullyQualifiedMethodName parameter cannot be null or empty");
}
String desiredMethodName = fullyQualifiedMethodName.trim();
@@ -286,10 +286,6 @@ public static boolean isMethodExplicityEnabled(String fullyQualifiedMethodName)
return false; // Property not found at all.
}
- if ( enabledMethods == null || enabledMethods.trim().isEmpty() ) {
- // TODO: Log something here? Maybe at DEBUG level?
- return false; // No methods in the list, so no match possible.
- }
// 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.
@@ -298,11 +294,6 @@ public static boolean isMethodExplicityEnabled(String fullyQualifiedMethodName)
.filter(methodName -> methodName.trim().equals( desiredMethodName ) )
.findFirst()
.orElse("");
-
- if ( result.isEmpty() ) {
- return false; // No match, so method not enabled
- } else {
- return true; // Method found, thus enabled
- }
+ return !result.isEmpty();
}
}
From 717d9f150350569220b8dc053eb5c09137766a9d Mon Sep 17 00:00:00 2001
From: "jeremiah.stacey"
Date: Mon, 16 Jun 2025 17:59:03 -0500
Subject: [PATCH 07/25] ESAPI methodEnabled Tests
Adding branch testing for ESAPI.isMethodExplicitlyEnabled behavior to
account for parameter cases.
Only case not covered is providing an ESAPI.properties that does not
contain the new key.
---
.../esapi/ESAPIVerifyAllowedMethods.java | 50 +++++++++++++++++++
1 file changed, 50 insertions(+)
create mode 100644 src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java
diff --git a/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java b/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java
new file mode 100644
index 000000000..651df53c4
--- /dev/null
+++ b/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java
@@ -0,0 +1,50 @@
+package org.owasp.esapi;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+
+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"));
+ }
+
+}
From 2474d44e6e189cad2bcc971454b2fe9884ebdede Mon Sep 17 00:00:00 2001
From: "jeremiah.stacey"
Date: Mon, 16 Jun 2025 20:23:21 -0500
Subject: [PATCH 08/25] Test Coverage
using the SecurityConfigurationWrapper to verify remaining test case
when a ConfigurationException is thrown when the new property is
missing or undefined.
---
.../owasp/esapi/ESAPIVerifyAllowedMethods.java | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java b/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java
index 651df53c4..751a95d52 100644
--- a/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java
+++ b/src/test/java/org/owasp/esapi/ESAPIVerifyAllowedMethods.java
@@ -1,7 +1,10 @@
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 {
@@ -47,4 +50,19 @@ 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);
+ }
+
+ }
+
}
From 8a1a2976f3ffc2eeb7223721cad9d40e9ef2ee1f Mon Sep 17 00:00:00 2001
From: kwwall
Date: Fri, 20 Jun 2025 22:57:18 -0400
Subject: [PATCH 09/25] Added deprecations, deprecation warnings, and other
Javadoc refinements.
---
src/main/java/org/owasp/esapi/Encoder.java | 8 ++-
.../java/org/owasp/esapi/codecs/DB2Codec.java | 6 ++
.../org/owasp/esapi/codecs/MySQLCodec.java | 6 ++
.../org/owasp/esapi/codecs/OracleCodec.java | 36 +++++++++--
.../DefaultSecurityConfiguration.java | 62 ++++++++++++++-----
5 files changed, 95 insertions(+), 23 deletions(-)
diff --git a/src/main/java/org/owasp/esapi/Encoder.java b/src/main/java/org/owasp/esapi/Encoder.java
index b544a02b6..e083dd5a1 100644
--- a/src/main/java/org/owasp/esapi/Encoder.java
+++ b/src/main/java/org/owasp/esapi/Encoder.java
@@ -490,8 +490,14 @@ public interface Encoder {
* the text to encode for SQL
*
* @return input encoded for use in SQL
+ * @see
+ * ESAPI Security Bulletin #13
+ * @deprecated This class is considered dangerous and not easily made safe and thus under strong
+ * consideration to be removed within 1 years time after the 2.7.0.0 release. Please
+ * see the referenced ESAPI Security Bulletin #13 for further details.
*/
- String encodeForSQL(Codec codec, String input);
+ @Deprecated
+ String encodeForSQL(Codec codec, String input);
/**
* Encode for an operating system command shell according to the selected codec (appropriate codecs include the WindowsCodec and UnixCodec).
diff --git a/src/main/java/org/owasp/esapi/codecs/DB2Codec.java b/src/main/java/org/owasp/esapi/codecs/DB2Codec.java
index f57555571..61d1f70cd 100644
--- a/src/main/java/org/owasp/esapi/codecs/DB2Codec.java
+++ b/src/main/java/org/owasp/esapi/codecs/DB2Codec.java
@@ -26,7 +26,13 @@
* @author Sivasankar Tanakala (stanakal@TRS.NYC.NY.US)
* @since October 26, 2010
* @see org.owasp.esapi.Encoder
+ * @see
+ * ESAPI Security Bulletin #13
+ * @deprecated This class is considered dangerous and not easily made safe and thus under strong
+ * consideration to be removed within 1 years time after the 2.7.0.0 release. Please
+ * see the referenced ESAPI Security Bulletin #13 for further details.
*/
+@Deprecated
public class DB2Codec extends AbstractCharacterCodec {
public String encodeCharacter(char[] immune, Character c) {
diff --git a/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java b/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java
index 9154f8df8..bd2829521 100644
--- a/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java
+++ b/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java
@@ -63,7 +63,13 @@
* MySQL 8.0 String Literals
* OWASP
* SQL_Injection_Prevention_Cheat_Sheet#MySQL_Escaping
+ * @see
+ * ESAPI Security Bulletin #13
+ * @deprecated This class is considered dangerous and not easily made safe and thus under strong
+ * consideration to be removed within 1 years time after the 2.7.0.0 release. Please
+ * see the referenced ESAPI Security Bulletin #13 for further details.
*/
+@Deprecated
public class MySQLCodec extends AbstractCharacterCodec {
/**
* Specifies the SQL Mode the target MySQL Server is running with. For details about MySQL Server Modes
diff --git a/src/main/java/org/owasp/esapi/codecs/OracleCodec.java b/src/main/java/org/owasp/esapi/codecs/OracleCodec.java
index 4cd946286..2746f9137 100644
--- a/src/main/java/org/owasp/esapi/codecs/OracleCodec.java
+++ b/src/main/java/org/owasp/esapi/codecs/OracleCodec.java
@@ -20,20 +20,44 @@
/**
* Implementation of the {@link org.owasp.esapi.codecs.Codec} interface for Oracle DB strings.
* This function will only protect you from SQLi in limited situations.
- * To improve your chances of success, you made also need to do some
+ * To improve your chances of success, you may also need to do some
* additional canonicalization and input validation first. Before using this class,
- * please be sure to read the "SECURITY WARNING" in
+ * please be sure to read the "SECURITY WARNING" in
* {@link org.owasp.esapi.Encoder#encodeForSQL}
* before using this particular {@link org.owasp.esapi.codecs.Codec} and raising your hope of finding
* a silver bullet to kill all the SQLi werewolves.
- *
- * @see how-to-escape-single-quotes-in-strings
- *
+ *
+ * CAUTION: This class has some known issues. During the investigation of
+ * CVE-2025-5878, it was discovered that since this class' inception in
+ * 2007, that Oracle databases also use \ (backslash) as a default escape char.
+ * That was fundamental in the vulnerability, since the escape character itself
+ * was not being escaped. We had originally planned to address this, but while
+ * researching the issue, we discovered that not only was there a new default
+ * escape character for Oracle SQL*Plus, but that developers could actually
+ * override the default to a character of their choosing. (For details see
+ * SET ESCAPE
+ * and
+ * How to Escape Characters in Oracle PL/SQL Queries.) The second instance is
+ * especially scary, since it illustrates how a developer can potentially can
+ * the default escape character as part of an ordinary SQL statement. We
+ * realized that there is no way we can defend against this, so it seemed
+ * pointless to even bother to try to quote default escape character passed in
+ * as input when {@code OracleCodec} is used with the {@code Encoder.encodeForSQL}
+ * interface. Therefore, you really should not use this, but if dead set in
+ * still using this leg canon, it;s on you. You have been warned.
+ *
+ * @see org.owasp.esapi.Encoder
+ * @see
+ * ESAPI Security Bulletin #13
* @author Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security
* @author Jim Manico (jim@manico.net) Manico.net
* @since June 1, 2007
- * @see org.owasp.esapi.Encoder
+ * @see how-to-escape-single-quotes-in-strings
+ * @deprecated This class is considered dangerous and not easily made safe and thus under strong
+ * consideration to be removed within 1 years time after the 2.7.0.0 release. Please
+ * see the referenced ESAPI Security Bulletin #13 for further details.
*/
+@Deprecated
public class OracleCodec extends AbstractCharacterCodec {
diff --git a/src/main/java/org/owasp/esapi/reference/DefaultSecurityConfiguration.java b/src/main/java/org/owasp/esapi/reference/DefaultSecurityConfiguration.java
index eb561349b..7b622c32d 100644
--- a/src/main/java/org/owasp/esapi/reference/DefaultSecurityConfiguration.java
+++ b/src/main/java/org/owasp/esapi/reference/DefaultSecurityConfiguration.java
@@ -43,29 +43,59 @@
import org.owasp.esapi.errors.ConfigurationException;
/**
- * The reference {@code SecurityConfiguration} manages all the settings used by the ESAPI in a single place. In this reference
- * implementation, resources can be put in several locations, which are searched in the following order:
+ * Thse reference implementation class for {@code SecurityConfiguration} manages all the settings used by the ESAPI
+ * in a single place. In this reference implementation, resources can be put in several locations, which are
+ * searched in the following order:
*
- * 1) Inside a directory set with a call to SecurityConfiguration.setResourceDirectory( "C:\temp\resources" ).
- *
- * 2) Inside the System.getProperty( "org.owasp.esapi.resources" ) directory.
+ *
+ * -
+ * Inside a directory set with a call to SecurityConfiguration.setResourceDirectory( "C:\temp\resources" ).
+ *
+ * CAUTION: Generally this technique should be avoided if you are
+ * using ESAPI in a resusable library, as it makes it very difficult for an
+ * application using your library to use its own version of
+ * ESAPI.properties.
+ *
+ * The only exception might be if you are writing a wrapper library for ESAPI
+ * and wish to provide a set of ESAPI properties that the application cannot accidentally
+ * change. However, selecting this option won't intentionally prevent changing ESAPI.properties
+ * unless you are signing the jar * and somehow forcing the verifiction of its digital signature at
+ * runtime. That's because it's easy enough to unjar your library, edit the ESAPI.properties
+ * file and then re-jar the library.
+ *
+ * This option was probably more intended for use by web applications by embedding
+ * them as resources in .war or .ear files, possibly with the intent of
+ * dissauding operations staff from making "improvements", a practice which
+ * makes much less--if any--sense in the era of DevOps and DevSecOps.
+ *
+ *
+ * -
+ * Inside the {@code System.getProperty( "org.owasp.esapi.resources" )} directory.
* You can set this on the java command line as follows (for example):
*
- * java -Dorg.owasp.esapi.resources="C:\temp\resources"
+ *
+ * java -Dorg.owasp.esapi.resources="C:\apps\myApp\resources"
*
* You may have to add this to the start-up script that starts your web server. For example, for Tomcat,
* in the "catalina" script that starts Tomcat, you can set the JAVA_OPTS variable to the {@code -D} string above.
- *
- * 3) Inside the {@code System.getProperty( "user.home" ) + "/.esapi"} directory (supported for backward compatibility) or
+ *
+ * -
+ * Inside the {@code System.getProperty( "user.home" ) + "/.esapi"} directory (supported for backward compatibility) or
* inside the {@code System.getProperty( "user.home" ) + "/esapi"} directory.
- *
- * 4) The first ".esapi" or "esapi" directory on the classpath. (The former for backward compatibility.)
- *
- * Once the Configuration is initialized with a resource directory, you can edit it to set things like master
- * keys and passwords, logging locations, error thresholds, and allowed file extensions.
- *
- * WARNING: Do not forget to update ESAPI.properties to change the master key and other security critical settings.
- *
+ *
+ * -
+ * The first ".esapi" or "esapi" directory on the classpath. (The former for backward compatibility.)
+ *
+ *
+ *
+ * Once the ESAPI configuration is initialized with a resource directory, you can edit it to set things like master
+ * keys and passwords, logging locations, error thresholds, and allowed file extensions. (But see the above cautionary
+ * note if you are using ESAPI in a reusable library.)
+ *
+ * WARNING: Do not forget to update ESAPI.properties to change the master key and other security critical settings
+ * as well as reviewing changes in the esapi-<vers-configuration.jar for differences
+ * with your current version to see if any important properties were added or removed.
+ *
* DEPRECATION WARNING: All of the variables of the type '{@code public static final String}'
* are now declared and defined in the {@code org.owasp.esapi.PropNames}. These public fields
* representing property names and values in this class will be eventually deleted and
From 6b46be358f646c11207b5577971f08104d6a0ecc Mon Sep 17 00:00:00 2001
From: kwwall
Date: Sat, 21 Jun 2025 14:27:34 -0400
Subject: [PATCH 10/25] Reference specific CVE ID for logged message.
---
src/main/java/org/owasp/esapi/reference/DefaultEncoder.java | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java b/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
index e83e5a367..35c644a51 100644
--- a/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
+++ b/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
@@ -343,7 +343,7 @@ 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",
"",
- "see CVE-2025-????? and ESAPI Security Bulletin #13 for details" );
+ "see CVE-2025-5878 and ESAPI Security Bulletin #13 for details" );
if( input == null ) {
return null;
From 5f4ee1ed27bf677ae61083ecddece13386c53abd Mon Sep 17 00:00:00 2001
From: kwwall
Date: Sat, 21 Jun 2025 22:48:52 -0400
Subject: [PATCH 11/25] Change from EVENT_FAILURE to SECURITY_FAILURE, because
it potentially is, despite best intentions.
---
src/main/java/org/owasp/esapi/reference/DefaultEncoder.java | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java b/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
index 35c644a51..862c17e47 100644
--- a/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
+++ b/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java
@@ -329,7 +329,7 @@ private void ensureDangerousMethodExplicitlyEnabled(String fullyQualifiedMethodN
if ( justification == null || justification.trim().isEmpty() ) {
justification = "None";
}
- logger.warning( Logger.EVENT_FAILURE, auditMsg + " Provided justification: " + justification );
+ logger.warning( Logger.SECURITY_FAILURE, auditMsg + " Provided justification: " + justification );
}
return;
}
From aa1c9d979161708342a8ff4f4db37da47a82993e Mon Sep 17 00:00:00 2001
From: kwwall
Date: Sat, 21 Jun 2025 23:50:08 -0400
Subject: [PATCH 12/25] Draft #2. Needs reviewd and completed. Track changes
disabled.
---
documentation/ESAPI-security-bulletin13.odt | Bin 0 -> 63565 bytes
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 documentation/ESAPI-security-bulletin13.odt
diff --git a/documentation/ESAPI-security-bulletin13.odt b/documentation/ESAPI-security-bulletin13.odt
new file mode 100644
index 0000000000000000000000000000000000000000..788c1e27548045f65d2d6cf6518d982f03d2f9be
GIT binary patch
literal 63565
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 |