2.5.3.1 preparation

documentation/esapi4java-core-2.5.3.1-release-notes.txt

@@ -0,0 +1,184 @@
+Release notes for ESAPI 2.5.3.1
+    Release date: 2023-12-01
+    Project leaders:
+        -Kevin W. Wall <[email protected]>
+        -Matt Seil <[email protected]>
+
+Previous release: ESAPI 2.5.3.0, 2023-11-24
+
+
+Executive Summary: Important Things to Note for this Release
+------------------------------------------------------------
+* Rewrite the Javadoc for Validator.isValidSafeHTML to make the dangers more evident.\
+* Changes to the DefaultValidator.isValidSafeHTM method so that a warning is always logs one time about the method being deprecated and a reference to the relevant GitHub Security Advisory.
+
+Notes if you are not updating from the immediate previous release. release 2.5.3.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.5.3.0 release:
+     207 Java source files
+    4293 JUnit tests in 131 Java source files (0 failures, 0 errors, 0 tests skipped)
+
+ESAPI 2.5.3.1 release: (unchanged)
+     207 Java source files
+    4293 JUnit tests in 131 Java source files (0 failures, 0 errors, 0 tests skipped)
+
+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%3D2023-11-24)
+
+Issue #         GitHub Issue Title
+----------------------------------------------------------------------------------------------
+794             canonicalize sees entity which isn't there (wontfix)
+
+-----------------------------------------------------------------------------
+
+        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.
+
+-----------------------------------------------------------------------------
+
+        Other changes in this release, some of which not tracked via GitHub issues
+
+-----------------------------------------------------------------------------
+
+* Minor updates to README.md file with respect to version information.
+
+-----------------------------------------------------------------------------
+
+Developer Activity Report (Changes between release 2.5.3.0 and 2.5.3.1, i.e., between 2023-11-24 and 2023-12-01)
+Generated manually (this time) -- all errors are the fault of kwwall and his inability to do simple arithmetic.
+
+Developer       Total       Total Number        # Merged
+(GitHub ID)     commits   of Files Changed        PRs
+========================================================
+kwwall           13             16              2
+========================================================
+                                    Total PRs:  2
+
+-----------------------------------------------------------------------------
+
+CHANGELOG:      Create your own. May I suggest:
+
+        git log --stat --since=2023-11-24 --reverse --pretty=medium
+
+    which will show all the commits since just after the previous (2.5.3.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.6.1:tree (default-cli) @ esapi ---
+        [INFO] org.owasp.esapi:esapi:jar:2.5.3.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.9.4: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.4:compile
+        [INFO] +- org.apache-extras.beanshell:bsh:jar:2.0b6:compile
+        [INFO] +- org.owasp.antisamy:antisamy:jar:1.7.4:compile
+        [INFO] |  +- org.htmlunit:neko-htmlunit:jar:3.6.0:compile
+        [INFO] |  +- org.apache.httpcomponents.client5:httpclient5:jar:5.2.1:compile
+        [INFO] |  |  \- org.apache.httpcomponents.core5:httpcore5-h2:jar:5.2:compile
+        [INFO] |  +- org.apache.httpcomponents.core5:httpcore5:jar:5.2.3:compile
+        [INFO] |  +- org.apache.xmlgraphics:batik-css:jar:1.17:compile
+        [INFO] |  |  +- org.apache.xmlgraphics:batik-shared-resources:jar:1.17:compile
+        [INFO] |  |  +- org.apache.xmlgraphics:batik-util:jar:1.17:compile
+        [INFO] |  |  |  +- org.apache.xmlgraphics:batik-constants:jar:1.17:compile
+        [INFO] |  |  |  \- org.apache.xmlgraphics:batik-i18n:jar:1.17:compile
+        [INFO] |  |  \- org.apache.xmlgraphics:xmlgraphics-commons:jar:2.9: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.6:compile
+        [INFO] +- xml-apis:xml-apis:jar:1.4.01:compile
+        [INFO] +- commons-io:commons-io:jar:2.14.0:compile
+        [INFO] +- com.github.spotbugs:spotbugs-annotations:jar:4.8.1:compile
+        [INFO] |  \- com.google.code.findbugs:jsr305:jar:3.0.2:compile
+        [INFO] +- commons-codec:commons-codec:jar:1.15:test
+        [INFO] +- junit:junit:jar:4.13.2:test
+        [INFO] +- org.bouncycastle:bcprov-jdk15on:jar:1.70: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
+        ...
+
+        -----------------------------------------------------------------------------
+
+Acknowledgments:
+    Another hat tip to Dave Wichers for suggesting logging a warning via the deprecated isValidSafeHTML method.
+    And, as always, 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)

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.owasp.esapi</groupId>
     <artifactId>esapi</artifactId>
-    <version>2.5.4.0-SNAPSHOT</version>
+    <version>2.5.3.1-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <distributionManagement>
@@ -141,7 +141,7 @@
             <!-- TODO: Be sure to update. Should be date of previous official release -->
             <!-- Exact date in the form 'yyyy-dd-yy 00:00:00' should be used. You can find the previous release date -->
             <!-- in the previous release notes file under the 'documentation/' directory. -->
-        <date.prev_release>2023-04-12 00:00:00</date.prev_release>
+        <date.prev_release>2023-11-24 00:00:00</date.prev_release>
     </properties>
 
     <dependencies>

scripts/vars.2.5.3.0

@@ -8,7 +8,7 @@ VERSION=2.5.3.0
 PREV_VERSION=2.5.2.0
 
 # Release date of current version in yyyy-mm-dd format
-YYYY_MM_DD_RELEASE_DATE=2023-11-22
+YYYY_MM_DD_RELEASE_DATE=2023-11-24
 
 # Previous ESAPI release date in same format
 PREV_RELEASE_DATE=2023-04-12

scripts/vars.2.5.3.1

@@ -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.5.3.1
+
+# Previous ESAPI version
+PREV_VERSION=2.5.3.0
+
+# Release date of current version in yyyy-mm-dd format
+YYYY_MM_DD_RELEASE_DATE=2023-12-01
+
+# Previous ESAPI release date in same format
+PREV_RELEASE_DATE=2023-11-24

src/main/java/org/owasp/esapi/ValidationRule.java

@@ -20,10 +20,14 @@ public interface ValidationRule {
      *            the value to be parsed
      * @return a validated value
      * @throws ValidationException
-     *             if any validation rules fail, <i>except</i> if the
+     *             Thrown if any validation rules fail, <i>except</i> when the
      *             <b>{@code ESAPI.properties}></b> property
-     *             "Validator.ValidationRule.getValid.ignore509Fix" is set to
-     *             {@code true}, which is the default behavior for ESAPI 2.x
+     *             "Validator.HtmlValidationAction" is set to
+     *             {@code clean}. The default <b>{@code ESAPI.properties}></b> property file
+     *             has "Validator.HtmlValidationAction" is set to {@code throw}, which results
+     *             in a {@code ValidationException} being thrown if any of the validation rules
+     *             fail.
+     *             
      *             releases. See ESAPI GitHub Issues
      *             <a href="https://github.com/ESAPI/esapi-java-legacy/issues/509}>509</a>
      *             and <a href="https://github.com/ESAPI/esapi-java-legacy/issues/521">521</a>