search

secvisogram / csaf-cms-backend

CSAF CMS Backend is a REST-based backend to support the creation and management of CSAF 2.0 documents
MIT License
5 stars 4 forks source link
csaf csaf-cms-backend mit-license

readme

BSI Secvisogram CSAF Backend

Coverage

About The Project

This is the backend for a Content Management System for CSAF documents. It offers a REST service for listing, searching, deleting, creating, commenting on and exporting CSAF documents.

(back to top)

Getting started

To run the CSAF CMS server you need the following:

You can find an example setup for local development in the 'compose.yaml' and an example configuration for Keycloak in 'keycloak/csaf-realm.json'. You can take this as a starting point, but please check the documentation of the individual projects for a proper production setup. We also recommend running everything behind some kind of reverse proxy. Please take a look at our Architecture for an overview.

The secvisogram frontend is usable as a standalone version without this server. You can still use this standalone mode if the frontend is not behind the proxy, like in the development setup. In this setup where both standalone and server mode are available, the login is only required to manage documents on the server or validate against the validator service.

To build the application run:

./mvn package

The resulting jar file in the target folder can then be run with java -jar filename.jar. To manage the process you can use Docker or an init system of your choice.

(back to top)

How to use

Please have a look at the API documentation on how to use this application.

(back to top)

Management of tracking information

The system automatically manages information under document/tracking of CSAF documents. The revision history is managed as described in the architecture decisions document.

The tracking ID is automatically set to a temporary ID when creating a new advisory and updated to a final ID when the document is published. For generating the tracking IDs, a company name should be set in the environment variable CSAF_TRACKINGID_COMPANY. The variable CSAF_TRACKINGID_DIGITS defines the number of digits used in the tracking ID. It defaults to 5 if nothing is set. If CSAF_REFERENCES_BASE_URL is defined, a reference in document/references with the set URL is added when publishing the document. See .env.example for an example configuration.

Management of engine data

When creating or updating an advisory, the information for document/tracking/engine is updated. The name and version are set according to the corresponding values of the backend's build.

Importing

Existing valid and published advisories can be imported on startup of the application. The advisories to be imported must be stored in JSON format in a directory called import in the root directory. Duplicates are identified by their tracking ID and not imported again.

Developing

The configuration of the application as well as the compose file is done in a local .env file. To start, simply copy the .env.example file to .env. If you want different passwords, database names or ports you can change them in that file. Please note that the following setup is for development purposes only and should not be used in production.

   C4Component
    title Component diagram for CSAF CMS Backend

    Person(user,"User")
    Container(reverseproxy, "Reverse-Proxy", "nginx")

    Container_Boundary(c4, "Internal") {
        Container(secvisogram, "Secvisogram", "nginx + javascript", "Provides secvisogramm via their web browser.")

        Container_Boundary(c2, "Keycloak") {
            Container(keycloak, "Keycloak", "keycloak")
            ContainerDb(keycloak-db, "PostGreSQL", "Keycloak-Database")
        }

        Container_Boundary(c3, "Oauth") {
            Container(oauth, "OAuth2-Proxy", "Authentication for REST-API")
            Container(validator, "CSAF validator service", "node")

            Container_Boundary(c1, "Backend") {
                Container(backend, "CSAF-CMS-Backend", "Spring Boot")
                ContainerDb(backend-db, "CouchDB", "CMS-Backend-Database")
            }
        }
    }

    Rel(user, reverseproxy,"","HTTPS")
    Rel(reverseproxy, secvisogram,"/")
    Rel(reverseproxy, oauth,"/api/*")
    Rel(reverseproxy, keycloak,"/realm/csaf/")
    Rel(oauth, validator, "/api/v1/test")
    Rel(oauth, validator, "/api/v1/validate")
    Rel(oauth, backend, "/api/v1/advisories/*")
    Rel(backend, backend-db,"")
    Rel(backend, keycloak,"")
    Rel(keycloak, keycloak-db,"")

You should now be able to start the spring boot application, navigate to http://localhost/api/v1/about, log in with one of the users and get a response from the server.

You should now be able to access Secvisogram, navigate to http://localhost/. There are the following default users: User Password Roles
registered registered registered
author author registered, editor, author
editor editor registered, editor
publisher publisher registered, editor, publisher
reviewer reviewer registered, reviewer
auditor auditor auditor
all all auditor, reviewer, publisher, editor, author, registred
none none

Login & Logout in combination with Secvisogram

Some explantion on the logoutUrl configured in .well-known/appspecific/de.bsi.secvisogram.json for Secvisogram

"logoutUrl": "/oauth2/sign_out?rd=http://localhost/realms/csaf/protocol/openid-connect/logout?post_logout_redirect_uri=http%3A%2F%2Flocalhost&client_id=secvisogram",

/oauth2/sign_out is the logout URI from the OAUTH-Proxy. This will invalidate the session on the proxy. Then, a redirect to Keycloak (http://localhost/realms/csaf/protocol/openid-connect/logout?post_logout_redirect_uri=http%3A%2F%2Flocalhost&client_id=secvisogram) is necessary to log out from the session on Keyloak. Subsequently, there is a redirect back to Secvisogram (localhost). When hostnames are changed, this has to adapted.

build and execute tests

./mvnw clean verify

start application

./mvnw spring-boot:run

with main class: de.bsi.secvisogram.csaf_cms_backend.SecvisogramApplication

check application running

The port is defined in .env - CSAF_CMS_BACKEND_PORT, default 8081.

http://localhost:8081/api/v1/about

Swagger UI

http://localhost:8081/swagger-ui/index.html

OpenAPI specification

http://localhost:8081/api-docs/

access couchDB

The port is defined in .env - CSAF_CMS_BACKEND_PORT, default 5984.

http://localhost:5984/_utils/#login

CouchDb Info (port is defined in .env):

http://localhost:5984/

Contributing

You can find our guidelines here CONTRIBUTING.md

(back to top)

Dependencies

Check for Maven Plugin update

mvn versions:display-plugin-updates

Check for dependency update

` mvn versions:display-dependency-updates

Spring Boot

Reference Documentation

For further reference, please consider the following sections:

(back to top)

Guides

The following guides illustrate how to use some features concretely:

(back to top)

Additional Links

These additional references should also help you:

(back to top)

Code Quality Rules

Exxcellent Code Quality Rules

(back to top)

SpotBugs

(back to top)

Jacoco

(back to top)

Links

CSAF

OASIS CSAF

BSI CSAF

(back to top)

JSON

(back to top)

Mustache

Mustache samskivert

(back to top)

PoC for Backend

PoC Backend

(back to top)

Open API/ Swagger

Open API Swagger Annotations

(back to top)

diagrams.net (formerly known as draw.io)

(back to top)