Working with Custom Templates

Metasploit Pro ships with a set of predefined standard reports, which are created with Metasploit templates and designed to meet basic pentesting reporting requirements. However, if the standard reports do not provide you with the content or layout that you need, you can use a custom template to build your report. A custom template enables you to do things like apply corporate styles to your reports, control how and where content is displayed in your reports, and customize your reports for regional compliance needs.

A custom template is a JRXML file, which is an XML document with a JasperReport file extension. It contains the report structure, which defines where the report displays content, where it places images, and how it queries data. It can be built by directly manipulating XML or more easily by using a visual report tool for JasperReports, such as iReport Designer or the Eclipse-based Jaspersoft Studio.

Jasper Reports and iReport Designer

Metasploit Pro uses JasperReports 5.0, which is an open source Java-based reporting library, to compile JRXML templates and generate reports in output formats such as PDF, RTF, HTML, and Word. The JRXML template is a standards-based XML file that defines the elements and attributes that control where content is placed in a report. You can build the JRXML template with a visual report designer called iReport Designer, which is an open source tool maintained by Jaspersoft.

iReport Designer provides a graphical user interface that enables you to visually design your report templates without extensive knowledge of the JasperReports library, XML, and Java. You can drag and drop report elements to create layout of the report, and you can connect it to a data source, like JDBC and XML, to query data for the report. The resulting JRXML template can be imported into a Metasploit Pro project and used to create a custom report.

Downloading Jasper iReport

To download Jasper iReport, please visit the following site: http://jasperforge.org/projects/ireport.

Resources for JasperReports and iReport Designer

In order to build a custom template, you must be familiar with JasperReports and iReport Designer. There are quite a few resources available that will help you learn how to build report templates with iReport Designer and understand how JasperReports works.

To learn more about JasperReports or iReport Designer, visit the following resources:

• JasperReports documentation list - A list of the documentation that is available for JasperStudio, JasperReports Server, JasperReports Library, and iReport Designer. You can access this list at the following URL: http://community.jaspersoft.com/documentation.
• JasperReports Library materials reference - A list of the documentation, webinars, and articles that may be helpful for working with JasperReports. You can access this list at the following URL: http://community.jaspersoft.com/wiki/jasperreports-library-reference-materials.
• iReport Designer tutorials and help wiki - A wiki that lists the tutorials that are available for iReport Designer. You can access this list at the following URL: http://community.jaspersoft.com/wiki/ireport-designer-tutorials-help.
• An article on chart customizations - A useful list of chart customizers for JasperReports, iReport Designer, and JasperReports Server. You can view this article at the following URL: http://mdahlman.wordpress.com/2011/04/17/chart-customizers-2/.
• Groovy documentation - Groovy is a Java-compatible scripting language that you can use in place of Java to define expressions in iReport.
  
  To learn more about how Groovy and iReport Designer work together, visit the iReport wiki here: http://http://community.jaspersoft.com/wiki/ireport-designer-groovy.
  
  To learn more about Groovy, you can view their documentation here: http://groovy.codehaus.org/.
• Jaspersoft training - To learn more about Jaspersoft training, you can visit https://www.jaspersoft.com/training-services or https://www.jaspersoft.com/training.

Requirements for Designing Custom Templates

To design a report template, you will need the following:

• Experience with Jasper iReport, JasperReports, XML, and SQL/XPath
• Experience with Java or a Java scripting language, like Groovy or Javascript
• A working instance of Jasper iReport
• Access to the Metasploit database

Setting Up the Metasploit Database in iReport Designer

To fill your report with data, you will need to set up a data source that points to the Metasploit postgres server. The information for the Metasploit postgres server can be found in /path/to/metasploit/apps/pro/config/database.yml.

You will need the following information from the database.yml file:

• The database name - The default database name is msf3.
• The postgresql port - The default postgresql port is 7337.
• The user name - The default user name is msf3.
• The password - Please view the database.yml file for your database password.

To set up a data source in iReport Designer:

1. Open iReport Designer.
   
   The Quick Start window appears.
   
2. Click the Database Connection icon.
   
   
   
   The Datasource window appears.
3. Select Database JDBC connection from the list of data sources.
   
   
   
   
4. Click Next. The Database JDBC Connection window appears.
   
   
   
