From 9ac6c97e3931fb8c789f0bd2ddc55b1d1ba619de Mon Sep 17 00:00:00 2001 From: kwwall Date: Mon, 2 Jun 2025 23:06:27 -0400 Subject: [PATCH 01/32] Modify pom.xml for next planned release. --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 43072de09..8c954c6bd 100644 --- a/pom.xml +++ b/pom.xml @@ -3,7 +3,7 @@ 4.0.0 org.owasp.esapi esapi - 2.6.2.0 + 2.7.0.0-SNAPSHOT jar From bc0d887c675ed8ad5e3de899b37d031047de91cb Mon Sep 17 00:00:00 2001 From: kwwall Date: Mon, 2 Jun 2025 23:09:53 -0400 Subject: [PATCH 02/32] Update latest version to 2.6.2.0 --- README.md | 4 ++-- SECURITY.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4c4218298..8856c029d 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ specific Jakarta version of ESAPI, in Maven, you would specify your ESAPI depend org.owasp.esapi esapi - 2.6.1.0 + 2.6.2.0 jakarta ``` @@ -105,7 +105,7 @@ link to the specific release notes. the ESAPI GitHub Discussion https://github.com/ESAPI/esapi-java-legacy/discussions/841. # Locating ESAPI Jar files -The [latest ESAPI release](https://github.com/ESAPI/esapi-java-legacy/releases/latest) is 2.6.1.0. +The [latest ESAPI release](https://github.com/ESAPI/esapi-java-legacy/releases/latest) is 2.6.2.0. All the *regular* ESAPI jars, with the exception of the ESAPI configuration jar (i.e., esapi-2.#.#.#-configuration.jar) and its associated detached GPG signature, are available from Maven Central. The ESAPI configuration diff --git a/SECURITY.md b/SECURITY.md index 4945f7338..083874215 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -12,8 +12,8 @@ but if it is anything but trivial, we would charge a TBD consulting fee. | Version | Supported | | ------- | ------------------ | -| 2.6.0.0 (latest) | :white_check_mark: | -| 2.1.0.1-2.5.5.0 | :x:, upgrade to latest release | +| 2.6.2.0 (latest) | :white_check_mark: | +| 2.1.0.1-2.6.1.0 | :x:, upgrade to latest release | | <= 1.4.x | :x:, no longer supported AT ALL | ## Reporting a Vulnerability From 849c15e4ceb0821625f81a04e3274865e6a299a3 Mon Sep 17 00:00:00 2001 From: kwwall Date: Sun, 8 Jun 2025 23:24:00 -0400 Subject: [PATCH 03/32] Sdd comment about doclint options. --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 8c954c6bd..e69d57aa4 100644 --- a/pom.xml +++ b/pom.xml @@ -643,7 +643,7 @@ 3.11.2 8 - none + none From 40026bfc9212a83ad4f2400144b4a5f2531e1472 Mon Sep 17 00:00:00 2001 From: kwwall Date: Sun, 8 Jun 2025 23:25:42 -0400 Subject: [PATCH 04/32] Add 2 properties associated w/ disabling stuff by default. --- src/test/resources/esapi/ESAPI.properties | 34 +++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/test/resources/esapi/ESAPI.properties b/src/test/resources/esapi/ESAPI.properties index 8ffc61f66..1007597f5 100644 --- a/src/test/resources/esapi/ESAPI.properties +++ b/src/test/resources/esapi/ESAPI.properties @@ -578,3 +578,37 @@ Validator.AcceptLenientDates=false # #Validator.HtmlValidationAction=clean Validator.HtmlValidationAction=throw + +######################################################################################## +# The following methods are now disabled in the default configuration and must +# be explicity enabled. If you try to invoke a method disabled by default, ESAPI +# will thrown a NotConfiguredByDefaultException. +# +# The reason for this varies, but ranges from they are not really suitable for +# enterprise scale to that are only marginally tested (if at all) versus the are +# unsafe for general use, although them may be fine when combined with other +# security-in-depth techiques. +# +# The disabled-by-default methods are: +# org.owasp.esapi.reference.DefaultEncoder.encodeForSQL +# org.owasp.esapi.ESAPI.accessController [FUTURE] +# +# The format is a comma-separated list of fully,Qualified.ClassNames.methodName +# +# Note to ESAPI Devs: There is presently no way to specific which specific +# method to indicate here when the method name alone, +# absent from its signature, is ambiguous, so it is +# best to avoid those if at all possible! +# +# An example of that would be something like: +# org.owasp.esapi.reference.DefaultValidator.getValidPrintable +# which has 4 interfaces so currently, there's no way to +# specify a specific one. +# +ESAPI.enableLegCannonModeAndGetMyAssFired.methodNames=org.owasp.esapi.reference.DefaultEncoder.encodeForSQL + +# Normally you would put some text here (that will be logged) that provides some +# 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 From 436fee51465d04400bf13ab5fd447a92474ce6ff Mon Sep 17 00:00:00 2001 From: kwwall Date: Sun, 8 Jun 2025 23:29:59 -0400 Subject: [PATCH 05/32] Class for new unchecked exception type. --- .../NotConfiguredByDefaultException.java | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java diff --git a/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java b/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java new file mode 100644 index 000000000..fb624e75c --- /dev/null +++ b/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java @@ -0,0 +1,31 @@ +package org.owasp.esapi.errors; + +/** + * A {@code NotConfiguredByDefaultException} should be thrown when a method that + * is disabled by default is invoked, + *

+ * See the ESAPI properties "ESAPI.enableLegCannonModeAndGetMyAssFired.methodNames" and + * "ESAPI,enableLegCannonModeAndGetMyAssFired,justification" in the + * ESAPI.properties file for additional details. + *

+ */ +public class NotConfiguredByDefaultException extends ConfigurationException { + + protected static final long serialVersionUID = 1L; + + public NotConfiguredByDefaultException(Exception e) { + super(e); + } + + public NotConfiguredByDefaultException(String s) { + super(s); + } + + public NotConfiguredByDefaultException(String s, Throwable cause) { + super(s, cause); + } + + public NotConfiguredByDefaultException(Throwable cause) { + super(cause); + } +} From 1da613b79246814906647799e9694037fe2332c8 Mon Sep 17 00:00:00 2001 From: kwwall Date: Sun, 8 Jun 2025 23:31:13 -0400 Subject: [PATCH 06/32] Miscellaneous Javadoc enhancements. --- src/main/java/org/owasp/esapi/Encoder.java | 96 +++++++++++++++---- .../java/org/owasp/esapi/codecs/Codec.java | 12 +++ .../java/org/owasp/esapi/codecs/DB2Codec.java | 11 ++- .../org/owasp/esapi/codecs/MySQLCodec.java | 37 ++++--- .../org/owasp/esapi/codecs/OracleCodec.java | 14 ++- 5 files changed, 131 insertions(+), 39 deletions(-) diff --git a/src/main/java/org/owasp/esapi/Encoder.java b/src/main/java/org/owasp/esapi/Encoder.java index ad4950dc9..d4e7656a3 100644 --- a/src/main/java/org/owasp/esapi/Encoder.java +++ b/src/main/java/org/owasp/esapi/Encoder.java @@ -96,7 +96,7 @@ * stores some untrusted data item such as an email address from a user. A * developer thinks "let's output encode this and store the encoded data in * the database, thus making the untrusted data safe to use all the time, thus -* saving all of us developers all the encoding troubles later on". On the surface, + * saving all of us developers all the encoding troubles later on". On the surface, * that sounds like a reasonable approach. The problem is how to know what * output encoding to use, not only for now, but for all possible future * uses? It might be that the current application code base is only using it in @@ -147,10 +147,28 @@ * target="_blank" rel="noopener noreferrer">ESAPI Encoder JUnittest cases for ideas. * If you are really ambitious, an excellent resource for XSS attack patterns is * BeEF - The Browser Exploitation Framework Project. + *
  • A final note on {@code Encoder} implementation details: + * Most of the {@code Encoder} methods make extensive use of ESAPI's {@link org.owasp.esapi.codecs.Codec} + * classes under-the-hood. These {@code Codec} classes are intended for use for encoding and decoding + * input based on some particular context or specification. While the OWASP team + * over the years have made every effort to be cautious--often going to extremes + * to make "safe harbor" decisions on harmful inputs other similar encoders assume are already safe + * (we did this to in order to protect the client's users from buggy browsers that don't adhere + * to the W3C HTML specications)&em;the various {@code Codec} implemtations can offer + * NO GUARANTEE of safety of the content being encoded or decoded. Therefore, + * it is highly advised to practice a security-in-depth approach for everything you do. + * By following that advise, you will minimize the impact and/or likelihood of any + * vulnerabilities from bugs in the ESAPI code or accidental misuse of the ESAPI + * library on your part. In particular, whenever there are cases where cients use + * any of these {@link org.owasp.esapi.codecs.Codec} classes drectly, it is highly + * recommended to perform canonicalization followed by strict input valiation both + * prior to encoding and after decoding to protect your application from input-based + * attacks. *
    • * - * + *

    * @see OWASP Cross-Site Scripting Prevention Cheat Sheet + * @see org.owasp.esapi.Validator * @see OWASP Proactive Controls: C4: Encode and Escape Data * @see Properly encoding and escaping for the web * @author Jeff Williams (jeff.williams .at. owasp.org) @@ -215,7 +233,7 @@ public interface Encoder { *
    • Perverse but legal variants of escaping schemes
      • *
    • Multiple escaping (%2526 or &lt;)
      • *
    • Mixed escaping (%26lt;)
      • - *
    • Nested escaping (%%316 or &%6ct;)
      • + *
    • Nested escaping (%%316 or &%6ct;)
      • *
    • All combinations of multiple, mixed, and nested encoding/escaping (%253c or ┦gt;)
    *

    * Using canonicalize is simple. The default is just... @@ -395,25 +413,69 @@ public interface Encoder { /** * Encode input for use in a SQL query, according to the selected codec - * (appropriate codecs include the MySQLCodec and OracleCodec). - * - * This method is not recommended. The use of the {@code PreparedStatement} - * interface is the preferred approach. However, if for some reason - * this is impossible, then this method is provided as a weaker - * alternative. - * - * The best approach is to make sure any single-quotes are double-quoted. - * Another possible approach is to use the {escape} syntax described in the - * JDBC specification in section 1.5.6. - * + * (appropriate codecs include the {@link org.owasp.esapi.codecs.MySQLCodec} + * and {@link org.owasp.esapi.codecs.OracleCodec}), but see + * "SECURITY WARNING" below before using. + *

    + * The this method attempts to ensure make sure any single-quotes are double-quoted + * (i.e., as '', not double-quotes, as in "). Another possible approach + * is to use the {escape} syntax described in the JDBC specification in section 1.5.6. * However, this syntax does not work with all drivers, and requires * modification of all queries. - * + *

    + * SECURITY WARNING: This method is NOT recommended. The use of the {@code PreparedStatement} + * interface is the preferred approach. However, if for some reason + * this is impossible, then this method is provided as significantly weaker + * alternative. In particular, it should be noted that if all you do to + * address potential SQL Injection attacks is to use this method to escape + * parameters, you will fail miserably. According to the + * + * OWASP SQL Injection Prevention Cheat Sheet, these are the primary + * defenses against SQL Injection (as of June 2025): + *

      + *
    • Option 1: Use of Prepared Statements (with Parameterized Queries)
      • + *
    • Option 2: Use of Properly Constructed Stored Procedures
      • + *
    • Option 3: Allow-list Input Validation
      • + *
    • Option 4: STRONGLY DISCOURAGED: Escaping All User Supplied Input
      • + *
    + *

    + * According to "Option 4" (which is what this method implements), that OWASP Cheat Sheet + * states: + *

    + * In this approach, the developer will escape all user input + * before putting it in a query. It is very database specific + * in its implementation. This methodology is frail compared + * to other defenses, and we CANNOT guarantee that this option + * will prevent all SQL injections in all situations. + *
    + * (Emphasis ours.) + *

    + * Note you could give yourself a slightly better chance at success if prior to + * escaping by this method, you first canonicalize the input and run it through + * some strong allow-list validation. We will not provide anymore details than + * that, lest we encourage its misuse; however, it should be noted that resorting + * to use this method--especially by itself--should rarely, if ever, used. It + * is intended as a last ditch, emergency, Hail Mary effort. (To be honest, you'd + * likely have more success setting up a WAF such as + * OWASP ModSecurity and + * OWASP CRS + * if you need a temporary emergency SQLi defense shield, but using {@code PreparedStatement} + * is still your best option if you have the time and resources. + *

    + * Note to AppSec / Security Auditor teams: If see this method being used in + * application code, the risk of an exploitable SQLi vulnerability is still high. We + * stress the importance of the first two Options discussed in the + * + * OWASP SQL Injection Prevention Cheat Sheet. If you allow this, we recommend only + * doing so for a limited time duration and in the meantime creating some sort of security + * exception ticket to track it. + *

    * @see JDBC Specification * @see java.sql.PreparedStatement * * @param codec - * a Codec that declares which database 'input' is being encoded for (ie. MySQL, Oracle, etc.) + * a {@link org.owasp.esapi.codecs.Codec} that declares which database 'input' is being encoded for (ie. MySQL, Oracle, etc.) * @param input * the text to encode for SQL * @@ -526,7 +588,7 @@ public interface Encoder { * For more information, refer to this * article which specifies the following list of characters as the most - * dangerous: ^&"*';<>(). ( ) . This * paper suggests disallowing ' and " in queries. * diff --git a/src/main/java/org/owasp/esapi/codecs/Codec.java b/src/main/java/org/owasp/esapi/codecs/Codec.java index 52c49c1e2..80eb914ca 100644 --- a/src/main/java/org/owasp/esapi/codecs/Codec.java +++ b/src/main/java/org/owasp/esapi/codecs/Codec.java @@ -22,6 +22,17 @@ * and canonicalization. The design of these codecs allows for character-by-character decoding, which is * necessary to detect double-encoding and the use of multiple encoding schemes, both of which are techniques * used by attackers to bypass validation and bury encoded attacks in data. + *

    + * Other than the interfaces, very few of these concrete classes are intended to be used directly. + * Rather, most of them are used through implementations of the {@link org.owasp.esapi.Encoder} + * interface. While the OWASP team over the years have made every effort to be extra cautious, the + * various {@code Codec} implemtations can offer NO GUARANTEE of safety if the client is + * using these {@code Codec} classes directly. Therefore, if the client is using + * these classes directly, it is highly advised to practice security-in-depth + * and also perform canonicalization, followed by strict input valiation, both + * prior to encoding and after decoding, to protect your application from input-based + * attacks. + *

    * * @author Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security @@ -30,6 +41,7 @@ * @author Matt Seil (mseil .at. owasp.org) * @since June 1, 2017 * @see org.owasp.esapi.Encoder + * @see org.owasp.esapi.Validator */ public interface Codec { /** diff --git a/src/main/java/org/owasp/esapi/codecs/DB2Codec.java b/src/main/java/org/owasp/esapi/codecs/DB2Codec.java index 8df61bc34..979d35ae1 100644 --- a/src/main/java/org/owasp/esapi/codecs/DB2Codec.java +++ b/src/main/java/org/owasp/esapi/codecs/DB2Codec.java @@ -14,7 +14,14 @@ /** - * Implementation of the Codec interface for DB2 strings. This function will only protect you from SQLi in limited situations. + * Implementation of the Codec interface for IBM Db2 strings. + * This function will only protect you from SQLi in limited situations. + * To improve your changces of success, you made also need to do some + * additional canonicalization and input validation first. Before using this class, + * pleaes 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 find + * a silver bullet to kill all the SQLi werewolves. * * @author Sivasankar Tanakala (stanakal@TRS.NYC.NY.US) * @since October 26, 2010 @@ -65,4 +72,4 @@ public Character decodeCharacter(PushbackString input) { return (Character.valueOf('\'')); } -} \ No newline at end of file +} diff --git a/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java b/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java index c507b0362..a1938ef24 100644 --- a/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java +++ b/src/main/java/org/owasp/esapi/codecs/MySQLCodec.java @@ -19,9 +19,16 @@ /** * Codec implementation which can be used to escape string literals in MySQL. - *
    - * Implementation accepts 2 Modes as identified by the OWASP Recommended - * escaping strategies: + * This function will only protect you from SQLi in limited situations. + * To improve your changces of success, you made also need to do some + * additional canonicalization and input validation first. Before using this class, + * pleaes 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 find + * a silver bullet to kill all the SQLi werewolves. + *

    + * This implementation accepts 2 {@code org.owasp.esapi.codes.MySQLCodec.Mode}s as identified + * by the OWASP recommended escaping strategies: *