ESAPI for Java legacy: the 2.x branch you can still deploy

What the legacy branch means for the 2.x line

OWASP ESAPI is a library of security controls that aims to make it easier to write lower-risk web applications, and the project describes it as a foundation for new development as well as a way to retrofit security into existing applications. The legacy repository holds the 2.x branch.

The project is explicit about the arrangement. Legacy means the branch is actively maintained, but significant new feature development will not happen there. Features already scheduled for the 2.x branch move forward. Development for the next generation, starting with ESAPI 3.0, happens in the separate ESAPI/esapi-java repository.

That second point deserves attention. The project says work on ESAPI 3 has not begun in earnest and is in its earliest planning stages, and that even the code presently there will likely change. So the split is not yet a migration story with a destination. For now, legacy is where the released, supported artifact lives, and 3.x is a place to watch.

The default branch is develop rather than main, where future development and bug fixes happen. main is marked as protected and reflects the latest stable release. The project warns that this switch of default branch may affect pull requests you had been intending to make, which is the kind of detail that catches out automated tooling.

The javax and jakarta split runs through your pom.xml

ESAPI has supported the Jakarta Servlet API since release 2.5.3.0, which means the library ought to work with Spring Boot 3, Spring 6, Tomcat 10 and other applications built on Jakarta EE. The project asks users to file an issue if they find a case where it does not.

The choice between the two APIs happens at dependency resolution time through a Maven classifier. Adding the jakarta classifier pulls the Jakarta flavoured jar:

<dependency>
    <groupId>org.owasp.esapi</groupId>
    <artifactId>esapi</artifactId>
    <version>2.7.0.0</version>  <!-- Preferably the latest version, but > 2.5.3.0 -->
    <classifier>jakarta</classifier>
</dependency>

Leave the classifier out and you get the older javax.servlet build instead, which the project still supports. In other words, the same coordinates serve two runtimes, and the difference between a Jakarta deployment that starts and one that fails on a missing javax class sits in four characters of your build file.

The library version must be later than 2.5.3.0 for the Jakarta jar to exist, and a long GitHub Discussion records the approaches that were tried before this landed.

Java 8 is the baseline and the javax era is the constraint

The minimum JDK is Java 8. That baseline was raised from Java 7 during the 2.4.0.0 release, and 2.3.0.0 is the last release to run on Java 7.

The more consequential constraint for many teams is the servlet namespace. The Jakarta classifier exists to serve applications on the newer namespace, but ESAPI 3 is where the long term direction sits, and it is not ready. A team that wants to be on Jakarta EE, wants a maintained 2.x API surface, and cannot wait years is exactly the audience for this repository.

Logging is the other migration scar. Support for Log4J 1 was dropped during the 2.5.0.0 release, and the project directs anyone who still needs it to configure it through SLF4J. The 2.5.0.0 release notes hold the details.

One more change is easy to miss until your application refuses to start. Starting with 2.5.4.0, if you were using the default JUL logger through the ESAPI.Logger property set to org.owasp.esapi.logging.java.JavaLogFactory, you must remove or rename the old esapi-java-logger.properties configuration file. Leaving it in place causes ESAPI to throw a ConfigurationException and the application fails to start.

The release notes carry the real upgrade instructions

The project makes no attempt to compress the upgrade notes into the README. Release notes live in the documentation directory and are named esapi4java-core-*2.#.#.#*-release-notes.txt, following semantic versioning, and the GitHub Releases page links to each one.

The project warns readers to treat several sections as mandatory reading. From 2.2.1.0, the details of how the ESAPI Logger is read changed, and the project says that if you hit ClassNotFoundException you probably have not read that section. From 2.2.3.0, ESAPI uses a version of AntiSamy that by default includes slf4j-simple and performs XML schema validation on the AntiSamy policy files, which can affect an existing configuration.

The pattern across these notes is worth noticing for anyone planning an upgrade: the breaking changes are mostly about configuration files and logger wiring rather than API signatures. They fail at startup, which is better than failing silently, but it means a version bump is a configuration exercise.

Vulnerability history is tracked separately in a Vulnerability Summary document that collects the ESAPI Security Bulletins and GitHub Security Advisories. The project notes it is too lengthy for the README and is mostly irrelevant if you are on the latest available version.

Where the legacy branch is the wrong choice

The clearest case against this repository is a greenfield project that can wait. If you can start on ESAPI 3.x, or on a stack that does not need ESAPI at all, taking on the 2.x API surface means taking on a migration later. The project is frank that 3.x code will likely change, but the same is true of the 2.x surface in a longer time frame, and legacy is where you will not get new features.

A second case is a team that wants new capabilities. Legacy is maintained for bug fixes and for features already scheduled for the 2.x branch, so anything genuinely new has to come from the other repository.

A third case is operational appetite. The 2.x line carries breaking changes that arrive through configuration files across several releases in a row. An organization that cannot absorb a startup failure during a routine dependency bump has to plan for it rather than discover it.

The licence is worth reading too. The repository license is a custom one that GitHub cannot classify, and the tree contains LICENSE, LICENSE-CONTENT and LICENSE-README files. Whether that suits your organisation's policy is a question for your legal reviewers, not something the repository answers for you.

Picking a version and a branch on purpose

The published releases show how the line has moved. Version 2.7.0.0 was published on 2025-06-28, 2.6.2.0 on 2025-06-03 and 2.6.1.0 on 2025-05-19, so the 2.x branch has kept producing versioned releases in 2025. The last push to the repository was on 2026-09-18, which means the branch is receiving changes beyond those release tags.

Note the difference between the branch and the artifact. The project states that main reflects the latest stable ESAPI release, which it identifies as 2.5.3.1 as of the time of writing, while develop carries future development and bug fixes. The 2.7.0.0 dependency shown earlier therefore comes from a line further along than that stable reference, so which branch you build from and which version you declare in the pom are two separate decisions.

For a team starting now, the practical shape of adoption is: pick a 2.x version at or above 2.5.3.0, add the jakarta classifier only if you are on Jakarta EE, read the release notes for every version between your current one and your target, and check whether the fix you need has landed on develop rather than in a tagged release.

Editorial conclusion

Adopt esapi-java-legacy when your application still targets javax.servlet, or when you need the 2.x API surface and cannot wait for the 3.x repository to mature. Do not start new work on it expecting new features, since the branch is closed to significant feature development and ESAPI 3 is still in early planning. Before upgrading, read the release notes for the version you move to, because the 2.2.1.0 logger change, the 2.2.3.0 AntiSamy change and the 2.5.4.0 configuration file removal each break existing setups in a different way.

Frequently asked questions

Official sources

1. ESAPI/esapi-java-legacy on GitHub
2. Issues
3. Project website
4. README
5. Releases