GSoC2013 Ideas/OWASP ZAP Exploring Advanced reporting using BIRT

= Abstract = OWASP ZAP (Zed Attack Proxy) is an open source penetration testing tool for finding vulnerabilities in web applications. The ZAP application’s current report capability is to generate limited types of reports for ZAP testing results in the formats such as in HTML and XML. Although these reports serve the basic purpose but they are not efficient when it comes to data manipulation and to provide support for flexible data formats such as PDF.

The proposed project shall provide the users of ZAP, a reporting module that will be integrated with the existing ZAP implementation. The module will use the existing ZAP result outputs and generate reports for the end-users to analyse the testing results in a productive way. Objectives:
 * Installed and Configured BIRT environment to be used in Eclipse OWASP ZAP project.
 * Be able to generate reports from the application using the BIRT report engine API.
 * Creation of prototype reports regarding the results output of the Sessions & attacks such as: Alerts, History, Search etc.
 * A new user interface for generating reports which is easy to use and provides the user with a wide range of options.
 * Analysis report of the pros-and cons of using BIRT within OWASP ZAP as a reporting tool.

= Work breakdown structure with Timeline and expected results =

Introduction
The current reporting module in ZAP is capable to generate limited types of reports on the results produced by ZAP e.g., in HTML and XML formats. Although these reports serve the basic purpose but they are not efficient when it comes to data manipulation and to provide support for flexible data formats such as PDF.

The proposed project shall provide the users of ZAP, a reporting module that will be integrated with the existing ZAP implementation. The module will use the existing ZAP result outputs and generate reports for the end-users to analyze the testing results. The report structure shall be designed by using BIRT RCP Report Designer.

BIRT (The Business Intelligence and Reporting Tools) project is an open source software project that provides reporting and business intelligence capabilities for rich client and web applications.

In relation to this project, there are two main components of BIRT:
 * A report designer within the Eclipse IDE for creating BIRT Report prototypes.
 * A runtime component (BIRT Report Engine API) for generating reports that can be deployed to OWASP ZAP.
 * Proposed Solution and Implementation

The proposed solution consists of the following three stages:

1. Create a Reporting Module Develop a reporting module using BIRT Report Engine API. This module shall be able to generate reports within OWASP ZAP. The Report Engine API is a part of the package "org.eclipse.birt.report.engine.api". This API shall provide the most commonly used functionality for the proposed module. The module shall use the "ReportEngine" class of the API for generating reports.

2. Design Report structure Several report prototypes for various ZAP result outputs shall be designed using the BIRT RCP Report Designer application. It is a standalone tool that is used to build a BIRT report design and preview a report. The prototypes, created by the tool, will be used by the proposed Reporting module to display the reports for ZAP output results.

3. Create a Data source OWASP ZAP shall produce XML results which will be fed into the proposed BIRT reporting module. The reporting module shall read it as a data source to generate reports. XML output is generated by the ZAP namespace “org.parosproxy.paros.extension.report”

System Context Diagram The following diagram shows the high level system context diagram within ZAP.

Figure: System context diagram.

= Progress First phase(June 22, 2013) =

Prototype project using the Reporting Engine API
Rauf has created a prototype. This prototype contains the reporting engine API with a sample report. The next challenge with the prototype consist in using a XML generated output data source from OWASP ZAP and how to use this XML output to render the first report.

The Actual OWASP ZAP xml output comes from data on the alerts tab.

Figure: Alert Tab from owaspzap

Figure: XML output generated by OWASP ZAP

UNIT tests prototype
Rauf will be working on UNIT test to make sure the prototype has the proper error handling.

Extending OWASP ZAP with new reporting module
We are researching the best way to integrate this new module into OWASP ZAP. The first part of this is by creating a new extension as explained in

https://code.google.com/p/zap-extensions/wiki/Examples

Once the prototype is working properly, the code will be integrated in the new extension module as shown the following figure.



Source Code repository
Once the prototype code is integrated into OWASP ZAP.

the code will be set up into a ZAP dev environment: http://code.google.com/p/zaproxy/wiki/Building

Creating new reporting module as an ADD-ON
We will consult with Simon Bennets(project leader) on the best alternative to whether create a new menu, or keep the Reports one and create a new sub-menu.



= Progress First phase(June 27, 2013) =

First Draft Report using OWASP xml generated output
Using a ready to run instance of Eclipse Juno with BIRT plugins installed in it,Raul was able to create a BIRT draft report using the xml generated output from OWASP ZAP as the xml data source. This report still needs improvements in layout and design. CSS can be used for this part to enhace the look and feel of reports. Next week we will be concentrating on creating a nice CSS for the reports

Prototype running the BIRT report API with the created report
Implementation of the Report API is the coolest part of the project. Indeed running the report from a prototype project provided us with the possibility to create reports in multiple formats. By using HTML or PDF render options, we can create 2 reports at once as shown in the code:





= Progress 2nd Phase: Integration with OWASP ZAP(27 June - 10th July, 2013)= During this phase we have focused on integrating the code with OWASP ZAP. The challenges in this phase are:
 * Understand how extensions work within OWASP ZAP
 * Library structure
 * Flow and interaction with the user
 * New Design Report Alerts

Understand how extensions work within OWASP ZAP
For this part, the extensions examples was of great help. Rauf practiced using both examples(TopMenu & RightClickMenu) and he was able to complete this part. By implementing these examples, Rauf was able to understand how the extensions work and create an extension for the BIRT module

Library Structure
BIRT Report API contains many JAR files. One, js.jar conflicts with the existing one in OWASP ZAP library. For this part we replaced the old one with the one from BIRT engine and the OWASP ZAP code was able to build and run without issues. We asked Simon about this particular issue.It seems that this Jar is not been used by OWASP ZAP, however, the way extentions and Add-on works, should allow us to set the library in the extension of the package we have created for the BIRT project.



Integrating the rough prototype
For the purpose of testing the integration : A new package “org.zapproxy.extension.birtreports” was created 2 classes were added as seen here including the Message.properties file On the ReportLastScan.java (which is a ripoff of the same ReportLastScan from paros.extension) we added a new method

On the BirtTopMenu.java class we call the method:

Then we run OWASP ZAP

Report is generated and saved on the hard-coded location in the code

Work-flow and UML classes - Interaction with the user
One of the upcoming tasks for Rauf consists in creating a better flow for interacting with the user The work flow must answer to questions such as:


 * Will a user be allowed to define a report? (he could pass is as a parameter, in the future a user could create his own reports to be generated from XML data-source the TEMP HSQL database?)
 * The report is using an XML data source generated from OWASP ZAP. The source path must be defined and must be a relative path when OWASP ZAP is installed. Propose a clear method to do this
 * The user should have the option to define the output path in his drive to save the generated PDF/HTML report
 * BIRT engine supports multiple formats :HTML, Paginated HTML, PDF, WORD, XLS, and PostScript . Do we create Menu items for each one?
 * Implement Exceptions and messages to interact with the user once reports are generated
 * Create Unit tests

New Design
For this section a new style needs to be defined to be used with the reports. We will propose 2 designs and users can vote for selection.

Right now this is the first version. Charts are also generated by BIRT, creating a summary of the alerts xml output.

=Progress 2nd Phase (10th July - 18th July 2013) =

Redefine prototype workflow
Rauf created a workflow which we discussed. The original workflow was missing a clear integration based on how the code works and how OWASP ZAP generates an XML file. The following represents the actual flow built in the code after Rauf did the correct representation and understood how OWASP ZAP generates the Alert data and later on generates an XML file.