STRLCPY/wrongsecrets

Merge pull request #451 from commjoen/ctf-docs

First iteration of the full CTF documentation for #372

Jeroen Willemsen committed with GitHub 2 years ago

e219c267

2 parents
657e840d
319f0d2d

Revision indexing in progress... (symbol navigation in revisions will be accurate after indexed)

Total 2 files Show one by one

■ ■ ■ ■ ■ ■

README.md

		skipped 78 lines
79	79
80	80		### Running on Fly.io
81	81
82		-	You can test them out at [https://wrongsecrets.fly.dev](https://wrongsecrets.fly.dev) as well! Please understand that we
83		-	run on a free-tier instance, we cannot give any guarantees. Please do not fuzz and/or try to bring it down: you would be
84		-	spoiling it for others that want to testdrive it.
	82	+	You can test them out at [https://wrongsecrets.fly.dev](https://wrongsecrets.fly.dev) as well! Please understand that we run on a free-tier instance, we cannot give any guarantees. Please do not fuzz and/or try to bring it down: you would be spoiling it for others that want to testdrive it.
85	83
86	84		## Basic K8s exercise
87	85
		skipped 59 lines
147	145		- vault [Install from here](https://www.vaultproject.io/downloads),
148	146		- grep, Cat, and Sed
149	147
150		-	Run `./k8s-vault-minkube-start.sh`, when the script is done, then the challenges will wait for you
151		-	at <http://localhost:8080> . This will allow you to run challenges 1-8, 12-22.
	148	+	Run `./k8s-vault-minkube-start.sh`, when the script is done, then the challenges will wait for you at <http://localhost:8080> . This will allow you to run challenges 1-8, 12-22.
152	149
153		-	When you stopped the `k8s-vault-minikube-start.sh` script and want to resume the port forward
154		-	run: `k8s-vault-minikube-resume.sh`. This is because if you run the start script again it will replace the secret in the
155		-	vault and not update the secret-challenge application with the new secret.
	150	+	When you stopped the `k8s-vault-minikube-start.sh` script and want to resume the port forward run: `k8s-vault-minikube-resume.sh`.
	151	+	This is because if you run the start script again it will replace the secret in the vault and not update the secret-challenge application with the new secret.
156	152
157	153		## Cloud Challenges
158	154
		skipped 20 lines
179	175		When you want to include your own Canarytokens for your cloud-deployment, do the following:
180	176
181	177		1. Fork the project.
182		-	2. Make sure you use the [GCP ingress](/gcp/k8s-vault-gcp-ingress-start.sh) or [AWS ingress](aws/k8s-aws-alb-script.sh)
183		-	scripts to generate an ingress for your project.
184		-	3. Go to [canarytokens.org](https://canarytokens.org/generate) and select `AWS Keys`, in the webHook URL field
185		-	add `<your-domain-created-at-step1>/canaries/tokencallback`.
186		-	4. Encrypt the received credentials so
187		-	that [Challenge15](/src/main/java/org/owasp/wrongsecrets/challenges/docker/Challenge15.java) can decrypt them again.
	178	+	2. Make sure you use the [GCP ingress](/gcp/k8s-vault-gcp-ingress-start.sh) or [AWS ingress](aws/k8s-aws-alb-script.sh) scripts to generate an ingress for your project.
	179	+	3. Go to [canarytokens.org](https://canarytokens.org/generate) and select `AWS Keys`, in the webHook URL field add `<your-domain-created-at-step1>/canaries/tokencallback`.
	180	+	4. Encrypt the received credentials so that [Challenge15](/src/main/java/org/owasp/wrongsecrets/challenges/docker/Challenge15.java) can decrypt them again.
188	181		5. Commit the unencrypted and encrypted materials to Git and then commit again without the decrypted materials.
189	182		6. Adapt the hints of Challenge 15 in your fork to point to your fork.
190	183		7. Create a container and push it to your registry
191		-	8. Override the K8s definition files for either [AWS](/aws/k8s/secret-challenge-vault-deployment.yml)
192		-	or [GCP](/gcp/k8s/secret-challenge-vault-deployment.yml.tpl).
	184	+	8. Override the K8s definition files for either [AWS](/aws/k8s/secret-challenge-vault-deployment.yml) or [GCP](/gcp/k8s/secret-challenge-vault-deployment.yml.tpl).
193	185
194	186		## Do you want to play without guidance?
195	187
196		-	Each challenge has a `Show hints` button and a `What's wrong?` button. These buttons help to simplify the challenges and
197		-	give explanation to the reader. Though, the explanations can spoil the fun if you want to do this as a hacking exercise.
	188	+	Each challenge has a `Show hints` button and a `What's wrong?` button. These buttons help to simplify the challenges and give explanation to the reader. Though, the explanations can spoil the fun if you want to do this as a hacking exercise.
198	189		Therefore, you can manipulate them by overriding the following settings in your env:
199	190
200	191		- `hints_enabled=false` will turn off the `Show hints` button.
		skipped 41 lines
242	233
243	234		- Star us
244	235		- Share this app with others
245		-	- Of course, we can always use your help [to get more flavors](https://github.com/commjoen/wrongsecrets/issues/37) of "
246		-	wrongly" configured secrets in to spread awareness! We would love to get some help with other cloudproiders, like
247		-	Alibabaor Tencent cloud for instance. Do you miss something else than a cloud provider as an example? File an issue or
248		-	create a PR! See [our guide on contributing for more details](CONTRIBUTING.md). Contributors will be listed in
249		-	releases, in the "Special thanks & Contributors"-section, and the web-app.
	236	+	- Of course, we can always use your help [to get more flavors](https://github.com/commjoen/wrongsecrets/issues/37) of "wrongly" configured secrets in to spread awareness! We would love to get some help with other cloudproiders, like Alibabaor Tencent cloud for instance. Do you miss something else than a cloud provider as an example? File an issue or create a PR! See [our guide on contributing for more details](CONTRIBUTING.md). Contributors will be listed in releases, in the "Special thanks & Contributors"-section, and the web-app.
250	237
251	238		## Use OWASP WrongSecrets as a secret detection benchmark
252	239
253	240		As tons of secret detection tools are coming up for both Docker and Git, we are creating a Benchmark testbed for it.
254		-	Want to know if your tool detects everything? We will keep track of the embedded secrets
255		-	in [this issue](https://github.com/commjoen/wrongsecrets/issues/201) and have
256		-	a [branch](https://github.com/commjoen/wrongsecrets/tree/experiment-bed) in which we put additional secrets for your
257		-	tool to detect.
258		-	The branch will contain a Docker container generation script using which you can eventually test your container secret
259		-	scanning.
	241	+	Want to know if your tool detects everything? We will keep track of the embedded secrets in [this issue](https://github.com/commjoen/wrongsecrets/issues/201) and have a [branch](https://github.com/commjoen/wrongsecrets/tree/experiment-bed) in which we put additional secrets for your tool to detect.
	242	+	The branch will contain a Docker container generation script using which you can eventually test your container secret scanning.
260	243
261	244		## CTF
262	245
	246	+	We have 3 ways of playing CTFs:
	247	+	- The quick "let's play"-approach based on our own Heroku domain [https://wrongsecrets-ctf.herokuapp.com](https://wrongsecrets-ctf.herokuapp.com), which we documente for you here.
	248	+	- A more extended approach documented in [ctf-insstructions.md](/ctf-instructions.md).
	249	+	- A fully customizable CTF setup where every player gets its own virtual instance of WrongSecrets and a virtual instance of the wrongsecrets-desktop, so they all can play hassle-free. For this you have to use [the WrongSecrets CTF Party setup](https://github.com/commjoen/wrongsecrets-ctf-party).
	250	+
263	251		### CTFD Support
264	252
265		-	NOTE: CTFD support is experimental, and now works based on
266		-	the [Juiceshop CTF CLI](https://github.com/juice-shop/juice-shop-ctf).
267		-	NOTE-II: https://wrongsecrets-ctf.herokuapp.com is based on a free heroku instance, which takes time to warm up.
268		-	Initial creation of the zip file for CTFD requires you to
269		-	visit [https://wrongsecrets-ctf.herokuapp.com/api/Challenges](https://wrongsecrets-ctf.herokuapp.com/api/Challenges)
270		-	once before executing the steps below.
	253	+	Want to use CTFD to play a CTF based on the free Heroku wrongsecrets-ctf instance together with CTFD? You can!
	254	+
	255	+	NOTE: CTFD support now works based on the [Juiceshop CTF CLI](https://github.com/juice-shop/juice-shop-ctf).
	256	+	NOTE-II: [https://wrongsecrets-ctf.herokuapp.com](https://wrongsecrets-ctf.herokuapp.com) is based on a free heroku instance, which takes time to warm up.
	257	+	Initial creation of the zip file for CTFD requires you to visit [https://wrongsecrets-ctf.herokuapp.com/api/Challenges](https://wrongsecrets-ctf.herokuapp.com/api/Challenges) once before executing the steps below.
271	258
272	259		Follow the following steps:
273	260
		skipped 3 lines
277	264		docker run -p 8001:8000 -it ctfd/ctfd:3.4.3
278	265		```
279	266
280		-	Now visit the CTFD instance at [http://localhost:8001](http://localhost:8001) and setup your CTF. Then use the
281		-	administrative backup function to import the zipfile you created with the juice-shop-ctf command.
282		-	Game on using [https://wrongsecrets-ctf.herokuapp.com](https://wrongsecrets-ctf.herokuapp.com) !
283		-	Want to setup your own? You can! Watch out for people finding your key though, so secure it properly: make sure the
284		-	running container with the actual ctf-key is not exposed to the audience, similar to our heroku container.
	267	+	Now visit the CTFD instance at [http://localhost:8001](http://localhost:8001) and setup your CTF.
	268	+	Then use the administrative backup function to import the zipfile you created with the juice-shop-ctf command.
	269	+	Game on using [https://wrongsecrets-ctf.herokuapp.com](https://wrongsecrets-ctf.herokuapp.com)!
	270	+	Want to setup your own? You can! Watch out for people finding your key though, so secure it properly: make sure the running container with the actual ctf-key is not exposed to the audience, similar to our heroku container.
285	271
286	272		## FBCTF Support (Experimental!)
287	273
288	274		NOTE: FBCTF support is experimental.
289	275
290		-	follow the same step as with CTFD, only now choose fbctfd and as a url for the countrymapping
291		-	choose `https://raw.githubusercontent.com/commjoen/wrongsecrets/79a982558016c8ce70948a8106f9a2ee5b5b9eea/config/fbctf.yml`
292		-	. Then
293		-	follow [https://github.com/facebookarchive/fbctf/wiki/Quick-Setup-Guide](https://github.com/facebookarchive/fbctf/wiki/Quick-Setup-Guide)
294		-	to run the FBCTF.
	276	+	Follow the same step as with CTFD, only now choose fbctfd and as a url for the countrymapping choose `https://raw.githubusercontent.com/commjoen/wrongsecrets/79a982558016c8ce70948a8106f9a2ee5b5b9eea/config/fbctf.yml`.
	277	+	Then follow [https://github.com/facebookarchive/fbctf/wiki/Quick-Setup-Guide](https://github.com/facebookarchive/fbctf/wiki/Quick-Setup-Guide) to run the FBCTF.
295	278
296	279		## Notes on development
297	280
		skipped 28 lines
326	309		./mvnw spring-boot:run -Dspring-boot.run.profiles=local,without-vault
327	310		```
328	311
329		-	Want to push a container? See `.github/scripts/docker-create-and-push.sh` for a script that generates and pushes all
330		-	containers. Do not forget to rebuild the app before composing the container
	312	+	Want to push a container? See `.github/scripts/docker-create-and-push.sh` for a script that generates and pushes all containers. Do not forget to rebuild the app before composing the container
331	313
332	314		### Dependency management
333	315
334	316		We have CycloneDX and OWASP Dependency-check integrated to check dependencies for vulnerabilities.
335		-	You can use the OWASP Dependency-checker by calling `mvn dependency-check:aggregate` and `mvn cyclonedx:makeBom` to use
336		-	CycloneDX to create an SBOM.
	317	+	You can use the OWASP Dependency-checker by calling `mvn dependency-check:aggregate` and `mvn cyclonedx:makeBom` to use CycloneDX to create an SBOM.
337	318
338	319		### Automatic reload during development
339	320
340		-	To make changes made load faster we added `spring-dev-tools` to the Maven project. To enable this in IntelliJ
341		-	automatically, make sure:
	321	+	To make changes made load faster we added `spring-dev-tools` to the Maven project.
	322	+	To enable this in IntelliJ automatically, make sure:
342	323
343	324		- Under Compiler -> Automatically build project is enabled, and
344	325		- Under Advanced settings -> Allow auto-make to start even if developed application is currently running.
345	326
346		-	You can also manually invoke: Build -> Recompile the file you just changed, this will also force reloading of the
347		-	application.
	327	+	You can also manually invoke: Build -> Recompile the file you just changed, this will also force reloading of the application.
348	328
349	329		### How to add a Challenge
350	330
351	331		Follow the steps below on adding a challenge:
352	332
353		-	1. First make sure that you have an [Issue](https://github.com/commjoen/wrongsecrets/issues) reported for which a
354		-	challenge is really wanted.
355		-	2. Add the new challenge in the `org.owasp.wrongsecrets.challenges` folder. Make sure you add an explanation
356		-	in `src/main/resources/explanations` and refer to it from your new Challenge class.
	333	+	1. First make sure that you have an [Issue](https://github.com/commjoen/wrongsecrets/issues) reported for which a challenge is really wanted.
	334	+	2. Add the new challenge in the `org.owasp.wrongsecrets.challenges` folder. Make sure you add an explanation in `src/main/resources/explanations` and refer to it from your new Challenge class.
357	335		3. Add a unit and integration test to show that your challenge is working.
358	336		4. Don't forget to add `@Order` annotation to your challenge ;-).
359	337
360		-	If you want to move existing cloud challenges to another cloud: extend Challenge classes in
361		-	the `org.owasp.wrongsecrets.challenges.cloud` package and make sure you add the required Terraform in a folder with the
362		-	separate cloud identified. Make sure that the environment is added to `org.owasp.wrongsecrets.RuntimeEnvironment`.
	338	+	If you want to move existing cloud challenges to another cloud: extend Challenge classes in the `org.owasp.wrongsecrets.challenges.cloud` package and make sure you add the required Terraform in a folder with the separate cloud identified. Make sure that the environment is added to `org.owasp.wrongsecrets.RuntimeEnvironment`.
363	339		Collaborate with the others at the project to get your container running so you can test at the cloud account.
364	340
365	341		### Local testing
366	342
367		-	If you have made some changes to the codebase or added a new challenge and would like to see exactly how the container
368		-	will look after merge for testing, we have a script that makes this very easy. Follow the steps below:
	343	+	If you have made some changes to the codebase or added a new challenge and would like to see exactly how the container will look after merge for testing, we have a script that makes this very easy. Follow the steps below:
369	344
370	345		1. Ensure you have bash installed and open.
371	346		2. Navigate to .github/scripts.
		skipped 3 lines
375	350
376	351		## Want to play, but are not allowed to install the tools?
377	352
378		-	If you want to play the challenges, but cannot install tools like keepass, Radare, etc. But are allowed to run Docker
379		-	containers, try the following:
	353	+	If you want to play the challenges, but cannot install tools like keepass, Radare, etc. But are allowed to run Docker containers, try the following:
380	354
381	355		```shell
382	356		docker run -p 3000:3000 -v /var/run/docker.sock:/var/run/docker.sock jeroenwillemsen/wrongsecrets-desktop:latest
		skipped 34 lines

■ ■ ■ ■ ■ ■

ctf-instructions.md

1	1		# CTF Instructions
2	2
3	3		So you want to play a CTF with WrongSecrets? This is the place to read up all about it.
4		-	Our CTF setup makes use of the [Juice Shop CTF CLI extension](https://github.com/juice-shop/juice-shop-ctf), which you
5		-	can read all about at [here](https://pwning.owasp-juice.shop/part1/ctf.html).
	4	+	Our CTF setup makes use of the [Juice Shop CTF CLI extension](https://github.com/juice-shop/juice-shop-ctf), which you can read all about at [here](https://pwning.owasp-juice.shop/part1/ctf.html).
6	5
7		-	The difference between Juiceshop and WrongSecrets, is that WrongSecrets is more of a secrets-hunter game. Thiss means
8		-	that your contestants will try to find the CTF key soon after a few challenges. That is why we should separate out the
9		-	actual container for which the CTF scores are generated, from the container where the challenges live in.
	6	+	The difference between Juiceshop and WrongSecrets, is that WrongSecrets is more of a secrets-hunter game.
	7	+	This means that your contestants will try to find the CTF key soon after a few challenges.
	8	+	That is why we should separate out the actual container for which the CTF scores are generated, from the container where the challenges live in. We call this the 3-domain setup where you now have 3 environments:
10	9
11		-	You can see this practice already here in our repository: Our standard [Dockerfile](/Dockerfile) does not contain any
12		-	CTF entries, our Heroku [Dockerfile.web](/Dockerfile.web) does contain them.
13		-	So make sure you host your actual scoring Dockerfile.web at a place where your contestants cannot enter the container (
14		-	image) in order to extract the CTF key.
	10	+	- the play-environment: here players can just play with WrongSecrets: this can be something you host online, or just a Docker container they start up locally.
	11	+	- the CTF-scoring-environment: this is the intermediary domain where people exchange answers found in the 'play-environment' for actual flags for the CTF-platform.
	12	+	- your CTF-platform: this can be a platform like CTFD or FBCTF.
	13	+
	14	+	You can see this practice already here in our repository: Our standard [Dockerfile](/Dockerfile) does not contain any CTF entries, our Heroku [Dockerfile.web](/Dockerfile.web) does contain them.
	15	+	So make sure you host your actual scoring Dockerfile.web at a place where your contestants cannot enter the container (image) in order to extract the CTF key.
	16	+
	17	+	## Want to get rid of the additional domain?
	18	+
	19	+	Want to make sure you don't need to bug your users to copy paste values twice to get points? Here we describe the "2-domain setup". With the 2-domain setup you need to do a manual crafted approach instead of the HMAC based approach for platforms like CTFD. That way, you do not need the 'CTF-scoring-environment' to exchange answers for flags, for this you:
	20	+	- Follow the steps described at [instructions in the readme](https://github.com/commjoen/wrongsecrets#ctfd-support).
	21	+	- Then unzip the created zip file and update all the flags in flags.jsson with the actual values of the answers for your CTF.
	22	+	- Zip the json files again.
	23	+	- Upload your own crafted zipfile with the actual answers, instead of HMACs to CTFD.
	24	+
	25	+	Now users can directly use your Wrongsecrets setup together with the CTF-platform to play challenges without having to copy answers and flags twice!
	26	+
	27	+	Note: make sure that you do set `CTF_SERVER_ADDRESS` to point to the address where you are running your CTF-platform (E.g. CTFD/Facebook CTF) and that you set `challenge_acht_ctf_to_provide_to_host_value` to the flag you store in your CTF-platform.
15	28
16	29		## Setting up CTFs
17	30
		skipped 1 lines
19	32
20	33		### Docker or Heroku CTF
21	34
22		-	When doing a Docker or Heroku based CTF, you can follow
23		-	the [instructions in the readme](https://github.com/commjoen/wrongsecrets#ctfd-support).
24		-	If you want to use your own CTF key, you can build a container with the following
25		-	arguments `CTF_ENABLED=true,HINTS_ENABLED=false,CTF_KEY=<YOURNEWKEYHERE>`. Just make sure you provide the same key
	35	+	When doing a Docker or Heroku based CTF, you can follow the [instructions in the readme](https://github.com/commjoen/wrongsecrets#ctfd-support).
	36	+	If you want to use your own CTF key, you can build a container with the following arguments `CTF_ENABLED=true,HINTS_ENABLED=false,CTF_KEY=<YOURNEWKEYHERE>`. Just make sure you provide the same key
26	37		to `juice-shop-ctf` when you run it.
27		-
28		-	Want to make it a little more exciting? Override the Dockerfile with your preferred values, so that copying from online
29		-	hosted solutions no longer works!
	38	+	Host the Docker container somewhere, where your users can not access the container variables directly, so they cannot extract the CTF key that easily.
	39	+	Want to make it a little more exciting? Create your own custom Docker image for both the 'play-environment' and the 'CTF-scoring-environment', where you override certain values (e.g. the ARG, the docker ENV, etc.) with your preferred values, so that copying from any existing online solution no longer works!
	40	+	There are a few env-vars that you need to pay attention to when setting this up:
	41	+	- `CTF_SERVER_ADDRESS` in the 'play-environment' to be set to the URL of the 'CTF-scoring-environment' (e.g. your instance of wrongsecrets-ctf.herokuapp.com), and in the 2-domain approach that would be your CTF-platform. Note that in the domain where your users exchange answers for flags for your CTF-platform, you can set it to the URL where your CTF-platform lives.
	42	+	- `challenge_acht_ctf_to_provide_to_host_value` needs to be set to a sufficiently long value at the 'play-environment' where your players interact with WrongSecrets to hack around. The value of this entry is returned to the players when they have found the randomly generated value in the logs. If you have the 2-domain approach: make sure that this value is actually the flag-entry for challenge 8 in your CTF-platform, if you have the normal setup, make sure that your 'CTF-scoring-environment' where people provide answers in exchange for flags has the same value stored under `challenge_acht_ctf_host_value`.
	43	+	- `challenge_acht_ctf_host_value` needs to be set in your 'ctf scoring environment' where players exchange answers for CTF flags to the same value as `challenge_acht_ctf_to_provide_to_host_value` in the environment players play around. Note that this value is not required in a 2-domain approach.
30	44
31	45		### K8s based CTF
32	46
33		-	TODO as #https://github.com/commjoen/wrongsecrets/issues/372
	47	+	If you are interested in setting up a Kubernetes based CTF, you might want to look at [WrongSecrets CTF party](https://github.com/commjoen/wrongsecrets-ctf-party) instead. Still want to take a different approach than using that? Please read the rest of the paragraph.
	48	+
	49	+	When you want to enable the Kubernetes challenges in your CTF-environment, make sure your 'play-environment' is actually running in a Kubernetes environment where the K8ss Configmap, K8s secret, and optionally the Vault setup, are configured correctly. See [our k8s folder](/k8s/) as an example, or have a look at our [Okteto](/okteto/) setup for just having the K8s & Configmap challenges supported.
	50	+	When you take the 2-domain approach, make sure that the decoded K8S Secret entry and the Configmap value are stored correctly in the CTF-platform. If you take the standard HMAC approach instead, make sure that your CTF-scoring-environment has the following environment variables set:
	51	+
	52	+	- `SPECIAL_K8S_SECRET` which should be set to the value stored in your K8S Configmap
	53	+	- `SPECIAL_SPECIAL_K8S_SECRET` which should be set to the value of your K8S Secret.
	54	+	- `vaultPassword` (optionally when having vault setup for your players) which should be set to the value stored inside Vault for challenge 7.
34	55
35	56		### Cloud based CTF
36	57
37		-	TODO as #https://github.com/commjoen/wrongsecrets/issues/372
	58	+	If you are interested in setting up a Cloud-based CTF in AWS, you might want to look at [WrongSecrets CTF party](https://github.com/commjoen/wrongsecrets-ctf-party) instead. Still want to take a different approach than using that? Please read the rest of the paragraph.
	59	+
	60	+	When you take the 2-domain approach, make sure that the decoded K8S Secret entry and the Configmap value are stored correctly in the CTF-platform, next: make sure that the values used for Challenge 9,10 & 11 are stored there correctly as well.
	61	+
	62	+	Note: if you want to support challenge 11 at your CTF: make sure players don't share the same cloud-account together, or make sure that the privilege escalation path can only be done to the given account described in the challenge code and not to a role/user with more administrative access, as this would allow your players to wreak havoc to your CTF setup. We rather recommend disabling challenge 11 in your CTF setups.
	63	+
	64	+	If you take the 3 domain setup, make sure the following values are configured in your CTF-scoring-environment:
	65	+
	66	+	- `default_aws_value_challenge_9` set to the value of the secret generated for challenge 9. Don't be fooled by the name, as this will work for AWS/GCP/Azure.
	67	+	- `default_aws_value_challenge_10` set to the value of the secret generated for challenge 10. Don't be fooled by the name, as this will work for AWS/GCP/Azure.
	68	+	- `default_aws_value_challenge_11` (Optionally, when you have separated cloud accounts or took care of permissiosn boundaries) set to the value of the secret generated for challenge 11. Don't be fooled by the name, as this will work for AWS/GCP/Azure.
38	69