@secvisogramtesting/csaf-validator-lib NPM | npm.io

1.3.27 • Published 20 days ago

Install

Weekly downloads

-

License

MIT

Repository

Last release

20 days ago

BSI CSAF Validator Lib

About The Project
Getting Started
How to use
- Strict Mode
- API
Testing
Contributing
Dependencies

About The Project

This JavaScript library is intended to include logic that can be shared across application working with CSAF.

Getting Started

Add the library to your project by using one of the following methods. After that you can reference the modules from within your JavaScript application.

Using the official npm package

There is an official package in the npm registry.

You can add it to your project using the following command:

npm install @secvisogram/csaf-validator-lib

Using a git subtree

You can also include this library as a subtree in your repository.

include as git subtree

git subtree add --prefix csaf-validator-lib https://github.com/secvisogram/csaf-validator-lib.git main --squash

install dependencies
```
cd csaf-validator-lib && npm ci --prod
```
This repository includes git submodules. Make sure to initialize and update the submodules before you start working with the repository.
```
git submodule update --init --recursive
```
For test 6.3.8 an installation of hunspell as well as all languages that you want to spell check is required.

Managing Hunspell languages

A CSAF Document can contain a language. For example, valid entries could be en or en-US. When running test 6.3.8 we try to match this language to the list of installed hunspell languages. If the region is specified (like in en-US) and the corresponding language is installed the test will run. If you want/need to check a en language specifically with en-US (or any other variant) you need to make sure that you link en to en-US using a symlink.

Example of linking en to en-US:

ln -s /usr/share/hunspell/en_US.aff /usr/share/hunspell/en.aff
ln -s /usr/share/hunspell/en_US.dic /usr/share/hunspell/en.dic

You can find out what languages you have installed by running hunspell -D.

If you need additional languages they are most likely available in the repository of your distribution. If you have a custom dictionary copy them in the directory provided by the command above. Hunspell should automatically recognize them.

How to use

example usage

import validateStrict from '../csaf-validator-lib/validateStrict.js'
import * as mandatory from '../csaf-validator-lib/mandatoryTests.js'
import { optionalTest_6_2_1 } from '../csaf-validator-lib/optionalTests.js'
import { csaf_2_0_strict } from './schemaTests.js'

const document = {}
const tests = [
  csaf_2_0_strict,
  ...Object.values(mandatory),
  optionalTest_6_2_1,
]

const result = await validateStrict(tests, document)

Strict Mode

The library has two validate functions, validate and validateStrict. validateStrict checks whether the test that should be executed was defined in the library. Otherwise, it throws an error. To extend the library you can use the validate function instead. In such case, the calling function is responsible for checking whether the test function passed to the csaf-validator-lib is benign. Calling arbitrary functions (especially those resulting from user input) may result in a code execution vulnerability. Therefore, the check of the test function to determine whether it is benign MUST be done before calling it. To proceed this dangerous path, use the validate function.

API

Interfaces

interface Result {
  isValid: boolean
  warnings: Array<{ message: string; instancePath: string }>
  errors: Array<{ message: string; instancePath: string }>
  infos: Array<{ message: string; instancePath: string }>
}

interface TestResult {
  isValid?: boolean
  warnings?: Array<{ message: string; instancePath: string }>
  errors?: Array<{ message: string; instancePath: string }>
  infos?: Array<{ message: string; instancePath: string }>
}

/**
 * Every document test has its identifier set as the functions name. You can access
 * it using `<myTest>.name`
 */
type DocumentTest = (doc: any) => TestResult | Promise<TestResult>

Module `schemaTests.js`

export const csaf_2_0_strict: DocumentTest
export const csaf_2_0: DocumentTest

Module `mandatoryTests.js`

