This document describes how you can contribute to WrongSecrets. Please read it carefully.
Table of Contents
- How to Contribute to the Project
- How to set up your Contributor Environment
- How to get your PR Accepted
- Beginner Guide
- How to add a Challenge
There are a couple of ways on how you can contribute to the project:
- File issues for missing content or errors. Explain what you think is missing and give a suggestion as to where it could be added.
- Create a pull request (PR). This is a direct contribution to the project and may be merged after review. You should ideally create an issue for any PR you would like to submit, as we can first review the merit of the PR and avoid any unnecessary work. This is of course not needed for small modifications such as correcting typos.
- Promote us by giving us a Star or share information via social media.
Your PR is valuable to us, and to make sure we can integrate it smoothly, we have a few items for you to consider. In short: The minimum requirements for code contributions are:
- The code must be compliant with the configured pre-commit hooks, and Checkstyle and PMD rules.
- All new and changed code should have a corresponding unit and/or integration test.
- New and changed lessons must have a corresponding integration test.
- Status checks should pass for your last commit.
Additionally, the following guidelines can help:
Pull requests should be as small/atomic as possible. Large, wide-sweeping changes in a pull request will be rejected, with comments to isolate the specific code in your pull request. Some examples:
- If you are making spelling corrections in the docs, don't modify other files.
- If you are adding new functions don't 'cleanup' unrelated functions. That cleanup belongs in another pull request.
-
Make sure your commit message passes the conventional commit standards
-
Explain why you make the changes. More info about a good commit message.
-
If you fix an issue with your commit, please close the issue by adding one of the keywords and the issue number to your commit message.
For example:
Fix #545orCloses #10
-
Create a GitHub account. Multiple different GitHub subscription plans are available, but you only need a free one. Follow these steps to set up your account.
-
Fork the repository. Creating a fork means creating a copy of the repository on your own account, which you can modify without any impact on this repository. GitHub has an article that describes all the needed steps.
-
Clone your own repository to your host computer so that you can make modifications. If you followed the GitHub tutorial from step 2, you have already done this.
-
Go to the newly cloned directory "wrongsecrets" and add the remote upstream repository:
$ git remote -v origin [email protected]:<your Github handle>/wrongsecrets.git (fetch) origin [email protected]:<your Github handle>/wrongsecrets.git (push) $ git remote add upstream [email protected]:OWASP/wrongsecrets.git $ git remote -v origin [email protected]:<your Github handle>/wrongsecrets.git (fetch) origin [email protected]:<your Github handle>/wrongsecrets.git (push) upstream [email protected]:OWASP/wrongsecrets.git (fetch) upstream [email protected]:OWASP/wrongsecrets.git (push)
See also the GitHub documentation on "Configuring a remote for a fork".
-
Choose what to work on, based on any of the outstanding issues.
-
Create a branch so that you can cleanly work on the chosen issue:
git checkout -b fix/Issue66 -
Open your favorite editor and start making modifications. We recommend using the IntelliJ Idea.
-
Install pre-commit the dependencies for our pre-commit configuration to make sure your code complies with standards used in the project. This requires terraform, terraform-docs, tflint, and commitlint. For commitlint, you need NodeJS 20 installed, after which you you can use
npm installin the root folder of this project. -
Install the pre-commit hook using
pre-commit install --hook-type commit-msg. We recommend to runpre-commit run -aevery so often if you're working on a bigger change. -
After your modifications are done, push them to your forked repository. This can be done by executing the command
git add MYFILEfor every file you have modified, followed bygit commit -m 'your commit message here'to commit the modifications andgit pushto push your modifications to GitHub. -
Create a Pull Request (PR) by going to your fork, https://github.com/Your_Github_Handle/wrongsecrets and click on the "New Pull Request" button. The target branch should typically be the Master branch. When submitting a PR, be sure to follow the checklist that is provided in the PR template. The checklist itself will be filled out by the reviewer.
-
If something in your git workflow went wrong (and e.g., the precommit hook CI run failed), check out "O Shit, Git!?!" to view tips on editing your historical commit message(s), among others.
-
Your PR will be reviewed and comments may be given. In order to process a comment, simply make modifications to the same branch as before and push them to your repository. GitHub will automatically detect these changes and add them to your existing PR. If pre-commit can auto-fix the issue, it will automatically try to do so by adding a new commit. This new commit can be pulled in with a simple
git pull, or, if you've already made one or more new commits:git pull --rebase. -
When starting on a new PR in the future, make sure to always keep your local repo up to date:
git fetch upstream git merge upstream/develop
See also the following article for further explanation on "How to Keep a Downstream git Repository Current with Upstream Repository Changes".
If at any time you want to work on a different issue, you can simply switch to a different branch, as explained in step 5.
Tip: Don't try to work on too many issues at once though, as it will be a lot more difficult to merge branches the longer they are open.
Although we greatly appreciate any and all contributions to the project, there are a few things that you should take into consideration:
- The Wrongsecrets project should not be used as a platform for advertisement for commercial tools, companies or individuals. Write-ups should be written with free and open-source tools in mind and commercial tools are typically not accepted, unless as a reference in the security tools section.
- Unnecessary self-promotion of tools or blog posts is frowned upon. If you have a relation with on of the URLs or tools you are referencing, please state so in the PR so that we can verify that the reference is in line with the rest of the guide.
Please be sure to take a careful look at our Code of Conduct for all the details.
WrongSecrets is an application teaching how to not store secrets by offering challenges to the user, helping the user to Self-reflect and correct those mistakes.
-
Docker Docker is a software platform that allows you to build, test, and deploy applications quickly and in a more efficient manner.
-
Node.Js 20 Node.Js is an open-source library and a cross-platform JavaScript runtime environment specifically for running web applications outside one's browser.
-
JDK-21 JDK is a tool used in development and testing programs written in the Java programming language.
-
IntelliJ IDEA IntelliJ IDEA is an integrated development environment basically an IDE written in Java for developing software written in Java, Kotlin, Groovy etc.
-
GitHub Desktop GitHub Desktop is an application that enables you to interact with GitHub using a GUI instead of the command line or a web browser. (Not Mandatory but is recommended for beginners)
Navigate to the landing page of the repository in your web browser and click on the Fork button on the repository’s home page. A forked copy of that Git repository will be added to your personal GitHub.
A clone is a full copy of a repository, including all logging and versions of files. To clone the Project to your local desktop by clicking on the button as shown below.
Open the Cloned Project using IntelliJ IDEA by clicking on the button as shown below.
Wait till the Project Loads.
Open Settings by pressing Ctrl+Alt+S
Follow the path IDE settings>Language & Frameworks > Lombok and then click on Lombok.
Make sure that the Lombok processing is enabled.
Select Plugins > Marketplace and type 'google-java-format' and restart IntelliJ to install the plugin.
Open Settings by pressing Ctrl+Alt+S
Select google-java-format Settings and click enable.
Open _File > Project structure _.
In the tab Project make sure that an SDK of version 21 is selected (e.g. openjdk-21, oraclejdk-21 or just 21 depending on which Java JDK variant you installed).
In the tab SDKs make sure that an SDK of version 21 is selected.
Open the Maven Tab
Press the Reload button as shown below and allow the project to Reload.
Further use the OWASP WrongSecrets --> Lifecycle --> install step to load all the depedencies
NOTE: Indians and other Asia-Pacific countries users may have to use VPN if you enounter this exception org.owasp.dependencycheck.utils.DownloadFailedException: TLS Connection Reset.
Open the WrongSecretsApplication by following the path main>java>org.owasp.wrongsecrets>WrongSecretApplication.
Press Shift+F10 to run the application, this will open up the Run/Debug Configurations Menu.
Select Edit configuration templates then select Application section.
There under the Application section click on the button shown below.
Select all the fields that are Selected in the below picture.
Fill out all the fields as shown below.
Again press Shift+F10 which runs the Application.
Here is a preview on how does it look after successfully running the Application. Note: Running the Application doesn't open any kind of GUI, it only initializes the local webserver that you can open via a browser.
Here is the preview of the web server, you can try to find the secrets by means of solving the challenge offered at: Challenges
First make sure that you have an Issue reported for which a challenge is really wanted, or pick an existing issue you want to implement. Make sure the challenge is assigned to you, as others might be working on the challenge.
Add the new challenge in this folder wrongsecrets/src/main/java/org/owasp/wrongsecrets/challenges/.
These are the things that you have to keep in mind.
- First and foremost make sure your challenge is coded in Java.
- Don't forget to add your challenge number in
@Order(28)annotation, 28 in my case. - Here is an example of a possible Challenge 28:
package org.owasp.wrongsecrets.challenges.docker;
import lombok.extern.slf4j.Slf4j;
import org.owasp.wrongsecrets.RuntimeEnvironment;
import org.owasp.wrongsecrets.ScoreCard;
import org.owasp.wrongsecrets.challenges.Challenge;
import org.owasp.wrongsecrets.challenges.ChallengeTechnology;
import org.owasp.wrongsecrets.challenges.Spoiler;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import java.util.List;
/**
* Describe what your challenge does
*/
@Slf4j
@Component
@Order(28) //make sure this number is the same as your challenge
public class Challenge28 extends Challenge {
private final String secret;
public Challenge28(ScoreCard scoreCard) {
super(scoreCard);
secret = "hello world";
}
//is this challenge usable in CTF mode?
@Override
public boolean canRunInCTFMode() {
return true;
}
//return the plain text secret here
@Override
public Spoiler spoiler() {
return new Spoiler(secret);
}
//here you validate if your answer matches the secret
@Override
public boolean answerCorrect(String answer) {
return secret.equals(answer);
}
//which runtime can you use to run the challenge on? (You can just use Docker here)
/**
* {@inheritDoc}
*/
@Override
public List<RuntimeEnvironment.Environment> supportedRuntimeEnvironments() {
return List.of(RuntimeEnvironment.Environment.DOCKER);
}
//set the difficulty: 1=low, 5=very hard
/**
* {@inheritDoc}
* Difficulty: 1.
*/
@Override
public int difficulty() {
return 1;
}
//on which tech is this challenge? See ChallengeTechnology.Tech for categories
/**
* {@inheritDoc}
* Secrets based.
*/
@Override
public String getTech() {
return ChallengeTechnology.Tech.SECRETS.id;
}
//if you use this in a shared environment and need to adapt it, then return true here.
@Override
public boolean isLimittedWhenOnlineHosted() {
return false;
}
}Add the new TestFile in this folder wrongsecrets/src/test/java/org/owasp/wrongsecrets/challenges/. TestFile is required to do unit testing.
These are the things that you have to keep in mind.
Make sure that this file is also of Java type. Here is a unit test for reference:
package org.owasp.wrongsecrets.challenges.docker;
import org.assertj.core.api.Assertions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.Mockito;
import org.mockito.junit.jupiter.MockitoExtension;
import org.owasp.wrongsecrets.ScoreCard;
@ExtendWith(MockitoExtension.class)
class Challenge28Test {
@Mock
private ScoreCard scoreCard;
@Test
void rightAnswerShouldSolveChallenge() {
var challenge = new Challenge28(scoreCard);
Assertions.assertThat(challenge.solved("wrong answer")).isFalse();
Assertions.assertThat(challenge.solved(challenge.spoiler().solution())).isTrue();
}
}Please note that PRs for new challenges are only accepted when unit tests are added to prove that the challenge works. Normally tests should not immediately leak the actual secret, so leverage the .spoil() functionality of your test implementation for this.
Add the explanation for your challenge along with the hints that will help in finding the secret in this folder wrongsecrets/src/main/resources/explanations/.
Things to be noted:
- All the possible explanations for your challenge, included with all the hints and reasons should be provided.
- Everything must be in separate AsciiDoc files.
- Follow this fashion in naming the file:
challenge<number>.adoc,challenge<number>_hint.adoc, andchallenge<number>_reason.adoc.
Here is a Explanation for reference:
=== Hello world challenge
Welcome to OWASP WrongSecrets Beginner guide Challenge
Basically this challenge is there only to demonstrate how to add a challenge in our project and to give you a basic idea on how does things work.
refer this block for reasons:
==== What’s the purpose of this specific challenge?
With this challenge, we basically aim to help new contributors to better understand the code and encourage them to add new challenges for our end-user.Use this block as refrence for hints:
Your secret is `Hello World`
Copy this and paste it in the box provided and press "Submit" and you are good to go.
This challenge is only meant for helping new contributors to add new challenges. Please, have fun with trying more difficult challenges;-).After completing all the above steps, final step is to submit the PR and refer Contributing.md on how to get your PR accepted.