csaf-lint 0.0.6

Experimental CSAF validator for envelope and body profiles.

fluffy-funicular

Experimental CSAF envelope and body profile validator.

Status

Experimental.

Installing

Recommended installation of current experimental package:

$ python -m pipx install csaf-lint

Note: The default branch is default.

CSAF Lint

Experimental CSAF envelope and body profile validator.

In short: The current version of the csaf-lint validates documents in various Common Security Advisory Framework (CSAF) formats against built-in or user custom schema files.

The supported versions are:

• CSAF 2.0 (default is now the 2021.03.19 editor version)
• CSAF 1.2 (aka CVRF 1.2)
• CSAF 1.1 (aka CVRF 1.1)

Caveat Emptor

1. Expect changes to the CSAF v2.0 support because the underlying OASIS specification is undergoing development by the members of the OASIS technical committee. This may lead to breaking changes until the standard is published on committee specification level. The current supported draft JSON Schema versions are from 2021-03-19 and 2021-03-07.
2. The previous versions namely CVRF 1.1 and 1.2 were in XML format.
3. The current version CSAF 2.0-candidates are in JSON Schema format.

Available on PyPI as csaf-lint and hub.docker.com as shagen/csaf-lint

Status

Experimental.

Random Statements

Cascaded shape schema validation via russian doll design? Maybe.

Practical validation should expose the most convenient structure for stacked profiles (always adding not subtracting).

Read the source, Lucy!

Installing

There are multiple ways to install / make available csaf-lint.

Local Environment per pipx

A quite safe option to evaluate python packages is per pipx.

$ pipx install csaf-lint

Later upgrades can be installed per pipx upgrade csaf-lint

Install per pip

Another option to evaluate python packages on environment level is per pip. It is good practice to trial pacakges at first inside a python virtual environment.

$ pip install csaf-lint

Later upgrades can be installed per pip install --upgrade csaf-lint

Install per docker

For now cf. hub.docker.com as shagen/csaf-lint to obtain install and initial usage instructions for the docker image.

Inside Repository Clone

For contributing to csaf-lint development it is a good idea to fork the repository and clone that fork to your work environment.

The following one-time install steps set up a working virtual environment inside the clone directory (pyenv is used as example assuming the active python interpreter is 3.9.2):

$ pyenv virtualenv fluffy-funicular-3-9-2
$ pyenv local fluffy-funicular-3-9-2
$ pip install --upgrade pip
$ pip install -r requirements.txt
$ pip install -r requirements-dev.txt

In case these steps succeed, inside this directory a complete development and test environment should be ready to use.

Usage Examples

Using the Service Script csaf-lint

Assuming there is a valid CSAF v2.0 file inside in the current directory with the name valid_csaf_v_2_0.json validation works like this:

$ csaf-lint valid_csaf_v_2_0.json

resulting in no output at all and a return code of 0 for success.

Another way to obtain the same result is to provide the document per standard input like:

$ csaf-lint < valid_csaf_v_2_0.json

Using the Python Module csaf_lint

Again, assuming there is a valid CSAF v2.0 file inside in the current directory with the name valid_csaf_v_2_0.json validation works like this (note the underscore instead of the dash separating the words csaf and lint):

$ python -m csaf_lint valid_csaf_v_2_0.json

resulting in no output at all and a return code of 0 for success.

Another way to obtain the same result is to provide the document per standard input like:

$ python -m csaf_lint < valid_csaf_v_2_0.json

Also in this install mode (as with pipx) you can call the application csaf-lint.

Using the docker image shagen/csaf-lint

For now cf. hub.docker.com as shagen/csaf-lint to obtain insatll and initial usage instructions for the docker image.

Inside a Repository Checkout

Using the Module

Executing the csaf_lint module (first two executions succeed, third fails):

$ python -m csaf_lint tests/fixtures/csaf-2.0/baseline/spam/01.json
$ python -m csaf_lint tests/fixtures/cvrf-no-version-given/is_wun_two.xml
$ python -m csaf_lint examples/empty_object.json 2>&1 | grep -i validat
    return 0 if validate(document, schema) is None else 1
  File ".../fluffy-funicular/csaf_lint/lint.py", line 145, in validate
    return jsonschema.validate(document, schema, format_checker=conformance)
  File ".../site-packages/jsonschema/validators.py", line 934, in validate
jsonschema.exceptions.ValidationError: 'document' is a required property
Failed validating 'required' in schema:

Switching between editor versions is supported by explicitly stating
the path for the schema like for the 2021.03.07 editor version:

$ export SCHEMA="csaf_lint/schema/csaf/2021.03.07/csaf.json"
$ python -m csaf_lint $SCHEMA validate_me_as_csaf.json

Executing the Tests

Executing the tests per pytest:

$ pytest
============================= test session starts =========================
platform ...
rootdir: ...fluffy-funicular, configfile: pyproject.toml
plugins: ...
collected 21 items

tests/test_cli.py .....                                              [ 23%]
tests/test_lint.py ................                                  [100%]

============================= 21 passed in 32.26s =========================

For intermediate local development feedback (exclude the slow tests and
report in a terse manner) excluding the complete corpus tests:

$ PYTEST_ADDOPTS="-q -m 'not slow'" pytest
...................                                                  [100%]
19 passed, 2 deselected in 10.02s

Executing Code Quality Analysis

Running prospector:

$ prospector
Check Information
=================
         Started: ...
        Finished: ...
      Time Taken: 2.32 seconds
       Formatter: grouped
        Profiles: default, no_doc_warnings, no_test_warnings, ...
      Strictness: None
  Libraries Used:
       Tools Run: dodgy, mccabe, pep8, profile-validator, pyflakes, pylint
  Messages Found: 0

Changelog

0.0.6 (2021-03-22)

• Added meta data and harmonized packaging
• Sixth release on PyPI.

0.0.5 (2021-03-22)

• Enhanced PyPI documentation (project links)
• Fifth release on PyPI.

0.0.4 (2021-03-22)

• Updated CSAF Schema draft to 2021.03.19 (default)
• 2021.03.07 still available per csaf_lint/schema/csaf/2021.03.07/csaf.json
• Updated user documentation
• Fourth release on PyPI.

0.0.3 (2021-03-21)

• Validation implemented for CSAF (CVRF) versions 1.1 and 1.2
• Implemented further CLI and linter tests
• Created user documentation for install and usage
• Third release on PyPI.

0.0.2 (2021-03-19)

• Validation implemented as per CSAF draft 2021.03.07 schema
• Added the CSAF draft 2021.03.07 schema
• Implemented initial CLI and linter tests
• Created corpus of baseline and invalid documents for test
• Second release on PyPI.

0.0.1 (2021-03-10)

• First release on PyPI.