diff --git a/ webgoat/main/project/JavaSource/doc/New Lesson Instructions.txt b/ webgoat/main/project/JavaSource/doc/New Lesson Instructions.txt new file mode 100644 index 000000000..123a45888 --- /dev/null +++ b/ webgoat/main/project/JavaSource/doc/New Lesson Instructions.txt @@ -0,0 +1,204 @@ +How to write a new WebGoat lesson + +All you have to do is implement the abstract methods in LessonAdapter. +Follow the outline below. + +WebGoat uses the Element Construction Set from the Jakarta project. +You should read up on the API for ECS at +http://www.peerfear.org/alexandria/content/html/javadoc/ecs/HEAD/index.html. +In addition you can look at the other lessons for examples of how to use the ECS. + + + +Step 1: Set up the framework + + import java.util.*; + import org.apache.ecs.*; + import org.apache.ecs.html.*; + + /** + * Copyright (c) 2002 Free Software Foundation developed under the + * custody of the Open Web Application Security Project + * (http://www.owasp.org) This software package is published by OWASP + * under the GPL. You should read and accept the LICENSE before you + * use, modify and/or redistribute this software. + * + * @author jwilliams@aspectsecurity.com + * @created November 6, 2002 + */ + public class NewLesson extends LessonAdapter + { + + protected Element createContent(WebSession s) + { + return( new StringElement( "Hello World" ) ); + } + + public String getCategory() + { + } + + protected List getHints() + { + } + + protected String getInstructions() + { + } + + protected Element getMenuItem() + { + } + + protected Integer getRanking() + { + } + + public String getTitle() + { + } + } + + + +Step 2: Implement createContent + +Creating the content for a lesson is fairly simple. There are two main parts: + (1) handling the input from the user's last request, + (2) generating the next screen for the user. +This all happens within the createContent method. Remember that each lesson +should be handled on a single page, so you'll need to design your lesson to +work that way. A good generic pattern for the createContent method is shown +below: + + // define a constant for the field name + private static final String INPUT = "input"; + + protected Element createContent(WebSession s) + { + ElementContainer ec = new ElementContainer(); + try + { + // get some input from the user -- see ParameterParser for details + String userInput = s.getParser().getStringParameter(INPUT, ""); + + // do something with the input + // -- SQL query? + // -- Runtime.exec? + // -- Some other dangerous thing + + // generate some output -- a string and an input field + ec.addElement(new StringElement("Enter a string: ")); + ec.addElement( new Input(Input.TEXT, INPUT, userInput) ); + + // Tell the lesson tracker the lesson has completed. + // This should occur when the user has 'hacked' the lesson. + getLessonTracker( s ).setCompleted( true ); + + } + catch (Exception e) + { + s.setMessage("Error generating " + this.getClass().getName()); + e.printStackTrace(); + } + return (ec); + } + +ECS is quite powerful -- see the Encoding lesson for an example of how to use +it to create a table with rows and rows of output. + + +Step 3: Implement the other methods + +The other methods in the LessonAdapter class help the lesson plug into the overall +WebGoat framework. They are simple and should only take a few minutes to implement. + + public String getCategory() + { + // The default category is "General" Only override this + // method if you wish to create a new category or if you + // wish this lesson to reside within a category other the + // "General" + + return( "NewCategory" ); // or use an existing category + } + + protected List getHints() + { + // Hints will be returned to the user in the order they + // appear below. The user must click on the "next hint" + // button before the hint will be displayed. + + List hints = new ArrayList(); + hints.add("A general hint to put users on the right track"); + hints.add("A hint that gives away a little piece of the problem"); + hints.add("A hint that basically gives the answer"); + return hints; + } + + protected String getInstructions() + { + // Instructions will rendered as html and will appear below + // the area and above the actual lesson area. + // Instructions should provide the user with the general setup + // and goal of the lesson. + + return("The text that goes at the top of the page"); + } + + protected Element getMenuItem() + { + // This is the text of the link that will appear on + // the left hand menus under the appropriate category. + // Their is a limited amount of horizontal space in + // this area before wrapping will occur. + + return( "MyLesson" ); + } + + protected Integer getRanking() + { + // The ranking denotes the order in which the menu item + // will appear in menu list for each category. The lowest + // number will appear as the first lesson. + + return new Integer(10); + } + + public String getTitle() + { + // The title of the lesson. This will appear above the + // control area at the top of the page. This field will + // be rendered as html. + + return ("My Lesson's Short Title"); + } + + +Step 4: Build and test + +Once you've implemented your new lesson, you can use ant to build and deploy +your new web application. First you want to remove the webgoat .war *AND* +the webgoat directory from your webapps directory. Then, from your webgoat +directory, type: + + > ant install + +This will compile your new lesson and "install" the path into Tomcat. +You only need to "install" once. If you make changes to the web application +and want to test them, you can use: + + > ant reload + + + + +Step 5: Give back to the community + +If you've come up with a lesson that you think helps to teach people about +web application security, please contribute it by sending it to the people +who maintain the WebGoat application. + +Thanks! + +The WebGoat Team. diff --git a/ webgoat/main/project/JavaSource/doc/WebGoatv4UsersGuide_DRAFT.doc b/ webgoat/main/project/JavaSource/doc/WebGoatv4UsersGuide_DRAFT.doc new file mode 100644 index 000000000..23c11538c Binary files /dev/null and b/ webgoat/main/project/JavaSource/doc/WebGoatv4UsersGuide_DRAFT.doc differ