Javadoc enhancements #886

kwwall · 2025-06-09T03:40:02Z

Work on fixing up some Javadoc and tweak test version of ESAPI.properties.

kwwall · 2025-06-09T03:48:53Z

@xeno6696 @jeremiahjstacey @sempf @hackermatic - The Javadoc is ready to review. No code changes to this PR.

jeremiahjstacey · 2025-06-09T09:07:33Z

src/test/resources/esapi/ESAPI.properties

+#                       which has 4 interfaces so currently, there's no way to
+#                       specify a specific one.
+#       
+ESAPI.enableLegCannonModeAndGetMyAssFired.methodNames=org.owasp.esapi.reference.DefaultEncoder.encodeForSQL


I agree with the intent, but we may want to adjust the property name before releasing to the public. I expect folks will be using this as a stop-gap to keep code from breaking as they're working through migration processes.

It caught your attention didn't it?

jeremiahjstacey · 2025-06-09T09:07:40Z

src/test/resources/esapi/ESAPI.properties

+# justification as to why you have enabled these functions. This can be
+# anythuing such as a Jira or ServiceNow ticket number, a security exception
+# reference, etc. If it is left empty, it will just like "Justification: none".`
+ESAPI.enableLegCannonModeAndGetMyAssFired.justification=blah,blah. Please don't fire my @$$. Ticket # 12345


I would prefer to not allow this feature for client-specific messages in library workflows.
We should have a message that is either attributed to an Exception or logged at a Warning level which states the feature that is bound for deprecation and the date which it will be removed (per deprecation policy).

Clients can track this however they want in their own environments.

EG:

