git-svn-id: http://webgoat.googlecode.com/svn/trunk@11 4033779f-a91e-0410-96ef-6bf7bf53c507

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.