OWASP Stinger Manual

From OWASP
Revision as of 12:34, 23 September 2006 by Esheridan (Talk | contribs)

Jump to: navigation, search

Contents

Overview

The purpose of the OWASP Stinger manual is to provide users a comprehensive guide to developing upon and deploying the OWASP J2EE Stinger filter. If you have any comments or suggestions concerning the Stinger manual, please to not hesitate to email me at eric.sheridan@owasp.org.

Development

Deployment

Actions

AbstractAction

Description

Developing your own action is relatively straight forward within Stinger. To implement a custom class, simply extend the AbstractAction class and implement the abstract doAction method. For more information related to building custom actions, please refer to the development section.

Source Code

public abstract class AbstractAction {
	
	private HashMap<String, String> parameters = new HashMap<String, String>();
	
	public String getParameter(String name) {
		return parameters.get(name);
	}
	
	public void setParameter(String name, String value) {
		parameters.remove(name);
		parameters.put(name, value);
	}
	
	public abstract void doAction(Violation violation, MutableHttpRequest request, 
                                     MutableHttpResponse response) throws  BreakChainException;
}

ClearCookies

Description

As the name implies, the ClearCookies action will set the maximum age of every cookie in the request to 0; effectively clearing all cookies for the session.

Parameters

The ClearCookies action currently does not accept any parameters.

Source Code

public class ClearCookies extends AbstractAction {
	
	public void doAction(Violation violation, MutableHttpRequest request, MutableHttpResponse response) {
		Cookie[] cookies = null;
		
		cookies = request.getCookies();
		
		if(cookies != null) {
			for(int i=0; i<cookies.length; i++) {
				cookies[i].setMaxAge(0);
			}
		}
	}
}

DisplayMessage

Description

When a violation occurs, the DisplayMessage action can be configured to display a custom message to the user. This message currently resides at the top of the response in an HTML table format.

Parameters

The DisplayMessage action currently accepts two parameters.

message - the message to be displayed back to the user upon finding a violation
bgcolor - the background color of the HTML table

Source Code

public class DisplayMessage extends AbstractAction {
	
	public String formatMessage(String message, String bgcolor) {
		StringBuffer buffer = new StringBuffer();
		
		buffer.append("<table width=300 border=1 align=center bgcolor=" + bgcolor + " cellpadding=2\n");
		buffer.append("<tr><td>\n");
		buffer.append("<div align=\"center\" >" + message + "</div>\n");
		buffer.append("</td></tr></table>\n");
		
		return buffer.toString();
	}
	
	public void displayMessage(MutableHttpResponse response, String message, String bgcolor) {
		PrintWriter out = null;
		String formatedMessage = formatMessage(message, bgcolor);
		
		out = response.getWriter();
		out.write(formatedMessage);
	}
	
	public void doAction(Violation violation, MutableHttpRequest request, MutableHttpResponse response) {
		String message = getParameter("message");
		String bgcolor = getParameter("bgcolor");
		
		displayMessage(response, message, bgcolor);
	}
}

Drop

Description

The Drop action simply throws the BreakChainException when called. This effectively prevents the HTTP request from ever reaching the web application.

Parameters

The Drop action currently accepts one parameter:

message - the message to be displayed in the exception stack trace. This message is never displayed to the user.

Source Code

public class Drop extends AbstractAction {
	
	public void doAction(Violation violation, MutableHttpRequest request,
                            MutableHttpResponse response) throws  BreakChainException {
		String message = getParameter("message");
		
		/** Let the user define the message to be displayed in the exception **/
		throw new BreakChainException(message);
	}
}

Invalidate

Description

If the session object exists, then it will be invalidated by this action. This action is considered more severe and should be deployed only when an obvious attack occurs. For example, cookie values are rarely tampered with by the client side code (i.e. javascript). Therefore, we can (safely?) assume that any cookie modification is considered a deliberate attack.

Parameters

The Invalidate action currently accepts no parameters.

Source Code

public class Invalidate extends AbstractAction {
	
	public void doAction(Violation violation, MutableHttpRequest request, MutableHttpResponse response) {
		HttpSession session = null;
		
		session = request.getSession(false);
		
		if(session != null) {
			session.invalidate();
		}
	}
}

Log

Description

As the name implies, we can log any and every request sent to the web application. The Log action is an essential action and should be heavily implemented in Stinger deployment.

Parameters

The Log action currently accepts 3 parameters:

log - the log file where the message should be recorded
level - the level of the log message (i.e. INFO, SEVERE, etc.)
message - the message which shall be logged. The message parameter itself accepts 3 format parameters.
          These include the offender's ip address, the offender's remote port, the parameter/cookie name,
          the parameter/cookie value, and the JSESSIONID. The format strings are %ip, %port, %name, %value, %js respectively.

Source Code

public class Log extends AbstractAction {
	
	private static Logger logger = Logger.getLogger("org.owasp.stinger.actions.Log");
	
	private static HashMap<String, FileHandler> handlers = new HashMap<String, FileHandler>();
	
	public Log() {
		
	}
	
	public void doAction(Violation violation, MutableHttpRequest request, MutableHttpResponse response) {
		FileHandler handler = null;
		String log = getParameter("log");
		String level = getParameter("level");
		String message = getParameter("message");
		
		/** Offender's IP **/
		message = message.replace("%ip", request.getRemoteAddr());
		/** Offender's Port **/
		message = message.replace("%port", String.valueOf(request.getRemotePort()));
		/** Offending parameter name **/
		if(violation.getName() != null) {
			message = message.replace("%name", violation.getName());
		} else {
			message = message.replace("%name", "NULL");
		}
		/** Offending parameter value **/
		if(violation.getValue() != null) {
			message = message.replace("%value", violation.getValue());
		} else {
			message = message.replace("%value", "NULL");
		}
		/** Offender's JSESSIONID **/
		if(request.getCookie("JSESSIONID") != null) {
 			message = message.replace("%js", request.getCookie("JSESSIONID").getValue());
		} else {
			message = message.replace("%js", "NULL");
		}
		
		handler = getHandler(log);
		logger.addHandler(handler);
		
		logger.log(Level.parse(level.toUpperCase()), message);
		handler.flush();
		
		logger.removeHandler(handler);
	}
	
	private synchronized FileHandler getHandler(String log) {
		FileHandler handler = null;
		
 		handler = handlers.get(log);
		
		if(handler == null) {
			try {
				handler = new FileHandler(log);
			} catch (IOException ioe) {
				ioe.printStackTrace();
			}
			
			handlers.put(log, handler);
		}
		
		return handler;
	}
}

Redirect

Description

The Redirect action redirect's a user to a specific page. This action is often used to send a user to an error message upon finding a violation.

Parameters

The Redirect action currently accepts 1 parameter:

page - the page to redirect the user to

Source Code

public class Redirect extends AbstractAction {
	
	public void doAction(Violation violation, MutableHttpRequest request,
                            MutableHttpResponse response) throws  BreakChainException {
		String page = getParameter("page");
		
		try {
			response.sendRedirect(page);
		} catch (IOException ioe) {
			ioe.printStackTrace();
		}
	}
}

Feedback and Participation

We hope you find Stinger useful. Please contribute back to the project by sending your comments, questions, and suggestions to the Stinger mailing list. Thanks!

To join the OWASP Stinger mailing list or view the archives, please visit the subscription page.

Project Sponsors

The Stinger project is sponsored by aspect_logo.gif.