GUIDE.md

Welcome to the oval-graph guide

This tool generates an OVAL result in the form of a tree graph from an ARF xml report from an OpenSCAP scan.

Prerequisites

Required dependencies

• python3
• lxml

Optional dependencies

• includes required dependencies
• inquirer Not supported until oval-graph 1.3.0

Installation

Enterprise Linux

Before installing, enable Extra Packages for Enterprise Linux (EPEL). Learn how to enable EPEL in EPEL documentation.

Enable EPEL for RHEL/CentOS 8

Run these commands as root. Enable EPEL for RHEL/CentOS 7 is very similar.

yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

on RHEL 8 it is required to also enable the codeready-builder-for-rhel-8-*-rpms repository since EPEL packages may depend on packages from it:

subscription-manager repos --enable "codeready-builder-for-rhel-8-$(/bin/arch)-rpms"

RHEL/CentOS 7

sudo yum install oval-graph

RHEL/CentOS 8 /Fedora 30 and later

sudo dnf install oval-graph

Install inquirer, if you want have nice cli features. (optional) (Not supported until oval-graph 1.3.0)

sudo pip3 install inquirer

Installation via pip

# If you want to install oval-graph to $HOME/.local/bin, you have to run the below command:
pip3 install --user oval-graph

# If you want to install oval-graph globally instead, you have to run the below commands as admin, e.g. on Linux:
sudo pip3 install oval-graph

Installation from source

git clone https://github.com/OpenSCAP/oval-graph.git
cd oval-graph

# Install without features (light version)
sudo pip3 install .

If you don't want to install anything, look here.

Commands

• arf-to-graph Generates a tree graph from ARF xml report
• arf-to-json Generates a JSON from ARF xml report
• json-to-graph Generates a tree graph from JSON

Arguments

Run the utility with -h to see what optional args do.

---

Usage Examples

This commands consumes the rule name or regular expression of rule name and the ARF file, which is one of possible standardized format for results of SCAP-compliant scanners. You can read about generating ARF report files using OpenSCAP in the OpenSCAP User Manual. Or you can use test arf files from repository /tests/test_data.

arf-to-graph

This command serves to fast visualization of rule.

arf-to-graph scan-data/ssg-fedora-ds-arf.xml xccdf_org.ssgproject.content_rule_audit_rules_unsuccessful_file_modification_creat

This command generates a graph and saves file named graph-of-<rule_id>-<date>.html (The date the graph was created.) in the working directory. Then, it opens the generated file in your web browser. Default web browser is Firefox. If Firefox is not installed, the default web browser in OS is used.

arf-to-graph -o ~/graphs scan-data/ssg-fedora-ds-arf.xml 't.[a-zA-Z0-9_]*on_creat$'

This command generates a graph and saves file named graph-of-<rule_id>-<date>.html (The date the graph was created.) in ~/graphs because -o was used. Then, it opens the generated file in your web browser. Default web browser is Firefox. If Firefox is not installed, the default web browser in OS is used. Resulting output

Click on any test for show OVAL details

arf-to-json

This command serves to generate a JSON of rule.

arf-to-json scan-data/ssg-fedora-ds-arf.xml 'on_creat$'

This command prints JSON of rule. User can easily transfer the output to file with >.

arf-to-json -o ~/rules.json scan-data/ssg-fedora-ds-arf.xml 'on_creat$'

This command saves JSON to ~/rules.json and, if there are any saved graphs in the file, it joins the other charts because -o was used.

json-to-graph

This command consumes the rule name and the JSON file.

This command serves to restore graph form json of rules.

json-to-graph ~/rules.json 'on_creat$'

This command restores the graph and saves file named graph-of-<rule_id>-<date>.html (The date the graph was created.) in working directory. Then, it opens the generated file in your web browser. Default web browser is Firefox. If Firefox is not installed, the default web browser in OS is used.

json-to-graph -o ~/graphs ~/rules.json 'on_creat$'

This command restore graph and saves all necessary files to a directory named graph-of-<rule_id>-<date>.html (The date the graph was created.) in ~/graphs because -o was used. Then, it opens the generated file in your web browser. Default web browser is Firefox. If Firefox is not installed, the default web browser in OS is used.

The resulting output is the same as the previous image.

Option to hide pass tests in graph

This option is available in arf-to-graph and json-to-graph. This parameter hides all pass tests for better orientation in graph. (see pictures)

Not used --hide-passing-tests

Used --hide-passing-tests

Run from source

Warning: Required dependencies must be installed.

#get sources
git clone https://github.com/OpenSCAP/OVAL-visualization-as-graph.git
cd OVAL-visualization-as-graph

# run command arf-to-graph -h
python3 -m oval_graph.command_line arf-to-graph -h

# run command arf-to-json -h
python3 -m oval_graph.command_line arf-to-json -h

# run command json-to-graph -h
python3 -m oval_graph.command_line json-to-graph -h

Execute the test suite

There are many test options for syntax, code, code coverage.

Before testing install requirements

pip3 install -r test_suite_requirements.txt

Test all that stuff together with tox

Run tests:

tox

If requirements changes tox -r (recreates virtual environment) can help.

# Show coverage report
firefox htmlcov/index.html

You can run test for more python environments with command like this one:

tox -e py36,py37,py38,py39

Test code and code coverage with pytest

Run tests:

python3 -m pytest

Run tests coverage:

python3 -m pytest --cov oval_graph --cov-report html --cov-branch

# Show coverage report
firefox htmlcov/index.html

Test syntax

Run syntax tests:

flake8 ./oval_graph ./tests setup.py

#OR

pylint ./oval_graph ./tests setup.py