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(student) created a workflow which was discussed with Johanna(mentor). 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.



We presented the prototype to Simon, code was made available to him through DropBox. Simon was able to generate a report. Code will be soon available through Github

Rauf is working on unit tests for the methods created and enhance some bugs in the prototype. Also, he must research if we are able to generate a report on the fly, so no predefined report file is used, but instead, report is created on the fly. This seems possible using the Birt Design API jars, which are already included in the Jar library files. This has lower priorities, but we see the advantages as basically , everything could be generated code wise.

Unit tests and enhacements
In the birtreports package, Rauf did some big fixing and made the function openPDF functional so it opens the PDF after saving the file.

- The testbirt package contains a file that has 4 test cases on the LastReportScan file. We can add more test cases as we proceed that's why Rauf created a separate package(test birt). Rauf used Junit for the test cases.

- The four test cases are: i. To test if the xml file is missing ii. To test if the rptdesign file is missing ii. To test the generation of xml file ii. To test openPDF functionality

Enhancing Alerts report data
One feedback we received from Simon was to generate the data on the following format: Type of Alert:       X-Content-Type-Options header missing Low (Warning)        The Anti-MIME-Sniffing header X-Content-Type-Options was not set to 'nosniff' First 10 examples: URL:https://mydummywebsite/home URL:https://mydummywebsite/etc URL:https://mydummywebsite/login Solution: This check is specific to Internet Explorer 8 and Google Chrome. Ensure each pagesets a Content-Type header and the X-CONTENT-TYPE-OPTIONS if the ContentType header is
 * Each type of alert should only be shown once
 * Where multiple instances occur it would be good to see the first X details shown (where the user can specify X?), eg:

For this part, we can think of different solutions such as:
 * Transform the XML to another XML with the right regrouping using XSLT
 * Create an interface which generates the data we need and use BIRT Scripted data source to generate the reports

Make the extension an Add-On
A lot of information is found on the OWASP ZAP developer Wiki on how to create an add-on, but for new developers working with OWASP ZAP this can be confusing. For this purpose, Johanna (mentor) created a guide step by step on how to create extensions and Add-ons. This is especially handy for developers working for the first time in OWASP ZAP. This guideline is available here: (feel free to comment and feedback!)



Generating BIRT reports in ZAP using scripted data source & Enhancing data in the Alert reports
So far we have been able to create a working prototype as original planned, however,this prototype uses predefined BIRT reports and an XML file as data source. After talking to Simon, he pointed out that there is a more efficient way to Generate reports using BIRT: using a scripted data source.

Also Simon provided us a very good link about this subject here: http://thoughts.inphina.com/2010/09/12/using-scripted-data-sources-in-birt-and-deploying-in-application-server/

As explained in the book “Integrating and Extending BIRT, 3rd edition”: “BIRT supports accessing data using JavaScript code. This type of data source is called a scripted data source. Using a scripted data source, you can access objects other than the built-in data source types. Because the JavaScript code for accessing and managing a scripted data source can wrap Java objects, a scripted data source can access an EJB, an XML stream, a Hibernate object, or any other Java object that retrieves data. A scripted data source must return data in tabular format, so that BIRT can perform sorting, aggregation, and grouping.” (Weathersby and et al, 2011)

The challenge for the next phase consists in understanding ZAP code more deeply, especially because there is already an API.

We need to define a plan for this phase after Rauf has completed redifing the code and submitting the code for final revision to Simon Bennets,project leader of OWASP ZAP.