Skip to content

How to Create a Web Shepherd Level

Jump to bottom
ismisepaul edited this page Sep 23, 2015 · 18 revisions

This wiki page will attempt to guide new Shepherd contributors in the effort of creating a Web Based level with View, Controller and Model type functionality. Where each piece operates the following type functionality;

  1. View
    The view can be a web page, a mobile application or both. You could write a level that is simply one View, which stores a hard coded key for the user to find. Most mobile levels have two views, the Web page with instructions on the Shepherd Web Server and the Android Application.
  2. Controller
    The Controller is a Java Servlet that operates on the Shepherd Server. They are accessed by clients via url-mapping defined in the Shepherd Server's web.xml file. Many levels are made up of a View/Controller combo, with hardcoded base-keys which are made user specific when players complete the level.
  3. Model
    Not all levels in Security Shepherd offer model functionality, but it can be done. If a level needs a database, the schema is written and added to the moduleSchemas.sql file and a user defined for it. This user has READ ONLY access to the specified schema. It's not recommended to give any other permissions to the user without great care.

This wiki page will detail how to craft these aspects of a level.

How To Create a View

Every level in Security Shepherd needs a .jsp page and a corresponding .properties file. The JSP page does the following;

  • Informs a user on what they have to do
  • Reveals hints if the level is a lesson (i.e. First time a user encounters this type of security risk)
  • Contains a description of the vulnerability.
  • Contains i18n references that correspond to text in the properties files.

The .properties file holds all the text that you display to your user on the webpage. They are in the form of key value pairs used for translating your level. The default properties file should be in English for example text.properties where corrisponding languages are a copy of this file with an underscore and language code e.g. for Irish text_ga.properties.

To find your language use this [ISO 639-1 Codes] (https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). The keys in the properties file should remain the same where the values are the translation of the English text.

To Create a JSP page with the corresponding .properties file use the following steps;

  1. Open the directory "owaspSecurityShepherd\SecurityShepherdCore\src\jsp" in your local git repository
  2. Open the WebLevelTemplate.jsp or MobileLevelTemplate.jsp file, depending on which you are making
  3. Fill in the levelName parameter which is the name that will be entered into the logs as players access it. This should be in English.
  4. You must go to the Create a Level Entry wiki page to get the levelHash parameter information. Put this hash value into the levelHash string.
  5. Once you have the levelHash you can now create the properties file by firstly locating the i18n folder under src.
  6. Depending on whether you level is a lesson or a challenge create a file under that package. The structure breaks down further into level categories. So for instance if you're creating an XSS level put your file under the XSS package. The file name should be the levelHash, if you have a translation from Englsih see this guide on creating a translation properties file https://github.com/OWASP/SecurityShepherd/wiki/Adding-a-new-Language-to-Shepherd
  7. If your .jsp is going to call a Controller on the web server, you can uncomment the form/javascript examples on how to do so starting at line 69 (This is unlikely to be necessary if you are making a mobile level)
  8. When calling a Servlet take a note of what URL you are defining the javascript ajax call. You will need to use this in the servlet-mapping stage
  9. When you have completed the view save the file as the levelHash.jsp (The hash you recovered from step 4) and put it in the Challenge or Lesson directory depending on which you have defined in step 4.
  10. All the text in your level should be stored in the corresponding properties file. Your JSP should contain the .properties file key e.g. bundle.getString("title.question.xss") which references the text value that will be displayed to the user please refer to this wiki page for information https://github.com/OWASP/SecurityShepherd/wiki/Adding-a-new-Language-to-Shepherd

How to Make a Controller

The controller of a level is the brain of a level. This is most likely going to be the logic which the users will be attempting to exploit. To create this, use the following steps;

  1. Open the Directory owaspSecurityShepherd\SecurityShepherdCore\src\servlets\module
  2. Open the file ModuleServletTemplate.java
  3. Update the moduleName, moduleHash and moduleResult to match your DB settings.
  4. Skip down to line 76, and add in the code you need to get the data submitted by the user in from the View portion of this level
  5. If there is any text you want to display to the user please create a .properties file under i18 -> servlets -> challenge -> "appropriate category". Do not put text that will be displayed to the user into the servlet. For more information consult the Adding a New Language to Shepherd
  6. You can access the model from here as well, the template covers how, but the next section of this wiki will detail how to create it.
  7. If you wish to return user specific keys (Recommended wherever possible) use the template example.
  8. If your level has a hardcoded key make sure it is the same in the level as it is in the DB. Also ensure the hardcoded flag is set in the module database entry in the core database.
  9. Once you have finished coding and your logic is sound, open the owaspSecurityShepherd\SecurityShepherdCore\site\WEB-INF directory
  10. Add the following infrormation to the XML file, updating the levelhash to the module level hash, ServletClassName to the servlet class name and "challenges" to "lessons" if necessary;

<servlet>
<servlet-name>/challenges/levelhash</servlet-name>
<servlet-class>servlets.module.challenge.ServletClassName</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>/challenges/levelhash</servlet-name>
<url-pattern>/challenges/levelhash</url-pattern>
</servlet-mapping>

  1. After adding this information you can now test your Servlet. If you get a 404 error when trying to access the servlet please verify the values you entered in the web.xml match the resource your browser is trying to call.

How to make a Model

Model is the server side database. Follow these steps to make one and get your level to access it

  1. Open the owaspSecurityShepherd\SecurityShepherdCore\database\moduleSchemas.sql file
  2. Add a mySql Schema to it containing your level's database structure
  3. At the end of the file add a user with READ ONLY access like so;

DROP USER creativeName@'localhost';
CREATE USER creativeName@'localhost' IDENTIFIED BY somePasswordHere;
GRANT SELECT ON challengeSchemaName.challengeTableName TO creativeName;

  1. Then open the owaspSecurityShepherd\SecurityShepherdCore\site\WEB-INF\challenges directory and create a .properties file (You will have to call this properties file in your controller)
  2. Enter the following information into the file;

databaseConnectionURL=challengeSchemaName
databaseUsername=creativeName
databasePassword=somePasswordHere

  1. Run the moduleSchemas.sql file on your database
  2. Build the Shepherd application
  3. You're level should now be calling the DB

IF YOU MUST HAVE UPDATE PRIVILEGES ON YOUR SCHEMA FOR PLAYERS, PRACTISE EXTREME CAUTION AND BE AWARE OF RACE CONDITIONS

Clone this wiki locally