diff --git a/README.md b/README.md index b0928bacb..0c31f1de1 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.0.0 + 2.7.0.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.0.0. +The [latest ESAPI release](https://github.com/ESAPI/esapi-java-legacy/releases/latest) is 2.7.0.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..c551662fc 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.7.0.0 (latest) | :white_check_mark: | +| 2.1.0.1-2.6.2.0 | :x:, upgrade to latest release | | <= 1.4.x | :x:, no longer supported AT ALL | ## Reporting a Vulnerability diff --git a/Vulnerability-Summary.md b/Vulnerability-Summary.md index 7c6f3b0c9..e7eacb6d0 100644 --- a/Vulnerability-Summary.md +++ b/Vulnerability-Summary.md @@ -26,6 +26,5 @@ was provided in the description of the CVE. |[10](https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin10.pdf)|There is an RCE flaw caused by an insecure deserialization vulnerability in Apache Chainsaw, a Java-based GUI log viewer. CVE-2020-9493 identified a deserialization issue that was present in Apache Chainsaw 2.x prior to 2.1.0. However, prior to Chainsaw V2.0, Chainsaw was a component of Apache Log4j 1.2.x where the same issue exists and remains unfixed.|[CWE-502](https://cwe.mitre.org/data/definitions/502.html)|[CVE-2022-23307](https://nvd.nist.gov/vuln/detail/CVE-2022-23307)|Remote Code Execution is possible if you are running Apache Chainsaw 1.x from the Apache Log4J 1.2.x jar.|None. ESAPI uses ConsoleAppender as the default appender even if ESAPI logging is configured to use Log4J 1.| |[GHSA-8m5h-hrqm-pxm2](https://github.com/ESAPI/esapi-java-legacy/security/advisories/GHSA-8m5h-hrqm-pxm2)|The default implementation of `Validator.getValidDirectoryPath(String, String, File, boolean)` may incorrectly treat the tested input string as a child of the specified parent directory. This potentially could allow control-flow bypass checks to be defeated if an attack can specify the entire string representing the 'input' path.|[CWE-22](https://cwe.mitre.org/data/definitions/22.html)|[CVE-2022-23457](https://nvd.nist.gov/vuln/detail/CVE-2022-23457)|Control-flow bypass may be possible.|ESAPI 2.x, prior to the ESAPI 2.3.0.0 release. Version 2.3.0.0 and later are patched.| |[11](https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin11.pdf)|There is a DoS vulerablity in the FileUploadBase class of Apache Commons FileUpload for releases prior to 1.5. That DoS vulnerability is caused by not limiting the number of files that could be uploaded per single request.|[CWE-770](https://cwe.mitre.org/data/definitions/770.html)|[CVE-2023-24998](https://nvd.nist.gov/vuln/detail/CVE-2023-24998)|None. ESAPI uses a subclass of the affected FileUpladBase abstract class from Apache Commons FileUpload to which a new setFileCountMax() method was added.|Addressed in ESAPI 2.5.2.0 and later.| -|[GHSA-r68h-jhhj-9jvm](https://github.com/ESAPI/esapi-java-legacy/security/advisories/GHSA-r68h-jhhj-9jvm)|Decribes why ESAPI's Validator.isValidSafeHTML is being deprecated and will be removed one year after the ESAPI 2.5.3.0 release date.|[CWE-80](https://cwe.mitre.org/data/definitions/80.html)|N/A (no CVE)|XSS may be possible depending on how the method is used.|All ESAPI versions (all 1.x and 2.x versions). No patch is available until the methods are deleted one year after the ESAPI 2.5.3.0 release date.| - - +|[12](https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin12.pdf)
[GHSA-r68h-jhhj-9jvm](https://github.com/ESAPI/esapi-java-legacy/security/advisories/GHSA-r68h-jhhj-9jvm)|Decribes why ESAPI's Validator.isValidSafeHTML is being deprecated and will be removed one year after the ESAPI 2.5.3.0 release date.|[CWE-80](https://cwe.mitre.org/data/definitions/80.html)|N/A (no CVE)|XSS may be possible depending on how the method is used.|All ESAPI versions (all 1.x and 2.x versions). No patch is available until the methods are deleted one year after the ESAPI 2.5.3.0 release date.| +|[13](https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin13.pdf)|There is a bypass around ESAPI's Encoder.encodeForSQL interface (a method that always carried a strong warning) that be result in SQL injection vulnerabilities in code that use it.|[CWE-138](https://cwe.mitre.org/data/definitions/138.html)|[CVE-2025-5878](https://www.cve.org/CVERecord?id=CVE-2025-5878)|May leave applications that use Encoder.encodeForSQL vulnerable to SQL injection.|ESAPI 2.x versions before 2.7.0| diff --git a/configuration/esapi/ESAPI.properties b/configuration/esapi/ESAPI.properties index b5b6aacc6..2df6e7804 100644 --- a/configuration/esapi/ESAPI.properties +++ b/configuration/esapi/ESAPI.properties @@ -556,3 +556,30 @@ Validator.HtmlValidationAction=throw # This is the default behaviour of ESAPI. # #Validator.HtmlValidationConfigurationFile=antisamy-esapi.xml + +######################################################################################## +# 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; will correspond to deprecation notice] +# +# Mote details to explain this may be found in the ESAPI GitHub wiki article at +# https://github.com/ESAPI/esapi-java-legacy/wiki/Reducing-the-ESAPI-Library's-Attack-Surface +########### +# The format is a comma-separated list of fully.Qualified.ClassName.methodName; +# all class names must begin with "org.owasp.esapi.". +ESAPI.dangerouslyAllowUnsafeMethods.methodNames= +########### +# 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.dangerouslyAllowUnsafeMethods.justification= diff --git a/documentation/ESAPI-release-steps.odt b/documentation/ESAPI-release-steps.odt index 22fbd8f23..848b88dae 100644 Binary files a/documentation/ESAPI-release-steps.odt and b/documentation/ESAPI-release-steps.odt differ diff --git a/documentation/ESAPI-release-steps.pdf b/documentation/ESAPI-release-steps.pdf index db43ee14f..ea6970f89 100644 Binary files a/documentation/ESAPI-release-steps.pdf and b/documentation/ESAPI-release-steps.pdf differ diff --git a/documentation/ESAPI-security-bulletin13.odt b/documentation/ESAPI-security-bulletin13.odt new file mode 100644 index 000000000..ee9cb8ef8 Binary files /dev/null and b/documentation/ESAPI-security-bulletin13.odt differ diff --git a/documentation/ESAPI-security-bulletin13.pdf b/documentation/ESAPI-security-bulletin13.pdf new file mode 100644 index 000000000..8d272b042 Binary files /dev/null and b/documentation/ESAPI-security-bulletin13.pdf differ diff --git a/documentation/esapi4java-core-2.6.1.0-release-notes.txt b/documentation/esapi4java-core-2.6.1.0-release-notes.txt index 7f3c0a88b..e81f3bda0 100644 --- a/documentation/esapi4java-core-2.6.1.0-release-notes.txt +++ b/documentation/esapi4java-core-2.6.1.0-release-notes.txt @@ -1,5 +1,5 @@ Release notes for ESAPI 2.6.1.0 - Release date: 2025-05-18 + Release date: 2025-05-19 Project leaders: -Kevin W. Wall -Matt Seil @@ -93,7 +93,7 @@ None known, other than the remaining open issues on GitHub. ----------------------------------------------------------------------------- -* Changes since last release 2.6.0.0 and 2.6.1.0, i.e., changes between 2025-11-25 and 2025-05-18. +* Changes since last release 2.6.0.0 and 2.6.1.0, i.e., changes between 2025-11-25 and 2025-05-19. Note: I am no longer going to provide the 'Developer Activity Report' that I used to this manually create in tabluar form. This is in part because I use to use 'mvn site' to assist with its creation, but neither the 'Developer Activiity' nor 'File Activity' sections of the 'mvn site' output is currently working. diff --git a/documentation/esapi4java-core-2.6.2.0-release-notes.txt b/documentation/esapi4java-core-2.6.2.0-release-notes.txt new file mode 100644 index 000000000..a909feea2 --- /dev/null +++ b/documentation/esapi4java-core-2.6.2.0-release-notes.txt @@ -0,0 +1,180 @@ +Release notes for ESAPI 2.6.2.0 + Release date: 2025-06-02 + Project leaders: + -Kevin W. Wall + -Matt Seil + +Previous release: ESAPI 2.6.1.0, 2025-05-19 + + +Executive Summary: Important Things to Note for this Release +------------------------------------------------------------ +This is a minor patch release with the intent of updating the Apache Commons BeanUtils dependency from v1.9.4 to v1.11.0 to CVE-2025-48734. This CVE wouuld only potentially affect application code that uses the ESAPI's AccessController component. It is extremently unlikely that anyone is using that because the default implmentation for that (the class "org.owasp.esapi.reference.DefaultAccessController") is really a toy implementation that doesn't scale to enterprise levels with out some customization. (The class "org.owasp.esapi.filters.ESAPIFilter" also uses "DefaultAccessController", but it is unlikely that anyone is using that either, unless they are using a customized AccessController implementation.) We plan to deprecate this ESAPI "DefaultAccessControler" shortly in a future release. + +Notes if you are not updating from the immediate previous release. release 2.6.1.0: + * You need to read through the series of release notes FIRST, going in order. + * For example, if you were updating from an older ESAPI release (say, 2.3.0.0), you should go back and FIRST read all the subsequent release notes in turn. For instance, if you are currently on release 2.3.0.0 and upgrading to (say) release 2.x.y.z, you should MINIMALLY read the sections "Changes Requiring Special Attention" in each of the subsequent release notes. So, going from release 2.3.0.0 to 2.x.y.z, you should in turn, read: + + esapi4java-core-2.4.0.0-release-notes.txt + esapi4java-core-2.5.0.0-release-notes.txt + esapi4java-core-2.5.1.0-release-notes.txt + esapi4java-core-2.5.2.0-release-notes.txt + ...etc., up through the current set of release notes... + esapi4java-core-2.x.y.z-release-notes.txt + +in that order. YOU HAVE BEEN WARNED!!! (These release notes are too large to put all this in a given document; very few read them thoroughly as it is.) + +If your SCA tool is reporting any CVE from a direct or transitive dependency in ESAPI, before reporting it as an GitHub issue, please make sure that you review the vulnerability analysis written up in https://github.com/ESAPI/esapi-java-legacy/blob/develop/Vulnerability-Summary.md. Please email us or contact us in our GitHub Discussions page if you have questions about this. See also the SECURITY.md file to report any security issues with ESAPI. + +You are encouraged to review the vulnerability analysis written up in https://github.com/ESAPI/esapi-java-legacy/blob/develop/Vulnerability-Summary.md and email us or contact us in our GitHub Discussions page if you have questions. + + +================================================================================================================= + +Basic ESAPI facts +----------------- + +ESAPI 2.6.1.0 release: + 207 Java source files + 4312 JUnit tests in 133 Java source files + +ESAPI 2.6.2.0 release: + 207 Java source files + 4312 JUnit tests in 133 Java source files + +1 GitHub Issue closed in this release, including those we've decided not to fix (marked 'wontfix' and 'falsepositive'). +(Reference: https://github.com/ESAPI/esapi-java-legacy/issues?q=is%3Aissue+state%3Aclosed+updated%3A%3E%3D2025-05-19) + +Issue # GitHub Issue Title +---------------------------------------------------------------------------------------------- +883 Update Apache Commons BeanUtils from 1.9.4 to 1.11.0 to address CVE-2025-48734 + +----------------------------------------------------------------------------- + + Changes Requiring Special Attention + +----------------------------------------------------------------------------- +Important JDK Support Announcement +* ESAPI 2.3.0.0 was the last Java release to support Java 7. ESAPI 2.4.0 requires using Java 8 or later. See the ESAPI 2.4.0.0 release notes (https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.4.0.0-release-notes.txt) for details as to the reason. + - This means if your project requires Java 7, you must use ESAPI 2.3.0.0 or earlier. + +Important ESAPI Logging Changes + +* Since ESAPI 2.5.0.0, support for logging directly via Log4J 1 has been removed. (This was two years after it haveing first been deprecated.) Thus, you only choice of ESAPI logging are + - java.util.logging (JUL), which as been the default since ESAPI 2.2.1.0. + * Set ESAPI.Logger=org.owasp.esapi.logging.java.JavaLogFactory in your ESAPI.properties file. + - SLF4J (which your choice of supported SLF4J logging implemmentation) + * Set ESAPI.Logger=org.owasp.esapi.logging.slf4j.Slf4JLogFactory in your ESAPI.properties file. +* Logger configuration notes - If you are migrating from prior to ESAPI 2.2.1.1, you will need to update your ESAPI.properties file as logging-related configuration as per the ESAPI 2.2.1.1 release notes, which may be found at: + https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.2.1.1-release-notes.txt#L39-L78 + +If you use ESAPI 2.5.0.0 or later, you will get an ClassNotFoundException as the root cause if you still have your ESAPI.Logger property set to use Log4J because the org.owasp.esapi.logger.log4j.Log4JFactory class has been completely removed from the ESAPI jar. If you are dead set on continuing to use Log4J 1, you ought to be able to do so via SLF4J. The set up for Log4J 1 (which has not be tested), should be similar to configure ESAPI to use SLF4J with Log4J 2 as described here: + https://github.com/ESAPI/esapi-java-legacy/wiki/Using-ESAPI-with-SLF4J#slf4j-using-log4j-2x + +----------------------------------------------------------------------------- + + Remaining Known Issues / Problems + +----------------------------------------------------------------------------- +None known, other than the remaining open issues on GitHub and that 'mvn site' fails to properly build some pieces as the ESAPI tag library Javadoc. I suspect this is related to problems with one or more of the Maven plugins. + +----------------------------------------------------------------------------- + + Other changes in this release, some of which not tracked via GitHub issues + +----------------------------------------------------------------------------- + +* Changes since last release 2.6.1.0 and 2.6.2.0, i.e., changes between 2025-05-19 and 2025-06-02). + + Note: I am no longer going to provide the 'Developer Activity Report' that I used to this manually create in tabluar form. This is in part because I use to use 'mvn site' to assist with its creation, but neither the 'Developer Activiity' nor 'File Activity' sections of the 'mvn site' output is currently working. + + That said, I don't care as this was always a major PITA and I think it had dubious value to start with. + + Therefore, I am replacing it to a stock GitHub tag comparison of the current and previous release, which I can automate. + + Please see, + + https://github.com/ESAPI/esapi-java-legacy/compare/esapi-...esapi-2.6.2.0 + + for details. It contains all the information that the previous 'Developer Activity Reports' did and then some. + +----------------------------------------------------------------------------- + +CHANGELOG: Create your own. May I suggest: + + git log --stat --since=2025-05-19 --reverse --pretty=medium + + which will show all the commits since just after the previous (2.6.1.0) release. + + Alternately, you can download the most recent ESAPI source and run + + mvn site + + which will create a CHANGELOG file named 'target/site/changelog.html' + + +----------------------------------------------------------------------------- + +Direct and Transitive Runtime and Test Dependencies: + + $ mvn -B dependency:tree + ... + [INFO] --- maven-dependency-plugin:3.8.1:tree (default-cli) @ esapi --- + [INFO] org.owasp.esapi:esapi:jar:2.6.1.0 + [INFO] +- javax.servlet:javax.servlet-api:jar:3.1.0:provided + [INFO] +- javax.servlet.jsp:javax.servlet.jsp-api:jar:2.3.3:provided + [INFO] +- xom:xom:jar:1.3.9:compile + [INFO] +- commons-beanutils:commons-beanutils:jar:1.11.0:compile + [INFO] | +- commons-logging:commons-logging:jar:1.2:compile + [INFO] | \- commons-collections:commons-collections:jar:3.2.2:compile + [INFO] +- commons-configuration:commons-configuration:jar:1.10:compile + [INFO] +- commons-lang:commons-lang:jar:2.6:compile + [INFO] +- commons-fileupload:commons-fileupload:jar:1.5:compile + [INFO] +- org.apache.commons:commons-collections4:jar:4.5.0-M2:compile + [INFO] +- org.apache-extras.beanshell:bsh:jar:2.0b6:compile + [INFO] +- org.owasp.antisamy:antisamy:jar:1.7.8:compile + [INFO] | +- commons-io:commons-io:jar:2.19.0:compile + [INFO] | +- org.apache.httpcomponents.client5:httpclient5:jar:5.4.4:compile + [INFO] | | \- org.apache.httpcomponents.core5:httpcore5-h2:jar:5.3.4:compile + [INFO] | +- org.apache.httpcomponents.core5:httpcore5:jar:5.3.4:compile + [INFO] | +- org.apache.xmlgraphics:batik-css:jar:1.19:compile + [INFO] | | +- org.apache.xmlgraphics:batik-shared-resources:jar:1.19:compile + [INFO] | | +- org.apache.xmlgraphics:batik-util:jar:1.19:compile + [INFO] | | | +- org.apache.xmlgraphics:batik-constants:jar:1.19:compile + [INFO] | | | \- org.apache.xmlgraphics:batik-i18n:jar:1.19:compile + [INFO] | | \- org.apache.xmlgraphics:xmlgraphics-commons:jar:2.11:compile + [INFO] | +- org.htmlunit:neko-htmlunit:jar:4.11.0:compile + [INFO] | +- xerces:xercesImpl:jar:2.12.2:compile + [INFO] | \- xml-apis:xml-apis-ext:jar:1.3.04:compile + [INFO] +- org.slf4j:slf4j-api:jar:2.0.16:compile + [INFO] +- xml-apis:xml-apis:jar:1.4.01:compile + [INFO] +- com.github.spotbugs:spotbugs-annotations:jar:4.9.3:compile (optional) + [INFO] | \- com.google.code.findbugs:jsr305:jar:3.0.2:compile (optional) + [INFO] +- commons-codec:commons-codec:jar:1.17.1:test + [INFO] +- junit:junit:jar:4.13.2:test + [INFO] +- org.bouncycastle:bcprov-jdk18on:jar:1.78.1:test + [INFO] +- org.hamcrest:hamcrest-core:jar:2.2:test + [INFO] | \- org.hamcrest:hamcrest:jar:2.2:test + [INFO] +- org.powermock:powermock-api-mockito2:jar:2.0.9:test + [INFO] | \- org.powermock:powermock-api-support:jar:2.0.9:test + [INFO] +- org.mockito:mockito-core:jar:3.12.4:test + [INFO] | +- net.bytebuddy:byte-buddy:jar:1.11.13:test + [INFO] | +- net.bytebuddy:byte-buddy-agent:jar:1.11.13:test + [INFO] | \- org.objenesis:objenesis:jar:3.2:test + [INFO] +- org.powermock:powermock-core:jar:2.0.9:test + [INFO] | \- org.javassist:javassist:jar:3.27.0-GA:test + [INFO] +- org.powermock:powermock-module-junit4:jar:2.0.9:test + [INFO] | \- org.powermock:powermock-module-junit4-common:jar:2.0.9:test + [INFO] +- org.powermock:powermock-reflect:jar:2.0.9:test + [INFO] \- org.openjdk.jmh:jmh-core:jar:1.37:test + [INFO] +- net.sf.jopt-simple:jopt-simple:jar:5.0.4:test + [INFO] \- org.apache.commons:commons-math3:jar:3.6.1:test + [INFO] ------------------------------------------------------------------------ +----------------------------------------------------------------------------- + +Acknowledgments: + Thanks to GitHub Advanced Security's Dependabot SCA tool for flagging and fixing this one. And thanks to Matt Seil, Jeremiah Stacey, and all the ESAPI users who make this worthwhile. This is for you. + +A special thanks to the ESAPI community from the ESAPI project co-leaders: + Kevin W. Wall (kwwall) <== The irresponsible party for these release notes! + Matt Seil (xeno6696) diff --git a/documentation/esapi4java-core-2.7.0.0-release-notes.txt b/documentation/esapi4java-core-2.7.0.0-release-notes.txt new file mode 100644 index 000000000..f88656067 --- /dev/null +++ b/documentation/esapi4java-core-2.7.0.0-release-notes.txt @@ -0,0 +1,194 @@ +Release notes for ESAPI 2.7.0.0 + Release date: 2025-06-27 + Project leaders: + -Kevin W. Wall + -Matt Seil + +Previous release: ESAPI 2.6.2.0, 2025-06-02 + + +Executive Summary: Important Things to Note for this Release +------------------------------------------------------------ +This is a major patch release with the primary intent of addressing CVE-2025-5878. See https://nvd.nist.gov/vuln/detail/CVE-2025-5078 and especially Security Bulletin #13 (https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin13.pdf) for details. It also updates Apache Commons FileUploads to 1.6.0 to address CVE-2025-48976. That CVE likely does not affect the HTTP.getFileUloads interfaces (which is the only methods that use that library), but we have not had time to analyze it fully given the CVE cited against ESAPI. Apache Commons BeanUtils was also updated to 1.11.0 to address CVE-2025-48734 which potentially could anyone using ESAPI's AccessController and has placed their access control policy in a place where an attacker may be overwrite it. That is highly unlikely, but better safe than sorry. + +This 2.7.0.0 release also has significant Javadoc clarifications. Security Bulletin #13 explains why. + +If you fail to read Security Bulletin #13 and you are affected by CVE-2025-5878, your application using ESAPI 2.7.0.0 will not work, so it is VERY IMPORTANT that you read that. + +Notes if you are NOT updating from the immediate previous release. release 2.6.2.0: + * You need to read through the series of release notes FIRST, going in order. + * For example, if you were updating from an older ESAPI release (say, 2.3.0.0), you should go back and FIRST read all the subsequent release notes in turn. For instance, if you are currently on release 2.3.0.0 and upgrading to (say) release 2.x.y.z, you should MINIMALLY read the sections "Changes Requiring Special Attention" in each of the subsequent release notes. So, going from release 2.3.0.0 to 2.x.y.z, you should in turn, read: + + esapi4java-core-2.4.0.0-release-notes.txt + esapi4java-core-2.5.0.0-release-notes.txt + esapi4java-core-2.5.1.0-release-notes.txt + esapi4java-core-2.5.2.0-release-notes.txt + ...etc., up through the current set of release notes... + esapi4java-core-2.x.y.z-release-notes.txt + +in that order. YOU HAVE BEEN WARNED!!! (These release notes are too large to put all this in a given document; very few read them thoroughly as it is.) + +If your SCA tool is reporting any CVE from a direct or transitive dependency in ESAPI, before reporting it as an GitHub issue, please make sure that you review the vulnerability analysis written up in https://github.com/ESAPI/esapi-java-legacy/blob/develop/Vulnerability-Summary.md. Please email us or contact us in our GitHub Discussions page if you have questions about this. See also the SECURITY.md file to report any security issues with ESAPI. + +You are encouraged to review the vulnerability analysis written up in https://github.com/ESAPI/esapi-java-legacy/blob/develop/Vulnerability-Summary.md and email us or contact us in our GitHub Discussions page if you have questions. + + +================================================================================================================= + +Basic ESAPI facts +----------------- + +ESAPI 2.6.2.0 release: + 207 Java source files + 4312 JUnit tests in 133 Java source files + +ESAPI 2.7.0.0 release: + 208 Java source files + 4312 JUnit tests in 134 Java source files + +1 GitHub Issues closed in this release, including those we've decided not to fix (marked 'wontfix' and 'falsepositive'). +(Reference: https://github.com/ESAPI/esapi-java-legacy/issues?q=is%3Aissue+state%3Aclosed+updated%3A%3E%3D2025-06-02) + +Issue # GitHub Issue Title +---------------------------------------------------------------------------------------------- +883 Update Apache Commons BeanUtils from 1.9.4 to 1.11.0 to address CVE-2025-48734 + +----------------------------------------------------------------------------- + + Changes Requiring Special Attention + +----------------------------------------------------------------------------- + +IMPORTANT: Read Security Bulletin #13 (https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/ESAPI-security-bulletin13.pdf) + +Important JDK Support Announcement +* ESAPI 2.3.0.0 was the last Java release to support Java 7. ESAPI 2.4.0 requires using Java 8 or later. See the ESAPI 2.4.0.0 release notes (https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.4.0.0-release-notes.txt) for details as to the reason. + - This means if your project requires Java 7, you must use ESAPI 2.3.0.0 or earlier. + +Important ESAPI Logging Changes + +* Since ESAPI 2.5.0.0, support for logging directly via Log4J 1 has been removed. (This was two years after it having first been deprecated.) Thus, you only choice of ESAPI logging are + - java.util.logging (JUL), which as been the default since ESAPI 2.2.1.0. + * Set ESAPI.Logger=org.owasp.esapi.logging.java.JavaLogFactory in your ESAPI.properties file. + - SLF4J (which your choice of supported SLF4J logging implementation) + * Set ESAPI.Logger=org.owasp.esapi.logging.slf4j.Slf4JLogFactory in your ESAPI.properties file. +* Logger configuration notes - If you are migrating from prior to ESAPI 2.2.1.1, you will need to update your ESAPI.properties file as logging-related configuration as per the ESAPI 2.2.1.1 release notes, which may be found at: + https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.2.1.1-release-notes.txt#L39-L78 + +If you use ESAPI 2.5.0.0 or later, you will get an ClassNotFoundException as the root cause if you still have your ESAPI.Logger property set to use Log4J because the org.owasp.esapi.logger.log4j.Log4JFactory class has been completely removed from the ESAPI jar. If you are dead set on continuing to use Log4J 1, you ought to be able to do so via SLF4J. The set up for Log4J 1 (which has not be tested), should be similar to configure ESAPI to use SLF4J with Log4J 2 as described here: + https://github.com/ESAPI/esapi-java-legacy/wiki/Using-ESAPI-with-SLF4J#slf4j-using-log4j-2x + +----------------------------------------------------------------------------- + + Remaining Known Issues / Problems + +----------------------------------------------------------------------------- +None known, other than the remaining open issues on GitHub. + +----------------------------------------------------------------------------- + + Other changes in this release, some of which not tracked via GitHub issues + +----------------------------------------------------------------------------- + +* Changes since last release 2.6.2.0 and 2.7.0.0, i.e., changes between 2025-06-02 and 2025-06-27). + + Note: I am no longer going to provide the 'Developer Activity Report' that I used to this manually create in tabular form. This is in part because I use to use 'mvn site' to assist with its creation, but neither the 'Developer Activity' nor 'File Activity' sections of the 'mvn site' output is currently working. + + That said, I don't care as this was always a major PITA and I think it had dubious value to start with. + + Therefore, I am replacing it to a stock GitHub tag comparison of the current and previous release, which I can automate. + + Please see, + + https://github.com/ESAPI/esapi-java-legacy/compare/esapi-...esapi-2.7.0.0 + + for details. It contains all the information that the previous 'Developer Activity Reports' did and then some. + +----------------------------------------------------------------------------- + +CHANGELOG: Create your own. May I suggest: + + git log --stat --since=2025-06-02 --reverse --pretty=medium + + which will show all the commits since just after the previous (2.6.2.0) release. + + Alternately, you can download the most recent ESAPI source and run + + mvn site + + which will create a CHANGELOG file named 'target/site/changelog.html' + + +----------------------------------------------------------------------------- + +Direct and Transitive Runtime and Test Dependencies: + + $ mvn -B dependency:tree + ... + [INFO] --- maven-dependency-plugin:3.8.1:tree (default-cli) @ esapi --- + [INFO] org.owasp.esapi:esapi:jar:2.7.0.0-SNAPSHOT + [INFO] +- javax.servlet:javax.servlet-api:jar:3.1.0:provided + [INFO] +- javax.servlet.jsp:javax.servlet.jsp-api:jar:2.3.3:provided + [INFO] +- xom:xom:jar:1.3.9:compile + [INFO] +- commons-beanutils:commons-beanutils:jar:1.11.0:compile + [INFO] | +- commons-logging:commons-logging:jar:1.3.5:compile + [INFO] | \- commons-collections:commons-collections:jar:3.2.2:compile + [INFO] +- commons-configuration:commons-configuration:jar:1.10:compile + [INFO] +- commons-lang:commons-lang:jar:2.6:compile + [INFO] +- commons-fileupload:commons-fileupload:jar:1.6.0:compile + [INFO] +- org.apache.commons:commons-collections4:jar:4.5.0-M2:compile + [INFO] +- org.apache-extras.beanshell:bsh:jar:2.0b6:compile + [INFO] +- org.owasp.antisamy:antisamy:jar:1.7.8:compile + [INFO] | +- commons-io:commons-io:jar:2.19.0:compile + [INFO] | +- org.apache.httpcomponents.client5:httpclient5:jar:5.4.4:compile + [INFO] | | \- org.apache.httpcomponents.core5:httpcore5-h2:jar:5.3.4:compile + [INFO] | +- org.apache.httpcomponents.core5:httpcore5:jar:5.3.4:compile + [INFO] | +- org.apache.xmlgraphics:batik-css:jar:1.19:compile + [INFO] | | +- org.apache.xmlgraphics:batik-shared-resources:jar:1.19:compile + [INFO] | | +- org.apache.xmlgraphics:batik-util:jar:1.19:compile + [INFO] | | | +- org.apache.xmlgraphics:batik-constants:jar:1.19:compile + [INFO] | | | \- org.apache.xmlgraphics:batik-i18n:jar:1.19:compile + [INFO] | | \- org.apache.xmlgraphics:xmlgraphics-commons:jar:2.11:compile + [INFO] | +- org.htmlunit:neko-htmlunit:jar:4.11.0:compile + [INFO] | +- xerces:xercesImpl:jar:2.12.2:compile + [INFO] | \- xml-apis:xml-apis-ext:jar:1.3.04:compile + [INFO] +- org.slf4j:slf4j-api:jar:2.0.16:compile + [INFO] +- xml-apis:xml-apis:jar:1.4.01:compile + [INFO] +- com.github.spotbugs:spotbugs-annotations:jar:4.9.3:compile (optional) + [INFO] | \- com.google.code.findbugs:jsr305:jar:3.0.2:compile (optional) + [INFO] +- commons-codec:commons-codec:jar:1.17.1:test + [INFO] +- junit:junit:jar:4.13.2:test + [INFO] +- org.bouncycastle:bcprov-jdk18on:jar:1.78.1:test + [INFO] +- org.hamcrest:hamcrest-core:jar:2.2:test + [INFO] | \- org.hamcrest:hamcrest:jar:2.2:test + [INFO] +- org.powermock:powermock-api-mockito2:jar:2.0.9:test + [INFO] | \- org.powermock:powermock-api-support:jar:2.0.9:test + [INFO] +- org.mockito:mockito-core:jar:3.12.4:test + [INFO] | +- net.bytebuddy:byte-buddy:jar:1.11.13:test + [INFO] | +- net.bytebuddy:byte-buddy-agent:jar:1.11.13:test + [INFO] | \- org.objenesis:objenesis:jar:3.2:test + [INFO] +- org.powermock:powermock-core:jar:2.0.9:test + [INFO] | \- org.javassist:javassist:jar:3.27.0-GA:test + [INFO] +- org.powermock:powermock-module-junit4:jar:2.0.9:test + [INFO] | \- org.powermock:powermock-module-junit4-common:jar:2.0.9:test + [INFO] +- org.powermock:powermock-reflect:jar:2.0.9:test + [INFO] \- org.openjdk.jmh:jmh-core:jar:1.37:test + [INFO] +- net.sf.jopt-simple:jopt-simple:jar:5.0.4:test + [INFO] \- org.apache.commons:commons-math3:jar:3.6.1:test + [INFO] ------------------------------------------------------------------------ + +----------------------------------------------------------------------------- + +Acknowledgments: + A whole bunch of folks to thank this time: + - Longlong Gong (uglory-gll) - The security researcher who discovered the vulnerability that became CVE-2025-5878. + Most people curse those who find CVEs in their software, but because of Longlong's work, we feel ESAPI is a better library and has a more secure future. (See the "Lessons Learned" section of Security Bulletin #13 for an explanation.) + - The VulDB CNA team. + - In no particular order, Jeff Williams, Matt Seil, Jeremiah Stacey, Erika von Kampen, Bill Sempf, and Ken Pyle, all who provided me with excellent feedback on the documentation and code changes and help me keep my sanity for the past 3 weeks. + - My wife for tolerating my long evenings for the past 3 weeks. I know I've been cranky and it's been stressful for us both, but thanks for being so understanding and supportive. + - And finally, thanks to all the ESAPI users who make this worthwhile. This is for you. + +A special thanks to the ESAPI community from the ESAPI project co-leaders: + Kevin W. Wall (kwwall) <== The irresponsible party for these release notes! + Matt Seil (xeno6696) diff --git a/pom.xml b/pom.xml index 5da4fd7e1..f0bc96e7b 100644 --- a/pom.xml +++ b/pom.xml @@ -3,7 +3,7 @@ 4.0.0 org.owasp.esapi esapi - 2.6.1.0 + 2.7.1.0-SNAPSHOT jar @@ -135,13 +135,13 @@ 2.0.0-M11 2.0.9 4.9.3 - 4.9.3.0 + 4.9.3.1 3.5.3 1.8 - 2024-11-25 00:00:00 + 2025-06-02 00:00:00 @@ -185,8 +185,8 @@ commons-beanutils commons-beanutils - - 1.9.4 + + 1.11.0 @@ -478,7 +478,7 @@ org.apache.maven.plugins maven-clean-plugin - 3.4.1 + 3.5.0 @@ -643,7 +643,7 @@ 3.11.2 8 - none + none @@ -664,7 +664,7 @@ org.apache.maven.plugins maven-pmd-plugin - 3.26.0 + 3.27.0 diff --git a/scripts/vars.2.6.1.0 b/scripts/vars.2.6.1.0 index fba98e28d..b067cb61f 100644 --- a/scripts/vars.2.6.1.0 +++ b/scripts/vars.2.6.1.0 @@ -8,7 +8,7 @@ VERSION=2.6.1.0 PREV_VERSION=2.6.0.0 # Release date of current version in yyyy-mm-dd format -YYYY_MM_DD_RELEASE_DATE=2025-05-18 +YYYY_MM_DD_RELEASE_DATE=2025-05-19 # Previous ESAPI release date in same format PREV_RELEASE_DATE=2024-11-25 diff --git a/scripts/vars.2.6.2.0 b/scripts/vars.2.6.2.0 new file mode 100644 index 000000000..244aeaf3b --- /dev/null +++ b/scripts/vars.2.6.2.0 @@ -0,0 +1,14 @@ +# Do NOT edit this file directly. It will be created by the new createVarsFile.sh script, +# which should be run prior to the newReleaseNotes.sh script. + +# ESAPI (new / current) version +VERSION=2.6.2.0 + +# Previous ESAPI version +PREV_VERSION=2.6.1.0 + +# Release date of current version in yyyy-mm-dd format +YYYY_MM_DD_RELEASE_DATE=2025-06-02 + +# Previous ESAPI release date in same format +PREV_RELEASE_DATE=2025-05-19 diff --git a/scripts/vars.2.7.0.0 b/scripts/vars.2.7.0.0 new file mode 100644 index 000000000..829c1663c --- /dev/null +++ b/scripts/vars.2.7.0.0 @@ -0,0 +1,14 @@ +# Do NOT edit this file directly. It will be created by the new createVarsFile.sh script, +# which should be run prior to the newReleaseNotes.sh script. + +# ESAPI (new / current) version +VERSION=2.7.0.0 + +# Previous ESAPI version +PREV_VERSION=2.6.2.0 + +# Release date of current version in yyyy-mm-dd format +YYYY_MM_DD_RELEASE_DATE=2025-06-27 + +# Previous ESAPI release date in same format +PREV_RELEASE_DATE=2025-06-02 diff --git a/src/main/java/org/owasp/esapi/ESAPI.java b/src/main/java/org/owasp/esapi/ESAPI.java index c42a21ff8..55e4d896d 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,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 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. + } + + + // 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 index ad4950dc9..409b27b24 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 advice, 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 directly, 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,31 +413,91 @@ 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 a 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. + *

    + * 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 + * 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" + * (wihch defaults to "org.owasp.esapi.reference.DefaultEncoder") in your "ESAPI.properties" file, + * to the ESAPI property "ESAPI.dangerouslyAllowUnsafeMethods.methodNames". See + * the Security Bulletin #13 document referenced below for additional details. + *

    * @see JDBC Specification * @see java.sql.PreparedStatement + * @see ESAPI Security Bulletin #13 * * @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 * * @return input encoded for use in SQL + * @see + * ESAPI Security Bulletin #13 + * @deprecated This method 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). @@ -526,7 +604,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/PropNames.java b/src/main/java/org/owasp/esapi/PropNames.java index ab30e47fa..8aa4179a9 100644 --- a/src/main/java/org/owasp/esapi/PropNames.java +++ b/src/main/java/org/owasp/esapi/PropNames.java @@ -87,6 +87,8 @@ public final class PropNames { public static final String ADDITIONAL_ALLOWED_CIPHER_MODES = "Encryptor.cipher_modes.additional_allowed"; public static final String KDF_PRF_ALG = "Encryptor.KDF.PRF"; public static final String PRINT_PROPERTIES_WHEN_LOADED = "ESAPI.printProperties"; + public static final String ACCEPTED_UNSAFE_METHOD_NAMES = "ESAPI.dangerouslyAllowUnsafeMethods.methodNames"; + public static final String ACCEPTED_UNSAFE_METHODS_JUSTIFICATION = "ESAPI.dangerouslyAllowUnsafeMethods.justification"; public static final String WORKING_DIRECTORY = "Executor.WorkingDirectory"; public static final String APPROVED_EXECUTABLES = "Executor.ApprovedExecutables"; @@ -129,7 +131,7 @@ public final class PropNames { public static final String DISCARD_LOGSPECIAL = "org.owasp.esapi.logSpecial.discard"; /* - * Implementation Keys + * Implementation Keys for the various major ESAPI components. */ public static final String LOG_IMPLEMENTATION = "ESAPI.Logger"; public static final String AUTHENTICATION_IMPLEMENTATION = "ESAPI.Authenticator"; diff --git a/src/main/java/org/owasp/esapi/codecs/Codec.java b/src/main/java/org/owasp/esapi/codecs/Codec.java index 52c49c1e2..b46de6d5d 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} implementations 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 validation, 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..61d1f70cd 100644 --- a/src/main/java/org/owasp/esapi/codecs/DB2Codec.java +++ b/src/main/java/org/owasp/esapi/codecs/DB2Codec.java @@ -14,12 +14,25 @@ /** - * 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 chances of success, you made also need to do some + * additional canonicalization and input validation first. Before using this class, + * 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. * * @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) { @@ -65,4 +78,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..bd2829521 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 chances of success, you made also need to do some + * additional canonicalization and input validation first. Before using this class, + * 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. + *

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

      *
    • ANSI
      * Simply encode all ' (single tick) characters with '' (two single ticks)
    • @@ -29,19 +36,19 @@ *
    • Standard * *
      - *   NUL (0x00) --> \0  [This is a zero, not the letter O]
      - *   BS  (0x08) --> \b
      - *   TAB (0x09) --> \t
      - *   LF  (0x0a) --> \n
      - *   CR  (0x0d) --> \r
      - *   SUB (0x1a) --> \Z
      - *   "   (0x22) --> \"
      - *   %   (0x25) --> \%
      - *   '   (0x27) --> \'
      - *   \   (0x5c) --> \\
      - *   _   (0x5f) --> \_
      + *   NUL (0x00) --> \0  [This is a zero, not the letter O]
      + *   BS  (0x08) --> \b
      + *   TAB (0x09) --> \t
      + *   LF  (0x0a) --> \n
      + *   CR  (0x0d) --> \r
      + *   SUB (0x1a) --> \Z
      + *   "   (0x22) --> \"
      + *   %   (0x25) --> \%
      + *   '   (0x27) --> \'
      + *   \   (0x5c) --> \\
      + *   _   (0x5f) --> \_
        *   
      - * all other non-alphanumeric characters with ASCII values less than 256 --> \c + * all other non-alphanumeric characters with ASCII values less than 256 --> \c * where 'c' is the original non-alphanumeric character. *
      * @@ -56,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 eb91a07ce..2746f9137 100644 --- a/src/main/java/org/owasp/esapi/codecs/OracleCodec.java +++ b/src/main/java/org/owasp/esapi/codecs/OracleCodec.java @@ -18,18 +18,46 @@ /** - * Implementation of the Codec interface for Oracle strings. This function will only protect you from SQLi in the case of user data - * bring placed within an Oracle quoted string such as: - * - * select * from table where user_name=' USERDATA '; - * - * @see how-to-escape-single-quotes-in-strings - * + * 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 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 + * {@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. + *

      + * 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 { @@ -87,4 +115,4 @@ public Character decodeCharacter( PushbackSequence input ) { return( Character.valueOf( '\'' ) ); } -} \ No newline at end of file +} 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..58a0cbc98 --- /dev/null +++ b/src/main/java/org/owasp/esapi/errors/NotConfiguredByDefaultException.java @@ -0,0 +1,34 @@ +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.dangerouslyAllowUnsafeMethods.methodNames" + * and "ESAPI.dangerouslyAllowUnsafeMethods.justification" in the + * ESAPI.properties file for additional details. + *

      + */ +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 == null || s.trim().isEmpty()) ? defaultMsg : s); + } + + public NotConfiguredByDefaultException(String s, Throwable cause) { + super( (s == null || s.trim().isEmpty()) ? defaultMsg : s, cause); + } + + public NotConfiguredByDefaultException(Throwable cause) { + super(defaultMsg, cause); + } +} diff --git a/src/main/java/org/owasp/esapi/logging/appender/ClientInfoSupplier.java b/src/main/java/org/owasp/esapi/logging/appender/ClientInfoSupplier.java index cfb8bea61..21d0955c8 100644 --- a/src/main/java/org/owasp/esapi/logging/appender/ClientInfoSupplier.java +++ b/src/main/java/org/owasp/esapi/logging/appender/ClientInfoSupplier.java @@ -15,8 +15,7 @@ package org.owasp.esapi.logging.appender; -// Uncomment and use once ESAPI supports Java 8 as the minimal baseline. -// import java.util.function.Supplier; +import java.util.function.Supplier; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpSession; @@ -28,7 +27,7 @@ * Supplier which can provide a String representing the client-side connection * information. */ -public class ClientInfoSupplier // implements Supplier +public class ClientInfoSupplier implements Supplier { /** Default Last Host string if the Authenticated user is null.*/ private static final String DEFAULT_LAST_HOST = "#UNKNOWN_HOST#"; diff --git a/src/main/java/org/owasp/esapi/logging/appender/EventTypeLogSupplier.java b/src/main/java/org/owasp/esapi/logging/appender/EventTypeLogSupplier.java index 93d3bd416..0788d558c 100644 --- a/src/main/java/org/owasp/esapi/logging/appender/EventTypeLogSupplier.java +++ b/src/main/java/org/owasp/esapi/logging/appender/EventTypeLogSupplier.java @@ -15,8 +15,7 @@ package org.owasp.esapi.logging.appender; -// Uncomment and use once ESAPI supports Java 8 as the minimal baseline. -// import java.util.function.Supplier; +import java.util.function.Supplier; import org.owasp.esapi.Logger; import org.owasp.esapi.Logger.EventType; @@ -26,7 +25,7 @@ * an EventType for logging * */ -public class EventTypeLogSupplier // implements Supplier +public class EventTypeLogSupplier implements Supplier { /** EventType reference to supply log representation of. */ private final EventType eventType; diff --git a/src/main/java/org/owasp/esapi/logging/appender/ServerInfoSupplier.java b/src/main/java/org/owasp/esapi/logging/appender/ServerInfoSupplier.java index 8d62a58f0..88cc786b8 100644 --- a/src/main/java/org/owasp/esapi/logging/appender/ServerInfoSupplier.java +++ b/src/main/java/org/owasp/esapi/logging/appender/ServerInfoSupplier.java @@ -15,8 +15,7 @@ package org.owasp.esapi.logging.appender; -// Uncomment and use once ESAPI supports Java 8 as the minimal baseline. -// import java.util.function.Supplier; +import java.util.function.Supplier; import javax.servlet.http.HttpServletRequest; @@ -26,7 +25,7 @@ * Supplier which can provide a String representing the server-side connection * information. */ -public class ServerInfoSupplier // implements Supplier +public class ServerInfoSupplier implements Supplier { /** Whether to log the server connection info. */ private boolean logServerIP = true; diff --git a/src/main/java/org/owasp/esapi/logging/appender/UserInfoSupplier.java b/src/main/java/org/owasp/esapi/logging/appender/UserInfoSupplier.java index 445be3dc2..bf5fd731c 100644 --- a/src/main/java/org/owasp/esapi/logging/appender/UserInfoSupplier.java +++ b/src/main/java/org/owasp/esapi/logging/appender/UserInfoSupplier.java @@ -15,8 +15,7 @@ package org.owasp.esapi.logging.appender; -// Uncomment and use once ESAPI supports Java 8 as the minimal baseline. -// import java.util.function.Supplier; +import java.util.function.Supplier; import org.owasp.esapi.ESAPI; import org.owasp.esapi.User; @@ -25,7 +24,7 @@ * Supplier which can provide a String representing the client-side connection * information. */ -public class UserInfoSupplier // implements Supplier +public class UserInfoSupplier implements Supplier { /** Default UserName string if the Authenticated user is null.*/ private static final String DEFAULT_USERNAME = "#ANONYMOUS#"; diff --git a/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java b/src/main/java/org/owasp/esapi/reference/DefaultEncoder.java index 348cb4a4d..2b87e0d34 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,80 @@ 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.SECURITY_FAILURE, auditMsg + " Provided justification: " + justification ); + } + return; + } + /** * {@inheritDoc} + * + * @deprecated This method 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 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-5878 and ESAPI Security Bulletin #13 for details" ); + if( input == null ) { return null; } 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. + *

        + *
      1. + * 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. + *

        + *
      2. + *
      3. + * 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 + *

      4. + *
      5. + * 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. - *

        + *

      6. + *
      7. + * The first ".esapi" or "esapi" directory on the classpath. (The former for backward compatibility.) + *
      8. + *
      + *

      + * 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 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..751a95d52 --- /dev/null +++ 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-test.properties b/src/test/resources/esapi/ESAPI-test.properties index 72dd9e50a..d46c2d34e 100644 --- a/src/test/resources/esapi/ESAPI-test.properties +++ b/src/test/resources/esapi/ESAPI-test.properties @@ -5,4 +5,4 @@ invalid_int_property=invalid int boolean_property=true boolean_yes_property=yes boolean_no_property=no -invalid_boolean_property=invalid boolean \ No newline at end of file +invalid_boolean_property=invalid boolean diff --git a/src/test/resources/esapi/ESAPI.properties b/src/test/resources/esapi/ESAPI.properties index 8ffc61f66..e10691d1f 100644 --- a/src/test/resources/esapi/ESAPI.properties +++ b/src/test/resources/esapi/ESAPI.properties @@ -578,3 +578,40 @@ 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.ClassName.methodName; +# all class names must begin with "org.owasp.esapi.". +# +# 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. +# +# We need this there for our existing JUnit tests for encodeForSQL. Use an +# alternate ESAPI property config filen name for testing this aspect out. +ESAPI.dangerouslyAllowUnsafeMethods.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.dangerouslyAllowUnsafeMethods.justification=blah,blah. Please don't fire my @$$. Ticket # 12345-not-the-winning-lotto#