Detailed instructions for adding a 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://jakarta.apache.org/site/downloads/downloads_ecs.cgi.
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.*;

// Add copyright text - use text from another lesson 

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.
		makeSuccess(s);

	}
	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 test the lesson by
starting the Tomcat server (within Eclipse). See the
"readme.txt" document in the WebGoat root.

	
Step 5: Create the lesson plan

All WebGoat lessons have a lesson plan that describes the goals of the lesson.
Create a lesson plan and put it in lesson_plans folder for each supported language.


Step 6: 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.
