Difference between revisions of "ESAPI Documentation"

From OWASP
Jump to: navigation, search
(Larger Documents)
(Larger Documents)
Line 35: Line 35:
 
''Getting Started Guide''
 
''Getting Started Guide''
 
  Audience: Developers new to ESAPI<br>
 
  Audience: Developers new to ESAPI<br>
  Purpose: Explain to these developers how to start immediately using ESAPI<br>
+
  Purpose: Explain to these developers how to start immediately using ESAPI
Outline:<br>
+
Outline: (20 pages or less)<br>
 
* Overview of ESAPI
 
* Overview of ESAPI
 
* How to download, install, get dependencies
 
* How to download, install, get dependencies
Line 46: Line 46:
 
''How to Secure an Existing Application with ESAPI''
 
''How to Secure an Existing Application with ESAPI''
 
  Audience: Developers<br>
 
  Audience: Developers<br>
  Purpose: Explain to developers how to address most of the common security problems in an existing application using ESAPI<br>
+
  Purpose: Explain to developers how to address most of the common security problems in an existing application using ESAPI
 
Outline:<br>
 
Outline:<br>
 
* Similar to previous, except it goes through all major areas where ESAPI provides controls, not just the top 5.
 
* Similar to previous, except it goes through all major areas where ESAPI provides controls, not just the top 5.
Line 52: Line 52:
 
''How to Use ESAPI in a New Application''
 
''How to Use ESAPI in a New Application''
 
  Audience: Developers
 
  Audience: Developers
  Purpose: Provide application architecture guidance on how to build your applications in a manner that facilitates the use of ESAPI. This should help make it easier to use ESAPI, make your application more secure, easier to analyze, and easier to maintain.
+
  Purpose: Provide application architecture guidance on how to build your applications in a manner that facilitates the use of ESAPI.
  Assumption: This assumes that an ESAPI that works in the developers' environment is already available (either the reference implementation or a customized version).
+
Benefit: This should help make it easier to use ESAPI, make your application more secure, easier to analyze, and easier to maintain.
 +
  Assumption: This assumes that an ESAPI that works in the developers' environment is already available.
 
Outline/Topics:
 
Outline/Topics:
 
* Architectural guidance for each control, if any, on how to take most facilitate the use of ESAPI in your application
 
* Architectural guidance for each control, if any, on how to take most facilitate the use of ESAPI in your application
 
* e.g., use of DAOs, application organizational considerations wrt Access Control, etc.
 
* e.g., use of DAOs, application organizational considerations wrt Access Control, etc.
 +
<br>
 
''How to Create a Custom ESAPI for Your Organization''
 
''How to Create a Custom ESAPI for Your Organization''
  Audience: Organizations and developers that want to use ESAPI
+
  Audience: Organizations and developers that want to use ESAPI<br>
 
  Purpose: How to extend or customize ESAPI for your organization or project
 
  Purpose: How to extend or customize ESAPI for your organization or project
 
Outline:
 
Outline:
Line 66: Line 68:
 
** How to extend this control
 
** How to extend this control
 
** How to replace this control
 
** How to replace this control
 +
 +
Goals: All of this content would be on the wiki, and PDFs of each of these 'may' be produced as well.
  
 
=== Web Pages ===
 
=== Web Pages ===

Revision as of 14:50, 11 December 2008

Contents

Overview

This page documents our current thoughts on the various documents we need to produce for the ESAPI project, and the audience, purpose, and high level outline of each document.

Documentation Plan

Proposed Documents

Smaller Documents

  • ESAPI Executive Overview

Audience: Executives
Purpose: To provide executives with an understanding of:

  • What ESAPI is? Goals.
  • Why an ESAPI is necessary. (App Sec is important/why/standardization)
  • The benefits of using an ESAPI? (Cost, ROI)
  • The current status of ESAPI? (Maturity, Stability, Licensing, Support)
  • Who created it, where it came from, credibility, who is using it?
  • How to adopt an ESAPI?

Outline: (See Purpose)

  • FAQ (For non-users)

Audience: Potential users of ESAPI
Purpose: To provide 'quick' hit, information about ESAPI
Topics: Summary of main points in the Executive Overview

  • FAQ (For people using ESAPI)

Audience (Technical people using ESAPI)
Purpose: To provide 'quick' hit, information about how to use ESAPI, and how to add ESAPI to or integrate ESAPI with your existing security controls. Outline:

  • How to use it the first time
  • Common usage issues
  • Common extension questions
  • Performance


Larger Documents

Getting Started Guide

Audience: Developers new to ESAPI
Purpose: Explain to these developers how to start immediately using ESAPI

Outline: (20 pages or less)

  • Overview of ESAPI
  • How to download, install, get dependencies
  • Where is all the documentation/javadoc
  • Where/what is Swingset - where are the coding examples
  • List of the top 5 quick hits you can achieve with ESAPI
  • Concrete examples of how to accomplish each of these 5 things, with problem descriptions, example problem code, and example code that addresses the problem


How to Secure an Existing Application with ESAPI

Audience: Developers
Purpose: Explain to developers how to address most of the common security problems in an existing application using ESAPI

Outline:

  • Similar to previous, except it goes through all major areas where ESAPI provides controls, not just the top 5.


How to Use ESAPI in a New Application

Audience: Developers
Purpose: Provide application architecture guidance on how to build your applications in a manner that facilitates the use of ESAPI.  
Benefit: This should help make it easier to use ESAPI, make your application more secure, easier to analyze, and easier to maintain.
Assumption: This assumes that an ESAPI that works in the developers' environment is already available.

Outline/Topics:

  • Architectural guidance for each control, if any, on how to take most facilitate the use of ESAPI in your application
  • e.g., use of DAOs, application organizational considerations wrt Access Control, etc.


How to Create a Custom ESAPI for Your Organization

Audience: Organizations and developers that want to use ESAPI
Purpose: How to extend or customize ESAPI for your organization or project

Outline:

  • Overview of related controls, how dependent/independent they are on the rest of the API
  • For each control:
    • Expectations for 'as is' use, extension, replacement of this control
    • How to extend this control
    • How to replace this control

Goals: All of this content would be on the wiki, and PDFs of each of these 'may' be produced as well.

Web Pages

  • Revamp the ESAPI Website
  • How will the ESAPI be updated and released.
  • CWE_ESAPI CWEs addressed by ESAPI - Assigned to Steve Christey
  • Features List


Other Documents