Developer Getting Started Guide for WebGoat

This page is for tips and tricks for developers who want to build WebGoat themselves and think about contributing to WebGoat.

Basic understanding

Development and test of WebGoat can be done on Microsoft Windows, Apple MacOS or a Linux based OS. WebGoat is finally packaged and released as Java jar files and docker containers on Docker Hub. The end result should be runnable on all of the mentioned operating systems.

WebGoat also supports multiple languages. The unit tests and integration tests should be able to handle localisation and user zone settings.

Travis is used to test code that is pushed to GitHub. Everyone with a GitHub account can contribute by creating a fork of WebGoat, then create a branch off of develop in their local repository and making a cross repository pull request. This will trigger the Travis build. Pull requests require that a contributor signs an agreement. Otherwise the pull request can never be merged.

Pre-requisites

  • Windows, MacOS, Linux operating system
  • Maven 3.5 or higher
  • Java 11 up to Java 13 (which are both tested in the Travis build)
  • An IDE will be handy: e.g. Visual Studio Code, Eclipse or IntelliJ. Make sure that the IDE has the extensions to support Lombok.
  • (optionally) docker (e.g. Docker Desktop for Windows, MacOS)
  • Browser to test manually: Safari, Firefox, Chrome, Edge

Free ports

When you build or run the application with default settings make sure that the following ports are not in use:

  • 8080
  • 9001
  • 9090

Building from Maven

git clone https://github.com/yourgitaccount/WebGoat.git
cd WebGoat
git checkout -b yourbranch
mvn clean install

Default components

The Java build results in two ‘executable’ jar files:

  • WebGoat in webgoat-server/target
  • WebWolf in webwolf/target

Run WebGoat from generated jar

java -jar webgoat-server/target/webgoat-server-v8.2.0-SNAPSHOT.jar

This starts WebGoat with the UI on http://127.0.0.1:8080/WebGoat And an hsql database on port 9001 which has persistent data stored in .webgoat folder.

Run WebWolf from generated jar

java -jar webwolf/target/webwolf-v8.2.0-SNAPSHOT.jar

This starts WebWolf with an UI on http://127.0.0.1:9090/WebWolf whixh is connected to the database on port 9001

First time usage

When you open WebGoat for the first time, you will see the login screen. If you do not have a username and password, then you can use the register function to create a new user. As long as you do not delete the .webgoat folder that username and your results will be present when you use it the next time. Even if you stop and start the application.

Project structure

At the root level there is a overall parent pom.xml which contains all the references to all components of WebGoat and WebWolf. Below this level there are a few main folders:

  • webgoat-container
    • A maven java project that contains the core or framework of the WebGoat application
    • application-webgoat.properties is the main property file used for Spring Boot
  • webgoat-lessons
    • Folder that contains a lot of sub maven project folders, where each folder is a lesson on its own
  • webgoat-server
    • Contains the Spring Boot application for WebGoat
    • org.owasp.webgoat.StartWebGoat.java is the main class
  • webwolf
    • Contains the Spring Boot application for WebWolf
    • org.owasp.webwolf.WebWolf.java is the main class
    • application-webwolf.properties is the main property file for Spring Boot
  • webgoat-integration-tests

Building your own WebGoat lesson

WebGoat comes with an built-in lesson on how to build your own WebGoat lesson. Make sure you first complete this exercise before you try to add a new lesson.

Building a MongoDB topology using MMS automation

As mentioned in previous blogs the reference application can use MongoDB.
For this a MongoDB database needs to be set up. You can do this in any number of ways:

  1. Download the software on your server, start the mongod process and configure your application with the connection details
  2. Get MongoDB as a SaaS service from MongoLab or other providers, followed by the same steps

If you decide to build your own database, you can do so by configuring everything manually or using scripts, however you can also choose to use MMS as a kind of SaaS solution for managing your MongoDB environment. This can be done on private clouds/networks using your own dedicated MMS solution, or in the public cloud.

The picture below shows such an environment:
MongoDB topology

Using MMS to set up this complex topology is quite simple:

  1. Start by installing the automation agents. These will then connect to the mms.mongodb.com environment using some shared secrets that have been configured for your account. This will make these agents appear on your account.
  2. Then use the web interface of MMS to install monitor agents and/or backup agents and everything else that you need: standalone servers, sharded clusters etc.

The automation agents will automate all the deployment and installation tasks needed, such as:

  • downloading software of the desired version
  • upgrading versions of the agents and databases
  • configuring security
  • creating & changing clusters

Without MMS, I would have needed much more time to set up such a cluster. The alternative is to go SaaS all the way, where you don’t care anymore about how and where it is installed. In that case MongoLab solutions or the MongoLab within Bluemix solution is a good choice as well.

For now I think that using MMS in combination with your own infrastructure is a very good choice. And using a private MMS would be even better from a security and trust/privacy point of view.

Content Security Policy, browsers and angularJS

In order to protect your application on the client side, content security filtering (CSP) has been introduced. It is basically an HTTP Header added by your web application to instruct a browser to handle content in a certain secure way.

Unfortunately, as it is dependent on the browser technology, not all browsers support CSP and not all browsers act on the same HTTP Header. However, for most recent browsers you can improve your overall security by introducing CSP. Older browsers will not use this additional safety.

With CSP enabled, you can instruct the browser to only allow JavaScript from trusted and file based resources. Disallowing inline JavaScript. The same applies for stylesheets and in-line styles.

You can enable CSP fully or in reporting mode. Fully means that the browser will block all non-allowed elements. In reporting mode, means that the browser will send reports back to the server of all things that are not allowed. These reports are posted in to a REST service hosted by your application. This is a nice way for developers to test their application and see whether or not everything works fine with CSP enabled.

Enabling CSP & AngularJS

Enabling CSP has impact on the frameworks you are using. Suppose you are using AngularJS and/or BootStrap. Then you might need to set up things a bit different.

In AngularJS 1.3.9 you need to include a stylesheet angular-csp.css seperately. Also, you should add ng-csp as an attribute in your html tag.

Then start debugging in your browser to see what goes wrong and should be changed in your application to make it more safe.

HTTP Headers

The HTTP Headers you should provide are at least the following:

  • Content-Security-Policy
  • X-Content-Security
  • Content-Security-Policy
  • X-WebKit-CSP

The values can be the same for each header, but this will cover most browsers. -Report-Only can be added in reporting mode.

More info

For more info see the official web sites on CSP and check out sample implementations on OWASP.

You should start using CSP early in your project development. Because it will be hard to fix all non compliant issues later on.