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.
To run the CSAF CMS server you need the following:
- Keycloak
- A proxy like oauth2-proxy
- CouchDB
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:
./gradlew clean buildThe resulting jar file in the build/libs 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.
Please have a look at the API documentation on how to use this application.
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.
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.
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.
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.
- run
docker compose up - After Keycloak is up, open a second terminal window and run
docker compose up csaf-keycloak-clito import a realm with all the users and roles already set up. - To set up our CouchDB server open
http://127.0.0.1:5984/_utils/#/setupand run the Single Node Setup. This creates databases like _users and stops CouchDB from spamming our logs - Open
http://localhost:9000/and log in with the admin user.- The port is defined in .env - CSAF_KEYCLOAK_PORT, default 9000
- On the left side, navigate to "Clients" and select the Secvisogram client.
- Select the Credentials tab and copy the Secret. This is our
CSAF_CLIENT_SECRETenvironment variable.
- Generate a cookie secret
and paste it in
CSAF_COOKIE_SECRET. - Create a database in CouchDB with the name specified in
CSAF_COUCHDB_DBNAME - restart compose
- (required for exports) install pandoc (tested with version 2.18) as well as weasyprint (tested with version 56.0) and make sure both are in your PATH
- (optional for exports) define the path to a company logo that should be used in the exports through the environment variable
CSAF_COMPANY_LOGO_PATH. The path can either be relative to the project root or absolute. See .env.example file for an example.
You should now be able to start the spring boot application, navigate to
localhost:4180/api/v1/about, log in with one of the users and get a
response from the server.
The port is defined in .env - CSAF_APP_EXTERNAL_PORT, default 4180
./gradlew clean build
./gradlew clean assemble spotbugsMain
./gradlew bootRun
with main class: de.bsi.secvisogram.csaf_cms_backend.SecvisogramApplication
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/v3/api-docs/
The port is defined in .env - CSAF_CMS_BACKEND_PORT, default 5984.
http://localhost:5984/_utils/#login
CouchDb Info (port is defined in .env):
You can find our guidelines here CONTRIBUTING.md
For further reference, please consider the following sections:
- Official Gradle documentation
- Spring Boot Gradle Plugin Reference Guide
- Create an OCI image
- Mustache
- Spring Data Couchbase
- Spring Web
The following guides illustrate how to use some features concretely:
- Building a RESTful Web Service
- Serving Web Content with Spring MVC
- Building REST services with Spring
These additional references should also help you: