Skip to content

Commit 19b739a

Browse files
xeno6696xeno6696
authored
Merge pull request #856 from kwwall/release-prep-2.5.5.0
Release prep 2.5.5.0 -- Visually inspected, looks routine. Special thanks to our newest contributors! :-)
2 parents 57c12af + a160de0 commit 19b739a

File tree

8 files changed

+385
-73
lines changed

8 files changed

+385
-73
lines changed

‎CONTRIBUTING.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Contributing to ESAPI -- Details
2+
3+
## Getting Started
4+
If you have not already done so, go back and read the section
5+
"[Contributing to ESAPI legacy](https://github.com/ESAPI/esapi-java-legacy/blob/develop/README.md#contributing-to-esapi-legacy)" in ESAPI's README.md file. It
6+
may contain updates and advice not contained herein.
7+
8+
### A Special Note on GitHub Authentication
9+
GitHub has announced that they are deprecating password based authentication
10+
using username / password and beginning 2021-08-13, you will no longer be
11+
able to your password to authenticate to 'git' operations on GitHub.com.
12+
Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/
13+
for details and plan accordingly.
14+
15+
### A Special Note Regarding Making Commits for PRs
16+
Shortly after the 2.5.1.0 ESAPI release in late November 2022, the ESAPI
17+
team decided to lock down the 'develop' amd 'main' branches. Merges from
18+
PRs are done to the 'develop' branch. That means that if you intend to
19+
contribute to ESAPI, you must be signing your commits. Please see the
20+
GitHub instructions at
21+
https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
22+
for details.
23+
24+
### Git Branching Model
25+
We are following the branching model described in
26+
https://nvie.com/posts/a-successful-git-branching-model
27+
If you are unfamiliar with it, you would be advised to give it a quick
28+
perusal. The major point is that the 'main' (formerly 'master') branch is
29+
reserved for official releases (which will be tagged), the 'develop' branch
30+
is used for ongoing development work and is the default branch, and we
31+
generally work off 'issue' branches named 'issue-#' where # is the GitHub
32+
issue number. (The last is not an absolute requirement, but rather a
33+
suggested approach.)
34+
35+
Finally, we recommend setting the git property 'core.autocrlf' to 'input'
36+
in your $HOME/.gitconfig file; e.g., that file should contain something
37+
like this:
38+
39+
[core]
40+
autocrlf = input
41+
42+
43+
### Required Software
44+
We use Maven for building. Maven 3.6.3 or later is required. You also need
45+
JDK 8 or later. [Note: If you use JDK 9 or later, there will be multiple
46+
failures when you try to run 'mvn test' as well as some general warnings.
47+
See [ESAPI GitHub issue #496](https://github.com/ESAPI/esapi-java-legacy/issues/496) for details. We welcome volunteers to address
48+
this.]
49+
## Finding Something Interesting to Work on
50+
51+
See the section [Contributing to ESAPI Legacy](https://github.com/ESAPI/esapi-java-legacy/blob/develop/README.md#contributing-to-esapi-legacy)
52+
in the ESAPI README for suggestions. While you don't *have* to work on something labeled "good first issue"
53+
or "help wanted", those are good places to start for someone not yet familiar with the ESAPI code base.
54+
55+
You will need a account on GitHub though. Once you create one, let us know
56+
what it is. Then if you want to work on a particular issue, we can assign
57+
it to you so someone else won't take it.
58+
59+
If you have questions, email Kevin Wall ([email protected]) or Matt
60+
Seil ([email protected]).
61+
62+
63+
## Building ESAPI
64+
See our local GitHub wiki page, [Building ESAPI](https://github.com/ESAPI/esapi-java-legacy/wiki/Building-ESAPI),
65+
which briefly discusses how to build ESAPI via Maven.
66+
67+
You can also refer to [Using ESAPI for Java with Eclipse](https://github.com/ESAPI/esapi-java-legacy/wiki/Using-ESAPI-for-Java-with-Eclipse)
68+
if you prefer working from IDEs. There is also a much older ESAPI wiki page,
69+
[Building with Eclipse](https://www.owasp.org/index.php/ESAPI-BuildingWithEclipse)
70+
that might be useful.
71+
72+
As always, any contributions to ESAPI's admittedly skimpy documentation in this area is welcome.
73+
In particular, contributing some hints about debugging applications using ESAPI
74+
would be very useful to our ESAPI clients.
75+
76+
## Steps to work with ESAPI
77+
I usually do everything from the bash command prompt in Linux Mint,
78+
but other people use Windows. If you prefer an IDE, I can't help you
79+
much, but I can help with at least modest problems. If you have more
80+
difficult problems, I will probably refer you to my project co-leader,
81+
Matt who groks git a lot better than I.
82+
83+
But the basic high level steps are:
84+
85+
1. Fork https://github.com/ESAPI/esapi-java-legacy to your own GitHub repository using the GitHub web site.
86+
2. On your local laptop, clone your own GitHub ESAPI repo (i.e, the forked repo created in previous step)
87+
3. Create a new branch to work on an issue. I usually name the branch 'issue-#' where '#' is the GitHub issue # is will be working on, but you can call it whatever. E.g.,
88+
```bash
89+
$ git checkout -b issue-#
90+
```
91+
4. Work on the GitHub issue on this newly created issue-# branch. Be sure that you also create new JUnit tests as required that confirm that the issue is corrected, or if you are introducing new functionality, ensure
92+
that functionality is sufficiently covered.
93+
5. Make sure everything builds correctly and all the JUnit tests pass ('mvn test'). [Note: There are some known issues with test failures if your are running under Windows and your local ESAPI Git repo located anywhere other than the C: drive, where the test `ValidatorTest.testIsValidDirectoryPath()` fails.
94+
6. If you have added any dependencies, please also run OWASP Dependency-Check and look at the generated report left in 'target/dependency-check-report.html' to make sure there were not any CVEs introduced. (Alternately you can run 'mvn verify' which will first run the tests and then run Dependency-Check.) Note if this is the first time you have run Dependency-Check for ESAPI, expect it to take a while (often 30 minutes or so!). To execute Dependency Check from Maven, run:
95+
```bash
96+
$ mvn org.owasp:dependency-check-maven:check
97+
```
98+
7. Commit your changes locally.
99+
8. Push your 'issue-#' branch to your personal, forked ESAPI GitHub repo. E.g.,
100+
```bash
101+
$ git checkout issue-444
102+
$ git remote -v | grep origin # Confirm 'origin' refers to YOUR PERSONAL GitHub repo
103+
$ git push origin issue-444 # Push the committed changes on the 'issue-444' branch
104+
```
105+
9. Go to your personal, forked ESAPI GitHub repo (web interface) and create a 'Pull Request' (PR) from your 'issue-#' branch.
106+
10. Back on your local personal laptop / desktop, merge your issue branch with your local 'develop' branch. I.e.,
107+
$ git checkout develop
108+
$ git merge issue-444
109+
11. Do not remove your branch on your forked repository until your PR from your branch has been merged into the ESAPI/esapi-java/legacy 'develop' branch.
110+
Note at least one the 3 main contributors on will review your commits before
111+
merging them and they may do a formal code review and request further changes.
112+
Once they are satisfied, they will merge your PR.
113+
114+
In theory, you can do all this 'git' magic from Eclipse and presumably other
115+
IDEs like Oracle NetBeans or JetBrains IntelliJ IDEA. From Eclipse, it is right-click
116+
on the project and then select 'Team' to do the commits, etc. If you choose that
117+
route, you're pretty much on your own because none of us use that for Git
118+
interactions.

‎README.md

+26-49
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ specific Jakarta version of ESAPI, in Maven, you would specify your ESAPI depend
3030
<dependency>
3131
<groupId>org.owasp.esapi</groupId>
3232
<artifactId>esapi</artifactId>
33-
<version>2.5.4.0</version>
33+
<version>2.5.5.0</version> <!-- Preferably the latest version, but > 2.5.3.0 -->
3434
<classifier>jakarta</classifier>
3535
</dependency>
3636
```
@@ -46,40 +46,6 @@ fact, without the
4646
```
4747
that's the version that will be used by default.
4848

49-
# Quickstart - Maven Example
50-
### Step 1: Add the required maven dependencies.
51-
```xml
52-
<dependency>
53-
<groupId>org.owasp.esapi</groupId>
54-
<artifactId>esapi</artifactId>
55-
<version>2.5.3.0 [or later]</version>
56-
<classifier>jakarta</classifier>
57-
</dependency>
58-
<!-- Add the below dependency if the not using JakartaEE -->
59-
<dependency>
60-
<groupId>jakarta.servlet</groupId>
61-
<artifactId>jakarta.servlet-api</artifactId>
62-
<version>6.1.0</version>
63-
<scope>provided</scope>
64-
</dependency>
65-
```
66-
### Step 2: Create 2 properties file namely: ESAPI.properties and validation.properties and add them to your classpath. You can refer to below for boilerplate configurations.
67-
[ESAPI.properties](https://github.com/ESAPI/esapi-java-legacy/blob/develop/configuration/esapi/ESAPI.properties) <br/>
68-
[validation.properties](https://github.com/ESAPI/esapi-java-legacy/blob/develop/configuration/esapi/validation.properties)
69-
70-
### Step 3: Let's say, you want to remediate log injection vulnerabilities. Below is an example to achieve it.
71-
```code
72-
import org.owasp.esapi.ESAPI;
73-
import org.owasp.esapi.Logger;
74-
75-
public class Example {
76-
private static Logger LOGGER = ESAPI.getLogger(Example.class);
77-
public void printLog(){
78-
LOGGER.info(Logger.EVENT_SUCCESS, "Log injection remediated !");
79-
}
80-
}
81-
```
82-
For more examples, please visit [https://owasp.org/www-project-enterprise-security-api/](https://owasp.org/www-project-enterprise-security-api/).
8349

8450
# A word about ESAPI vulnerabilities
8551
A summary of all the vulnerabilities that we have written about in either the
@@ -118,7 +84,7 @@ The ESAPI release notes may be found in ESAPI's "documentation" directory. They
11884
See the GitHub [Releases](https://github.com/ESAPI/esapi-java-legacy/releases) information for a list of releases which generally
11985
link to the specific release notes.
12086

121-
### Really IMPORTANT information in release notes
87+
### Really IMPORTANT information in release notes - Ignore at your peril
12288
* Starting with ESAPI 2.2.1.0, important details changed reading the ESAPI
12389
Logger. If you have are getting things like ClassNotFoundException, you
12490
probably have not read it. Please be sure to read this specific section
@@ -176,6 +142,30 @@ references in documentation). If you must, you still should be able to
176142
use Log4J 1.x logging via ESAPI SLF4J support. See the ESAPI 2.5.0.0 release
177143
notes for further details.
178144

145+
# Quickstart - Maven Example
146+
### Step 1: Add the required dependencies.
147+
See https://mvnrepository.com/artifact/org.owasp.esapi/esapi/latest, the tab for
148+
whatever build tool you are using. If you need the Jakarta version, make sure to
149+
add
150+
```xml
151+
<classifier>jakarta</classifier>
152+
```
153+
and include whatever jakara.servlet:jakarta.servlet-api version you are using with
154+
```xml
155+
<scope>provided</scope>
156+
```
157+
### Step 2: Obtain the 2 properties files ESAPI.properties and validation.properties
158+
1. Download these 2 files from the ESAPI release that you are using from https://github.com/ESAPI/esapi-java-legacy/releases
159+
and download the esapi-<release>-configuration.jar file (and the .asc file if you wish to confirm the GPG signature).
160+
2. Unjar that configuration file that you just downloaded and find the 2
161+
properties files under the "configuration/esapi" subdirectory where you
162+
unjarred the config jar.
163+
3. Read through Javadoc for [DefaultSecurityConfiguration](https://javadoc.io/static/org.owasp.esapi/esapi/2.5.4.0/org/owasp/esapi/reference/DefaultSecurityConfiguration.html)
164+
to understand the ways that ESAPI locates these files and then use the mechanism that works best for you. Copy the 2 properties
165+
files from the 'configuration/esapi' directory to the directory where you
166+
choose to have them reside. Note that you may also edit them to customize
167+
them according to your needs.
168+
179169
# Contributing to ESAPI legacy
180170
### How can I contribute or help with fix bugs?
181171
Fork and submit a pull request! Easy as pi! (How's that for an irrational
@@ -250,19 +240,6 @@ discussion or even show us how it works with a PR. (Note that we vet all pull
250240
requests, including coding style of any contributions, so please use the same
251241
coding style found in the files you are already editing.)
252242

253-
# Ancient History
254-
### What happened to Google code?
255-
In mid-2014 ESAPI migrated all code and issues from Google Code to GitHub. This migration was completed in November 2014.
256-
257-
### What about the issues still located on Google Code?
258-
All issues from Google Code have been migrated to GitHub issues. We now
259-
use GitHut Issues for reporting everything *except* security vulnerabilities.
260-
Other bug tracking sites are undoubtedly more advanced, but as developers,
261-
we do not want to spent time having to close issues from multiple bug-tracking
262-
systems. Therefore, until the synchronization happens with the Atlassian Jira
263-
instance that we have (but are not using; see GitHub issue #371), please
264-
ONLY use GitHub Issues for reporting bugs.
265-
266243
# References: Where to Find More Information on ESAPI
267244
**OWASP Wiki:** https://owasp.org/www-project-enterprise-security-api/
268245

0 commit comments

Comments
 (0)