BSI Secvisogram CSAF Validator Service

• About the project
• Getting started
  • Docker
  • Manual installation
  • Testrun
    • Use API webpage
• Documentation
• Configuration
  • CORS
• Developing
  • Prerequisites
  • Installation
  • Run server
  • Generate documentation
  • Create new version
• Testing
• Persist with pm2
• Contributing
• Dependencies

About the project

This is a service to validate documents against the CSAF standard. It uses the csaf-validator-lib under the hood which is included as a git subtree module.

(back to top)

Requirements

• install Node.js 20
• install npm
• test 6.3.8 requires an installation of hunspell.
  • For more details on how to manage languages, please also see Managing Hunspell languages

Getting started

To run the validator service, you basically need the same as for developing.

Quick-Start Using Docker

If you want to run by using the default settings, use docker installation option

• Build docker image

  docker build -t csaf-validator-service .

• Start container

  docker run -d -p 8082:8082 --name csaf-validator-service csaf-validator-service

Installation (step by step)

• get into the git folder

• run npm ci to install production dependencies.

• run npm run dist to build the validation service.

• Copy the content of the dist folder to your working directory

  cp -r ./dist/* .

• Configure the service using a production.json file in backend/config. All available parameters are outlined in backend/config/development.json. See https://www.npmjs.com/package/config for more information on how to configure using different techniques such as environment variables.

• Make sure to set the environment variable NODE_ENV to production.

  echo $NODE_ENV

  If a configuration file with the displayed name exists in the config folder, it will be used. If not, default.json will be loaded instead.

• start the service with

  cd backend/
  node server.js

To manage the process you can use Docker or an init system of your choice.

You most likely also want to run this behind a reverse proxy to handle TLS termination or CORS headers if the service is accessed from other domains. See https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS for more information.

(back to top)

Testrun

Once the server is running, visit http://localhost:<config port>/docs in your browser. The default port of the application 8082. See configuration to learn about ways to change it.

Validate a Json File

• Expand POST under default

• Click Try it out to change the test input and add your whole json file

  "document": {
    <content of your json file>
  }

• Hit execute and check the generate output below

(back to top)

Documentation

The documentation is available as a swagger resource provided by the service itself under /docs. So once the server is running, visit http://localhost:<config port>/docs in your browser. The default port of the application 8082. See configuration to learn about ways to change it.

(back to top)

Configuration

The project uses the config npm package for configuration. It provides a variety of possibilities to inject configuration values e.g. environment variables or environment specific files.

CORS

Fastify CORS options can be configured by passing an options object by the name cors

The following options are available: origin, methods, allowedHeaders, exposedHeaders, credentials, maxAge

See Fastify CORS options for more information

(back to top)

Developing

Prerequisites

You need at least Node.js version 20 or higher. Nodesource provides binary distributions for various Linux distributions.

(back to top)

Installation Developing

• Install server and csaf-validator-lib dependencies

  npm ci

(back to top)

Run server

• Start the server

  npm run dev

(back to top)

Generate documentation

The server needs to be running and the openapi-generator-cli must be installed. The file backend/lib/app.js needs to reflect the target version. Then, you can use the following commands to generate the documentation:

openapi-generator-cli generate -i http://localhost:8082/docs/json -g html -o ./documents/generated/html/
openapi-generator-cli generate -i http://localhost:8082/docs/json -g asciidoc -o ./documents/generated/asciidoc/

(back to top)

Create new version

To create a new version use npm's version command and make sure that your server is not running (since this command will start it).

(back to top)

Testing

Many tests are integration tests which need a running server. So make sure to start it before running the tests:

npm run dev

Tests are implemented using mocha. They can be run using the following command:

npm test

(back to top)

Persist with pm2

If you want to start the service with pm2 you have to adjust the instance_var attribute for pm2. You can do this by adding the following configuration in the backend folder. Depending on the directory you chose, you have to adjust the cwd and NODE_CONFIG_DIR attributes accordingly.

// pm2.config.cjs
module.exports = {
  apps: [
    {
      name: 'csaf-validator-service',
      script: './server.js',
      cwd: '/var/www/csaf-validator-service/backend',
      instance_var: 'INSTANCE_ID',
      env: {
        NODE_ENV: 'development',
        NODE_CONFIG_DIR: '/var/www/csaf-validator-service/backend/config/',
      },
      env_production: {
        NODE_ENV: 'production',
        NODE_CONFIG_DIR: '/var/www/csaf-validator-service/backend/config/',
      },
    },
  ],
}

To start the service execute this command inside the backend directory:

pm2 start pm2.config.js --env production

Contributing

You can find our guidelines here CONTRIBUTING.md

(back to top)

Dependencies

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

• fastify
• fastify-swagger
• csaf-validator-lib

(back to top)