export const mandatoryTest_6_1_1: DocumentTest
export const mandatoryTest_6_1_2: DocumentTest
export const mandatoryTest_6_1_3: DocumentTest
export const mandatoryTest_6_1_4: DocumentTest
export const mandatoryTest_6_1_5: DocumentTest
export const mandatoryTest_6_1_6: DocumentTest
export const mandatoryTest_6_1_7: DocumentTest
export const mandatoryTest_6_1_8: DocumentTest
export const mandatoryTest_6_1_9: DocumentTest
export const mandatoryTest_6_1_10: DocumentTest
export const mandatoryTest_6_1_11: DocumentTest
export const mandatoryTest_6_1_12: DocumentTest
export const mandatoryTest_6_1_13: DocumentTest
export const mandatoryTest_6_1_14: DocumentTest
export const mandatoryTest_6_1_15: DocumentTest
export const mandatoryTest_6_1_16: DocumentTest
export const mandatoryTest_6_1_17: DocumentTest
export const mandatoryTest_6_1_18: DocumentTest
export const mandatoryTest_6_1_19: DocumentTest
export const mandatoryTest_6_1_20: DocumentTest
export const mandatoryTest_6_1_21: DocumentTest
export const mandatoryTest_6_1_22: DocumentTest
export const mandatoryTest_6_1_23: DocumentTest
export const mandatoryTest_6_1_24: DocumentTest
export const mandatoryTest_6_1_25: DocumentTest
export const mandatoryTest_6_1_26: DocumentTest
export const mandatoryTest_6_1_27_1: DocumentTest
export const mandatoryTest_6_1_27_2: DocumentTest
export const mandatoryTest_6_1_27_3: DocumentTest
export const mandatoryTest_6_1_27_4: DocumentTest
export const mandatoryTest_6_1_27_5: DocumentTest
export const mandatoryTest_6_1_27_6: DocumentTest
export const mandatoryTest_6_1_27_7: DocumentTest
export const mandatoryTest_6_1_27_8: DocumentTest
export const mandatoryTest_6_1_27_9: DocumentTest
export const mandatoryTest_6_1_27_10: DocumentTest
export const mandatoryTest_6_1_27_11: DocumentTest
export const mandatoryTest_6_1_28: DocumentTest
export const mandatoryTest_6_1_29: DocumentTest
export const mandatoryTest_6_1_30: DocumentTest
export const mandatoryTest_6_1_31: DocumentTest
export const mandatoryTest_6_1_32: DocumentTest
export const mandatoryTest_6_1_33: DocumentTest

Module `optionalTests.js`

export const optionalTest_6_2_1: DocumentTest
export const optionalTest_6_2_2: DocumentTest
export const optionalTest_6_2_3: DocumentTest
export const optionalTest_6_2_4: DocumentTest
export const optionalTest_6_2_5: DocumentTest
export const optionalTest_6_2_6: DocumentTest
export const optionalTest_6_2_7: DocumentTest
export const optionalTest_6_2_8: DocumentTest
export const optionalTest_6_2_9: DocumentTest
export const optionalTest_6_2_10: DocumentTest
export const optionalTest_6_2_11: DocumentTest
export const optionalTest_6_2_12: DocumentTest
export const optionalTest_6_2_13: DocumentTest
export const optionalTest_6_2_14: DocumentTest
export const optionalTest_6_2_15: DocumentTest
export const optionalTest_6_2_16: DocumentTest
export const optionalTest_6_2_17: DocumentTest
export const optionalTest_6_2_18: DocumentTest
export const optionalTest_6_2_19: DocumentTest
export const optionalTest_6_2_20: DocumentTest

Module `informativeTests.js`

export const informativeTest_6_3_1: DocumentTest
export const informativeTest_6_3_2: DocumentTest
export const informativeTest_6_3_3: DocumentTest
export const informativeTest_6_3_4: DocumentTest
export const informativeTest_6_3_5: DocumentTest
export const informativeTest_6_3_6: DocumentTest
export const informativeTest_6_3_7: DocumentTest
export const informativeTest_6_3_8: DocumentTest
export const informativeTest_6_3_9: DocumentTest
export const informativeTest_6_3_10: DocumentTest
export const informativeTest_6_3_11: DocumentTest

Module `basic.js`

This module exports the strict schema test and all mandatory tests except 6.1.8.

Module `extended.js`

This module exports all tests included in basic.js and all optional tests.

Module `full.js`

This module exports all tests included in extended.js and all informative tests.

Module `validate.js`

This function validates the given document against the given tests.

Module `validateStrict.js`

This function validates the given document against the given tests. It throws an error if an unknown test function was passed. See Strict Mode for more details.

Module `strip.js`

This function strips empty nodes and nodes with errors. The strict option (default true) throws an error if an unknown test function was passed. See Strict Mode for more details.

type StripFn = (
  tests: DocumentTest[],
  document: any,
  options?: { strict?: boolean }
) => Promise<{
  document: any
  strippedPaths: {
    instancePath: string
    message: string
    error: boolean
  }[]
}>

export default StripFn

Module `cwe.js`

export const weaknesses: Array<{ id: string; name: string }>

Testing

Tests are implemented using mocha. The minimal supported Node.js version is 14. They can be run using the following command:

npm test

Contributing

You can find our guidelines here CONTRIBUTING.md

Dependencies

For the complete list of dependencies please take a look at package.json

csaf csaf-validator-lib csaf full validator secvisogram

@js-joda/core @js-joda/timezone ajv ajv-formats bcp47 cvss2js json-pointer lodash packageurl-js semver undici

20 days ago