encodeForSQL(Codec codec, String input) { String deprecationMsg="ESAPI.DEPRECATION-6//9/2026 ESAPI.encodeForSQL method use should be replaced with ....blah blah blah"; if ( ! deprecationsEnabled("encodeForSQL")) { throw new NotConfiguredByDefaultException(deprecationMsg); } else { log.warning(deprecationMsg); }

We will still have our own messages and this might not want to limit it to just things that we've deprecated. But the intent here is that many companies require approval of use of dangerous and/or deprecated methods and this would allow them to provide an identifying security exception ID that InfoSec could cross reference in audit logs. I would likely log it independently rather than make it part of the exception message (which you never know, may end up being displayed to the end user, which might have been your concern). But the ESAPI's safe logging should be able to handle whatever get's thrown at it, otherwise it's not really "safe".

Anyhow, that's the thought behind it. Mostly to help track in audit logging, which was @xeno6696's idea. I don;t think I can compose any sort of structure here as different companies use different things to ID long-standing security exceptions.

I think for log statements, including the CVE number directly in the logs would be proper. Not sure we should push that however until we're ready to be public-public.

Right; I intend to do that, but it will be hard-coded into the code, not via some property. If they want to get rid of it, they'll have to at least work a bit harder at it than just tweaking some ESAPI.properties file.

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

src/main/java/org/owasp/esapi/codecs/DB2Codec.java

src/main/java/org/owasp/esapi/codecs/MySQLCodec.java

xeno6696 · 2025-06-09T20:40:38Z

src/main/java/org/owasp/esapi/codecs/DB2Codec.java

- * Implementation of the Codec interface for DB2 strings. This function will only protect you from SQLi in limited situations.
+ * Implementation of the Codec interface for IBM Db2 strings.
+ * This function will only protect you from SQLi in limited situations.
+ * To improve your changces of success, you made also need to do some


may instead of "made"

xeno6696 · 2025-06-09T20:41:09Z

src/main/java/org/owasp/esapi/codecs/MySQLCodec.java

+ * This function will only protect you from SQLi in limited situations.
+ * To improve your changces of success, you made also need to do some
+ * additional canonicalization and input validation first. Before using this class,
+ * pleaes be sure to read the "SECURITY WARNING" in


xeno6696 · 2025-06-09T20:42:40Z

src/main/java/org/owasp/esapi/codecs/OracleCodec.java

+ * This function will only protect you from SQLi in limited situations.
+ * To improve your changces of success, you made also need to do some
+ * additional canonicalization and input validation first. Before using this class,
+ * pleaes be sure to read the "SECURITY WARNING" in


xeno6696 · 2025-06-10T18:41:24Z

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

+ * By following that advise, you will minimize the impact and/or likelihood of any
+ * vulnerabilities from bugs in the ESAPI code or accidental misuse of the ESAPI
+ * library on your part. In particular, whenever there are cases where cients use
+ * any of these {@link org.owasp.esapi.codecs.Codec} classes drectly, it is highly


xeno6696 · 2025-06-10T18:42:34Z

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

+     * </p><p>
+     * <b>SECURITY WARNING:</b> This method is <u>NOT</u> recommended. The use of the {@code PreparedStatement}
+     * interface is the preferred approach. However, if for some reason
+     * this is impossible, then this method is provided as significantly weaker


"as a significantly..."

xeno6696 · 2025-06-10T18:44:29Z

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

+     * 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.
+     * </p><p>
+     * <b>Note to AppSec / Security Auditor teams:</b> If see this method being used in


"If you see this method..."

xeno6696 · 2025-06-10T18:45:25Z

src/main/java/org/owasp/esapi/codecs/MySQLCodec.java

- * Implementation accepts 2 Modes as identified by the OWASP Recommended
- * escaping strategies:
+ * This function will only protect you from SQLi in limited situations.
+ * To improve your changces of success, you made also need to do some


chances mispelled

xeno6696

Would request various typos be fixed prior to release. No other concerns regarding content however.

…sing.

…using.

…sing.

method is not explicitly enabled. Should result in a NotConfiguredByDefaultException being thrown.

Completed already

xeno6696 · 2025-06-11T15:38:01Z

I approve, just in the dentists chair and don’t have time to find the right button

kwwall added 4 commits June 8, 2025 23:24

Sdd comment about doclint options.

849c15e

Add 2 properties associated w/ disabling stuff by default.

40026bf

Class for new unchecked exception type.

436fee5

Miscellaneous Javadoc enhancements.

1da613b

kwwall added the javadoc label Jun 9, 2025

jeremiahjstacey reviewed Jun 9, 2025

View reviewed changes

sempf reviewed Jun 9, 2025

View reviewed changes

src/main/java/org/owasp/esapi/Encoder.java Show resolved Hide resolved

sempf reviewed Jun 9, 2025

View reviewed changes

src/main/java/org/owasp/esapi/codecs/DB2Codec.java Show resolved Hide resolved

sempf reviewed Jun 9, 2025

View reviewed changes

src/main/java/org/owasp/esapi/codecs/MySQLCodec.java Show resolved Hide resolved

Fix Javadoc typos. Shout-out to @sempf for spotting most of these.

2d444b9

xeno6696 reviewed Jun 9, 2025

View reviewed changes

Fix to spelling errors in the class javadoc.

02f4a91

xeno6696 reviewed Jun 10, 2025

View reviewed changes

xeno6696 previously requested changes Jun 10, 2025

View reviewed changes

kwwall added 8 commits June 10, 2025 15:28

Fix 2 typos identified by @xeno6696.

8225a67

Changed the tongue-in-cheek propert names to the actual ones we are u…

61de71f

…sing.

Changed the tongue-in-cheek property names to the actual ones we are …

06d0ff2

…using.

hanged the tongue-in-cheek property names to the actual ones we are u…

a10e323

…sing.

Add missing newline.

844eb0c

New property file for testing DefaultEncoder.encodeForSQL when it's

eb425bb

method is not explicitly enabled. Should result in a NotConfiguredByDefaultException being thrown.

Added 2 new field names whose values are the 2 new property names.

0129740

Added Javadoc to encodeForSQL method regarding how to enabled it.

23a2b76

xeno6696 merged commit e232291 into ESAPI:develop Jun 11, 2025
2 checks passed

Javadoc enhancements #886

Javadoc enhancements #886

Uh oh!

Conversation

kwwall commented Jun 9, 2025

Uh oh!

kwwall commented Jun 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xeno6696 left a comment

Choose a reason for hiding this comment

Uh oh!

xeno6696 commented Jun 11, 2025

Uh oh!

Uh oh!

Uh oh!