esapi-2.7.0.0

[kwwall]

Full Release Notes

Release notes for ESAPI release 2.7.00 are located at:

• https://github.com/ESAPI/esapi-java-legacy/blob/develop/documentation/esapi4java-core-2.7.0.0-release-notes.txt

What's Changed

• This is a major patch release with the primary intent of addressing CVE-2025-5878, the details of which are spelled out in Security Bulletin #13.
  • Major Javadoc enhancements, corrections, and clarifications.
  • Deprecated methods, interfaces, and classes.
  • The reference implementation for the Encoder.encodeForSQL interface is now disabled by default and must be explicitly enabled if you absolutely much use it. (WARNING: You shouldn't!) Instructions on how to enable it are provided in Appendix B of Security Bulletin #13. You will find the updated ESAPI.properties file in the configuration jar helpful.

• This release 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.

Full Changelog: esapi-2.6.2.0...esapi-2.7.0.0

Configuration Jar

Note the associated file "esapi-2.7.0.0-configuration.jar" contains the default ESAPI configuration files under 'configuration/' (ESAPI.properties, validation.properties, etc.) and the file "esapi-2.7.0.0-configuration.jar.asc" is a GPG signature of that jar file made by Kevin W. Wall. If you were using ESAPI's Encoder.encodeForSQL interface, you will want to use its updated ESAPI.properties file.

---

This discussion was created from the release esapi-2.7.0.0.

[kwwall]

Related: Discussion #890.

[kwwall]

ESAPI 2.7.0.0 now showing up in https://search.maven.org/search?q=ESAPI.
VulDB CNA team wrote that "We intend to sync and disclose the CVE in the next 48 hours" and that was written at 3:27AM EDT on 2025-06-28, so it should be soon.

[kwwall]

Important Update

My bad. I forgot to correct the joke that I originally perpetrated on my colleagues doing a code review(to see if they were paying attention). Instead, it backfired when I accidentally ended up using the phony property name. Apparently, I had only remembered to correct the first new property, but not the second new one in configuration/esapi/ESAPI.properties.

To see what I am referring to, see commit ID #a035387. It's actually mostly harmless as it would have the justification reason always be logged as "Justification: none". So I had to update the attached configuration jar, esapi-2.7.0.0-configuration.jar, and the detached GPG signature file, esapi-2.7.0.0-configuration.jar.asc.

I apologize for the inconvenience, but as I explained to my ESAPI developer colleagues, I did NOT do this intentionally. (Did I find it amusing? Sure. But, would I have intentionally cause the ESAPI user community to do addition work? To that I would answer a resounding 'NO'!

Anyway, the bottom line is, if you have already downloaded the 2.7.0.0 configuration jar, you either need to download it again or manually fix it as per the referenced commit ID above.

[madediosg]

@kwwall do you plan to perform further actions with respect https://nvd.nist.gov/vuln/detail/CVE-2025-5078?
In 2.7.0.0 it is disabled by default, and warned if enabled.
Do you plan in coming releases any additional actions like offering a secure implementation of the same method, or new secure methods?

Thanks in advance.

[xeno6696]

The answer to that question is NO because of all of the options suggested in OWASP's guideline to prevent SQLi, this is literally the worst option and it should be discouraged. We debated on offering a fix for the codec, but because escaping is so terrible, error prone, and problematic, "fixing" it would simply invite someone to come up with the next filter evasion character to continue the cat-and-mouse game that should be fixed by deleting the method from the library entirely. This will be open community debate, as of the current release we have deprecated the method. I'm of two minds about this. I feel it's fair to offer dangerous methods as a last resort, but doing that simultaneously allows good actors to misuse a dangerous method and assume it offers more protection than it actually does.

To understand why escaping is bad, you almost have to take a course in compiler implementation to fully appreciate why. A layman's answer is that escaping output correctly would require you to use a parser that was guaranteed 1:1 functionality with the target compiler. The problem, is this compiler is updated with every release of every JDBC driver, which isn't maintainable, we don't have the people for that, and if you go back to 2007-08 when this library started there are hundreds of JDBC versions that have to be tested. FWIW, allowing the backslash escape character didn't exist back then and this was added later, and because we're not an ORM we have no need to do unit testing with actual JDBC drivers. (Not that it isn't desirable, but think about how much work that would be.) At any rate, offering our own compiler is too far especially when PreparedStatements literally give you access to the real thing. (And there is research to also demonstrate that prepared statements can be bypassed too, but that's beyond the current scope of conversation.)

The way the method was originally designed, it is SUPPOSED to be used in concert with say, the SafeString validation call from the Validator interface, which would have caught and blocked the original attack submitted by the researcher. (actual regex to be determined by the programmer) However, the documentation of this was unclear and only existed in the heads of the experienced programmers who have been using this library (like myself) for well over a decade. The information is there--even the OWASP SQLi prevention cheat sheet details that escaping needs to be paired with input validation, but as you're well aware, not everyone reads all the docs all the time.

The use of this method as the sole defense against SQLi is an improper use of the library, and it is THAT use case specifically that is attacked by CVE-2025-5078. Our own testing concluded that the example attack submitted by the researcher is blocked by the SafeString validation call. If you follow that fix, and use the library properly, you are not vulnerable to THAT attack.

[kwwall]

@madediosg - To add to what @xeno6696 stated, I think if you read through ESAPI Security Bulletin 13, especially the "Lessons Learned" section, you will better understand why we made this decision. I don't think this is a battle that we can win as there is just too much of an opportunity for error here.

For instance, if it is true, as the referenced Oracle document seems to imply (we haven't tested it), some developer could conceivably write a SQL statement using the 'ESCAPE' keyword and dynamically change the Oracle DB escape character for that specific SQL statement and then use Encoder.encodeForSQL and expect that to protect them. But how would ESAPI ever know that was the case? (Sure, we could extend the Encoder interface to add additional encodeForSQL methods, but that interface is already too bloated for my taste. Yes; we already discussed that as a option and rejected it.) It just seemed like we'd not be able to ensure that the Encoder.encodeForSQL implementation would ever work in every context with the same level of confidence that ESAPI users have with the rest of the Encoder methods. And I am not sure that any amount of documentation (at least that developers would likely to read) would be able to change that situation. (NOTE: An unwritten design goal of ESAPI is that you shouldn't need to be an AppSec engineer to be able to use ESAPI correctly.)

So, either we leave it disabled by default (as it is now) and allow developers to shoot themselves in the foot, or we delete it completely. However, I am strongly against intentionally "breaking developer's code" by changing ESAPI unless there is some pressing vulnerability that can't be addressed any other way. In this case, I felt that the action of deleting the Encoder.encodeForSQL interface without prior warning might risk developers abandoning ESAPI altogether. We may still delete it, but not at least before waiting for a year to allow it's legitimate use to be debated. In fact, to me, unless the ESAPI user community convinces us otherwise, that's our default course of action after a year. (To be honest, had I been involved with ESAPI back when Encoder.encodeForSQL was first introduced, I would have fought hard against adding it as an interface in the first place.)

So, for all of you in the ESAPI community: if you have what you think are some legitimate use cases that you are aware of for Encoder.encodeForSQL, please share them here. Or, at least email Matt and I and discuss them. Because, if the only response we've have heard after 1 year has been the sound of crickets, we will be deleting those deprecated methods after a years' time.

[f-delahaye]

First of all, thanks @kwwall and @xeno6696 for your amazing work!

I 100% agree that prepared statement should be used whenever possible, however, I do have a couple of cases where I rely on OracleCodec, and I'm considering forking it should it be removed in a future release.
However, I would like to understand what exactly is the risk highlighted in the security bulletin.

dynamically change the Oracle DB escape character for that specific SQL statement

I'm no oracle expert but I believe the 'ESCAPE' keyword works at a different level. It is only relevant as an escape character for wildcards (i.e., _ and %) withinlike clauses and not as a general escape character for the whole statement. So, it's not really a risk, as far as I understand (happy to be proven wrong, though).

What worries me more is this (from the security bulletin):

the current Oracle JDBC Driver that was used in the proof-of-concept, now allows “\” (i.e., backslash) as an escape character.

Never heard about this before, do you have any more details? Any link?
Just to be sure, we're talking about some jdbc driver stuff, possibly oracle specific, right?
I did find some documentation about an escape jdbc keyword, but again only relevant for like clauses.

Sorry, I don’t mean to nitpick, just trying to understand the best course of action.

Hope you will find some time to shed some light on this.

Many thanks in advance.

[kwwall]

If you haven't already done so, I would refer you to the security researcher's discovery that did this. That write up is at "https://github.com/uglory-gll/javasec/blob/main/ESAPI.md" and is mentioned a few times in the write up for ESAPI Security Bulletin 13. It uses neither the 'ESCAPE' nor 'LIKE' keywords. There were several other security people besides Matt and myself (see the "Acknowledgements" section in the security bulletin) that seemed to reach the same conclusion that the the '\' (backslash) character is ultimately what caused this issue. I am not an Oracle expert either, which is why I sought the advice of other trusted security colleagues. The magic SQLi attack payload was this:

“1\’ andif(1=1,sleep(5),1)--”

That backslash allowed the single quote to sneak past the OracleCodec. Some of the folks identified in the Acknowledgements section (don't recall specifically who and there may have been multiple people) concluded that the JDBC driver was not treating the backslash also as a default escape character. I don't think we found anything on definitive in terms of documentation of that, but if you find any, please point us to it. You asked:

Just to be sure, we're talking about some jdbc driver stuff, possibly oracle specific, right?

I don't recall seeing in @uglory-gll's write-up what specific version of JDBC driver was used. I suspect it was an Oracle specific driver and this feature may have been around for a while. (@planetlevel said he did do dynamic testing when OracleCodec was originally written, but that was a very long time ago.) Since I do not have Oracle DB license and it is non-trivial to setup / configure Oracle DB, I did not try to replicate the dynamic testing. I know that @xeno6696 considered dynamic testing, but I think he got swamped with other things. I did a bit of searching for this unexpected (at least to Matt and I) behavior with \' as demonstrated in this code, but much of this was simply trusting @uglort-gll and others we worked with. Plus we were trying to work through a 30 day patch deadline while both myself and my wife were having severe health problems, so it is possible that we may have missed some things.

You wrote:

I did find some documentation about an escape jdbc keyword, but again only relevant for like clauses.

Also, the documentation about the ESCAPE keyword that I found on the web and did reference is a bit vague. It's possible that Oracle has better documentation on their website that is only available only to licensed Oracle DB customers, so if you can point us to something more specific that supports your belief that it is only relevant to LIKE clauses, please provide some evidence. If I have some evidence, I will gladly update the security bulletin to capture that and to explain that. I don't have an Oracle DB license and I separate my $dayjob from all my ESAPI work so I'm not willing to pursue that avenue. But since you seem to already have found that, please make it available if you are not restrained by Oracle licenses or other legal obligations as we certainly are in favor of clarity here.

All that said, I consider myself a pragmatic person. If there are a lot of others who were using this, I personally would be fine to leave it as deprecated and like it is, but reconsider not removing it, at least not immediately. It's just easier for us to remove it because we can't possibly keep up with things like changes to Oracle JDBC drivers, etc. that could potentially cause future code. So removing dubious code like this simplifies our ongoing maintenance and prevents fire drills like this. But at least it is now disabled by default, so perhaps that is good enough.

[uglory-gll]

Hello, thank you for your reply. I have tried using a MySQL database here. When you execute directly in the database, \ is treated as an escape character, and two 's also indicate escaped 's. However, our MyBatis's $ precompilation and PreparedStatement both convert one ' into two ' and one \ into two \\ at the underlying level before substituting them into the database. This ensures that SQL injection issues do not persist after precompilation. You should be executing directly in the database, right? After precompilation in the code, will "1\’ and if(1=1,sleep(5),1)--" still work? I'm not sure if I have understood you correctly 随风飘雪 ***@***.*** 原始邮件 发件人：Kevin W. Wall ***@***.***> 发件时间：2026年1月11日 03:08 收件人：ESAPI/esapi-java-legacy ***@***.***> 抄送：uglory ***@***.***>, Mention ***@***.***> 主题：Re: [ESAPI/esapi-java-legacy] esapi-2.7.0.0 (Discussion #889) If you haven't already done so, I would refer you to the security researcher's discovery that did this. That write up is at "https://github.com/uglory-gll/javasec/blob/main/ESAPI.md" and is mentioned a few times in the write up for ESAPI Security Bulletin 13. It uses neither the 'ESCAPE' nor 'LIKE' keywords. There were several other security people besides Matt and myself (see the "Acknowledgements" section in the security bulletin) that seemed to reach the same conclusion that the the '\' (backslash) character is ultimately what caused this issue. I am not an Oracle expert either, which is why I sought the advice of other trusted security colleagues. The magic SQLi attack payload was this: “1\’ and if(1=1,sleep(5),1)--” That backslash allowed the single quote to sneak past the OracleCodec. Some of the folks identified in the Acknowledgements section (don't recall specifically who and there may have been multiple people) concluded that the JDBC driver was not treating the backslash also as a default escape character. I don't think we found anything on definitive in terms of documentation of that, but if you find any, please point us to it. You asked: Just to be sure, we're talking about some jdbc driver stuff, possibly oracle specific, right? I don't recall seeing in @uglory-gll's write-up what specific version of JDBC driver was used. I suspect it was an Oracle specific driver and this feature may have been around for a while. ***@***.*** said he did do dynamic testing when OracleCodec was originally written, but that was a very long time ago.) Since I do not have Oracle DB license and it is non-trivial to setup / configure Oracle DB, I did not try to replicate the dynamic testing. I know that @xeno6696 considered dynamic testing, but I think he got swamped with other things. I did a bit of searching for this unexpected (at least to Matt and I) behavior with \' as demonstrated in this code, but much of this was simply trusting @uglort-gll and others we worked with. Plus we were trying to work through a 30 day patch deadline while both myself and my wife were having severe health problems, so it is possible that we may have missed some things. You wrote: I did find some documentation about an escape jdbc keyword, but again only relevant for like clauses. Also, the documentation about the ESCAPE keyword that I found on the web and did reference is a bit vague. It's possible that Oracle has better documentation on their website that is only available only to licensed Oracle DB customers, so if you can point us to something more specific that supports your belief that it is only relevant to LIKE clauses, please provide some evidence. If I have some evidence, I will gladly update the security bulletin to capture that and to explain that. I don't have an Oracle DB license and I separate my $dayjob from all my ESAPI work so I'm not willing to pursue that avenue. But since you seem to already have found that, please make it available if you are not restrained by Oracle licenses or other legal obligations as we certainly are in favor of clarity here. All that said, I consider myself a pragmatic person. If there are a lot of others who were using this, I personally would be fine to leave it as deprecated and like it is, but reconsider not removing it, at least not immediately. It's just easier for us to remove it because we can't possibly keep up with things like changes to Oracle JDBC drivers, etc. that could potentially cause future code. So removing dubious code like this simplifies our ongoing maintenance and prevents fire drills like this. But at least it is now disabled by default, so perhaps that is good enough. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[kwwall]

@uglory-gll - Thanks for that information, but the main reason I @-mentioned you to @f-delahaye was so that you could answer the what specific JDBC driver (vendor and version) you used with your testing of the OracleCodec as noted in your write-up at https://github.com/uglory-gll/javasec/ESAPI.md (which, IIRC, did not mention the specific JDBC driver). That may be important for anyone who wishes to reproduce your work. Thanks.

[uglory-gll]

Hello, thank you for your reply. I am using this project https://github.com/whgojp/JavaSecLab/blob/main/pom.xml 随风飘雪 ***@***.*** 原始邮件 发件人：Kevin W. Wall ***@***.***> 发件时间：2026年1月11日 12:53 收件人：ESAPI/esapi-java-legacy ***@***.***> 抄送：uglory ***@***.***>, Mention ***@***.***> 主题：Re: [ESAPI/esapi-java-legacy] esapi-2.7.0.0 (Discussion #889) @uglory-gll - Thanks for that information, but the main reason I @-mentioned you to @f-delahaye was so that you could answer the what specific JDBC driver (vendor and version) you used with your testing of the OracleCodec as noted in your write-up at https://github.com/uglory-gll/javasec/ESAPI.md (which, IIRC, did not mention the specific JDBC driver). That may be important for anyone who wishes to reproduce your work. Thanks. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[f-delahaye]

Many thanks @uglory-gll and @kwwall for your valuable insights!

I re-read the initial write-up and noticed that the OracleCodec was in fact used against a MySQL DB (and a MySQL jdbc driver) as shown in https://github.com/uglory-gll/javasec/blob/main/assets/image-20250604204352340.png (Class.forName("com.mysql.cj.jdbc.Driver").
Sorry if this was already mentioned somewhere.
This is backed up by @uglory-gll 's answer that the code was tested against MySQL, and by the query itself (if and sleep, as far as I know, are not Oracle functions).

So what about OracleCodec against an Oracle database?
I don't know. JavaSecLab only supports mysql so I could not use it to test.

Documentation-wise, I went by this
Double quote is the default escaping mechanism. Backslash is mentioned nowhere.

To represent one single quotation mark within a literal, enter two single quotation marks.

There is an alternative approach which I didn't know existed ( bottom branch of the syntax), but it would require different java code (something like `select * from sqli where id = q‘!" + ESAPI.encoder().encodeForSQL(oracleCodec, id)+ "!'") so I think it should be safe.

However, I do have access to an Oracle database instance.
Given the following table:
select * from TEST_USER

username
user1
manager's account

And driver ojdbc17,

The following tests all pass:

	@Test
void oracleEscaping() throws SQLException {
assertEquals(1, getCountFor("user1"));
assertEquals(1, getCountFor("manager''s account"));
assertEquals(ORA_00933, assertThrows(SQLException.class, () -> getCountFor("manager's account")).getErrorCode());
assertEquals(ORA_00933, assertThrows(SQLException.class, () -> getCountFor("manager\\'s account")).getErrorCode());
assertEquals(0, getCountFor("manager\\''s account"));
}
@Test
void unsafeSQL() throws SQLException {
assertEquals(2, getCountFor("1' OR 1=1 --"));
assertEquals(2, getCountFor("1\\' OR 1=1 --"));
assertEquals(ORA_01756, assertThrows(SQLException.class, () -> getCountFor("1' OR 1=1")).getErrorCode());
}
@Test
void encodedSQL() throws SQLException {
assertEquals(1, getCountFor(esapiEncode("manager's account")));
assertEquals(0, getCountFor(esapiEncode("manager\\'s account")));
assertEquals(0, getCountFor(esapiEncode("manager\\''s account")));
assertEquals(0, getCountFor(esapiEncode("1' OR 1=1 --")));
assertEquals(0, getCountFor(esapiEncode("1\\' OR 1=1 --")));
assertEquals(0, getCountFor(esapiEncode("1' OR 1=1")));
}
private String createSQL(String username) {
return "SELECT count(*) FROM TEST_USER WHERE username = '" + username + "'";
}
private int getCountFor(String username) throws SQLException {
ResultSet rs = connection.createStatement().executeQuery(createSQL(username));
rs.next();
return rs.getInt(1);
}
private String esapiEncode(String username) {
return ESAPI.encoder().encodeForSQL(new OracleCodec(), username);
}

getCountFor("manager\\'s account") (double \ to escape the second one, so the driver sees "manager\'s account") is not equivalent to getCountFor("manager''s account") and in fact is not a valid syntax.
When encoded with ESAPI. the syntax is valid but the query returns 0 result. Again, different behaviour to "manager''s account".

For the sake of completeness (?), I added a few tests that try to replicate the initial write-up, using OR 1=1 as a replacement for sleep().
In case of SQL Injections, the query should return the 2 results in the database. That never happens with encodeForSQL.

Bottom line:

• IMHO, the only misleading thing in the security bulletin is :

"\ is the default escape character for Oracle Database

• OracleEncoder against MySQL is not safe.
• As far as I am concerned, I'm feeling more and more comfortable using OracleEncoder as we use it only against an Oracle database, and I haven't (yet) found any evidence (either in the initial write-up or in the doc or in my tests) that it was not safe. BUT, I completely understand that you want to remove it for simplicity's sake.

Hope this helps.
I will do some more testing to make sure I didn't miss anything important.

Thanks again for your help.