5. Enter a name for the connection in the Name field.
   
   
   
6. Replace with content in the JDBC URL field with jdbc:postgresql://localhost:7337/msf3.
   
   
7. Enter the database user name in the Username field.
   
   
8. Enter the database password in the Password field.
   
   
9. Test the connection.
   
   If the connection is working properly, a window appears and alerts you that the connection was successful.
   
   Otherwise, if the connection fails, an exception window appears and alerts you that there is an issue with your database settings. You will need to verify that your database settings match the information in the database.yml file.
10. Save the connection, if the connection was successful.

You are now ready to create your report template.

For resources on creating report templates, seeResources for JasperReports and iReport Designer.

Custom Resources Directory

All custom templates and logos are stored in the following directory: /path/to/metasploit/apps/pro/reports/custom_resources.

You can go to the custom resources directory to download or view logos and templates; however, you should not make any changes directly within the directory. If you need to modify your logos or templates, you should make a copy of the directory and make your changes from the new directory.

Any changes that you make directly from within the custom reports directory can cause disparities between the metadata that displays for the file in the web interface and the file itself. If you need to remove or add custom resources, you should do it from within the web interface. Do not delete them directly from the custom resources directory.

Uploading Templates

After you have created your custom template, you will need to upload it to the project you want to use to build the custom report. The template will only be available to the project that you have uploaded it to; therefore, if you want to use the template across multiple projects, you will need to import the template into each project.

When you view the New Custom Report form, the template will be available in the Report Template dropdown menu.

To upload a template:

1. Open the project you want to use to store the custom template.
   
2. Select Reports > Create Custom Report from the Project tab bar.
   
   
   
   The Reports page appears with the Generate Custom Report tab selected.
3. Find the Custom Report Collateral area.
   
   
   
   If your project does not contain any templates, the New Custom Report page will not show the form.
4. Click the Upload Custom Report Collateral button.
   
   
   
   The Upload window appears.
5. Click the Choose File button.
   
   
   
   The Open Dialog window appears.
   
6. Browse to the location of the logo file.

7. Select the template and click the Open button.
   
   The template must have a JRXML extension.
8. Enter a name for the template in the Descriptive Name field. (Optional)
   
   
   
   If you do not specify a name, the Custom Report Collateral area shows the original file name.
9. Click the Submit button.
   
   The template appears under the Custom Report Collateral area.
   
   
   
   You are now ready to generate a custom report. For more information on generating custom reports, seeGenerating a Custom Report.

Downloading a Custom Report Template

1. Open the project that contains the custom report template that you want to download.
   
2. Select Reports > Create Custom Report from the Project tab bar.
   
   
   
   The Reports page appears with the Generate Custom Report tab selected.
3. Find the Custom Report Collateral area.
   
   
   
4. Find the row that contains the custom report template you want to download.
   
   
   
   The row displays the metadata and the actions that are available for the custom report template.
5. Click the Download link.
   
   
   
   The download process will automatically start.
   
   If your browser is not configured to automatically download files, a dialog window will appear and prompt you to save or run the file. You will need to save the template to your computer.

Deleting a Custom Report Template

1. Open the project that contains the custom report template that you want to delete.
   
2. Select Reports > Create Custom Report from the Project tab bar.
   
   
   
   The Reports page appears with the Generate Custom Report tab selected.
3. Find the Custom Report Collateral area.
   
   
   
4. Find the row that contains the custom report template you want to delete.
   
   
   
5. Click the Delete link.
   
   
   
   The browser will prompt you to confirm that you want to delete the custom report template.

Downloading the Example Template

Metasploit Pro provides you with an example template that you can use as a reference when creating your own templates. The template provides simple examples that show you how you can query data, such as host IP addresses, names, operating systems, services counts, and vulnerabilities counts from a project, and display that information in a table. Additionally, you can see examples for adding a title and footer to the report.

To download the example template:

1. Open any project.
   
2. Select Reports > Show Reports from the Project tab bar.
   
   The Reports page appears.
3. Scroll to the bottom of the Reports page.
4. Click the Download Example Template link, which is located below the reports table.
   
   
   
   The download process will automatically start.
   
   If your browser is not configured to automatically download files, a dialog window will appear and prompt you to save or run the file. You will need to save the report to your computer.