CVRF-CSAF-Converter

Introduction
Getting started
How to use CVRF-CSAF-converter
- Usage as CLI tool
- Config
Specifications
Developing CVRF-CSAF-converter
- Developer Guide, Architecture and Technical Design
- Security Considerations
Contributing
Project

Introduction

CVRF-CSAF-converter is a Python tool for converting CSAF CVRF 1.2 documents in CSAF 2.0 documents. It fulfills the conformance target CVRF CSAF converter.

Note: The project is currently still under development. Not all features have been implemented and therefore the conformance goal is not yet fulfilled.

Getting started

Ensure that you have installed python3 (version >= 3.6), python3-pip and python3-venv.

Assume your current directory is also avaliable at the environment variable $ROOT_DIR.

Check out the repository and navigate to the working directory.

   git clone https://github.com/csaf-tools/CVRF-CSAF-Converter.git
   cd CVRF-CSAF-Converter

Afterwards, create a virtual environment and install the package there:

   python3 -m venv venv
   . venv/bin/activate
   pip install .

Hint: If you would like to get the debugger running, try to install the code as follows: pip install -e .

How to use CVRF-CSAF-converter

Usage as CLI tool

To convert the CVRF CSAF 1.2 document $ROOT_DIR/CVRF-CSAF-Converter/examples/1.2/cvrf_example_a.xml use the following command:

   cvrf2csaf --input-file $ROOT_DIR/CVRF-CSAF-Converter/examples/1.2/cvrf_example_a.xml

The default output directory is ./, it can be set using --output-dir.

The output filename is derived from the CSAF field /document/tracking/id.

If there is an ERROR during conversion, the output file will not be written unless --force option is used.

The rest of the options can be shown with:

   cvrf2csaf -h

Config

The config file is installed inside the Python package. For the installation using venv, the config file is located in $PATH_TO_THE_VENV/lib/python3.X/site-packages/cvrf2csaf/config/config.yaml. When installing the PyPI package with pip (--user), the config file is located in $HOME/.local/lib/python3.X/site-packages/cvrf2csaf/config/config.yaml Converter options can be changed there, or overridden by command line arguments/options.

Specifications

We follow the official OASIS specifications in order to provide as much acceptance on the user base as possible.

Developing CVRF-CSAF-converter

Developer Guide, Architecture and Technical Design

The converter uses lxml.objectify to parse the whole input document.

Parsing and conversion of the following CSAF CVRF 1.2 XML elements are handled by separate section handlers. These section handlers process the elements recursively (converting also all their sub-elements). These elements are the direct children of the root XML element (<cvrfdoc>).

DocumentTitle, DocumentType, DocumentDistribution, AggregateSeverity -> DocumentLeafElements handler
DocumentPublisher -> DocumentPublisher handler
DocumentTracking -> DocumentTracking handler
DocumentNotes -> Notes handler
DocumentReferences -> References handler
Acknowledgments -> Acknowledgments handler
ProductTree -> ProductTree handler
Vulnerability -> Vulnerability handler

Vulnerability handler is reusing Acknowledgments, References and Notes handlers for its child elements.

Each of these section handlers is implemented by own class inheriting from SectionHandler class. This base class contains _process_mandatory_elements and _process_optional_elements methods which are parsing and converting mandatory/optional elements/attributes. Each subclass must implement these methods.

SectionHandler class holds error_occurred class variable. This variable is overwritten by any children class in case some error resulting in invalid output json happened. Depending on --force commandline parameter, the program either quits with error log message without producing output or produce invalid output and warning log message.

Complete conversion together with input and output validation against schemata is handled by the DocumentHandler class.

Security Considerations

These are the TOP OWASP categories of vulnerabilities which potentially affect the CVRF-CSAF-Converter. We are omitting those which do not apply (most of them), since it's a plain command-line tool (e.g. authentication failures)

Contributing

Please refer to CONTRIBUTING.md for details about how to contribute to the development of CVRF-CSAF-converter.

Project

CVRF-CSAF-Converter is a project between Deutsche Telekom Security GmbH and the Federal Office for Information Security. It aims to provide a CVRF 1.x to CSAF 2.0 converter.

Realization is taking place 100% Open Source. The final delivery will be in Q1/2022.

csaf-tools / CVRF-CSAF-Converter

readme