Welcome to OpenVAS2Report’s documentation!¶

What’s OpenVAS 2 Report¶

The idea is very simple:

Take an OpenVAS report, in it horrible XML format.
Convert it into an beautiful Excel, ready to give to your boss.

Why?¶

I’m security auditor and I really hate to pass OpenVAS XML report into to and Excel document. This is a work for a monkey, not for a human! (Yes: security auditors are humans too. I know, I know. It’s incredible)

So I started to develop this project and I thought share it for help other auditors that also hate make a monkey’s work.

Available tools¶

This package are composed by 2 tools:

openvas_to_document: This is the main program. You can use it to generate the Excel file.
openvas_cutter: This is a facility for filter and crop some information from OpenVAS XML report.

A picture is worth a 1000 words From XML. Using openvas_to_document you can obtain this Excel file:

As a library¶

Also, you can use the tool as a library and import them it in your own code. It has BSD license, Feel free to use!

Content Index¶

Quick start guide¶

The use of package is very simple. This document is a brief explanation.

Installation¶

Install the package is so easy. Simple type this: x .. code-block:: bash

> sudo pip install openvas-to-report

Note

Remember that you need Python 3!!

Generate Excel¶

To generate an Excel File you need to export the OpenVAS results as a XML format. If you can’t a report by hand, you can find one in example folder.

Then, you need to use openvas_to_document tool:

> openvas_to_document -i my_openvas_report.xml -o generated_excel.xlsx

For further information go to the Openvas to report manual.

Filter results¶

If you want to filter the XML OpenVAS file, deleting some targets for example, and generate a new XML document without this information, you can user openvas_cutter

First we create a file with the targets that we want to remove.

> echo 10.0.1.1 > remove_targets.txt

Now launch the script:

> openvas_cutter -i my_openvas_report.xml -o my_openvas_report_filtered.xml --exclude-hosts remove_targets.txt

For further information go to the Openvas cutter manual.

As a library¶

You also can use the library in your won code, importing as a usual lib. After install de library, using bellow instructions, you only must do:

from openvas_to_report.api import Config, convert

c = Config(input_files=["input_file.xml"], output_file="results.xlsx")
convert(c)

For further information go to the Openvas as library manual.

Openvas2Report Manual¶

What’s this tool?¶

In few words: with this tools you can convert the OpenVAS XML report to beautiful Excel file.

Basic usage¶

The more simple usage is with only one file as input.

Note

If you haven’t a XML as example, you can get one in folder examples.

This pictures shows the example XML file:

To run only write:

> openvas_to_document -i my_openvas_report.xml -o generated_excel.xslx

After running you got this Excel:

Also, you can specify more than one XML report as input:

> openvas_to_document-i my_openvas_report_1.xml -i my_openvas_report_2.xml -o generated_excel.xslx

Advanced usage¶

If you want to exclude some hosts from report, you can use two aproaches:

Using a scope filter.
Specify a list of hosts to exclude.

Setting a filter¶

Is you only want to include certain hosts in your Excel report, you only must create a .txt file with your scope:

> echo 10.0.0.1 > my_scope.txt
> echo 10.0.1.23 >> my_scope.txt

Then use it as a parameter in the tools:

> openvas_to_document -i my_openvas_report.xml -o generated_excel.xslx --scope-hosts my_scope.txt

Simple right? :)

Excluding hosts¶

The second approach is to create a black list. As in the previous case, we’ll define our file:

> echo 127.0.0.1 > excluded.txt
> echo 192.168.0.3 >> excluded.txt

And then, use it:

> openvas_to_document -i my_openvas_report.xml -o generated_excel.xslx --exclude-hosts excluded.txt

Openvas Cutter¶

What’s this tool?¶

There are some times that you need to exclude some hosts from the XML. For example: If you must to deliver the XML report, but it contains some hosts that are out of scope.

This tools can help us. It remove host information from the original XML file, and generates a new XML file without this information.

Basic usage¶

The usage si very simple. Only need to specify the input file/s and the new output file:

Note

If you haven’t a XML as example, you can get one in folder examples.

To run only write:

> openvas_cutter -i my_openvas_report.xml -o my_openvas_report_filtered.xml

Advanced usage¶

Advanced filer works as same as openvas_to_document tool. You can read it in: Advanced usage.

OpenVAS2Report as a library¶

You can user openvas2Report as a library. It’s easy.

Configuration object¶

All the actions in package has a common configuration object called Config. We need to configure it before to run.

This code display the Config objects and mark the parameters accepted:

# --------------------------------------------------------------------------
class Config(object):
    """Program configuration"""

    # ----------------------------------------------------------------------
    def __init__(self, input_files, output_file, template=None, lang="en", excluded=None, scope=None):
        """
        :param input_files: input file path
        :type input_files: list(str)

        :param output_file: output file path and name
        :type output_file: str

        :param template: path to template
        :type template: str

        :param lang: language
        :type lang: str

        :param excluded: path to file with excluded hosts.
        :type excluded: str

        :param scope: path to file with scope hosts
        :type scope: str

        :raises: TypeError, ValueError

The code is auto-explained. Then, we import them from openvas_to_report.api:

from openvas_to_report.api import Config

config = Config(["openvas_report1.xml", "openvas_report2.xml"],
                "results.xslx",
                "en",
                "excluded_hosts.txt",
                "scope_host.txt")

Run actions¶

I called action to these tasks or functions that you also can run in command line way.

After instance the config object, we can call actions:

from openvas_to_report.api import Config, convert, crop

# Convert to Excel
config_convert = Config(["openvas_report1.xml", "openvas_report2.xml"],
                        "results.xslx",
                        "en")

convert(config)

# Crop XML file
config_convert = Config(["openvas_report1.xml", "openvas_report2.xml"],
                        "results_filtered.xml")

crop(config)