@secvisogram/csaf-validator-service

BSI Secvisogram CSAF Validator Service

• About the project
• Getting started
• Documentation
• Configuration
  • CORS
• Developing
  • Prerequisites
  • Installation
  • Run server
  • Generate documentation
  • Create new version
• Testing
• Docker
• 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)

Getting started

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

• install Node.js 20
• install production dependencies and copy all relevant files to the dist folder by running npm run dist
• copy the content of the dist folder to your working directory
• Make sure to set the environment variable NODE_ENV to production
• Configure the service using a local-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.
• test 6.3.8 requires an installation of hunspell.
  • For more details on how to manage languages, please also see Managing Hunspell languages
• start the service with node backend/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.

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

• 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)

Docker

Build docker image

docker build -t csaf/validator-service .

Start container

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

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)