Metadata-Version: 2.1
Name: csaf-lint
Version: 0.0.9
Summary: Experimental CSAF validator for envelope and body profiles.
Home-page: https://github.com/sthagen/fluffy-funicular
Author: Stefan Hagen
Author-email: stefan@hagen.link
License: MIT
Project-URL: Homepage, https://github.com/sthagen/fluffy-funicular
Project-URL: Documentation, https://sthagen.github.io/fluffy-funicular/
Project-URL: Container, https://hub.docker.com/r/shagen/csaf-lint
Project-URL: Bug Tracker, https://github.com/sthagen/fluffy-funicular/issues
Keywords: csaf cvrf validation baseline extension core profile envelope body development
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
Requires-Dist: jsonschema
Requires-Dist: xmlschema

# csaf-lint

[![license](https://img.shields.io/github/license/sthagen/fluffy-funicular.svg?style=flat)](https://github.com/sthagen/fluffy-funicular/blob/default/LICENSE)
[![version](https://img.shields.io/pypi/v/csaf-lint.svg?style=flat)](https://pypi.python.org/pypi/csaf-lint/)
[![downloads](https://img.shields.io/pypi/dm/csaf-lint.svg?style=flat)](https://pypi.python.org/pypi/csaf-lint/)
[![wheel](https://img.shields.io/pypi/wheel/csaf-lint.svg?style=flat)](https://pypi.python.org/pypi/csaf-lint/)
[![supported-versions](https://img.shields.io/pypi/pyversions/csaf-lint.svg?style=flat)](https://pypi.python.org/pypi/csaf-lint/)
[![supported-implementations](https://img.shields.io/pypi/implementation/csaf-lint.svg?style=flat)](https://pypi.python.org/pypi/csaf-lint/)

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.23 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-23, 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](https://pypi.org/project/csaf-lint/) and
[hub.docker.com as shagen/csaf-lint](https://hub.docker.com/r/shagen/csaf-lint)

## Status
Experimental.

# 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`.

```bash
$ 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.

```bash
$ 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](https://hub.docker.com/r/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):
```bash
$ 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:

```bash
$ csaf-lint valid_csaf_v_2_0.json
2021-03-24 20:08:55 INFO [csaf-lint]: Validation(JSON): code=0, message='OK'
```
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:

```bash
$ csaf-lint < valid_csaf_v_2_0.json
2021-03-24 20:08:57 INFO [csaf-lint]: Validation(JSON): code=0, message='OK'
```

### 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`):

```bash
$ python -m csaf_lint valid_csaf_v_2_0.json
2021-03-24 20:08:58 INFO [csaf-lint]: Validation(JSON): code=0, message='OK'
```
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:

```bash
$ python -m csaf_lint < valid_csaf_v_2_0.json
2021-03-24 20:08:59 INFO [csaf-lint]: Validation(JSON): code=0, message='OK'
```
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](https://hub.docker.com/r/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):

```bash
$ python -m csaf_lint tests/fixtures/csaf-2.0/baseline/spam/01.json
2021-03-24 19:20:50 INFO [csaf-lint]: Validation(JSON): code=0, message='OK'
$ python -m csaf_lint tests/fixtures/cvrf-no-version-given/is_wun_two.xml
2021-03-24 19:21:15 INFO [csaf-lint]: Validation(XML): code=0, message='OK'
$ python -m csaf_lint examples/empty_object.json 2>&1 | grep -i validat| head -1
2021-03-24 19:22:05 ERROR [csaf-lint]: err.message="'document' is a required property" [err.validator='required'] err.relative_path=deque([])
```
Switching between editor versions is supported by explicitly stating  
the path for the schema like for the 2021.03.19 editor version:
```bash
$ export SCHEMA="csaf_lint/schema/csaf/2021.03.19/csaf.json"
$ python -m csaf_lint $SCHEMA validate_me_as_csaf.json
2021-03-24 19:51:30 INFO [csaf-lint]: Validation(JSON): code=0, message='OK'
```

#### Executing the Tests

Executing the tests per `pytest`:

```bash
$ 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:
```bash
$ PYTEST_ADDOPTS="-q -m 'not slow'" pytest
...................                                                  [100%]
19 passed, 2 deselected in 10.02s
```

#### Executing Code Quality Analysis

Running `prospector`:

```bash
$ 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

```
Running `mypy`:

```bash
$ mypy csaf_lint
Success: no issues found in 4 source files
```

# Changelog

## 0.0.10 (2021-05-01)

* Completed hardening of logging
* Enhanced reporting of failed validation
* Better test coverage
* Added experimental CSAF v2.0 test support (semantic validation)
* Tenth release on PyPI

## 0.0.9 (2021-04-29)

* Hardened logging and backported to Python 3.7
* Fixed corner cases
* Better test coverage
* Fixed csaf-lint app
* Ninth release on PyPI

## 0.0.8 (2021-03-24)

* Enhanced reporting capabilities
* Enhanced documentation
* Code spring-cleaning
* Better test coverage
* Eighth release on PyPI

## 0.0.7 (2021-03-23)

* Updated CSAF Schema draft to 2021.03.23 (default)
* 2021.03.19 still available per `csaf_lint/schema/csaf/2021.03.19/csaf.json`
* Changed logging concept (removed print style debug statements)
* Seventh release on PyPI

## 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


