How to Create a Web Shepherd Level

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. This page tells a user what they have to do, revels hints and when the level is a lesson (First time a user encounters this type of security risk), it contains a description of the vulnerability. To Create this, 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. This will be the name shown in the page and what will be entered into the logs as players access it.
4. You must go to the Create a Level Entry wiki page to get the levelHash parameter information
5. You can fill in the level information in the levelBlurb parameter if you like, or you can go down to the "contentDiv"
   element to write your own HTML.
6. 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)
7. If calling a Servlet, Take note of what URL you are defining the javascript ajax call. You will need to use this in the servlet-mapping stage
8. 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.

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. 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.
6. If you wish to return user specific keys (Recommended where ever possible), use the template example.
7. 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.
8. Once you have finished coding and your logic is sound, open the owaspSecurityShepherd\SecurityShepherdCore\site\WEB-INF directory
9. 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>

10. After adding this information you can now test your Servlet. If you get a 404 error when trying to access the servlet, it is likely what your browser or client are attempting to access does not specifically match

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;

4. 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)
5. Enter the following information into the file;

databaseConnectionURL=challengeSchemaName
databaseUsername=creativeName
databasePassword=somePasswordHere

6. Run the moduleSchemas.sql file on your database
7. Build the Shepherd application
8. 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