View source for 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.

[[File:FigOwaspZapBirt.jpg]]
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. 

[[File:Alertowaspzap.PNG]]
 
Figure: Alert Tab from owaspzap

[[File:Dummyxmloutput.png]]
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. 

[[File:Extension_example.gif]]

== 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.

[[File:Reportsmenuzap.png]]


= 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
 [[File:ReportDraftowaspzap.GIF]]

== 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:

 [[File:PrototypeReportAPIowaspzap.GIF]]

 [[File:GenerateReportsHMLTandPDF.GIF]]

= Progress 2nd Phase: Integration with OWASP ZAP – FIRST PART (27 June - 7th 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

==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  with Simon about this particular issue.It seems that this Jar is not been used by OWASP ZAP, however, the way extentions Add on works, shoudl allow us to set the library in the extention of the packege we have created for the BIRT project. 

[[File:library.png]]

==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

 public void executeBirtPdfReport(String reportDesign)
	{
		try {
			EngineConfig config = new EngineConfig();			
			Platform.startup(config);			
			ReportEngine engine = new ReportEngine(config);			
			IReportRunnable reportRunnable = 
                        engine.openReportDesign(reportDesign);
			IRunAndRenderTask runAndRender =        
                        engine.createRunAndRenderTask(reportRunnable);
			
			PDFRenderOption option = new PDFRenderOption();
			option.setOutputFileName("C:/TEMP/output_test.pdf");
			option.setOutputFormat("PDF");
			runAndRender.setRenderOption(option);
			
			runAndRender.run();
			
			runAndRender.close();
			engine.destroy();
			Platform.shutdown();
		} catch (EngineException e) {
			e.printStackTrace();
		} catch (BirtException e) {
			e.printStackTrace();
		}